cc-dev-template 0.1.31 → 0.1.33

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

@@ -1,269 +0,0 @@
-# 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.md 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.md">
-Create `plan.md` in the plan directory. Pull together everything from requirements (Phase 1) and exploration (Phase 2).
-
-**Format:** Markdown with YAML frontmatter. The frontmatter contains minimal metadata (status, title, created). The Markdown body contains the plan content.
-
-**Note on backward compatibility:** Existing plan.yaml files continue to work. The plan-status.js script supports both formats, preferring plan.md when present.
-
-**Schema:**
-
-```markdown
----
-status: draft
-title: [Descriptive title]
-created: [YYYY-MM-DD]
----
-
-# [Plan Title]
-
-## 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]
-
-## Integration Points
-
-From exploration - where this fits in the codebase.
-
-| Component | Interaction | Changes Required |
-|-----------|-------------|------------------|
-| [name] | [how this work interacts with it] | [what needs to change] |
-
-## Data Models
-
-Define the shape of data - structures, fields, relationships.
-
-### [Model name]
-
-[What it represents]
-
-| Field | Type | Description |
-|-------|------|-------------|
-| [field name] | [type] | [purpose] |
-
-## API Contracts
-
-Define how components communicate - inputs, outputs, contracts.
-
-### [Interface/endpoint name]
-
-[What it does]
-
-- **Inputs**: [What goes in]
-- **Outputs**: [What comes out]
-- **Between**: [Component A] -> [Component B]
-
-## Relevant ADRs
-
-ADRs that constrain this work.
-
-| ADR | Title | Constraint |
-|-----|-------|------------|
-| ADR-[XXX] | [title] | [What this ADR requires us to do or avoid] |
-
-## ADR Exceptions
-
-Intentional deviations from ADRs for this specific work. ADRs are gospel by default—exceptions must be explicitly acknowledged here with a reason.
-
-| ADR | Reason for Exception |
-|-----|---------------------|
-| [ADR-XXX] | [Why this work intentionally deviates from this ADR] |
-
-_If no exceptions, omit this section entirely._
-
-## Affected Submodules
-
-Submodules affected by this work (for repos with git submodules).
-
-| Path | Reason |
-|------|--------|
-| [relative/path/to/submodule] | [Why this submodule is affected by the plan] |
-```
-
-**Section guidance:**
-
-- **Required in frontmatter**: status, title, created
-- **Required sections**: Problem Statement, Goals, Success Criteria
-- **Include if relevant**: Integration Points, Data Models, API Contracts, Relevant ADRs, Affected Submodules
-- **Include if intentionally deviating from ADRs**: ADR Exceptions (document the reason for each deviation)
-- **Only include sections that were discussed**: The plan reflects the conversation from Phases 1 and 2
-
-**ADR Exceptions section:**
-
-ADRs are gospel by default—when an ADR says "don't do X", it should be impossible for X to reach production. However, intentional, documented deviations are acceptable when the exception is explicitly acknowledged during planning.
-
-Include this section when:
-- An ADR tension was surfaced during planning and the user consciously decided to deviate
-- The deviation applies only to this specific work (not a general change to the ADR)
-- The reason for the exception is clear and documented
-
-If no ADR exceptions exist, omit the section entirely. The presence of the section signals that execution agents should check it before flagging ADR violations—an ADR listed here is not a violation for this plan, but should still be documented in task outcomes as "relying on acknowledged exception."
-
-**Affected Submodules section:**
-
-Include this section when working in repositories with git submodules and the plan's scope touches specific submodules. This enables scope-aware ADR discovery—the adr-agent can filter to only show ADRs that are either global or scoped to the affected submodules.
-
-Use SubmoduleContext (from SKILL.md startup) to know which submodules exist:
-- `submodulePaths` lists all available submodules in the repo
-- If `isInSubmodule` is true, you're working inside a submodule (may want to target just the current one)
-
-Table columns:
-- **Path** (required): Relative path to the submodule, matching what appears in `.gitmodules`
-- **Reason** (optional): Brief explanation of why this submodule is affected by the plan
-
-Example:
-```markdown
-## Affected Submodules
-
-| Path | Reason |
-|------|--------|
-| packages/auth | Adding new authentication method |
-| packages/shared | Shared types need updating for new auth flow |
-```
-
-When a plan declares affected submodules, ADRs scoped to those submodules become relevant, while ADRs scoped to unaffected submodules can be filtered out. ADRs with no scope field are always treated as global and remain relevant regardless of which submodules are affected.
-
-**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.md 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.md
-- 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.md has been written with all required sections
-- 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

@@ -1,160 +0,0 @@
-# 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">
-Spawn multiple Task agents (subagent_type="Plan") in parallel to explore different aspects of the codebase. Each agent should have a focused question to answer.
-
-**How to do this:**
-
-Use the Task tool with subagent_type="Plan" to spawn several 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.
-
-                  Submodule context: [pass SubmoduleContext from SKILL.md if available]
-                  Affected submodules: [list from requirements, if identified]
-
-                  Use --include-parent flag with adr-list.js to discover both
-                  local and inherited ADRs. Filter results by scope when specific
-                  submodules are targeted."
-```
-
-ADRs discovered now will inform the plan you write. Better to know the rules before you design than to discover violations later.
-
-**For submodule-aware discovery:**
-- Pass SubmoduleContext so the agent knows if you're in a submodule
-- If in a submodule, inherited ADRs from the parent repo may apply
-- Scope-aware discovery surfaces the most relevant ADRs while filtering out ADRs that only apply to other submodules
-- The adr-agent uses `--include-parent` to find both local and inherited ADRs
-</step>
-
-<step name="Synthesize Findings">
-Once all agents return, synthesize what you learned into a coherent picture.
-
-**Critical: Validate exploration findings against ADRs.**
-
-ADRs are gospel—before moving to plan drafting, ensure the exploration findings don't suggest approaches that violate ADRs:
-
-1. Review each ADR discovered by adr-agent
-2. Check if any exploration finding conflicts with an ADR constraint
-3. If conflict found:
-   - Note it in "ADR tensions" below
-   - Surface to user before proceeding—they may need to choose between approaches or acknowledge an exception
-
-```
-## 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] (source: local/inherited)
-- [ADR-YYY]: [Why it matters, what it constrains] (source: local/inherited)
-
-**ADR tensions (if any):**
-- [Describe any conflicts between exploration findings and ADR constraints]
-- [Note: These must be resolved before drafting—either adjust approach or acknowledge exception]
-
-**Potential challenges:**
-[Anything that might make this tricky]
-```
-
-If you identified ADR tensions, use AskUserQuestion to resolve them now:
-```
-AskUserQuestion:
-Question: "The exploration suggests [approach], but this conflicts with ADR-XXX which says [constraint]. How should we proceed?"
-Options:
-- "Follow the ADR" - Adjust our approach to comply
-- "Exception for this work" - Document why we're deviating
-- "Update the ADR" - The ADR is outdated
-```
-</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:
-- **Codebase facts** (what exists, how it works) → Explore more. Spawn additional agents to investigate.
-- **User intent** (goals, preferences, decisions) → Ask the user.
-
-Explore until you understand the terrain, then present your findings and move on.
-</step>
-
-<checkpoint>
-Before proceeding to the next phase:
-- Codebase exploration agents have returned findings
-- ADR constraints have been identified
-- Findings have been validated against ADRs (no unresolved tensions)
-- Any ADR tensions have been surfaced to user and resolved (adjust approach, document exception, or update ADR)
-- 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>

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

@@ -1,184 +0,0 @@
-# Planning Phase 4: Finalize
-
-## Purpose
-
-Validate the plan against architectural constraints and get user approval. This is the last step before the plan is ready for the execution workflow.
-
-Validation catches ADR conflicts while they're cheap to fix. Approval ensures the user agrees with what's about to be built.
-
-**Success looks like**: The plan complies with all relevant ADRs, the user has approved it, and it's ready for the execution workflow.
-
-## What To Do
-
-Complete each step in order before proceeding to the next.
-
-<steps>
-
-<step name="Validate Against ADRs">
-Spawn the adr-agent to validate the plan. The agent will:
-- Read the plan.md (or plan.yaml for backward compatibility)
-- Find ALL ADRs that might be relevant (not just the ones declared in the plan)
-- Use `--include-parent` flag to discover both local AND inherited ADRs
-- Use the plan's Affected Submodules section for scope-aware filtering
-- Check compliance for each: COMPLIANT, TENSION, or CONFLICT
-- Report what needs attention
-
-```
-Spawn adr-agent: "Validate the plan at .claude/plans/[slug]/plan.md.
-
-Find all ADRs that could be relevant to this work—check beyond what's
-declared in the plan's Relevant ADRs section. Better to surface extra
-ADRs than miss important ones.
-
-Submodule context: [pass SubmoduleContext from SKILL.md]
-
-Use --include-parent flag with adr-list.js to discover both local
-and inherited ADRs. When in a submodule, parent repo ADRs may impose
-constraints on this work.
-
-Use the plan's Affected Submodules section to focus on ADRs that apply
-to the relevant submodules. Global ADRs always apply; submodule-scoped
-ADRs only apply when their scope matches the affected submodules.
-
-Apply precedence rules: local ADRs override inherited ADRs on the same topic.
-
-For each relevant ADR, report:
-- COMPLIANT: Plan follows this ADR
-- TENSION: Potential friction, worth noting
-- CONFLICT: Plan violates this ADR, must resolve
-- Source: local or inherited
-
-Note in the report when ADRs were filtered by scope or are inherited."
-```
-
-**Show the validation report to the user** before proceeding.
-</step>
-
-<step name="Handle Validation Results">
-**If all COMPLIANT (or only TENSION):**
-- Note any tensions for awareness
-- Proceed to user approval
-
-**If CONFLICT found:**
-- Present the conflicts to the user clearly
-- For each conflict, explain:
-  - Which ADR is violated
-  - What the ADR requires
-  - How the plan conflicts
-- Work with the user to resolve:
-  - Adjust the plan to comply
-  - Or discuss whether the ADR needs updating (spawn adr-agent to supersede if so)
-- Re-validate after changes
-
-Use AskUserQuestion to discuss conflicts:
-
-```
-AskUserQuestion:
-Question: "The plan conflicts with [ADR-XXX]. How should we resolve this?"
-Options:
-- "Adjust the plan" - I'll describe what to change
-- "The ADR is outdated" - Let's update or supersede the ADR
-- "Let's discuss" - I need more context before deciding
-- "Something else" - I have a different approach
-```
-
-Iterate until validation passes (no CONFLICT items).
-</step>
-
-<checkpoint>
-Before proceeding to approval:
-- adr-agent was spawned and returned results
-- Validation report was shown to user
-- Any CONFLICT items have been resolved
-</checkpoint>
-
-<step name="Present Final Plan">
-Once validation passes, present the plan summary to the user:
-
-```
-## Plan Ready for Approval
-
-**Title**: [plan title]
-**Type**: [feature / enhancement / refactor]
-
-**Problem**: [1-2 sentence summary]
-
-**Goals**:
-- [Goal 1]
-- [Goal 2]
-
-**Success Criteria**:
-- [Criterion 1]
-- [Criterion 2]
-
-**Key Components**:
-- [Data models, API contracts, integration points - high level]
-
-**Relevant ADRs**: [list with compliance status]
-
-The plan has been validated against architectural constraints.
-```
-</step>
-
-<step name="Get Approval">
-Use AskUserQuestion to get explicit approval:
-
-```
-AskUserQuestion:
-Question: "Approve this plan?"
-Options:
-- "Approved" - Mark as approved
-- "Needs changes" - I'll explain what to adjust
-- "Let's discuss first" - I have questions
-```
-
-**If approved:**
-1. Update plan.md frontmatter: `status: approved`
-2. Optionally add an `updated: [today's date]` field to the frontmatter
-
-**If changes requested:**
-- Make the requested changes
-- Re-validate if changes affect ADR compliance
-- Present again and get approval
-</step>
-
-<checkpoint>
-Before proceeding to execution handoff:
-- Plan summary was presented to user
-- User explicitly selected "Approved"
-- plan.md frontmatter status is now `approved`
-</checkpoint>
-
-<step name="Offer Next Steps">
-Ask what the user wants to do next:
-
-```
-AskUserQuestion:
-Question: "Plan approved. What's next?"
-Options:
-- "Start the execution workflow" - Proceed to decomposition phase
-- "Stop here for now" - Save and exit
-```
-
-**If "Start the execution workflow":**
-Read `references/execution/start.md` to begin. The execution workflow starts with decomposition—breaking the plan into tasks. Agents handle implementation; you orchestrate.
-
-**If "Stop here for now":**
-End with: "Plan saved and approved. Run `/prime` when you're ready to start the execution workflow."
-</step>
-
-</steps>
-
-## Key Principles
-
-**Validate thoroughly.** The adr-agent should find ADRs beyond what's declared. Missing a relevant ADR now means discovering violations during execution.
-
-**Resolve conflicts before approval.** A plan with known ADR conflicts shouldn't be approved. Either fix the plan or update the ADR.
-
-**Get explicit approval.** The plan represents a commitment. Make sure the user consciously agrees before marking it approved.
-
-**Approval and next steps are separate decisions.** Get approval first. Then ask about execution. Don't combine these into one question.
-
-<transition>
-When the user chooses to start execution, read `references/execution/start.md` to begin the execution workflow.
-</transition>