diff --git a/.claude/commands/handoff.md b/.claude/commands/handoff.md index e90b283..01a897d 100644 --- a/.claude/commands/handoff.md +++ b/.claude/commands/handoff.md @@ -1,8 +1,11 @@ Write a session handoff file for the current session. Steps: -1. Read `templates/claude-templates.md` and find the Session Handoff template (Template 4). Use the Light Handoff if this is a small project (under 5 sessions), Full Handoff otherwise. -2. Fill in every field based on what was accomplished in this session. Be specific — include exact file paths for every output, exact numbers discovered, and conditional logic established. -3. Write the handoff to `./docs/summaries/handoff-[today's date]-[topic].md`. -4. If a previous handoff file exists in `./docs/summaries/`, move it to `./docs/archive/handoffs/`. -5. Tell me the file path of the new handoff and summarize what it contains. +1. Determine handoff type: + - **Light Handoff (Template 4A)**: quick task, single session, or output is self-explanatory + - **Full Handoff (Template 4B)**: sustained work, multi-phase project, or significant decisions were made +2. Read `templates/claude-templates.md` and find the appropriate template. +3. Fill in every field based on what was accomplished this session. Include exact file paths for every output, exact numbers, and any conditional logic established. +4. Write the handoff to `./docs/summaries/handoff-[today's date]-[topic].md`. +5. If a previous handoff file exists in `./docs/summaries/`, move it to `./docs/archive/handoffs/`. +6. Tell me the file path of the new handoff and summarize what it contains. diff --git a/CLAUDE.md b/CLAUDE.md index e0349a1..a54e739 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,9 +2,11 @@ ## Session Start -Read the latest handoff in docs/summaries/ if one exists. Load only the files that handoff references — not all summaries. If no handoff exists, ask: what is the goal this session and what is the target deliverable. +Check `docs/summaries/` for a handoff file. If one exists, read it and the files it references — not all summaries. State: what you understand the project state to be, what you plan to do, and open questions. -Before starting work, state: what you understand the project state to be, what you plan to do this session, and any open questions. +If no handoff exists, determine session type before proceeding: +- **Quick task**: single-session, self-contained work (adding a task, fixing a bug, writing a role) → proceed without setup overhead +- **Sustained work**: multi-session project or significant design work → ask: what is the goal and what is the target deliverable ## Identity @@ -24,12 +26,12 @@ Load `docs/context/architecture.md` when working on playbooks, EDA rulebooks, or ## Rules 1. Do not mix unrelated project contexts in one session. -2. Write state to disk, not conversation. After completing meaningful work, write a summary to docs/summaries/ using templates from templates/claude-templates.md. Include: decisions with rationale, exact numbers, file paths, open items. -3. Before compaction or session end, write to disk: every number, every decision with rationale, every open question, every file path, exact next action. -4. When switching work types (development → documentation → review), write a handoff to docs/summaries/handoff-[date]-[topic].md and suggest a new session. +2. For sustained work: write state to disk after completing meaningful work. Use templates from `templates/claude-templates.md`. Include: decisions with rationale, exact numbers, file paths, open items. +3. For sustained work: before compaction or session end, write to disk — every number, every decision with rationale, every open question, every file path, exact next action. +4. For sustained work: when switching work types (development → documentation → review), write a handoff to `docs/summaries/handoff-[date]-[topic].md` and suggest a new session. 5. Do not silently resolve open questions. Mark them OPEN or ASSUMED. -6. Do not bulk-read documents. Process one at a time: read, summarize to disk, release from context before reading next. For the detailed protocol, read docs/context/processing-protocol.md. -7. Sub-agent returns must be structured, not free-form prose. Use output contracts from templates/claude-templates.md. +6. Do not bulk-read documents. Process one at a time: read, summarize to disk, release from context before reading next. For the detailed protocol, read `docs/context/processing-protocol.md`. +7. Sub-agent returns must be structured, not free-form prose. Use output contracts from `templates/claude-templates.md`. ## Where Things Live @@ -40,15 +42,18 @@ Load `docs/context/architecture.md` when working on playbooks, EDA rulebooks, or - `processing-protocol.md` — full document processing steps - `archive-rules.md` — summary lifecycle and file archival rules - `subagent-rules.md` — when to use subagents vs. main agent +- `.claude/agents/` — specialized subagents (ansible-idempotency-reviewer — use before adding tasks or before production runs) - `docs/archive/` — processed raw files. Do not read unless explicitly told. - `output/deliverables/` — final outputs +For cross-project user preferences, recurring constraints, or tool preferences: use Claude Code's native memory system, not `docs/summaries/`. + ## Error Recovery If context degrades or auto-compact fires unexpectedly: write current state to docs/summaries/recovery-[date].md, tell the user what may have been lost, suggest a fresh session. ## Before Delivering Output -Verify: exact numbers preserved, open questions marked OPEN, output matches what was requested (not assumed), no Ansible idempotency regressions introduced, summary written to disk for this session's work. +Verify: exact numbers preserved, open questions marked OPEN, output matches what was requested (not assumed), no Ansible idempotency regressions introduced. All Ansible files (playbooks, task files, templates, vars) must end with a trailing newline. diff --git a/templates/claude-templates.md b/templates/claude-templates.md index 44aa7f5..7e73a67 100644 --- a/templates/claude-templates.md +++ b/templates/claude-templates.md @@ -155,9 +155,38 @@ --- -## Template 4: Session Handoff +## Template 4A: Light Handoff -**Use when:** A session is ending (context limit approaching OR phase complete) +**Use when:** A quick-task session produced output worth continuing in a future session. + +**Write to:** `./docs/summaries/handoff-[YYYY-MM-DD]-[topic].md` + +```markdown +# Handoff: [Topic] +**Date:** [YYYY-MM-DD] +**Focus:** [one sentence] + +## Accomplished +- [task] → `[output path]` + +## Key Numbers & Decisions +- [metric/decision]: [value/outcome] — [rationale if not obvious] + +## Open Questions +- [ ] [question] — impacts [what] + +## Next Action +[Specific first thing to do next session, with file path if relevant] + +## Files to Load Next Session +- `[file path]` — [why needed] +``` + +--- + +## Template 4B: Full Session Handoff + +**Use when:** A sustained-work session is ending (context limit approaching OR phase complete) **Write to:** `./docs/summaries/handoff-[YYYY-MM-DD]-[topic].md`