cc-dev-template 0.1.1

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

@@ -0,0 +1,161 @@
+# 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.
+
+**Do the analysis:**
+1. **Read task outcomes** - Review what was done across all tasks
+2. **Look at code changes** - `git diff` against the base branch
+3. **Identify patterns** - Did we establish new patterns, architectures, or conventions?
+4. **Identify gotchas** - Did we discover non-obvious behaviors or workflow requirements?
+
+**ADR criteria** - Worth documenting if:
+- New architectural patterns ("We now use X for Y")
+- Design decisions with alternatives considered
+- Conventions established that future work should follow
+
+Not ADR-worthy: Bug fixes, implementation details, obvious choices
+
+**CLAUDE.md criteria** - Worth documenting if:
+- 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
+
+**Present your assessment and act on it:**
+
+```
+## Learnings Assessment
+
+**ADRs**: [Either "I identified patterns worth documenting: [list with brief reasons]. Creating ADRs now." OR "No architectural patterns emerged that warrant ADRs."]
+
+**CLAUDE.md**: [Either "I identified tribal knowledge worth capturing: [list]. Updating CLAUDE.md now." OR "No non-obvious knowledge discovered that warrants CLAUDE.md updates."]
+```
+
+**Then capture what you identified:**
+
+For each ADR identified:
+```
+Spawn adr-agent: "Create an ADR for: [pattern description and context]"
+```
+
+For CLAUDE.md learnings:
+```
+Spawn claude-md-agent: "Add to CLAUDE.md: [learning]. Discovered during [plan title]. This is non-obvious because [reason]."
+```
+
+If user disagrees with your assessment, adjust accordingly. But make your assessment and act - don't ask them to decide.
+</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

@@ -0,0 +1,66 @@
+# 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]."
+```
+
+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

@@ -0,0 +1,92 @@
+# 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]."
+```
+
+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: `"Fix these issues in task [task-id]: [issues]"`
+- The agent fixes and leaves status at `needs_review`
+- Next loop iteration will review again
+</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>

package/src/skills/orchestration/references/planning/draft.md

@@ -0,0 +1,195 @@
+# Planning Phase 3: Plan Drafting
+
+## Purpose
+
+Synthesize everything you've learned into a structured plan document. The plan becomes the single source of truth for this work—a contract between planning and execution.
+
+Someone should be able to read the plan and understand what's being built WITHOUT having been in the conversation. It captures requirements, context, constraints, and approach in one place.
+
+**Success looks like**: A plan.yaml file that's self-contained, realistic (informed by exploration), and actionable (can be decomposed into tasks).
+
+## The Right Level of Detail
+
+The plan is an **architecture document**, not a technical design document.
+
+**Include:**
+- What each component/module is responsible for (natural language)
+- Data models (structures, fields, relationships)
+- API contracts (what gets passed between components, inputs/outputs)
+- How pieces connect and communicate
+
+**Keep it at the architecture level.** Define the shape of the system—what exists, what it does, how pieces connect. Leave internal implementation details (function signatures, code snippets, specific algorithms) for execution.
+
+This level is right because:
+- It's enough to decompose into tasks during execution
+- It doesn't over-constrain implementation choices
+- It catches integration issues early (if contracts don't make sense, you find out now)
+- Stakeholders can review it and understand what's being built
+
+## What To Do
+
+Complete each step in order before proceeding to the next.
+
+<steps>
+
+<step name="Create the Plan Directory">
+Create a directory for this plan:
+
+```
+.claude/plans/[slug]/
+```
+
+The slug should be short, descriptive, kebab-case. Examples: `user-auth`, `api-rate-limiting`, `checkout-refactor`.
+</step>
+
+<step name="Write plan.yaml">
+Create `plan.yaml` in the plan directory. Pull together everything from requirements (Phase 1) and exploration (Phase 2).
+
+**Schema:**
+
+```yaml
+id: plan-[slug]
+title: [Descriptive title]
+type: feature | enhancement | refactor
+status: draft
+created: [YYYY-MM-DD]
+updated: [YYYY-MM-DD]
+
+problem_statement: |
+  [1-2 sentences: What problem are we solving? Why does it matter?]
+
+goals:
+  - [Goal 1]
+  - [Goal 2]
+
+success_criteria:
+  - [How we'll know it's done - criterion 1]
+  - [How we'll know it's done - criterion 2]
+
+# From exploration - where this fits in the codebase
+integration_points:
+  - component: [name]
+    interaction: [how this work interacts with it]
+    changes_required: [what needs to change]
+
+# Define the shape of data - structures, fields, relationships
+data_models:
+  - name: [Model name]
+    description: [What it represents]
+    fields:
+      - name: [field name]
+        type: [type]
+        description: [purpose]
+
+# Define how components communicate - inputs, outputs, contracts
+api_contracts:
+  - name: [Interface/endpoint name]
+    description: [What it does]
+    inputs: [What goes in]
+    outputs: [What comes out]
+    between: [Component A] -> [Component B]
+
+# ADRs that constrain this work
+relevant_adrs:
+  - id: ADR-[XXX]
+    title: [title]
+    constraint: [What this ADR requires us to do or avoid]
+```
+
+**Field guidance:**
+
+- **Required**: id, title, type, status, created, problem_statement, goals, success_criteria
+- **Include if relevant**: integration_points, data_models, api_contracts, relevant_adrs
+- **Only include fields that were discussed**: The plan reflects the conversation from Phases 1 and 2
+
+**Why no approach or risks?** The plan defines WHAT we're building, not HOW. The approach (phases, task breakdown) gets figured out during decomposition in execution. Risks emerge naturally during exploration or decomposition.
+</step>
+
+<step name="Present the Draft">
+Show the plan to the user. Highlight:
+- Key decisions made
+- How exploration findings shaped the approach
+- Any risks or concerns
+- Areas where you made judgment calls
+
+Summarize it in a readable format first, then offer to show the full plan.yaml if they want details.
+</step>
+
+<step name="Surface Ambiguities">
+**Before asking for approval, proactively identify what's unclear or unknown.**
+
+Ask yourself: "If I were to execute this plan right now, what information would I be missing? What decisions haven't been made?"
+
+Look for:
+- **Placeholder values**: Are there fields that say "TBD" or "[something]" that need real values?
+- **Implicit assumptions**: Did you assume something the user hasn't confirmed?
+- **Missing details**: Are there implementation choices that affect the plan but weren't discussed?
+- **Edge cases**: What happens when things go wrong or inputs are unexpected?
+- **Dependencies**: Are there external factors (APIs, data sources, other systems) with unknowns?
+
+**Present any ambiguities you find:**
+
+```
+## Potential Ambiguities
+
+Before we finalize this plan, I want to flag some things that might need clarification:
+
+1. **[Topic]**: [What's unclear and why it matters]
+2. **[Topic]**: [What's unclear and why it matters]
+
+Would you like to clarify these now, or are they acceptable unknowns?
+```
+
+If you find ambiguities, use AskUserQuestion to resolve them one at a time before proceeding.
+
+**If no ambiguities**: State that you reviewed the plan for unknowns and didn't find any that would block execution.
+</step>
+
+<step name="Iterate If Needed">
+The user may have feedback. If they want changes:
+- Update the plan.yaml
+- Re-present the updated version
+- Re-check for ambiguities
+- Repeat until they're satisfied
+
+Use AskUserQuestion to check:
+
+```
+AskUserQuestion:
+Question: "How does this plan look?"
+Options:
+- "Looks good" - Ready for validation
+- "Needs changes" - I'll explain what to adjust
+- "Let's discuss" - I have questions before deciding
+- "Start over" - This isn't the right direction
+```
+</step>
+
+<checkpoint>
+Before proceeding to the next phase:
+- Plan directory exists at .claude/plans/[slug]/
+- plan.yaml has been written with all required fields
+- Draft has been presented to user
+- Ambiguities have been surfaced and resolved (or explicitly accepted)
+- User has indicated they're satisfied with the draft
+</checkpoint>
+
+</steps>
+
+## Key Principles
+
+**Surface ambiguities proactively.** This is one of the most important things you can do when drafting a plan. Before asking "How does this look?", always ask yourself: "If I were to execute this, what information would I be missing?" Surface those unknowns and resolve them with the user. Ambiguity discovered during execution is expensive; ambiguity discovered during planning is cheap.
+
+**Keep implementation details for execution.** The plan stays at the architecture level—function signatures, code snippets, and library choices come later during task execution.
+
+**Define data models and contracts clearly.** When components pass data to each other, specify what that data looks like. Clear contracts prevent integration problems.
+
+**Match plan complexity to work complexity.** A simple enhancement gets a simple plan. Let the scope of the work determine the size of the document.
+
+**Include only what was discussed.** The plan reflects the conversation from Phases 1 and 2. Before adding anything, ask: "Did this come from our requirements or exploration?" If yes, include it. If you're inventing it, leave it out.
+
+The plan captures what the user asked for—goals, success criteria, data models, contracts. It stays focused on that.
+
+<transition>
+When the user is satisfied with the draft, read `references/planning/finalize.md` to validate against ADRs and get approval.
+</transition>

package/src/skills/orchestration/references/planning/explore.md

@@ -0,0 +1,129 @@
+# Planning Phase 2: Codebase Exploration
+
+## Purpose
+
+Ground the requirements in the reality of the codebase. You know WHAT you're building—now understand WHERE it fits and WHAT CONSTRAINTS exist.
+
+This is reconnaissance. You're gathering intelligence so the plan you write is realistic and informed, not wishful thinking that ignores how the codebase actually works.
+
+**Success looks like**: You understand the terrain well enough to write a plan with no surprises. You know the integration points, the patterns to follow, and the architectural constraints (ADRs) that apply.
+
+## What To Do
+
+Complete each step in order before proceeding to the next.
+
+<steps>
+
+<step name="Identify What You Need to Learn">
+Look at the requirements from Phase 1. Ask yourself:
+
+> "What do I need to understand about this codebase to write a realistic plan for this work?"
+
+This will vary based on the requirements. A new feature touching authentication needs different exploration than a refactor of the build system. Don't follow a checklist—think about what THIS specific work requires you to understand.
+
+Common things you might need to learn:
+- Where would this code live? What components/modules are involved?
+- What existing code would we integrate with or modify?
+- What patterns does this codebase use for similar functionality?
+- Are there conventions for testing, error handling, APIs, etc.?
+- What might make this tricky based on the current architecture?
+</step>
+
+<step name="Explore in Parallel">
+Use multiple Plan agents in parallel to explore different aspects of the codebase. Each agent should have a focused question to answer.
+
+**How to do this:**
+
+Spawn several Plan agents simultaneously, each with a specific exploration goal based on what you identified in Step 1. For example:
+
+```
+Agent 1: "Find where [feature area] is implemented. Identify the key files,
+         components, and how they interact."
+
+Agent 2: "Look at how similar functionality is implemented elsewhere in the
+         codebase. What patterns should we follow?"
+
+Agent 3: "Identify what would need to change to support [requirement].
+         What are the integration points?"
+```
+
+The specific agents you spawn depend on the requirements. Use your judgment—you know what you need to learn.
+</step>
+
+<step name="Find Relevant ADRs">
+While codebase exploration is happening, also spawn the adr-agent to find architectural constraints.
+
+```
+Spawn adr-agent: "Find ADRs that would be relevant to [summary of requirements].
+                  For each relevant ADR, explain why it matters and what
+                  constraints it imposes on this work."
+```
+
+ADRs discovered now will inform the plan you write. Better to know the rules before you design than to discover violations later.
+</step>
+
+<step name="Synthesize Findings">
+Once all agents return, synthesize what you learned into a coherent picture:
+
+```
+## Exploration Findings
+
+**Where this work fits:**
+[Which components/modules are involved]
+
+**Integration points:**
+[What existing code we'll touch or integrate with]
+
+**Patterns to follow:**
+[Conventions and patterns from the codebase we should match]
+
+**Relevant ADRs:**
+- [ADR-XXX]: [Why it matters, what it constrains]
+- [ADR-YYY]: [Why it matters, what it constrains]
+
+**Potential challenges:**
+[Anything that might make this tricky]
+```
+</step>
+
+<step name="Check for Gaps">
+Before moving on, ask yourself:
+
+> "Do I know enough to write a realistic plan?"
+
+If there are still unknowns that would affect the plan, explore further. If you're confident you understand the terrain, move on.
+
+You can also check with the user:
+
+```
+AskUserQuestion:
+Question: "I've explored the codebase. Ready to see what I found, or is there
+          something specific you want me to investigate first?"
+Options:
+- "Show me what you found" - Present the findings
+- "Also look into..." - I'll tell you what else to explore
+- "Let's move on" - Skip to drafting
+```
+</step>
+
+<checkpoint>
+Before proceeding to the next phase:
+- Codebase exploration agents have returned findings
+- ADR constraints have been identified
+- Findings have been synthesized and presented
+- No critical unknowns remain
+</checkpoint>
+
+</steps>
+
+## Key Principles
+
+**Gather information, save decisions for later.** You're exploring, not designing. Note what you find; implementation decisions come during drafting.
+
+**Stay focused on this work.** Explore what's relevant to the requirements. A targeted investigation beats a comprehensive codebase tour.
+
+**Find ADRs early.** Architectural constraints discovered now save expensive rework later. Include them in your exploration.
+
+<transition>
+When you have a clear picture of where this work fits, what patterns to follow, and what ADRs constrain it, read `references/planning/draft.md` to continue to plan drafting.
+</transition>