---
name: spec-driven-collaboration
description: >
  Generate self-contained collaboration documents for sharing issues with external AI
  systems (Gemini, ChatGPT, etc.) with structural anti-skip enforcement
  (Execute-Verify-Record pattern at every step). Interactively gathers context, reads
  actual code files, loads constitutional constraints, and produces a complete 10-section
  package ready to paste into the target LLM. Use when the user wants to collaborate with
  another AI, share an issue for joint problem-solving, get a fresh perspective from a peer
  LLM, or needs help from an external AI that doesn't have access to the codebase. Make sure
  to use this skill whenever the user mentions cross-AI collaboration, sharing issues with
  Gemini/ChatGPT/Copilot, peer review from another AI, or wants a second opinion from
  an external LLM.
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - AskUserQuestion
model: opus
effort: High
---

# 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/, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md

**If ambiguous or conflicts detected: HALT and use AskUserQuestion**

---

## Execution Model

See **`.claude/rules/core/anti-skip-behavior.md`** for the canonical execution contract (expand inline; do not wait passively or offer execution options; honor every step of every phase; Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076). After invocation, execute Phase 01 immediately.

---

## Anti-Skip Enforcement Contract

Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the `devforgeai-validate` phase gates, the `settings.json`-registered `.claude/hooks/` scripts, and `.claude/hooks/phase-steps-registry.json` (ADR-076). Behavioral residue: `.claude/rules/core/anti-skip-behavior.md`.

---

## Parameter Extraction

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

| Context Marker | Set By | Description |
|----------------|--------|-------------|
| `ISSUE_DESCRIPTION` | /collaborate | Issue description from user argument or AskUserQuestion |
| `TARGET_AI` | /collaborate | Target AI platform (default: "Gemini") |

**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 | Name | File | Steps | Key Tools |
|-------|------|------|-------|-----------|
| 01 | Context Gathering | `phases/phase-01-context-gathering.md` | 4 | AskUserQuestion, Glob, Grep |
| 02 | Constitution Loading | `phases/phase-02-constitution-loading.md` | 3 | Read (×6 parallel) |
| 03 | Code Collection | `phases/phase-03-code-collection.md` | 4 | Read, Glob, Grep |
| 04 | Analysis & Template Population | `phases/phase-04-analysis-template.md` | 4 | Read |
| 05 | Document Generation | `phases/phase-05-document-generation.md` | 3 | Write, Read |
| 06 | Completion Report | `phases/phase-06-completion-report.md` | 2 | Display |

---

## Phase Orchestration Loop

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

    1. LOAD: Read(file_path=".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

| File | Purpose | Loaded In |
|------|---------|-----------|
| `references/collaboration-prompt-template.md` | 10-section output document template | Phase 04 |
| `references/context-gathering-guide.md` | Interactive context gathering patterns | Phase 01 |
| `references/code-collection-patterns.md` | File discovery, test finding, error capture | Phase 03 |
| `references/analysis-reasoning-guide.md` | Hypothesis ranking, constraint analysis, question crafting | Phase 04 |

---

## Error Handling

| Error | Phase | Resolution |
|-------|-------|------------|
| No issue description from command | 01 | AskUserQuestion for description |
| Affected file not found | 03 | Warn user, skip file, continue |
| Constitution file missing | 02 | HALT — constitution files are required |
| Template reference missing | 04 | HALT — verify skill installation |
| `tmp/` directory missing | 05 | Create it, then write |
| Write fails | 05 | Report error path, suggest manual creation |
| Document verification fails | 05 | HALT — re-examine document content |
