Files
planning-with-files/docs/workflow.md
T
OthmanAdi 11b0ff6750 docs: document plan lifecycle (#202) and surface the v3 command, hook, and mode surface
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.
2026-07-13 08:15:03 +02:00

272 lines
15 KiB
Markdown

# 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](https://github.com/OthmanAdi/planning-with-files/issues/14) and [#202](https://github.com/OthmanAdi/planning-with-files/issues/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 `.gitignore` in 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_ID` or `.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:
1. Update `task_plan.md`:
- Change status: `in_progress` → `complete`
- Mark checkboxes: `[ ]` → `[x]`
2. Update `progress.md`:
- Log actions taken
- List files created/modified
- Note any issues encountered
### Error Handling
When an error occurs:
1. Log in `task_plan.md` → Errors Encountered table
2. Log in `progress.md` → Error Log with timestamp
3. Document the resolution
4. 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:
```text
.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:
```text
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](quickstart.md) - Step-by-step tutorial
- [Troubleshooting](troubleshooting.md) - Common issues and solutions