bacchus-labs/implement-spec

Implement-Spec Orchestrator

Skill Usage Announcement

MANDATORY: When using this skill, announce it at the start with:

Using Skill: implement-spec | [brief purpose based on context]

Example:

Using Skill: implement-spec | Implementing spec-auth-system.md with full audit trail

This creates an audit trail showing which skills were applied during the session.

Overview

End-to-end orchestration that takes a specification file and produces a GitHub Pull Request with comprehensive audit trail.

Core principle: Single command produces PR with verified implementation, full observability, and recovery capability.

Entry point: /wrangler:implement [spec-file]

Produces:

• GitHub Pull Request with comprehensive summary
• Audit trail in .wrangler/sessions/{session-id}/
• Machine-verifiable execution log

When to Use

Use this skill when:

• User says "implement this spec" and wants a PR
• You want full audit trail and observability
• You need session recovery capability
• You want isolated worktree for implementation

Do NOT use this skill when:

• Implementing a single issue (use implement skill directly)
• User wants manual control over each step
• Working on existing PR or branch (use implement skill)

Workflow Phases

The orchestrator executes 6 phases in order:

INIT -> PLAN -> EXECUTE -> VERIFY -> PUBLISH -> REPORT

Each phase is tracked via MCP session tools for full observability.

Phase 1: INIT

Initialize session, create worktree, and establish context.

Steps

1. Start session

   Call session_start MCP tool:

   session_start(specFile: "{SPEC_FILE}")
   

   Capture response:

   • SESSION_ID = response.sessionId
   • WORKTREE_ABSOLUTE = response.worktreePath
   • BRANCH_NAME = response.branchName
   • AUDIT_PATH = response.auditPath

2. Verify worktree

   cd {WORKTREE_ABSOLUTE} && \
     echo "=== WORKTREE VERIFICATION ===" && \
     echo "Directory: $(pwd)" && \
     echo "Git root: $(git rev-parse --show-toplevel)" && \
     echo "Branch: $(git branch --show-current)" && \
     test "$(git branch --show-current)" = "{BRANCH_NAME}" && echo "VERIFIED" || echo "FAILED"
   

   If verification fails, STOP and report error.

3. Log phase complete

   session_phase(
     sessionId: SESSION_ID,
     phase: "init",
     status: "complete"
   )
   

Outputs

• Session ID for all subsequent phases
• Worktree absolute path for subagent context
• Branch name for PR creation

Phase 2: PLAN

Create implementation plan with MCP issues.

Steps

1. Log phase start

   session_phase(sessionId: SESSION_ID, phase: "plan", status: "started")
   

2. Invoke writing-plans skill

   Use the Task tool to dispatch planning subagent:

   Tool: Task
   Description: "Create implementation plan for {SPEC_FILE}"
   Prompt: |
   You are creating an implementation plan for a specification.
   
   ## Working Directory Context
   
   **Working directory:** {WORKTREE_ABSOLUTE}
   **Branch:** {BRANCH_NAME}
   **Session ID:** {SESSION_ID}
   
   ## Specification
   
   Read and analyze: {SPEC_FILE}
   
   ## Your Job
   
   1. Read the specification file
   2. Break down into implementable tasks
   3. Create MCP issues for each task using issues_create
   4. Return the list of issue IDs created
   
   Use the writing-plans skill approach:
   
   - Each task should be <250 LOC
   - Clear acceptance criteria per task
   - Dependencies between tasks if any
   
   ## Output Required
   
   Return:
   
   - Total task count
   - List of issue IDs created (e.g., ["ISS-000042", "ISS-000043"])
   - Any blockers or clarification needed
   

3. Capture issue IDs

   Parse planning subagent response for:

   • ISSUE_IDS = list of created issue IDs
   • TASK_COUNT = number of tasks created

4. Log phase complete

   session_phase(
     sessionId: SESSION_ID,
     phase: "plan",
     status: "complete",
     metadata: {
       issues_created: ISSUE_IDS,
       total_tasks: TASK_COUNT
     }
   )
   

5. Save checkpoint

   session_checkpoint(
     sessionId: SESSION_ID,
     tasksCompleted: [],
     tasksPending: ISSUE_IDS,
     lastAction: "Created implementation plan with {TASK_COUNT} tasks",
     resumeInstructions: "Continue with execute phase, implement issues: {ISSUE_IDS}"
   )
   

Gate

If planning fails or returns blockers, ESCALATE to user.

Phase 3: EXECUTE

Implement all tasks using subagents.

Steps

1. Log phase start

   session_phase(sessionId: SESSION_ID, phase: "execute", status: "started")
   

2. Invoke implement skill

   Use the implement skill with worktree context:

   I'm using the implement skill to execute all tasks.
   
   ## Context for Implement Skill
   
   **Scope:** issues {ISSUE_IDS}
   **Working directory:** {WORKTREE_ABSOLUTE}
   **Branch:** {BRANCH_NAME}
   **Session ID:** {SESSION_ID}
   
   ## CRITICAL: Worktree Context
   
   ALL subagents MUST receive:
   
   - Working directory: {WORKTREE_ABSOLUTE}
   - Branch: {BRANCH_NAME}
   
   ALL bash commands MUST use:
   
   ```bash
   cd {WORKTREE_ABSOLUTE} && [command]
   ```
   

   Checkpoint After Each Task

   After each task completes, call:

   session_checkpoint(
     sessionId: {SESSION_ID},
     tasksCompleted: [...completed_ids],
     tasksPending: [...remaining_ids],
     lastAction: "Completed task {task_id}: {task_title}",
     resumeInstructions: "Continue with next task or proceed to verify if all done"
   )
   

3. Track task completion

   For each completed task:

   • Record task audit entry via session_phase with phase="task"
   • Save checkpoint via session_checkpoint

4. Log phase complete

   When all tasks complete:

   session_phase(
     sessionId: SESSION_ID,
     phase: "execute",
     status: "complete",
     metadata: {
       tasks_completed: TASK_COUNT,
       total_commits: N
     }
   )
   

Gate

If any task cannot be completed after escalation, session pauses.

Phase 4: VERIFY

Fresh test run and requirements check.

Steps

1. Log phase start

   session_phase(sessionId: SESSION_ID, phase: "verify", status: "started")
   

2. Run fresh test suite

   cd "{WORKTREE_ABSOLUTE}" && npm test 2>&1 | tee ".wrangler/sessions/{SESSION_ID}/final-test-output.txt"
   

   Capture:

   • TEST_EXIT_CODE = exit code
   • TESTS_TOTAL = total test count
   • TESTS_PASSED = passing test count

3. Check git status

   cd "{WORKTREE_ABSOLUTE}" && git status --short
   

   Capture:

   • GIT_CLEAN = true if output is empty

4. Log phase complete

   session_phase(
     sessionId: SESSION_ID,
     phase: "verify",
     status: "complete",
     metadata: {
       tests_exit_code: TEST_EXIT_CODE,
       tests_total: TESTS_TOTAL,
       tests_passed: TESTS_PASSED,
       git_clean: GIT_CLEAN
     }
   )
   

Gate

CRITICAL: Do NOT proceed to publish if:

• TEST_EXIT_CODE != 0 - tests failing
• GIT_CLEAN == false - uncommitted changes

If verification fails:

1. Log error and halt
2. Inform user of verification failure
3. Session remains in "paused" state for recovery

Phase 5: PUBLISH

Push branch and create PR.

Steps

1. Log phase start

   session_phase(sessionId: SESSION_ID, phase: "publish", status: "started")
   

2. Push branch

   cd "{WORKTREE_ABSOLUTE}" && git push -u origin "{BRANCH_NAME}"
   

3. Generate PR body

   Create comprehensive PR body from audit data:

   ## Summary
   
   Implements specification: `{SPEC_FILE}`
   
   ### Changes
   
   {git log main..HEAD --oneline formatted as bullet list}
   
   ### Test Results
   
   - All tests passing ({TESTS_TOTAL} tests)
   
   ### Tasks Completed
   
   {For each task from session:}
   
   - [x] {task_id}: {task_title} ({commit_hash})
   
   ### Implementation Details
   
   - TDD compliance: All functions certified
   - Code review: All tasks approved
   
   ---
   
   **Session ID:** `{SESSION_ID}`
   **Audit trail:** `.wrangler/sessions/{SESSION_ID}/`
   
   Generated with [Claude Code](https://claude.com/claude-code)
   

4. Create PR

   cd "{WORKTREE_ABSOLUTE}" && gh pr create \
     --title "feat({SPEC_NAME}): implement specification" \
     --body "{PR_BODY}" \
     --base main \
     --head "{BRANCH_NAME}"
   

   Capture:

   • PR_URL = PR URL from output
   • PR_NUMBER = PR number from output

5. Log phase complete

   session_phase(
     sessionId: SESSION_ID,
     phase: "publish",
     status: "complete",
     metadata: {
       pr_url: PR_URL,
       pr_number: PR_NUMBER,
       branch_pushed: true
     }
   )
   

Gate

If push or PR creation fails:

1. Log error
2. Inform user (may need to configure gh auth)
3. Session pauses but work is preserved

Phase 6: REPORT

Complete session and present summary.

Steps

1. Complete session

   session_complete(
     sessionId: SESSION_ID,
     status: "completed",
     prUrl: PR_URL,
     prNumber: PR_NUMBER,
     summary: "Implemented {TASK_COUNT} tasks from {SPEC_FILE}"
   )
   

2. Present summary to user

   ## Implementation Complete
   
   **Specification:** {SPEC_FILE}
   **PR:** {PR_URL}
   **Session:** {SESSION_ID}
   
   ### Summary
   
   | Metric          | Value                     |
   | --------------- | ------------------------- |
   | Tasks completed | {TASK_COUNT}/{TASK_COUNT} |
   | Tests passing   | {TESTS_TOTAL}             |
   | Code reviews    | {TASK_COUNT} approved     |
   
   ### Audit Trail
   
   Location: `.wrangler/sessions/{SESSION_ID}/`
   
   **Verify execution:**
   
   ```bash
   cat .wrangler/sessions/{SESSION_ID}/audit.jsonl | jq -s '{
     phases: [.[].phase] | unique,
     tasks: [.[] | select(.phase == "task")] | length,
     all_passed: [.[] | select(.phase == "task") | .tests_passed] | all,
     pr_created: ([.[] | select(.phase == "publish")] | length) > 0
   }'
   ```
   

Session Recovery

If a session is interrupted, it can be resumed.

Detection

On session start, check for interrupted sessions:

session_get()  // No sessionId = find most recent incomplete

If interrupted session found:

1. Read checkpoint
2. Present resume option to user
3. If user confirms, continue from last checkpoint

Resume Flow

1. Call session_get(sessionId: "{SESSION_ID}")
2. Read checkpoint.resumeInstructions
3. Continue from indicated phase/task
4. All MCP calls use existing sessionId

Worktree Isolation

CRITICAL: All subagent operations MUST use worktree context.

Context Injection

Every subagent prompt MUST include:

## CRITICAL: Working Directory Context

**Working directory:** {WORKTREE_ABSOLUTE}
**Branch:** {BRANCH_NAME}

### MANDATORY: Verify Location First

Before ANY work, run:

```bash
cd {WORKTREE_ABSOLUTE} && \
  echo "Directory: $(pwd)" && \
  echo "Branch: $(git branch --show-current)" && \
  test "$(pwd)" = "{WORKTREE_ABSOLUTE}" && echo "VERIFIED" || echo "FAILED"
```

If verification fails, STOP immediately.

Command Pattern

ALL bash commands MUST use:

cd {WORKTREE_ABSOLUTE} && [command]

### Why This Matters

- Worktree is separate from main repository
- Without explicit context, subagents may work in wrong directory
- Commits in wrong directory corrupt main branch

## Error Handling

### Phase Failures

Each phase has verification gates:
- **INIT:** Worktree must exist and be on correct branch
- **PLAN:** Issues must be created successfully
- **EXECUTE:** All tasks must complete (with escalation for blockers)
- **VERIFY:** Tests must pass, git must be clean
- **PUBLISH:** Push and PR creation must succeed

### Recovery Actions

| Error | Recovery |
|-------|----------|
| Worktree creation fails | Check disk space, permissions |
| Planning unclear | Escalate to user for clarification |
| Task blocked | Escalate via implement skill |
| Tests fail | Do not publish, inform user |
| Push fails | Check git remote, auth |
| PR creation fails | Check gh auth, permissions |

### Session States

| State | Meaning | Recovery |
|-------|---------|----------|
| `running` | Currently executing | Continue |
| `paused` | Blocked on something | Resume from checkpoint |
| `completed` | Successfully finished | No action needed |
| `failed` | Unrecoverable error | Start new session |

## Example Execution

User: /wrangler:implement spec-auth-system.md

Using Skill: implement-spec | Implementing spec-auth-system.md with full audit trail

PHASE 1: INIT -> session_start(specFile: "spec-auth-system.md") -> Created session: 2025-12-07-abc123-f8d2 -> Worktree: /project/.worktrees/spec-auth-system -> Branch: wrangler/spec-auth-system/2025-12-07-abc123 -> VERIFIED

PHASE 2: PLAN -> Invoking writing-plans skill -> Created 5 tasks: ISS-000042 through ISS-000046 -> session_checkpoint saved

PHASE 3: EXECUTE -> Invoking implement skill with worktree context -> Task ISS-000042: Complete (TDD certified, code reviewed) -> session_checkpoint saved -> Task ISS-000043: Complete -> session_checkpoint saved -> Task ISS-000044: Complete -> session_checkpoint saved -> Task ISS-000045: Complete -> session_checkpoint saved -> Task ISS-000046: Complete -> session_checkpoint saved

PHASE 4: VERIFY -> Running test suite: 42 tests, 42 passing -> Git status: clean -> PASSED

PHASE 5: PUBLISH -> Pushed branch to origin -> Created PR: https://github.com/org/repo/pull/123

PHASE 6: REPORT -> session_complete

Implementation Complete

Specification: spec-auth-system.md PR: https://github.com/org/repo/pull/123 Session: 2025-12-07-abc123-f8d2

| Metric | Value | | --------------- | ---------- | | Tasks completed | 5/5 | | Tests passing | 42 | | Code reviews | 5 approved |

Audit trail: .wrangler/sessions/2025-12-07-abc123-f8d2/

## Integration with Other Skills

**Required skills:**
- `implement` - Task execution with TDD and code review
- `writing-plans` - Breaking spec into MCP issues
- `test-driven-development` - TDD compliance in subagents
- `requesting-code-review` - Code review for each task

**Optional skills:**
- `using-git-worktrees` - Manual worktree management (automated here)
- `finishing-a-development-branch` - PR already created by this skill

## Verification Commands

After completion, verify execution:

```bash
# Verify all phases completed
jq -s '[.[].phase] | unique | sort' .wrangler/sessions/{id}/audit.jsonl
# Expected: ["checkpoint","complete","execute","init","plan","publish","task","verify"]

# Verify all tasks passed
jq -s '[.[] | select(.phase == "task" and .tests_passed == false)]' audit.jsonl
# Expected: []

# Verify PR created
jq -s '.[] | select(.phase == "publish") | .pr_url' audit.jsonl
# Expected: "https://github.com/..."

# Get session summary
jq -s '{
  session_id: .[0].session_id,
  phases: [.[].phase] | unique,
  tasks: [.[] | select(.phase == "task")] | length,
  duration_sec: ((.[length-1].timestamp | fromdateiso8601) - (.[0].timestamp | fromdateiso8601))
}' audit.jsonl

Red Flags - Anti-Patterns

Do NOT:

• Skip worktree verification (subagents may work in wrong directory)
• Proceed to publish with failing tests
• Create PR without complete audit trail
• Skip checkpoints (recovery becomes impossible)
• Ignore phase gates

Do:

• Always verify worktree location
• Save checkpoint after each task
• Use session tools for all phase transitions
• Halt on verification failures
• Provide comprehensive PR body