Skip to content

workflow.md

Latest commit

 

History

History
135 lines (108 loc) · 5.14 KB

workflow.md

File metadata and controls

135 lines (108 loc) · 5.14 KB
Raw

Workflow Details

Overall Flow

User describes a complex task
    │
    ▼
Skill triggers → Claude creates .plan/ directory
    │
    ▼
User confirms the plan (cannot be skipped)
    │
    ▼
┌─── Work Loop ────────────────────────────────┐
│                                               │
│  UserPromptSubmit hook (when user sends msg)  │
│  └─ If active phase → inject overview + spec  │
│     + checklist                               │
│                                               │
│  PreToolUse hook (before all tool calls)      │
│  └─ Inject overview.md (≤25 lines)           │
│                                               │
│  Claude executes tool operations              │
│                                               │
│  PostToolUse hook (after Write|Edit)          │
│  └─ Remind to update checklist and overview   │
│                                               │
│  Phase complete?                              │
│  ├─ No → Continue loop                       │
│  └─ Yes → Update current_phase, read new     │
│           phase spec                          │
│                                               │
└───────────────────────────────────────────────┘
    │
    ▼
Stop hook: Check all phase checkboxes
├─ All pending (awaiting confirmation) → exit 0 allow stop
├─ Partially complete → exit 2 block stop
└─ All complete → exit 0 allow stop

.plan/ Directory Structure

.plan/
├── overview.md              ← Global summary (≤25 lines, repeatedly injected by hooks)
├── decisions.md             ← All decision records
├── errors.md                ← All error records
└── phases/
    ├── phase1_xxx/
    │   ├── spec.md          ← Detailed spec (≤60 lines)
    │   ├── call_chain.md    ← Call chain change diagram (optional)
    │   └── checklist.md     ← Item-by-item completion status
    ├── phase2_xxx/
    │   └── ...
    └── ...

File Responsibilities

File Role Content Update Timing
overview.md Attention anchor Goal + phase list + status After each phase completes
spec.md Work manual File list, interfaces, data structures, acceptance criteria At plan creation, when new requirements emerge
checklist.md Progress tracker Item-by-item checkboxes After each subtask completes
call_chain.md Architecture reference Before/after call relationship comparison At plan creation
decisions.md Decision log Decision, rationale, impact After each important decision
errors.md Error log Error, attempt count, solution After each error encountered

Hook Injection Strategy

UserPromptSubmit (when user sends a message)

Checks overview.md for active phases (DONE > 0 and DONE < TOTAL). If found, injects:

  • overview.md full content
  • Current phase spec.md full content
  • Current phase checklist.md full content

Does NOT inject (exits silently) when:

  • .plan/ does not exist (planning not enabled)
  • All phases are pending (awaiting user confirmation)
  • All phases are complete

PreToolUse (before all tool calls)

Injects overview.md full content (≤25 lines), maintaining goal and progress awareness.

PostToolUse (after Write|Edit)

Reminds to update checklist:

[hplan] File updated. If you completed a subtask in the current phase, please update the corresponding checklist.md and the progress in overview.md.

Stop (when Claude wants to finish)

Calls check-complete.sh to check phase status in overview.md:

  • All pending (DONE=0) → exit 0, allow stop to wait for user plan confirmation
  • Partially complete (0 < DONE < TOTAL) → exit 2, block stop
  • All complete → exit 0, allow stop

Phase Switching

When a phase's checklist is fully checked:

  1. Update checklist.md: all [ ] → [x]
  2. Update overview.md: mark the phase as [x] ... → complete
  3. Update overview.md: change current_phase to the next phase ID
  4. Update next phase status to in_progress
  5. Record important findings from this phase in decisions.md
  6. Proactively read the new phase's spec.md and checklist.md

Run sh scripts/advance-phase.sh to assist with steps 2-4.

Error Handling

1st failure: Diagnose and fix → record in errors.md
2nd failure: Try a different approach → record in errors.md
3rd failure: Re-examine assumptions → update spec.md
After 3rd still failing: Explain the situation to user, request guidance

Read/Write Decision Matrix

Scenario Action Reason
Just wrote a file Don't read Content is still in context
Starting a new phase Read spec.md + checklist.md Fully understand work scope (cannot skip)
Before an important decision Read overview.md + related spec Ensure goal alignment
Encountered an error Read errors.md Avoid repeating failures