cc-dev-template 0.1.32 → 0.1.34

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

@@ -1,102 +0,0 @@
-# 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.md.
-
-Submodule context: [pass SubmoduleContext from SKILL.md or from debug.md]
-
-If the bug is in a submodule, ensure the test is created in the
-appropriate test directory for that submodule."
-```
-
-The agent reads the debug context, writes an appropriate test, runs it, 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="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>

package/src/skills/orchestration/references/execution/complete.md

@@ -1,175 +0,0 @@
-# Execution Phase 3: Complete
-
-## Purpose
-
-Verify the work, capture any new patterns as ADRs, and get human approval before closing out the plan.
-
-**Success looks like**: Tests pass, code compiles, new patterns are documented, user approves, plan marked complete.
-
-## What To Do
-
-Complete each step in order before proceeding to the next.
-
-<steps>
-
-<step name="Automated Verification">
-Run the project's verification suite:
-
-1. **Tests** - Run all tests (whatever "all tests" means for this project)
-2. **Compile/Build** - Ensure everything compiles with no errors or warnings
-3. **Lint** - Run any linters if the project uses them
-
-Figure out what's appropriate for the project.
-
-**If verification fails:** Identify which task caused the failure and spawn an execution-agent to fix it. Provide the error output and task context. Re-run verification after the fix. Repeat until all checks pass.
-</step>
-
-<step name="Capture New Patterns">
-Before human review, analyze the work for architectural decisions and tribal knowledge worth documenting.
-
-**1. Collect ADR candidates from task outcomes:**
-
-Read each task's outcome field and extract any `adr_candidates` that were flagged during execution. These are decisions the execution agents already identified as potentially ADR-worthy.
-
-**2. Apply the ADR checklist:**
-
-For each task outcome AND for the overall implementation, check:
-- [ ] Did we choose between multiple valid approaches? (e.g., "used X instead of Y because...")
-- [ ] Did we establish a pattern future work should follow? (e.g., "all API calls go through...")
-- [ ] Did we constrain how something should/shouldn't be done? (e.g., "never do X because...")
-- [ ] Did we deviate from or extend an existing ADR?
-
-If any checkbox applies, it's an ADR candidate.
-
-**3. Apply CLAUDE.md criteria:**
-
-- Non-obvious gotchas discovered during implementation
-- Workflow patterns specific to this project
-- Behaviors that would trip up a future developer
-
-Not CLAUDE.md-worthy: Standard practices, info already in docs, obvious behaviors
-
-**4. Present ADR candidates for user confirmation:**
-
-If you identified ADR candidates (from task outcomes or your analysis):
-
-```
-## ADR Candidates
-
-These decisions from this work might warrant ADRs:
-
-1. **[Brief title]**: [One sentence describing the decision and why it matters]
-2. **[Brief title]**: [One sentence describing the decision and why it matters]
-
-Which should we codify as ADRs? Enter numbers (e.g., "1, 2"), "all", or "none".
-```
-
-Wait for user response before creating any ADRs. They choose which decisions become permanent rules.
-
-**5. Capture what was approved:**
-
-For each ADR the user approved:
-```
-Spawn adr-agent: "Create an ADR for: [pattern description and context]
-
-Submodule context: [pass SubmoduleContext from SKILL.md]
-If this ADR applies only to specific submodules, set the scope field
-to list those submodule paths."
-```
-
-For CLAUDE.md learnings (these don't need user approval—use your judgment):
-```
-Spawn claude-md-agent: "Add to CLAUDE.md: [learning]. Discovered during [plan 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."
-```
-</step>
-
-<step name="Present Summary for Human Review">
-Summarize what was accomplished:
-
-```
-## Plan Complete: [plan title]
-
-**Tasks completed**: [N]
-
-### What Was Built
-- [Key accomplishment from task outcomes]
-- [Another accomplishment]
-
-### Files Changed
-[List notable files or run `git diff --stat`]
-
-### Tests
-[Test results summary]
-
-### Ready for Review
-Please review the implementation. Check for:
-- Bugs or issues
-- Manual testing needed
-- Anything that doesn't look right
-```
-</step>
-
-<step name="Get Approval">
-```
-AskUserQuestion:
-Question: "Does everything look good?"
-Options:
-- "Approved" - Mark plan complete
-- "Found issues" - Let's fix them together
-- "Need more time" - I'll review and get back to you
-```
-
-**If approved:**
-- Update `plan.yaml`: `status: completed`, `completed: [today's date]`
-- Confirm: "Plan [title] is complete. Run /prime when you have new work."
-
-**If issues found:**
-
-The orchestrator coordinates work—it gathers information and delegates to execution agents. Follow this flow:
-
-1. **Understand the issue** - Ask the user to describe what's wrong. Get specific details: what they expected, what actually happened, which files/features are affected.
-
-2. **Identify the responsible task** - Determine which task from the plan relates to this issue. Check the task manifest for context.
-
-3. **Delegate the fix** - Spawn an execution-agent with clear context:
-   ```
-   Spawn execution-agent:
-   "Fix issue in [task ID]: [Issue description from user]
-
-   Context:
-   - What was expected: [user's expectation]
-   - What actually happened: [observed behavior]
-   - Relevant files: [files if known]
-
-   The task manifest is at: [path to manifest]
-   Review your original implementation and fix the issue."
-   ```
-
-4. **Re-run verification** - After the fix, run tests/build/lint again
-
-5. **Return to approval** - Present updated summary and ask for approval again
-</step>
-
-<checkpoint>
-Before closing out:
-- Automated verification passed (tests, build, lint)
-- Learnings assessment was presented (ADR and CLAUDE.md)
-- Any identified learnings were captured
-- Summary was presented to user
-- User approved the work
-</checkpoint>
-
-<step name="Close Out">
-Final state:
-- `plan.yaml` has `status: completed`
-- All tasks have `status: completed` in manifest
-- Any new ADRs are created
-- User has approved
-</step>
-
-</steps>
-
-This is the final phase. The workflow ends here.

package/src/skills/orchestration/references/execution/start.md

@@ -1,77 +0,0 @@
-# Execution Phase 1: Start
-
-## Purpose
-
-Load the approved plan and decompose it into executable tasks. This bridges planning (what to build) and execution (doing the work).
-
-**Success looks like**: Task files exist with clear completion criteria, correct dependencies, and appropriate ADR mapping—ready for the execution loop.
-
-## What To Do
-
-Complete each step in order before proceeding to the next.
-
-<steps>
-
-<step name="Load the Plan">
-Read the plan at the path provided (or discovered by SKILL.md):
-
-```
-.claude/plans/[slug]/plan.yaml
-```
-
-If status is not `approved`, tell the user:
-
-> "This plan hasn't been approved yet. Run /prime to complete planning first."
-</step>
-
-<step name="Decompose">
-Spawn the decomposition-agent to break the plan into tasks:
-
-```
-Spawn decomposition-agent: "Decompose the plan at [plan-path].
-
-Submodule context: [pass SubmoduleContext from SKILL.md]
-
-If the plan has affected_submodules, consider submodule scope when:
-- Creating tasks that target specific submodules
-- Assigning ADRs to tasks (include both local and inherited ADRs)
-- Describing where work should happen
-
-Tasks should include submodule context in their descriptions when
-the work targets specific submodules. This helps execution agents
-work in the correct directory scope."
-```
-
-The agent reads the plan, creates task files, and returns a summary.
-</step>
-
-<step name="Review">
-Spawn the decomposition-agent again to review the decomposition:
-
-```
-Spawn decomposition-agent: "Review the decomposition at [plan-dir]."
-```
-
-The agent checks coverage, dependencies, ADR mapping, and criteria specificity.
-</step>
-
-<step name="Iterate">
-If review returns issues:
-1. Spawn decomposition-agent to fix the specific issues
-2. Review again
-3. Repeat until review returns `APPROVED`
-</step>
-
-<checkpoint>
-Before proceeding to task execution:
-- Plan has been loaded and verified as approved
-- decomposition-agent has created task files
-- decomposition-agent has reviewed and approved the decomposition
-- manifest.yaml exists with all tasks listed
-</checkpoint>
-
-</steps>
-
-<transition>
-Once decomposition is approved, read `references/execution/tasks.md` to begin the execution loop.
-</transition>

package/src/skills/orchestration/references/execution/tasks.md

@@ -1,114 +0,0 @@
-# Execution Phase 2: Tasks
-
-## Purpose
-
-Execute and review tasks until all are complete. Tasks run in parallel where dependencies allow, with a review step to verify each task meets its criteria.
-
-**Success looks like**: All tasks have `status: completed` in the manifest.
-
-## What To Do
-
-Execute the following loop until all tasks are complete.
-
-<steps>
-
-<step name="Find Executable Tasks">
-Read `manifest.yaml`. Find tasks where:
-- `status: pending`
-- All `dependencies` have `status: completed`
-
-These can all be executed in parallel.
-</step>
-
-<step name="Execute">
-For each executable task, spawn execution-agent:
-
-```
-Spawn execution-agent: "Implement task [task-id] at [task-path].
-
-Submodule context: [pass SubmoduleContext from SKILL.md if relevant]
-
-If the task targets a specific submodule, work within that directory.
-Use --include-parent with adr-list.js to discover inherited ADRs
-when validating against architectural constraints."
-```
-
-The agent reads the task, does the work, writes the outcome, and updates status to `needs_review`.
-
-Execute all ready tasks in parallel.
-</step>
-
-<step name="Find Reviewable Tasks">
-Read `manifest.yaml` again. Find tasks where:
-- `status: needs_review`
-</step>
-
-<step name="Review">
-For each reviewable task, spawn execution-agent:
-
-```
-Spawn execution-agent: "Review task [task-id] at [task-path]."
-```
-
-The agent verifies each `done_when` criterion. If all pass, it updates status to `completed`. If issues found, it returns the list of problems.
-
-Review all ready tasks in parallel.
-</step>
-
-<step name="Handle Issues">
-If any review returns issues:
-
-Spawn execution-agent to fix with ADR re-validation instruction:
-
-```
-Spawn execution-agent: "Fix these issues in task [task-id]: [issues]
-
-IMPORTANT - Before implementing any fix:
-1. Re-read all ADRs in this task's relevant_adrs
-2. Ensure your fix doesn't violate any ADR constraints
-3. ADR violations are BLOCKING - if the fix would violate an ADR,
-   you MUST escalate instead of proceeding. ADRs are gospel.
-4. Check the plan's ADR Exceptions section - if an ADR is listed there,
-   deviation is acceptable (but document you relied on the exception)
-
-The task manifest is at: [path to manifest]"
-```
-
-- The agent re-reads ADRs, fixes the issues, and leaves status at `needs_review`
-- Next loop iteration will review again (including ADR compliance check)
-</step>
-
-<step name="Continue">
-Return to the first step. Find next batch of executable tasks.
-
-Repeat until `manifest.yaml` shows all tasks with `status: completed`.
-</step>
-
-</steps>
-
-## Handling Escalation
-
-If an execution agent escalates (ADR conflict, invalid assumption, blocked), stop the loop and present to the user:
-
-```
-AskUserQuestion:
-Question: "Task [id] hit an issue: [description]. How should we proceed?"
-Options:
-- "Help me resolve it" - I'll provide guidance
-- "Skip this task" - Mark blocked, continue with others
-- "Stop execution" - Let's figure this out first
-```
-
-After resolving, resume the loop.
-
-## Key Points
-
-**Parallel execution** - Run all independent tasks at once. Don't serialize unnecessarily.
-
-**Fresh context per spawn** - Each agent spawn is stateless. The task file contains everything it needs.
-
-**Agents update status** - Execute agent sets `needs_review`, review agent sets `completed`. Orchestrator just reads manifest to find what's ready.
-
-<transition>
-When all tasks show `status: completed` in the manifest, read `references/execution/complete.md` to finish.
-</transition>