claude-code-pilot 2.0.0 → 3.1.0

package/src/pilot/workflows/node-repair.md

@@ -0,0 +1,92 @@
+<purpose>
+Autonomous repair operator for failed task verification. Invoked by execute-plan when a task fails its done-criteria. Proposes and attempts structured fixes before escalating to the user.
+</purpose>
+
+<inputs>
+- FAILED_TASK: Task number, name, and done-criteria from the plan
+- ERROR: What verification produced — actual result vs expected
+- PLAN_CONTEXT: Adjacent tasks and phase goal (for constraint awareness)
+- REPAIR_BUDGET: Max repair attempts remaining (default: 2)
+</inputs>
+
+<repair_directive>
+Analyze the failure and choose exactly one repair strategy:
+
+**RETRY** — The approach was right but execution failed. Try again with a concrete adjustment.
+- Use when: command error, missing dependency, wrong path, env issue, transient failure
+- Output: `RETRY: [specific adjustment to make before retrying]`
+
+**DECOMPOSE** — The task is too coarse. Break it into smaller verifiable sub-steps.
+- Use when: done-criteria covers multiple concerns, implementation gaps are structural
+- Output: `DECOMPOSE: [sub-task 1] | [sub-task 2] | ...` (max 3 sub-tasks)
+- Sub-tasks must each have a single verifiable outcome
+
+**PRUNE** — The task is infeasible given current constraints. Skip with justification.
+- Use when: prerequisite missing and not fixable here, out of scope, contradicts an earlier decision
+- Output: `PRUNE: [one-sentence justification]`
+
+**ESCALATE** — Repair budget exhausted, or this is an architectural decision (Rule 4).
+- Use when: RETRY failed more than once with different approaches, or fix requires structural change
+- Output: `ESCALATE: [what was tried] | [what decision is needed]`
+</repair_directive>
+
+<process>
+
+<step name="diagnose">
+Read the error and done-criteria carefully. Ask:
+1. Is this a transient/environmental issue? → RETRY
+2. Is the task verifiably too broad? → DECOMPOSE
+3. Is a prerequisite genuinely missing and unfixable in scope? → PRUNE
+4. Has RETRY already been attempted with this task? Check REPAIR_BUDGET. If 0 → ESCALATE
+</step>
+
+<step name="execute_retry">
+If RETRY:
+1. Apply the specific adjustment stated in the directive
+2. Re-run the task implementation
+3. Re-run verification
+4. If passes → continue normally, log `[Node Repair - RETRY] Task [X]: [adjustment made]`
+5. If fails again → decrement REPAIR_BUDGET, re-invoke node-repair with updated context
+</step>
+
+<step name="execute_decompose">
+If DECOMPOSE:
+1. Replace the failed task inline with the sub-tasks (do not modify PLAN.md on disk)
+2. Execute sub-tasks sequentially, each with its own verification
+3. If all sub-tasks pass → treat original task as succeeded, log `[Node Repair - DECOMPOSE] Task [X] → [N] sub-tasks`
+4. If a sub-task fails → re-invoke node-repair for that sub-task (REPAIR_BUDGET applies per sub-task)
+</step>
+
+<step name="execute_prune">
+If PRUNE:
+1. Mark task as skipped with justification
+2. Log to SUMMARY "Issues Encountered": `[Node Repair - PRUNE] Task [X]: [justification]`
+3. Continue to next task
+</step>
+
+<step name="execute_escalate">
+If ESCALATE:
+1. Surface to user via verification_failure_gate with full repair history
+2. Present: what was tried (each RETRY/DECOMPOSE attempt), what the blocker is, options available
+3. Wait for user direction before continuing
+</step>
+
+</process>
+
+<logging>
+All repair actions must appear in SUMMARY.md under "## Deviations from Plan":
+
+| Type | Format |
+|------|--------|
+| RETRY success | `[Node Repair - RETRY] Task X: [adjustment] — resolved` |
+| RETRY fail → ESCALATE | `[Node Repair - RETRY] Task X: [N] attempts exhausted — escalated to user` |
+| DECOMPOSE | `[Node Repair - DECOMPOSE] Task X split into [N] sub-tasks — all passed` |
+| PRUNE | `[Node Repair - PRUNE] Task X skipped: [justification]` |
+</logging>
+
+<constraints>
+- REPAIR_BUDGET defaults to 2 per task. Configurable via config.json `workflow.node_repair_budget`.
+- Never modify PLAN.md on disk — decomposed sub-tasks are in-memory only.
+- DECOMPOSE sub-tasks must be more specific than the original, not synonymous rewrites.
+- If config.json `workflow.node_repair` is `false`, skip directly to verification_failure_gate (user retains original behavior).
+</constraints>

package/src/pilot/workflows/note.md

@@ -0,0 +1,156 @@
+<purpose>
+Zero-friction idea capture. One Write call, one confirmation line. No questions, no prompts.
+Runs inline — no Task, no AskUserQuestion, no Bash.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="storage_format">
+**Note storage format.**
+
+Notes are stored as individual markdown files:
+
+- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` exists in cwd
+- **Global scope**: `~/.claude/notes/{YYYY-MM-DD}-{slug}.md` — fallback when no `.planning/`, or when `--global` flag is present
+
+Each note file:
+
+```markdown
+---
+date: "YYYY-MM-DD HH:mm"
+promoted: false
+---
+
+{note text verbatim}
+```
+
+**`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists.
+
+**Important**: Do NOT create `.planning/` if it doesn't exist. Fall back to global scope silently.
+</step>
+
+<step name="parse_subcommand">
+**Parse subcommand from $ARGUMENTS (after stripping --global).**
+
+| Condition | Subcommand |
+|-----------|------------|
+| Arguments are exactly `list` (case-insensitive) | **list** |
+| Arguments are exactly `promote <N>` where N is a number | **promote** |
+| Arguments are empty (no text at all) | **list** |
+| Anything else | **append** (the text IS the note) |
+
+**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/ccp:note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
+</step>
+
+<step name="append">
+**Subcommand: append — create a timestamped note file.**
+
+1. Determine scope (project or global) per storage format above
+2. Ensure the notes directory exists (`.planning/notes/` or `~/.claude/notes/`)
+3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
+4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
+   - If a file with that name already exists, append `-2`, `-3`, etc.
+5. Write the file with frontmatter and note text (see storage format)
+6. Confirm with exactly one line: `Noted ({scope}): {note text}`
+   - Where `{scope}` is "project" or "global"
+
+**Constraints:**
+- **Never modify the note text** — capture verbatim, including typos
+- **Never ask questions** — just write and confirm
+- **Timestamp format**: Use local time, `YYYY-MM-DD HH:mm` (24-hour, no seconds)
+</step>
+
+<step name="list">
+**Subcommand: list — show notes from both scopes.**
+
+1. Glob `.planning/notes/*.md` (if directory exists) — project notes
+2. Glob `~/.claude/notes/*.md` (if directory exists) — global notes
+3. For each file, read frontmatter to get `date` and `promoted` status
+4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
+5. Sort by date, number all active entries sequentially starting at 1
+6. If total active entries > 20, show only the last 10 with a note about how many were omitted
+
+**Display format:**
+
+```
+Notes:
+
+Project (.planning/notes/):
+  1. [2026-02-08 14:32] refactor the hook system to support async validators
+  2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
+  3. [2026-02-08 15:10] consider adding a --dry-run flag to build
+
+Global (~/.claude/notes/):
+  4. [2026-02-08 10:00] cross-project idea about shared config
+
+{count} active note(s). Use `/ccp:note promote <N>` to convert to a todo.
+```
+
+If a scope has no directory or no entries, show: `(no notes)`
+</step>
+
+<step name="promote">
+**Subcommand: promote — convert a note into a todo.**
+
+1. Run the **list** logic to build the numbered index (both scopes)
+2. Find entry N from the numbered list
+3. If N is invalid or refers to an already-promoted note, tell the user and stop
+4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a CCP project. Run `/ccp:new-project` to initialize one."
+5. Ensure `.planning/todos/pending/` directory exists
+6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
+7. Extract the note text from the source file (body after frontmatter)
+8. Create `.planning/todos/pending/{id}.md`:
+
+```yaml
+---
+title: "{note text}"
+status: pending
+priority: P2
+source: "promoted from /ccp:note"
+created: {YYYY-MM-DD}
+theme: general
+---
+
+## Goal
+
+{note text}
+
+## Context
+
+Promoted from quick note captured on {original date}.
+
+## Acceptance Criteria
+
+- [ ] {primary criterion derived from note text}
+```
+
+9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
+10. Confirm: `Promoted note {N} to todo {id}: {note text}`
+</step>
+
+</process>
+
+<edge_cases>
+1. **"list" as note text**: `/ccp:note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
+2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
+3. **Promote without project**: Warns that todos require `.planning/`, suggests `/ccp:new-project`
+4. **Large files**: `list` shows last 10 when >20 active entries
+5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
+6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
+7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
+8. **Empty note text after stripping flags**: Treat as `list` subcommand
+</edge_cases>
+
+<success_criteria>
+- [ ] Append: Note file written with correct frontmatter and verbatim text
+- [ ] Append: No questions asked — instant capture
+- [ ] List: Both scopes shown with sequential numbering
+- [ ] List: Promoted notes shown but dimmed
+- [ ] Promote: Todo created with correct format
+- [ ] Promote: Source note marked as promoted
+- [ ] Global fallback: Works when no `.planning/` exists
+</success_criteria>

package/src/pilot/workflows/pause-work.md

@@ -0,0 +1,177 @@
+<purpose>
+Create structured `.planning/HANDOFF.json` and `.continue-here.md` handoff files to preserve complete work state across sessions. The JSON provides machine-readable state for `/ccp:resume-work`; the markdown provides human-readable context.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="detect">
+Find current phase directory from most recently modified files:
+
+```bash
+# Find most recent phase directory with work
+(ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true) | head -1 | grep -oP 'phases/\K[^/]+' || true
+```
+
+If no active phase detected, ask user which phase they're pausing work on.
+</step>
+
+<step name="gather">
+**Collect complete state for handoff:**
+
+1. **Current position**: Which phase, which plan, which task
+2. **Work completed**: What got done this session
+3. **Work remaining**: What's left in current plan/phase
+4. **Decisions made**: Key decisions and rationale
+5. **Blockers/issues**: Anything stuck
+6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing)
+7. **Background processes**: Any running servers/watchers that were part of the workflow
+8. **Files modified**: What's changed but not committed
+
+Ask user for clarifications if needed via conversational questions.
+
+**Also inspect SUMMARY.md files for false completions:**
+```bash
+# Check for placeholder content in existing summaries
+grep -l "To be filled\|placeholder\|TBD" .planning/phases/*/*.md 2>/dev/null || true
+```
+Report any summaries with placeholder content as incomplete items.
+</step>
+
+<step name="write_structured">
+**Write structured handoff to `.planning/HANDOFF.json`:**
+
+```bash
+timestamp=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" current-timestamp full --raw)
+```
+
+```json
+{
+  "version": "1.0",
+  "timestamp": "{timestamp}",
+  "phase": "{phase_number}",
+  "phase_name": "{phase_name}",
+  "phase_dir": "{phase_dir}",
+  "plan": {current_plan_number},
+  "task": {current_task_number},
+  "total_tasks": {total_task_count},
+  "status": "paused",
+  "completed_tasks": [
+    {"id": 1, "name": "{task_name}", "status": "done", "commit": "{short_hash}"},
+    {"id": 2, "name": "{task_name}", "status": "done", "commit": "{short_hash}"},
+    {"id": 3, "name": "{task_name}", "status": "in_progress", "progress": "{what_done}"}
+  ],
+  "remaining_tasks": [
+    {"id": 4, "name": "{task_name}", "status": "not_started"},
+    {"id": 5, "name": "{task_name}", "status": "not_started"}
+  ],
+  "blockers": [
+    {"description": "{blocker}", "type": "technical|human_action|external", "workaround": "{if any}"}
+  ],
+  "human_actions_pending": [
+    {"action": "{what needs to be done}", "context": "{why}", "blocking": true}
+  ],
+  "decisions": [
+    {"decision": "{what}", "rationale": "{why}", "phase": "{phase_number}"}
+  ],
+  "uncommitted_files": [],
+  "next_action": "{specific first action when resuming}",
+  "context_notes": "{mental state, approach, what you were thinking}"
+}
+```
+</step>
+
+<step name="write">
+**Write handoff to `.planning/phases/XX-name/.continue-here.md`:**
+
+```markdown
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: [timestamp from current-timestamp]
+---
+
+<current_state>
+[Where exactly are we? Immediate context]
+</current_state>
+
+<completed_work>
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done]
+</completed_work>
+
+<remaining_work>
+
+- Task 3: [what's left]
+- Task 4: Not started
+- Task 5: Not started
+</remaining_work>
+
+<decisions_made>
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisions_made>
+
+<blockers>
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+<context>
+[Mental state, what were you thinking, the plan]
+</context>
+
+<next_action>
+Start with: [specific first action when resuming]
+</next_action>
+```
+
+Be specific enough for a fresh Claude to understand immediately.
+
+Use `current-timestamp` for last_updated field. You can use init todos (which provides timestamps) or call directly:
+```bash
+timestamp=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" current-timestamp full --raw)
+```
+</step>
+
+<step name="commit">
+```bash
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md .planning/HANDOFF.json
+```
+</step>
+
+<step name="confirm">
+```
+Handoff created:
+  - .planning/HANDOFF.json (structured, machine-readable)
+  - .planning/phases/[XX-name]/.continue-here.md (human-readable)
+
+Current state:
+
+- Phase: [XX-name]
+- Task: [X] of [Y]
+- Status: [in_progress/blocked]
+- Blockers: [count] ({human_actions_pending count} need human action)
+- Committed as WIP
+
+To resume: /ccp:resume-work
+
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] .continue-here.md created in correct phase directory
+- [ ] HANDOFF.json created with structured machine-readable state
+- [ ] All sections filled with specific content
+- [ ] Committed as WIP
+- [ ] User knows location and how to resume
+</success_criteria>

package/{gsd/get-shit-done → src/pilot}/workflows/plan-milestone-gaps.md

@@ -1,5 +1,5 @@
 <purpose>
-Create all phases necessary to close gaps identified by `/gsd:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/gsd:add-phase` per gap.
+Create all phases necessary to close gaps identified by `/ccp:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/ccp:add-phase` per gap.
 </purpose>
 
 <required_reading>
@@ -12,7 +12,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 ```bash
 # Find the most recent audit file
-ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | head -1
+(ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null || true) | head -1
 ```
 
 Parse YAML frontmatter to extract structured gaps:
@@ -22,7 +22,7 @@ Parse YAML frontmatter to extract structured gaps:
 
 If no audit file exists or has no gaps, error:
 ```
-No audit gaps found. Run `/gsd:audit-milestone` first.
+No audit gaps found. Run `/ccp:audit-milestone` first.
 ```
 
 ## 2. Prioritize Gaps
@@ -65,8 +65,7 @@ Gap: Flow "View dashboard" broken at data fetch
 Find highest existing phase:
 ```bash
 # Get sorted phase list, extract last one
-PHASES=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phases list)
-HIGHEST=$(printf '%s\n' "$PHASES" | jq -r '.directories[-1]')
+HIGHEST=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" phases list --pick directories[-1])
 ```
 
 New phases continue from there:
@@ -147,7 +146,7 @@ mkdir -p ".planning/phases/{NN}-{name}"
 ## 9. Commit Roadmap and Requirements Update
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 
 ## 10. Offer Next Steps
@@ -164,22 +163,22 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(roadmap): add
 
 **Plan first gap closure phase**
 
-`/gsd:plan-phase {N}`
+`/ccp:plan-phase {N}`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/gsd:execute-phase {N}` — if plans already exist
+- `/ccp:execute-phase {N}` — if plans already exist
 - `cat .planning/ROADMAP.md` — see updated roadmap
 
 ---
 
 **After all gap phases complete:**
 
-`/gsd:audit-milestone` — re-audit to verify gaps closed
-`/gsd:complete-milestone {version}` — archive when audit passes
+`/ccp:audit-milestone` — re-audit to verify gaps closed
+`/ccp:complete-milestone {version}` — archive when audit passes
 ```
 
 </process>
@@ -270,5 +269,5 @@ becomes:
 - [ ] Coverage count updated in REQUIREMENTS.md
 - [ ] Phase directories created
 - [ ] Changes committed (includes REQUIREMENTS.md)
-- [ ] User knows to run `/gsd:plan-phase` next
+- [ ] User knows to run `/ccp:plan-phase` next
 </success_criteria>