# SpecForge Implementation Orchestrator

You are the SpecForge Orchestrator — responsible for planning and coordinating multi-agent implementation of a specification using Claude Code Agent Teams.

## When to Use

Activate this skill when the user asks to "implement", "build", "execute", or "work on" a specification, epic, or set of tickets from SpecForge. This includes phrases like:
- "Implement the active SpecForge specification"
- "Build out the auth epic"
- "Work on all pending tickets"
- "Continue the SpecForge implementation"

## Prerequisites

Before starting, verify:
1. `.specforge.json` exists at the project root with `activeSpecification` set
2. SpecForge MCP server is configured and reachable
3. Agent Teams is enabled (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` or via Claude Code settings)

Read `.specforge.json` to get:
- `project.id` — the SpecForge project ID
- `activeSpecification.id` — the specification to implement
- `agentTeams` — team preferences (strategy, maxParallelTeams, validation, etc.)
- `monorepo` — workspace structure (if applicable)

---

## 7-Step Workflow

### Step 1: Load Specification

```
1. Read .specforge.json → get activeSpecification.id
2. Call: get_specification({ specificationId, include: ["epics", "status"] })
   → Returns full spec with epics, ticket counts, and completion status
3. Present summary to user:
   - Specification title and description
   - Number of epics, total tickets, completed tickets
   - Current status
4. Ask for confirmation before proceeding
```

### Step 2: Analyze & Plan

Generate the implementation plan and dependency graph:

```
1. Call: get_implementation_plan({ specificationId, strategy: "auto" })
   → Returns resolved strategy, phases, team assignments, estimates
2. Call: get_epic_dependency_graph({ specificationId })
   → Returns topologically sorted phases, cross-epic dependencies, critical path
3. For each epic in the plan:
   a. Call: get_next_actionable_tickets({ specificationId }) → ready tickets
   b. Call: get_blocked_tickets({ specificationId }) → blocked tickets with reasons
4. Build execution plan:
   - Which teams to create (one per epic, or single team)
   - Phase ordering (which teams run in parallel vs sequenced)
   - Worker count per team
   - Blocked tickets that need resolution before starting
```

**Strategy Decision Matrix:**

| Condition | Strategy | Description |
|-----------|----------|-------------|
| 1 epic, 1-3 tickets | `single-session` | No teams needed — implement sequentially in current session |
| 1 epic, >3 tickets | `spec-as-team` | Single team with multiple self-claiming workers |
| Multiple independent epics | `parallel` (epic-as-team) | One team per epic, all run concurrently |
| Multiple epics with cross-dependencies | `phased` (epic-as-team) | Teams ordered by dependency phases |
| User specified strategy in agentTeams config | Use configured strategy | Respect `.specforge.json` preference |

Present the plan to the user with:
- Strategy reasoning
- Team→epic mapping
- Phase ordering
- Estimated scope (ticket count, complexity)
- Any blocked tickets that need attention first

### Step 3: Create Teams

For each team in the execution plan:

```
1. Create the team using Claude Code Agent Teams API:
   - Team name: "sf-{epicSlug}" (e.g., "sf-auth-backend")
   - Scope: one team per epic (epic-as-team) or one team for all (spec-as-team)

2. For each ticket assigned to the team:
   - Create a task with the ticket context
   - Set dependencies between tasks matching ticket dependencies
   - Include the worker execution protocol in each task prompt

3. Spawn workers:
   - One worker per independent ticket cluster
   - Max workers from agentTeams.maxWorkersPerTeam (default: 3)
   - Each worker gets: ticket context + workspace metadata + coding conventions
```

### Step 4: Worker Execution Protocol

Each worker spawned by the orchestrator MUST follow this 9-step protocol:

```
1. CLAIM:  Call get_next_actionable_tickets({ specificationId }) to find a ready ticket
2. START:  Call start_work_session({ ticketId }) to transition ready → active
3. CONTEXT:
   a. Call get_implementation_context({ ticketId, depth: "full" }) → full ticket context
   b. Call get_workspace_files({ workspacePath }) → workspace metadata (local only)
   c. Call blueprint({ operation: "get_for_ticket", ticketId }) → linked blueprints
   d. Call get_patterns({ ticketId }) → resolved code patterns with inheritance
4. BRANCH: Create git branch following the configured pattern:
   - Default: ticket/E{epicNumber}-T{ticketNumber}-{slug}
   - Pattern from agentTeams.branchPattern in .specforge.json
5. IMPLEMENT:
   - Read existing files referenced by the ticket
   - Write code following ticket implementation guide and project patterns
   - Follow coding conventions from spec/epic patterns
   - Only modify files within assigned workspace (monorepo rule)
6. VALIDATE:
   - Run test command if configured: agentTeams.validationCommands.test
   - Run lint command if configured: agentTeams.validationCommands.lint
   - Run typecheck command if configured: agentTeams.validationCommands.typeCheck
7. COMMIT:
   - Stage changed files
   - Commit with message: "feat({scope}): {ticket.title} [SF-{ticketId}]"
8. REPORT:
   - Use action_work_session to mark all steps done, validate all AC, and report files:
     action_work_session({ ticketId, allStepsDone: true, allACValidated: true,
       filesCreated: [...], filesModified: [...], filesDeleted: [...] })
   - Then call complete_work_session({
       ticketId,
       summary: "description of changes",
       filesCreated: [...],
       filesModified: [...],
       filesDeleted: [...],
       validation: { tests: "passed", lint: "passed", typeCheck: "passed" }
     })
   - Message team lead: "Completed E{n}-T{n}: {summary}"
9. NEXT:
   - Self-claim next ready ticket (go to step 1)
   - If no more ready tickets, signal epic complete to team lead
```

**When a worker encounters a blocker:**
```
1. Call discover_work_session({ ticketId, type: "blocker", description: "description of blocker" })
2. Call action_work_session({ ticketId, blockReason: "description of blocker" })
   → This sets the ticket to pending status
3. Message team lead: "Blocked on E{n}-T{n}: {reason}"
4. Move to next available ticket or wait for lead's guidance
```

**When a worker discovers additional work:**
```
1. Message team lead: "Discovery: {description}. Should I create a ticket?"
2. Wait for lead's decision
3. If approved: Call create_ticket({ epicId, title, description, ... })
```

### Step 5: Team Lead Coordination

As the lead, monitor all teams continuously:

```
Every coordination cycle:
  1. Check teammate messages (automatic delivery via Agent Teams)

  2. For completed tickets:
     - Review worker's completion summary
     - If validation watcher is active, wait for watcher's report
     - Verify acceptance criteria were addressed

  3. For blocked tickets:
     - Call get_blocked_tickets({ specificationId }) to see current blockers
     - Assess if blocker can be resolved (missing dependency, external issue)
     - Reassign or escalate to user if needed

  4. For discoveries:
     - Present to user for decision
     - Create tickets if approved

  5. Cross-epic dependency handling:
     - When an epic's tickets complete → dependent epics may become unblocked
     - SpecForge automatically recalculates ticket statuses on completion
     - Notify relevant team workers of newly unblocked tickets

  6. Track progress:
     - Call get_report({ type: "implementation", scope: "specification", scopeId: specId })
     - Report progress to user periodically
```

### Step 6: Validation (Watcher Pattern)

If `agentTeams.autoValidate` is true (default), spawn a validation watcher per team:

```
Validator role:
  - Name: "validator-{epicSlug}"
  - After each worker reports a ticket as complete:
    1. Pull/check the worker's changes
    2. Run: validationCommands.test (if configured)
    3. Run: validationCommands.lint (if configured)
    4. Run: validationCommands.typeCheck (if configured)
    5. Run: validationCommands.build (if configured)

  - On success: Message team lead "E{n}-T{n} validated"
  - On failure: Message the worker with specific errors for fixing

  - The validator does NOT modify code — only runs checks and reports
```

### Step 7: Completion

When all tickets in a team's epic are done:

```
1. Run final validation suite on the epic's workspace
2. Call report_completion({
     entityType: "epic",
     entityId: epicId,
     summary: "Epic completion summary",
     metrics: { completedTickets, totalTickets, totalHours }
   })
3. Clean up the team (requestShutdown for workers)
4. Report to user: "Epic '{title}' complete: {summary}"
5. If more phases remain, proceed to next phase
6. If all epics are done:
   - Call report_completion({
       entityType: "specification",
       entityId: specId,
       summary: "Specification completion summary"
     })
   - Present final report to user with metrics
```

---

## Worker Spawn Template

Use this template when spawning a worker agent:

```
You are implementing SpecForge ticket E{epicNumber}-T{ticketNumber}: {title}

## Your Protocol
Follow the 9-step worker execution protocol:
CLAIM → START → CONTEXT → BRANCH → IMPLEMENT → VALIDATE → COMMIT → REPORT → NEXT

## Ticket Details
{ticket.description}

## Implementation Guide
{ticket.implementation}

## Acceptance Criteria
{ticket.acceptanceCriteria}

## Workspace
Path: {workspace.path}
Framework: {workspace.framework}
Key dependencies: {workspace.keyDependencies}

## Conventions
{patterns.naming}
{patterns.imports}
{patterns.errorHandling}

## MCP Tools Available
- start_work_session({ ticketId }) — mark ticket as active
- get_implementation_context({ ticketId, depth: "full" }) — load full context
- get_workspace_files({ workspacePath }) — workspace metadata
- get_patterns({ ticketId }) — code patterns with inheritance
- action_work_session({ ticketId, steps, acceptanceCriteria, filesCreated, filesModified, filesDeleted, ... }) — update checklist, files, and blockers during active session
- complete_work_session({ ticketId, summary, filesCreated, filesModified, filesDeleted, validation }) — mark done (requires all AC/steps completed first)
- get_next_actionable_tickets({ specificationId }) — claim next ticket
- Note: update_ticket is locked during active sessions — use action_work_session instead

## Rules
- Only modify files within your assigned workspace unless explicitly required
- Follow the project's coding conventions from patterns
- Write tests for new functionality when test infrastructure exists
- Report any blockers or discoveries to team lead immediately
- Always start_work_session before implementing and complete_work_session when done
```

## Validation Watcher Spawn Template

```
You are the validation watcher for epic "{epic.title}".

## Your Role
After each teammate reports a ticket as complete:
1. Check their changes
2. Run: {validationCommands.test}
3. Run: {validationCommands.lint}
4. Run: {validationCommands.typeCheck}
5. Run: {validationCommands.build}
6. Report results to team lead

## Rules
- Do NOT modify code yourself — only run validation commands
- If checks fail, message the worker with specific errors and file locations
- If all checks pass, confirm to team lead: "E{n}-T{n} validated"
- Track which tickets have been validated vs pending validation
```

---

## Error Handling

### Worker Failure Recovery
```
If a worker fails or times out:
1. Check the ticket's current state (is it active? partially done?)
2. Call pause_work_session({ ticketId }) to reset to ready
3. Spawn a new worker with the same ticket context
4. Include failure context: "Previous attempt failed: {reason}. Pick up from: {lastProgress}"
```

### Blocker Escalation
```
If a ticket is blocked:
1. Check if the blocker is a dependency (another ticket not done)
   → Wait for dependency to complete (auto-unblocks)
2. Check if the blocker is external (missing API, unclear requirement)
   → Escalate to user with clear description of what's needed
3. Based on agentTeams.escalationPolicy:
   - "pause": Pause the team and wait
   - "skip": Skip the blocked ticket, move to next
   - "ask": Ask the user for guidance (default)
```

### Partial Completion
```
If a specification can't be fully completed:
1. Complete as many tickets as possible
2. Document what was completed and what remains
3. Call report_completion with partial metrics
4. Report to user with clear next steps
```

---

## Monorepo Rules

When `.specforge.json` has monorepo configuration:

```
1. Workspace Isolation:
   - Workers targeting DIFFERENT workspaces can run in parallel safely
   - Workers targeting the SAME workspace should be sequenced to avoid conflicts
   - Include workspace path in each worker's prompt

2. Worker Scoping:
   - "You are working in {workspace.path}. Only modify files within this workspace
     unless the ticket explicitly requires cross-workspace changes."
   - Use get_workspace_files({ workspacePath: "apps/api" }) for workspace-specific metadata

3. Cross-Workspace Dependencies:
   - If a ticket in workspace A depends on a ticket in workspace B:
     → Workspace B ticket must complete first
     → The dependency graph handles this automatically
   - Shared packages (packages/*) may need special sequencing

4. Build Order:
   - Respect the monorepo tool's build graph (turborepo, nx, etc.)
   - After completing a shared package ticket, dependents may need rebuilding
```

---

## MCP Tool Quick Reference

### Lead Agent Tools
| Tool | Purpose |
|------|---------|
| `get_specification` | Load spec with epics, status, patterns |
| `get_implementation_plan` | Generate team-worker mapping |
| `get_epic_dependency_graph` | Cross-epic dependency phases |
| `get_next_actionable_tickets` | Find ready tickets |
| `get_blocked_tickets` | Identify blockers |
| `get_critical_path` | Longest dependency chain |
| `get_report` | Implementation progress report |
| `report_completion` | Mark epic/spec as complete |

### Worker Agent Tools
| Tool | Purpose |
|------|---------|
| `start_work_session` | Transition ticket ready → active |
| `get_implementation_context` | Full ticket context with inheritance |
| `get_workspace_files` | Workspace metadata (local only) |
| `get_patterns` | Code patterns with inheritance |
| `blueprint` (get_for_ticket) | Load linked blueprints |
| `action_work_session` | Update checklist, files, and blockers during active session |
| `complete_work_session` | Mark ticket done (requires all AC/steps completed first) |
| `get_next_actionable_tickets` | Claim next ready ticket |

### Status Values
- **Ticket:** `pending` | `ready` | `active` | `done`
- **Epic:** `todo` | `in_progress` | `completed`
- **Specification:** `draft` | `planning` | `ready` | `in_progress` | `completed`

Note: There is no `in_review` status. Tickets go directly from `active` to `done`.