OthmanAdi
11b0ff6750
Adds an "After Completion" section to docs/workflow.md stating that the planning files are ephemeral working memory, gitignored by default, and not archived automatically, with guidance on retaining a completed plan and a note that a completion-triggered archive step is a welcome opt-in extension. Pointers added in docs/quickstart.md and a README FAQ entry. This writes down the lifecycle that issue #14 answered only informally (#202). Expands the README, additively and in the visible body, to document the command surface that shipped across v2.33 through v3.4 but was never listed. The Claude Code command table gains pwf, plan-goal, plan-loop, plan-attest, and the language commands. New sections cover the Pi extension commands, a v3 long-running-agent feature list, a hooks and modes reference across Claude Code, Codex, and Pi, and a note on command names versus skill names (there is no /pwf-de and no /planning-with-files:planning-with-files-goal). The File Structure block now lists all 12 command files.
15 KiB
Workflow Diagram
This diagram shows how the three files work together and how hooks interact with them.
Visual Workflow
┌─────────────────────────────────────────────────────────────────┐
│ TASK START │
│ User requests a complex task (>5 tool calls expected) │
└────────────────────────┬────────────────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ STEP 1: Create task_plan.md │
│ (NEVER skip this step!) │
└───────────────┬───────────────┘
│
▼
┌───────────────────────────────┐
│ STEP 2: Create findings.md │
│ STEP 3: Create progress.md │
└───────────────┬───────────────┘
│
▼
┌────────────────────────────────────────────┐
│ WORK LOOP (Iterative) │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ PreToolUse Hook (Automatic) │ │
│ │ → Reads task_plan.md before │ │
│ │ Write/Edit/Bash operations │ │
│ │ → Refreshes goals in attention │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Perform work (tool calls) │ │
│ │ - Research → Update findings.md │ │
│ │ - Implement → Update progress.md │ │
│ │ - Make decisions → Update both │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ PostToolUse Hook (Automatic) │ │
│ │ → Reminds to update task_plan.md │ │
│ │ if phase completed │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ After 2 view/browser operations: │ │
│ │ → MUST update findings.md │ │
│ │ (2-Action Rule) │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ After completing a phase: │ │
│ │ → Update task_plan.md status │ │
│ │ → Update progress.md with details │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ If error occurs: │ │
│ │ → Log in task_plan.md │ │
│ │ → Log in progress.md │ │
│ │ → Document resolution │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ └──────────┐ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ More work to do? │ │
│ └──────┬───────────────┘ │
│ │ │
│ YES ───┘ │
│ │ │
│ └──────────┐ │
│ │ │
└─────────────────────────┘ │
│
NO │
│ │
▼ │
┌──────────────────────────────────────┐
│ Stop Hook (Automatic) │
│ → Checks if all phases complete │
│ → Verifies task_plan.md status │
└──────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ All phases complete? │
└──────────────┬───────────────────────┘
│
┌──────────┴──────────┐
│ │
YES NO
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ TASK COMPLETE │ │ Continue work │
│ Deliver files │ │ (back to loop) │
└─────────────────┘ └─────────────────┘
After Completion: What Happens to the Plan Files
The planning files are working memory for one task, not a deliverable. task_plan.md, findings.md, progress.md, and any .planning/<slug>/ directory are gitignored by default, and nothing archives them when a task finishes. In root mode the next task overwrites task_plan.md; in slug mode the old directory just stops being the active plan. There is no automatic "completed" or "archived" state, and check-complete reports completion without moving or extracting anything.
The behavior is consistent and intentional, though it was never stated as a rule until now (see #14 and #202). The model is the Manus one the skill is built on: the context window is RAM and the filesystem is disk, so work survives /clear and a crash during a task. Anything meant to outlive the task belongs somewhere durable already, in code, in a commit, in a spec or doc, or in a findings.md you deliberately keep out of the gitignore.
If you want a completed plan to persist, keep it yourself:
- Copy the decisions and errors you care about into code comments, a commit message, an ADR, or a
docs/note. - Move the
.planning/<slug>/directory outside the ignored path, or drop.planning/from.gitignorein a repo where you want plans tracked. - For personal reuse, keep the directory as a cache for a future related task and pin it with
PLAN_IDor.active_plan.
A completion-triggered archive step (move .planning/<slug>/ into an archive directory and extract the decisions and errors tables into a git-tracked record) is a reasonable opt-in extension. It would sit on top of the three-file default the way attestation, gated mode, and topic handoffs already do, without changing the ephemeral default. It is not built in today. If you want it, a focused issue or PR is welcome.
Key Interactions
Hooks
| Hook | When It Fires | What It Does |
|---|---|---|
| SessionStart | When Claude Code session begins | Notifies skill is ready |
| PreToolUse | Before Write/Edit/Bash operations | Reads task_plan.md to refresh goals |
| PostToolUse | After Write/Edit operations | Reminds to update phase status |
| Stop | When Claude tries to stop | Verifies all phases are complete |
The 2-Action Rule
After every 2 view/browser/search operations, you MUST update findings.md.
Operation 1: WebSearch → Note results
Operation 2: WebFetch → MUST UPDATE findings.md NOW
Operation 3: Read file → Note findings
Operation 4: Grep search → MUST UPDATE findings.md NOW
Phase Completion
When a phase is complete:
-
Update
task_plan.md:- Change status:
in_progress→complete - Mark checkboxes:
[ ]→[x]
- Change status:
-
Update
progress.md:- Log actions taken
- List files created/modified
- Note any issues encountered
Error Handling
When an error occurs:
- Log in
task_plan.md→ Errors Encountered table - Log in
progress.md→ Error Log with timestamp - Document the resolution
- Never repeat the same failed action
File Relationships
┌─────────────────────────────────────────────────────────────────┐
│ task_plan.md │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Goal: What you're trying to achieve │ │
│ │ Phases: 3-7 steps with status tracking │ │
│ │ Decisions: Major choices made │ │
│ │ Errors: Problems encountered │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ PreToolUse hook reads this │
│ before every Write/Edit/Bash │
└─────────────────────────────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ │ ▼
┌─────────────────┐ │ ┌─────────────────┐
│ findings.md │ │ │ progress.md │
│ │ │ │ │
│ Research │◄───────────┘ │ Session log │
│ Discoveries │ │ Actions taken │
│ Tech decisions │ │ Test results │
│ Resources │ │ Error log │
└─────────────────┘ └─────────────────┘
Topic Handoff Pattern
The three root files work best for one active task. When work splits into multiple unrelated topics, prefer isolated planning directories:
.planning/
2026-01-10-backend-refactor/
task_plan.md
findings.md
progress.md
2026-01-10-production-incident/
task_plan.md
findings.md
progress.md
Use scripts/init-session.sh <slug> to create a scoped plan and
scripts/set-active-plan.sh <plan-id> to switch the active plan. Hooks resolve
the active plan from $PLAN_ID, .planning/.active_plan, the newest scoped
plan, then the legacy root files.
Some teams also keep durable topic handoffs alongside the root planning files:
progress.md
Short runtime timeline, plus links to topic handoffs
handoffs/<topic>.md
Detailed current state, commands, validation, risks, rollback, PR links
This is useful when a topic spans many sessions or many chat threads. Keep
progress.md as the index and put details in the topic handoff. A good
handoff section answers:
| Question | Where to put it |
|---|---|
| What is running now? | handoffs/<topic>.md |
| How do I check it? | handoffs/<topic>.md |
| What changed today? | Short pointer in progress.md |
| What branch, commit, or PR matters? | Pointer in progress.md, details in the handoff |
| What risk remains? | handoffs/<topic>.md |
The 5-Question Reboot Test
If you can answer these questions, your context management is solid:
| Question | Answer Source |
|---|---|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases in task_plan.md |
| What's the goal? | Goal statement in task_plan.md |
| What have I learned? | findings.md |
| What have I done? | progress.md |
Next Steps
- Quick Start Guide - Step-by-step tutorial
- Troubleshooting - Common issues and solutions