cc-dev-template 0.1.32 → 0.1.33

package/src/skills/orchestration/SKILL.md

@@ -1,161 +0,0 @@
----
-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/skills/orchestration/scripts/plan-status.js
-```
-
-This returns a list of plans with their current status (draft, approved, in_progress, completed).
-</step>
-
-<step name="Detect Submodule Context">
-Detect whether you're operating in a git submodule environment. Run these commands:
-
-```bash
-# Check if we're inside a submodule (returns parent path if yes, empty if no)
-git rev-parse --show-superproject-working-tree 2>/dev/null
-
-# List submodules if this repo has any
-git submodule status 2>/dev/null
-```
-
-Build a SubmoduleContext from the results:
-
-```
-SubmoduleContext:
-  isInSubmodule: boolean     # true if superproject path is non-empty
-  hasSubmodules: boolean     # true if submodule status returns entries
-  parentRepoPath: string     # absolute path to parent repo (if isInSubmodule)
-  submodulePaths: string[]   # relative paths of submodules (if hasSubmodules)
-  currentSubmodulePath: string  # path of current submodule relative to parent
-```
-
-Store this context for use by workflow phases. When spawning sub-agents, pass relevant context so they can:
-- Use `--include-parent` flag with adr-list.js when in a submodule
-- Understand which submodules are available for plan scope
-- Filter ADRs by scope when working on submodule-specific plans
-
-This detection happens once at startup. Individual CLI scripts can also detect submodule context when called standalone, but when orchestrating, pass the context you've already gathered.
-</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
-
-**Use this skill's planning workflow, not built-in plan mode.** This skill provides its own structured planning phases (start → explore → draft → finalize). Use these workflow files for all planning work. The built-in `EnterPlanMode` tool is for ad-hoc work outside this framework.
-
-**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]/`. Also pass SubmoduleContext to workflow phases when relevant.
-
-**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.
-
-**Explore facts, ask preferences.** Discover codebase state (what exists, how things work) through exploration. Ask users only what they alone can answer: goals, preferences, decisions, and success criteria.
-
-## 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

@@ -1,144 +0,0 @@
-# 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.md` 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].
-
-Submodule context: [pass SubmoduleContext from SKILL.md]
-
-Use --include-parent with adr-list.js to discover both local and
-inherited ADRs. Bugs may relate to patterns established at the
-parent repo level."
-```
-</step>
-
-<step name="Create the Debug Artifact">
-Create `.claude/debug/[slug]/debug.md` with YAML frontmatter and Markdown body:
-
-```markdown
----
-status: investigating
-title: "[Short description]"
-created: [today's date]
----
-
-# Debug: [Short description]
-
-## Symptom
-
-[What the user described]
-
-## Expected Behavior
-
-[What should happen instead]
-
-## Baseline
-
-- **Test command**: [command]
-- **Result**: pass
-- **Summary**: [X tests passed]
-
-## Relevant ADRs
-
-- **ADR-[XXX]**: [Why it matters] (source: local or inherited)
-
-## Submodule Context
-
-*Include if SubmoduleContext is relevant*
-
-- **Is in submodule**: [boolean]
-- **Current submodule path**: [path if applicable]
-
-## Hypotheses
-
-*None yet - will be added during RCA phase*
-```
-
-**Note**: For backward compatibility, if you encounter an existing `debug.yaml` file, continue working with that format. New debug sessions should use the `debug.md` format.
-</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.md 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.md.** 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

@@ -1,117 +0,0 @@
-# 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.md.
-
-Submodule context: [pass SubmoduleContext from SKILL.md or from debug.md]
-
-If the fix is in a submodule, work within that submodule's directory.
-The fix should be scoped to the appropriate submodule."
-```
-
-The agent reads the debug context, fixes the code without modifying test files, runs the test, and updates the debug.md artifact with the result.
-
-**Note**: For backward compatibility, if the debug artifact is `debug.yaml` instead of `debug.md`, continue working with that format.
-</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 the debug artifact.
-
-**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 the debug.md artifact by adding a Resolution section:
-
-```markdown
-## Resolution
-
-**Hypothesis fixed**: h[N]
-
-**Description**: [What was fixed and why]
-
-**Files changed**:
-- [list of modified files]
-```
-
-Also update the hypothesis status in the Hypotheses section to mark it as fixed.
-
-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.md 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.** The debug artifact 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

@@ -1,185 +0,0 @@
-# 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].
-
-Submodule context: [pass SubmoduleContext from SKILL.md or from debug.md]
-
-If this ADR applies only to specific submodules, set the scope field.
-If the bug was discovered while working in a submodule, consider whether
-the pattern applies globally or only to that submodule."
-```
-
-**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 this learning is specific to a submodule, consider whether it
-belongs in the submodule's CLAUDE.md or the root CLAUDE.md."
-```
-
-**If neither identified:** Proceed directly to closing the session.
-</step>
-
-<step name="Close Debug Session">
-Update the debug.md artifact. Change the status in the frontmatter to `closed` and add a Learning section:
-
-```markdown
----
-status: closed
-title: "[Short description]"
-created: [original date]
----
-
-...existing content...
-
-## Learning
-
-- **ADR created**: ADR-[NNN] (or "None identified")
-- **ADR scope**: [submodule paths if scoped, or "global"]
-- **CLAUDE.md updated**: Yes/No
-- **CLAUDE.md location**: root (or submodule path)
-
-**Summary**: [What we learned]
-
-## Resolution
-
-...existing resolution content...
-
-- **Verified by user**: Yes
-```
-
-**Note**: For backward compatibility, if the debug artifact is `debug.yaml` instead of `debug.md`, continue working with that format.
-
-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.md 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

@@ -1,92 +0,0 @@
-# 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 the debug.md artifact 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.md.
-
-Submodule context: [pass SubmoduleContext from SKILL.md or from debug.md]
-
-If debugging in a submodule, the bug may relate to inherited ADRs
-or patterns from the parent repo. Check debug.md for submodule_context
-to understand the scope of investigation."
-```
-
-The agent reads the debug context, explores relevant code, forms a hypothesis, writes it to the debug.md artifact, 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 the debug.md artifact, understands why they were disproven, and forms a NEW hypothesis that accounts for what we learned.
-
-**Note**: For backward compatibility, if the debug artifact is `debug.yaml` instead of `debug.md`, continue working with that format.
-
-## 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>