cc-dev-template 0.1.1

package/src/skills/orchestration/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: orchestration
+description: Planning and execution workflows for feature development. Use when starting new features, debugging issues, executing approved plans, or resuming in-progress work.
+---
+
+# Orchestration Skill
+
+## Purpose
+
+This skill provides structured workflows for software development. Instead of ad-hoc work that drifts between sessions, orchestration ensures every task follows a repeatable process: requirements are captured, plans are validated, and execution is tracked.
+
+**Who this is for**: Developers starting feature work, debugging issues, resuming in-progress plans, or executing approved plans.
+
+**Success looks like**: The user knows exactly where they are in the workflow, what options they have, and can move forward with a single choice.
+
+## What To Do Now
+
+Complete each step in order before proceeding to the next.
+
+<steps>
+
+<step name="Discover Project State">
+Run the plan status script to find existing plans:
+
+```bash
+node ~/.claude/scripts/plan-status.js
+```
+
+This returns a list of plans with their current status (draft, approved, in_progress, completed).
+</step>
+
+<step name="Present Options to User">
+Based on what you found, use `AskUserQuestion` to ask what the user wants to do.
+
+**Build the options dynamically:**
+
+- Always include: "Create a new plan"
+- Always include: "Debug an issue"
+- If draft plans exist: "Continue planning: [plan title]" for each
+- If approved plans exist: "Execute: [plan title]" for each
+- If in-progress execution exists: "Resume execution: [plan title]" for each
+- If active debug sessions exist: "Continue debugging: [debug title]" for each
+- Always include: "Something else" (free text option)
+
+**Example AskUserQuestion:**
+
+```
+Question: "What would you like to work on?"
+
+Options (based on discovered state):
+- "Create a new plan" - Start fresh with a new feature, enhancement, or refactor
+- "Debug an issue" - Investigate and fix a bug using TDD
+- "Execute: User Authentication" - Begin implementing this approved plan
+- "Continue planning: API Refactor" - Resume drafting this incomplete plan
+- "Something else" - Describe what you need
+```
+
+Wait for the user's response before proceeding.
+</step>
+
+<step name="Route Based on User's Choice">
+Once the user chooses, read the appropriate workflow file:
+
+| User's Choice | Action |
+|---------------|--------|
+| "Create a new plan" | Read `references/planning/start.md` |
+| "Debug an issue" | Read `references/debugging/describe.md` |
+| "Execute: [plan]" | Store the plan slug, then read `references/execution/start.md` |
+| "Continue planning: [plan]" | Store the plan slug, determine which planning phase to resume, then read that phase file |
+| "Resume execution: [plan]" | Store the plan slug, then read `references/execution/tasks.md` |
+| "Continue debugging: [debug]" | Store the debug slug, determine phase using debug resumption logic below |
+| "Something else" | Address the user's custom request, or help them find the right workflow |
+
+Reading the workflow file is mandatory—it contains the instructions for the next phase.
+</step>
+
+</steps>
+
+## Debug Phase Resumption Logic
+
+When resuming a debug session, read `.claude/debug/[slug]/debug.yaml` and determine the phase:
+
+| debug.yaml State | Resume Phase |
+|------------------|--------------|
+| `status: investigating`, no hypotheses | `references/debugging/rca.md` |
+| `status: investigating`, hypothesis with `status: investigating` | `references/debugging/rca.md` |
+| `status: investigating`, hypothesis with `status: verified` | `references/debugging/fix.md` |
+| `status: investigating`, hypothesis with `status: disproven` | `references/debugging/rca.md` |
+| `status: investigating`, hypothesis with `status: fixed` | `references/debugging/learn.md` |
+| `status: closed` | Already complete, no action needed |
+
+## Important Notes
+
+**Always use AskUserQuestion for choices.** Present options as structured choices, not open-ended questions. Include "Something else" as an escape hatch for cases that don't fit the standard options.
+
+**Store context for later phases.** When the user selects a specific plan or debug session, remember the slug so subsequent phases can reference the correct directory at `.claude/plans/[slug]/` or `.claude/debug/[slug]/`.
+
+**Keep this routing simple.** The goal is to get the user into the right workflow quickly. Detailed instructions live in the phase files, not here.
+
+**Follow the workflow files.** Each phase file contains structured steps. Complete each step before proceeding to the next. The workflows are designed to be followed in order.
+
+## Workflow Overview
+
+This skill supports three main workflows:
+
+### Planning Workflow
+Transform a feature request into an approved, validated plan.
+
+```
+start.md → explore.md → draft.md → finalize.md
+```
+
+### Execution Workflow
+Transform an approved plan into working code.
+
+```
+start.md → tasks.md → complete.md
+```
+
+### Debugging Workflow
+Investigate and fix bugs using test-driven development.
+
+```
+describe.md → rca.md → verify.md → fix.md → learn.md
+```
+
+All workflows use progressive disclosure—each phase file contains only the instructions needed for that phase. Each phase file uses `<steps>`, `<checkpoint>`, and `<transition>` tags to structure the work.

package/src/skills/orchestration/references/debugging/describe.md

@@ -0,0 +1,122 @@
+# Debugging Phase 1: Describe
+
+## Purpose
+
+Transform a vague bug report into a precise understanding of the symptom and expected behavior, then establish a clean test baseline before investigation begins.
+
+**Success looks like**: Clear symptom, clear expected behavior, passing test suite baseline, relevant ADRs identified, and a `debug.yaml` artifact ready for investigation.
+
+## What To Do
+
+<steps>
+
+<step name="Capture the Symptom">
+Ask the user: **"What's happening that shouldn't be?"**
+
+Let them describe in their own words. Listen for:
+- What they observe (the actual behavior)
+- When it happens (trigger, conditions)
+- How consistently it reproduces
+</step>
+
+<step name="Probe for Clarity">
+Use `AskUserQuestion` to remove ambiguity. Ask one clarifying question at a time until the symptom is crystal clear.
+
+Focus on: exact behavior observed, reproduction conditions, when it started, recent changes.
+
+Always include an escape hatch option like "Let me explain" for context that doesn't fit your options.
+</step>
+
+<step name="Define Expected Behavior">
+Ask: **"What should happen instead?"**
+
+This becomes the acceptance criteria—when the code behaves this way, the bug is resolved.
+</step>
+
+<step name="Establish Baseline and Find ADRs">
+Run in parallel:
+
+**Run the test suite** to establish a clean starting point. If tests are already failing, address with the user before proceeding.
+
+**Spawn adr-agent** to find relevant ADRs:
+
+```
+Spawn adr-agent: "Find ADRs relevant to debugging [symptom summary] in [likely area]."
+```
+</step>
+
+<step name="Create the Debug Artifact">
+Create `.claude/debug/[slug]/debug.yaml` with:
+
+```yaml
+id: debug-[NNN]
+slug: [generated-slug]
+title: "[Short description]"
+status: investigating
+created: [today's date]
+
+baseline:
+  test_command: "[command]"
+  result: pass
+  summary: "[X tests passed]"
+
+symptom: |
+  [What the user described]
+
+expected_behavior: |
+  [What should happen instead]
+
+relevant_adrs:
+  - id: ADR-[XXX]
+    relevance: [Why it matters]
+
+hypotheses: []
+```
+</step>
+
+<step name="Confirm and Proceed">
+Summarize back to the user:
+
+```
+## Bug Report Captured
+
+**Symptom**: [summary]
+**Expected**: [summary]
+**Baseline**: All tests passing
+**Relevant ADRs**: [list or "None found"]
+
+Ready to investigate root cause.
+```
+
+```
+AskUserQuestion:
+Question: "Does this capture the issue correctly?"
+Options:
+- "Yes, investigate" - Proceed to root cause analysis
+- "Let me clarify" - I'll add more detail
+- "Something else" - Different feedback
+```
+</step>
+
+<checkpoint>
+Before proceeding:
+- Symptom is clearly documented
+- Expected behavior is defined
+- Test baseline is established
+- debug.yaml artifact is created
+- User has confirmed the description
+</checkpoint>
+
+</steps>
+
+## Key Principles
+
+**Invest time in clarity.** A precise symptom makes root cause analysis faster. Ambiguity discovered now is cheap; ambiguity discovered mid-investigation wastes effort.
+
+**Establish baseline before investigating.** Running tests first prevents confusion about whether failures are from the bug or pre-existing.
+
+**Document everything in debug.yaml.** The artifact is the source of truth for future phases.
+
+<transition>
+When the user confirms the description is accurate, read `references/debugging/rca.md` to begin root cause analysis.
+</transition>

package/src/skills/orchestration/references/debugging/fix.md

@@ -0,0 +1,110 @@
+# Debugging Phase 4: Fix
+
+## Purpose
+
+Fix the code to make the failing test pass. The test is the specification—your job is to make the code conform without modifying the test.
+
+**Success looks like**: The test passes, full test suite passes (no regressions), and only non-test files were modified.
+
+## What To Do
+
+<steps>
+
+<step name="Spawn TDD Agent">
+Spawn tdd-agent to fix the code:
+
+```
+Spawn tdd-agent: "Fix the code to pass the failing test in [debug-path]/debug.yaml."
+```
+
+The agent reads the debug context, fixes the code without modifying test files, runs the test, and updates debug.yaml with the result.
+</step>
+
+<step name="Verify Result">
+When the agent returns:
+
+**If test passes**: Check for regressions by running the full test suite. Compare against baseline from debug.yaml.
+
+**If test still fails**:
+```
+AskUserQuestion:
+Question: "The test still fails. How should we proceed?"
+Options:
+- "Keep fixing" - Spawn the agent again
+- "Review the fix" - Let me see what was changed
+- "Different approach" - Reconsider the hypothesis
+- "Something else" - Different feedback
+```
+
+**If regressions introduced**:
+```
+AskUserQuestion:
+Question: "The fix introduced [N] test failures. How should we proceed?"
+Options:
+- "Fix regressions" - Address the new failures
+- "Review changes" - Let me see what caused this
+- "Revert" - Try a different approach
+- "Something else" - Different feedback
+```
+</step>
+
+<step name="Update Debug Status">
+Once test passes with no regressions, update debug.yaml:
+
+```yaml
+hypotheses:
+  - id: h[N]
+    status: fixed
+
+resolution:
+  description: |
+    [What was fixed and why]
+  hypothesis_id: h[N]
+  files_changed:
+    - [list of modified files]
+```
+
+Present to user:
+
+```
+## Bug Fixed
+
+**Hypothesis**: [description]
+**Fix**: [what was changed]
+**Test**: Passes
+**Regressions**: None
+
+Ready for the learning phase.
+```
+
+```
+AskUserQuestion:
+Question: "The bug is fixed. Ready to capture learnings?"
+Options:
+- "Yes, continue" - Proceed to learning phase
+- "Let me verify" - I want to test more
+- "Something else" - Different feedback
+```
+</step>
+
+<checkpoint>
+Before proceeding:
+- tdd-agent fixed the code
+- Test passes
+- Full test suite passes (no regressions)
+- debug.yaml resolution is updated
+</checkpoint>
+
+</steps>
+
+## Key Principles
+
+**Test is the specification.** Don't modify the test—make the code conform.
+
+**Check for regressions.** A fix that breaks other things isn't a fix.
+
+**Document the resolution.** debug.yaml captures what was done for future reference.
+
+<transition>
+When the fix is complete and verified, read `references/debugging/learn.md` to capture learnings.
+</transition>

package/src/skills/orchestration/references/debugging/learn.md

@@ -0,0 +1,162 @@
+# Debugging Phase 5: Learn
+
+## Purpose
+
+Verify the fix works from the user's perspective, capture learnings, and close the debug session.
+
+**Success looks like**: User has verified the fix, learnings are captured, ADR created if applicable, debug session closed.
+
+## What To Do
+
+<steps>
+
+<step name="Present Summary for Human Review">
+Summarize what was done:
+
+```
+## Debug Summary: [title]
+
+**Symptom**: [what was broken]
+**Root Cause**: [the verified hypothesis]
+**Fix**: [what was changed]
+**Files Changed**: [list]
+**Test Added**: [test file] - verifies [behavior]
+
+### Ready for Verification
+
+Please verify the fix works:
+- Does the original symptom still occur?
+- Does the expected behavior now work correctly?
+```
+</step>
+
+<step name="Get User Verification">
+```
+AskUserQuestion:
+Question: "Please verify the bug is fixed. Does the expected behavior work correctly now?"
+Options:
+- "Yes, verified" - Proceed to capture learnings
+- "Not quite" - There's still an issue
+- "Need to test more" - I want to check more scenarios
+- "Something else" - Different feedback
+```
+
+**If "Not quite"**: Determine if it's the same symptom (back to RCA), a different issue (new debug session), or an edge case (enhance the fix).
+</step>
+
+<step name="Evaluate Learnings">
+Once verified, evaluate what we learned for documentation. Apply these criteria yourself and tell the user your assessment.
+
+**ADR Evaluation** - Ask: "If we had this ADR before, would we have avoided the bug?"
+
+ADR-worthy patterns:
+- Guardrails: "Async handlers must await before updating UI state"
+- Conventions: "All API responses must include timestamp for cache busting"
+- Patterns: "Always invalidate cache after upload operations"
+
+Not ADR-worthy:
+- Typos or syntax errors
+- One-off logic errors with no generalizable lesson
+- Bugs in third-party code
+- Implementation details specific to this feature
+
+**CLAUDE.md Evaluation** - Ask: "Is this non-obvious knowledge that changes how someone works?"
+
+CLAUDE.md-worthy:
+- Gotchas discovered: "Must restart Claude Code after changing hooks"
+- Non-obvious behaviors: "API returns 200 even on validation failure"
+- Workflow patterns: "Always run migration before tests in this project"
+
+Not CLAUDE.md-worthy:
+- Standard practices obvious to any developer
+- Information already in README or package.json
+- One-time debugging steps
+
+**Present your assessment** - Tell the user what you found:
+
+```
+## Learnings Assessment
+
+**ADR**: [Your assessment - either "I identified a pattern worth documenting: [description]" OR "No ADR needed - this was [reason: typo/one-off/third-party bug/etc]"]
+
+**CLAUDE.md**: [Your assessment - either "I identified tribal knowledge worth capturing: [description]" OR "No CLAUDE.md update needed - [reason]"]
+```
+
+If user disagrees with your assessment, adjust accordingly.
+</step>
+
+<step name="Capture Learnings">
+Based on your assessment (adjusted for any user feedback):
+
+**If ADR identified:**
+```
+Spawn adr-agent: "Create an ADR for: [pattern]. Context from debugging [title]: Root cause was [hypothesis]. This pattern prevents [class of bugs]."
+```
+
+**If CLAUDE.md learning identified:**
+```
+Spawn claude-md-agent: "Add to CLAUDE.md: [learning]. Discovered while debugging [title]. This is non-obvious because [reason]."
+```
+
+**If neither identified:** Proceed directly to closing the session.
+</step>
+
+<step name="Close Debug Session">
+Update debug.yaml:
+
+```yaml
+status: closed
+
+resolution:
+  verified_by_user: true
+
+learning:
+  adr_created: ADR-[NNN]  # or null if none identified
+  claude_md_updated: true  # or false
+  summary: |
+    [What we learned]
+```
+
+Present closure:
+
+```
+## Debug Session Complete
+
+**Bug**: [title]
+**Status**: Fixed and verified
+**Test**: [test file] - serves as regression test
+**ADR**: [ADR-NNN created / None identified]
+**CLAUDE.md**: [Updated / No update needed]
+```
+
+```
+AskUserQuestion:
+Question: "Debug session complete. Anything else?"
+Options:
+- "All done" - Close out
+- "Start another debug" - I have another bug
+- "Something else" - Different feedback
+```
+</step>
+
+<checkpoint>
+Before closing:
+- User verified the fix works
+- Learnings assessment was presented (ADR and CLAUDE.md)
+- Any identified learnings were captured
+- debug.yaml status is closed
+</checkpoint>
+
+</steps>
+
+## Key Principles
+
+**User verification is required.** Tests passing doesn't mean the bug is fixed from the user's perspective.
+
+**Autonomous learning capture.** Evaluate learnings yourself using the criteria above. Tell the user what you identified and why - don't ask them to decide. They can override if they disagree.
+
+**ADRs prevent recurrence.** Document patterns that prevent classes of bugs. The key question: "If we had this ADR before, would we have avoided the bug?"
+
+**CLAUDE.md captures tribal knowledge.** Document gotchas and non-obvious behaviors discovered during debugging. The key question: "Would a future developer stumble on this same issue?"
+
+**Tests are regression protection.** Even without an ADR, the test protects against this specific bug recurring.

package/src/skills/orchestration/references/debugging/rca.md

@@ -0,0 +1,84 @@
+# Debugging Phase 2: Root Cause Analysis
+
+## Purpose
+
+Form a hypothesis about WHY the bug is happening. The hypothesis must be specific enough to verify with a test—if you can't write a test for it, it's too vague.
+
+**Success looks like**: A testable hypothesis is written to debug.yaml with a clear description, confidence level, and proposed test strategy.
+
+## What To Do
+
+<steps>
+
+<step name="Spawn RCA Agent">
+Spawn rca-agent to investigate and form a hypothesis:
+
+```
+Spawn rca-agent: "Investigate root cause for the debug at [debug-path]/debug.yaml."
+```
+
+The agent reads the debug context, explores relevant code, forms a hypothesis, writes it to debug.yaml, and returns with findings.
+</step>
+
+<step name="Review the Hypothesis">
+When the agent returns, check:
+
+- **Is it specific?** Can you imagine a test that would prove or disprove it?
+- **Does the test strategy make sense?** Is it clear what behavior to test?
+
+If too vague (e.g., "something is wrong with the cache"), spawn rca-agent again asking for more specificity.
+</step>
+
+<step name="Present to User">
+Once you have a testable hypothesis:
+
+```
+## Root Cause Hypothesis
+
+**Hypothesis**: [description]
+**Confidence**: [high/medium/low]
+**Evidence**: [what supports this]
+**Test Strategy**: [how we'll verify]
+```
+
+```
+AskUserQuestion:
+Question: "Does this hypothesis make sense? Ready to write a test?"
+Options:
+- "Yes, write the test" - Proceed to verification
+- "Investigate more" - Explore a different angle
+- "I have context" - Let me share what I know
+- "Something else" - Different feedback
+```
+</step>
+
+<step name="Handle User Feedback">
+- **"Yes, write the test"**: Proceed to verify phase
+- **"Investigate more"**: Ask what angle to explore, spawn rca-agent with that direction
+- **"I have context"**: Incorporate their knowledge—may confirm, redirect, or reveal the answer
+</step>
+
+<checkpoint>
+Before proceeding:
+- rca-agent was spawned and returned a hypothesis
+- Hypothesis is specific enough to test
+- User approved proceeding to verification
+</checkpoint>
+
+</steps>
+
+## Handling Previous Hypotheses
+
+If this isn't the first RCA iteration (previous hypothesis was disproven), the agent reads previous hypotheses from debug.yaml, understands why they were disproven, and forms a NEW hypothesis that accounts for what we learned.
+
+## Key Principles
+
+**Hypotheses must be testable.** If you can't describe a test that would verify it, push for specificity.
+
+**Build on evidence.** The hypothesis should come from actual code exploration, not guessing.
+
+**Trust the user's context.** They may have debugging context that isn't in the code.
+
+<transition>
+When the user approves the hypothesis and is ready to write a test, read `references/debugging/verify.md` to proceed.
+</transition>

package/src/skills/orchestration/references/debugging/verify.md

@@ -0,0 +1,95 @@
+# Debugging Phase 3: Verify
+
+## Purpose
+
+Write a failing test that proves the hypothesis. The test is the TDD gate—we don't fix code until we have a test that demonstrates the bug exists.
+
+**Success looks like**: A test exists that fails because of the bug. When the test passes later, we'll know the bug is fixed.
+
+## What To Do
+
+<steps>
+
+<step name="Spawn TDD Agent">
+Spawn tdd-agent to write a failing test for the hypothesis:
+
+```
+Spawn tdd-agent: "Write a failing test for the hypothesis in [debug-path]/debug.yaml."
+```
+
+The agent reads the debug context, writes an appropriate test, runs it, and updates the debug.yaml with the result.
+</step>
+
+<step name="Evaluate Result">
+The agent returns one of three outcomes:
+
+**Test FAILS (hypothesis verified)**:
+The bug exists and we can reproduce it. Present to user:
+
+```
+## Hypothesis Verified
+
+The test fails as expected, confirming the hypothesis.
+
+**Test**: [test file path]
+**Failure**: [what the test asserts that fails]
+
+Ready to fix the code.
+```
+
+```
+AskUserQuestion:
+Question: "Test fails as expected. Ready to fix the code?"
+Options:
+- "Yes, fix it" - Proceed to fix phase
+- "Let me review" - I want to see the test code first
+- "Something else" - Different feedback
+```
+
+**Test PASSES (hypothesis disproven)**:
+The hypothesis was wrong—the bug has a different cause. Present to user:
+
+```
+## Hypothesis Disproven
+
+The test passed, meaning the expected behavior works in this scenario.
+The hypothesis was incorrect—the bug has a different cause.
+
+**What we learned**: [what the passing test tells us]
+```
+
+```
+AskUserQuestion:
+Question: "The hypothesis was wrong. How should we proceed?"
+Options:
+- "Investigate again" - Back to RCA with new evidence
+- "I have an idea" - Let me share what I think is happening
+- "Something else" - Different approach
+```
+
+**Test ERRORS (test itself is broken)**:
+Work with the user to fix or rewrite the test, then re-run.
+</step>
+
+<checkpoint>
+Before proceeding:
+- tdd-agent was spawned and returned a result
+- Result was evaluated and presented to user
+- User has chosen how to proceed
+</checkpoint>
+
+</steps>
+
+## Key Principles
+
+**Tests check expected behavior, not implementation.** The test asserts what SHOULD happen, not how it happens internally.
+
+**Failing test = verified hypothesis.** A test that fails proves the bug exists.
+
+**Passing test = wrong hypothesis.** If the test passes, our understanding was incorrect—back to RCA.
+
+<transition>
+If hypothesis verified (test fails) and user approves: Read `references/debugging/fix.md`
+
+If hypothesis disproven (test passes) and user chooses to investigate: Read `references/debugging/rca.md`
+</transition>