set-copilot: Skill for Claude Code

Decompose a specification document into an orchestration execution plan.

Input: Spec file path (provided as argument or via environment SPEC_PATH), optional phase hint via PHASE_HINT.

You are a planning agent. Your job is to analyze a spec document, explore the codebase, and produce an orchestration-plan.json that the orchestrator can dispatch.

Steps

1. Read the spec

   • If SPEC_PATH is a directory (multi-file spec):
     • Read the master file first (matching v*-*.md or README.md at root level)
     • Use the Agent tool (Explore) to analyze domains in parallel — one agent per subdirectory
     • Each agent should return: domain summary, key requirements, cross-references to other domains
     • Combine results into a unified view before decomposing
   • If SPEC_PATH is a single file:
     • If under 200 lines, read it directly
     • If over 200 lines, use the Agent tool (Explore) to analyze sections — do NOT load the entire spec into context
   • Identify completed items (checkboxes, "done" markers) and focus on incomplete work

2. Read project context (if files exist, skip gracefully if not)

   • set/plugins/project-type.yaml — verification rules, conventions, project type
   • set/knowledge/project-knowledge.yaml — cross-cutting files, feature registry
   • set/requirements/*.yaml — active requirements (status: captured or planned)
   • set/orchestration/config.yaml or .claude/orchestration.yaml — directives

   2b. Read design-manifest.yaml (v0 pipeline) — if docs/design-manifest.yaml exists

   • Load every route's path + scope_keywords into planning context
   • The manifest is the AUTHORITATIVE route inventory: every route MUST be accounted for in the plan
   • If no docs/design-manifest.yaml exists, skip this step + INFO log; the plan proceeds design-unaware (legacy mode)

3. Explore the codebase

   • Use the Agent tool (Explore) to scan for existing implementations matching spec topics
   • Understand what's already built vs what needs to be built
   • Identify shared files that multiple changes would touch (merge hazard)
   • Run multiple Explore agents in parallel for different spec sections

4. Recall relevant memories

   set-memory recall "<spec topic>" --tags "phase:planning" --limit 3 --mode hybrid
   

   Use the recall MCP tool with phase:planning tag. Look for past decomposition learnings, known pitfalls.

5. Check existing work

   openspec list --json
   

   List existing specs and active changes to avoid duplication.

6. Bind design-manifest routes to changes (v0 pipeline) — skip if docs/design-manifest.yaml was absent in step 2b

   • Every manifest route MUST end up in EITHER exactly one change's design_routes: ["/…"] OR the plan-level deferred_design_routes: [{route, reason}] list
   • A change without UI has design_routes: [] (explicit empty list)
   • When spec mentions UI for a page with no matching manifest route, emit a design_gap ambiguity with options: (a) regenerate v0 to include the page, (b) remove from spec, (c) accept that fidelity gate will skip for that page
   • Emit a design_route_map debug section in the plan's reasoning field showing each route → change binding

7. Generate the plan

   Write orchestration-plan.json to the project root with this schema:

   {
     "phase_detected": "Description of the phase/section being implemented",
     "reasoning": "Why this decomposition — what's the strategy",
     "changes": [
       {
         "name": "kebab-case-name",
         "scope": "Detailed description of what to implement + test requirements",
         "complexity": "S|M|L",
         "change_type": "<one of the valid change types — see below>",
         "model": "opus|sonnet",
         "has_manual_tasks": false,
         "depends_on": ["other-change-name"],
         "roadmap_item": "The spec section this implements",
         "design_routes": ["/", "/kavek"],
         "spec_files": ["path/relative/to/spec-dir.md"],
         "requirements": ["REQ-DOMAIN-001"],
         "also_affects_reqs": ["REQ-CROSS-001"]
       }
     ],
     "deferred_requirements": [
       {
         "id": "REQ-DOMAIN-002",
         "reason": "Depends on auth system, planned for next phase"
       }
     ],
     "deferred_design_routes": [
       {
         "route": "/admin/settings",
         "reason": "Phase 2 scope, skipped for this run"
       }
     ],
     "source_items": [
       {
         "id": "SI-1",
         "text": "Description of the spec item",
         "change": "assigned-change-name-or-null"
       }
     ]
   }
   
   **Note:** `spec_files`, `requirements`, and `also_affects_reqs` are only required when working with a multi-file spec that has been digested (`set/orchestration/digest/` exists). For single-file specs, omit these fields.
   
   **Source items (single-file mode only):** When there is NO digest directory, generate a `source_items` array listing every identifiable spec item (feature, requirement, task, checkbox) with an assigned change name or `null` if intentionally excluded. Omit `source_items` entirely in digest mode (digest uses `requirements.json` instead).
   
   **Requirement accounting (digest mode only):** When a digest exists, every requirement in `set/orchestration/digest/requirements.json` MUST be accounted for. Either:
   - Assign it to a change via `requirements[]` or `also_affects_reqs[]`, OR
   - List it in `deferred_requirements[]` with a reason explaining why it is deferred (e.g., dependency on another phase, out of scope for this sprint, intentionally excluded)
   
   Silent omission of requirements — assigning neither to a change nor to `deferred_requirements` — is a planning error. `validate_plan()` will report unaccounted requirements as errors and block dispatch.