spec-driven-collaboration

Spec-Driven Collaboration

Generate a self-contained collaboration document that packages an issue with actual code, constitutional constraints, analysis, and targeted questions for an external AI to review.

Constitution files are THE LAW: tech-stack.md, source-tree.md, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md

If ambiguous or conflicts detected: HALT and use AskUserQuestion

---

Execution Model

This skill expands inline. After invocation, execute Phase 01 immediately. Do not wait passively, ask permission, or offer execution options.

Self-Check (if ANY box is true = VIOLATION):

• Stopping to ask about token budget
• Stopping to offer execution options
• Waiting passively after skill invocation
• Asking "should I execute this?"
• Skipping a phase because it "seems simple"
• Combining multiple phases into one
• Summarizing instead of loading a reference file
• Skipping verification because "I already wrote the file"

IF any box checked: EXECUTION MODEL VIOLATION. Go directly to Phase 01 now.

---

Anti-Skip Enforcement Contract

This skill enforces structural anti-skip at every step using the Execute-Verify-Record pattern. Every mandatory step in every phase has three parts:

• EXECUTE: The exact action to perform (Read, Write, AskUserQuestion, Glob, Grep)
• VERIFY: How to confirm the action happened (file exists, content matches, count correct)
• RECORD: Confirmation that the step completed successfully

Token Optimization Bias is PROHIBITED. Do not skip, compress, or shortcut any step. Every phase step exists because a previous failure proved it necessary.

Prohibited rationalizations:

• "The template is simple enough to populate from memory" — Load the template file fresh.
• "I already read the constitution files" — Read them again in Phase 02.
• "The document is short, no need to verify" — Read it back to verify in Phase 05.
• "Phase 06 is just a display, I can skip it" — Execute it fully.
• "I can combine Phases 04 and 05" — Execute them separately, in order.

---

Parameter Extraction

Extract parameters from conversation context set by the /collaborate command:

Extraction Method:

1. Search conversation for **Issue Description:** marker → ISSUE_DESCRIPTION
2. Search conversation for **Target AI:** marker → TARGET_AI
3. If markers not found, search for natural language context about the issue
4. If still not found: AskUserQuestion to gather missing parameters

---

Phase Table

---

Phase Orchestration Loop

FOR phase_num in [01, 02, 03, 04, 05, 06]:

    1. LOAD: Read(file_path="src/claude/skills/spec-driven-collaboration/phases/{phase_file}")
       Do NOT rely on memory of previous reads. Load the phase file FRESH.

    2. EXECUTE: Follow every step in the phase file (EXECUTE-VERIFY-RECORD triplets)
       - Each step's EXECUTE instruction tells you exactly what to do
       - Each step's VERIFY instruction tells you how to confirm it happened
       - Each step's RECORD instruction confirms completion

    3. GATE: Verify all gate conditions before proceeding to next phase
       IF any gate condition fails: HALT

Critical: Load each phase file fresh using Read(). Do not execute phases from memory.

---

Success Criteria

• All 6 phases executed in sequence
• ISSUE_DESCRIPTION and TARGET_AI extracted
• AFFECTED_FILES identified (≥1 file)
• All 6 constitution files loaded and constraints extracted
• All affected files read with actual code captured
• Template loaded fresh from reference file
• All 10 sections populated (no empty sections, no placeholders)
• Document written to tmp/collaborate-{target}-{slug}-{date}.md
• Document verified by read-back (≥100 lines, all 10 section headers present)
• Completion report displayed to user

---

Reference Files

---

Error Handling