spec%3abg（规格%3abg）

Compatibility: If AskUserQuestion is unavailable, present options as a numbered list and wait for the user's reply. If Task is unavailable, run parallel steps sequentially. The context: fork and agent: frontmatter fields are Claude Code-specific — on OpenCode and VS Code Copilot they are ignored and the skill runs inline using the current model.

Execute the plan in the background using an autonomous agent.

Overview

This command launches a long-running agent that executes your plan autonomously while you continue working. The agent updates progress in real-time and pauses on errors.

Step 0: Parse Arguments and Flags

PLAN_NAME="[first non-flag argument, or empty]"
AUTO_APPROVE=false; ALLOW_COMMITS=false; SILENT=false
[[ "$*" =~ --yes|-y ]]    && AUTO_APPROVE=true
[[ "$*" =~ --commit|-c ]] && ALLOW_COMMITS=true
[[ "$*" =~ --silent ]]    && SILENT=true

Step 0.5: Select Plan

If plan name not provided in arguments:

If not provided:

1. Get all active plans with Last Updated timestamps: npx @codevoyant/agent-kit plans migrate npx @codevoyant/agent-kit plans list --status Active
2. Sort plans by Last Updated (most recent first)
3. If only one plan exists, auto-select it
4. If multiple plans exist, use AskUserQuestion to present the list (name, progress %, last-updated) and ask the user to choose. Example prompt: "Which plan would you like to work on?\n (1) feature-auth — 60% — updated 2h ago\n (2) refactor-api — 20% — updated 1d ago"
5. Report to user: "Using plan: {plan-name} (last updated: {timestamp})"
6. If no plans exist, inform user to create with /new

Step 1: Verify Plan Exists

1. Check that .codevoyant/plans/{plan-name}/plan.md exists
2. If not found, inform user to create one with /new or /init

Step 2: Analyze Plan Scope

Read .codevoyant/plans/{plan-name}/plan.md and report:

1. Total number of phases
2. Total number of tasks
3. Starting point (first unchecked task)
4. Estimated complexity

Example:

Plan: {plan-name} - Authentication System
- 4 phases, 23 tasks
- Starting from: Phase 1, Task 1
- Complexity: Medium (has test requirements)

Step 2.5: Validate and Setup Worktree Context

Handle worktree-based execution automatically:

# Get current branch and working directory
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
CURRENT_DIR=$(pwd)

# Parse plan metadata
PLAN_BRANCH=$(grep "^- \*\*Branch\*\*:" .codevoyant/plans/{plan-name}/plan.md | sed 's/^- \*\*Branch\*\*: //' | sed 's/ *$//')
PLAN_WORKTREE=$(grep "^- \*\*Worktree\*\*:" .codevoyant/plans/{plan-name}/plan.md | sed 's/^- \*\*Worktree\*\*: //' | sed 's/ *$//')

# Determine worktree status
if [ -n "$PLAN_WORKTREE" ] && [ "$PLAN_WORKTREE" != "(none)" ]; then
  # Plan has worktree specified
  if [ -d "$PLAN_WORKTREE" ]; then
    WORKTREE_EXISTS=true
  else
    WORKTREE_EXISTS=false
  fi
else
  # No worktree for this plan
  WORKTREE_EXISTS=""
fi

Case 1: Worktree exists → Auto-execute there

If WORKTREE_EXISTS=true:

✓ Plan has worktree at: $PLAN_WORKTREE
→ Executing in worktree automatically...

Then continue to Step 3 with this context:

• Set execution directory to $PLAN_WORKTREE
• When launching agent (Step 6), pass worktree path as working directory
• Agent will execute in worktree isolation
• No manual cd required!

Case 2: Worktree specified but doesn't exist → Offer to create

If WORKTREE_EXISTS=false:

If AUTO_APPROVE is true:

• Automatically create worktree without asking
• Report: → Auto-creating worktree with --yes flag
• Create worktree: git worktree add -b "$PLAN_BRANCH" "$PLAN_WORKTREE" HEAD
• Update.gitignore if needed
• Report: ✓ Created worktree at $PLAN_WORKTREE
• Set execution directory to $PLAN_WORKTREE
• Continue to Step 3

If AUTO_APPROVE is false:

Use AskUserQuestion tool:

question: "This plan needs worktree '$PLAN_WORKTREE' (branch: $PLAN_BRANCH) but it doesn't exist. Create it now?"
header: "Worktree Setup"
multiSelect: false
options:
  - label: "Create worktree and execute"
    description: "Create worktree at $PLAN_WORKTREE, then start execution there"
  - label: "Execute here anyway"
    description: "Skip worktree, execute in current directory (may cause issues)"
  - label: "Cancel"
    description: "Don't execute, let me set it up manually"

Handle response:

• "Create worktree and execute":

1. Create worktree: git worktree add -b "$PLAN_BRANCH" "$PLAN_WORKTREE" HEAD 2. Update.gitignore if needed 3. Report: ✓ Created worktree at $PLAN_WORKTREE 4. Set execution directory to $PLAN_WORKTREE 5. Continue to Step 3

• "Execute here anyway":

- Warn: ⚠️ Executing without worktree - changes will affect current branch - Continue to Step 3 (execute in current directory)

• "Cancel":

- Exit command

Case 3: No worktree for plan → Execute in current directory

If plan has no worktree (PLAN_WORKTREE is "(none)" or empty):

• Check if branch matches (if PLAN_BRANCH specified)
• If branch mismatch, offer to switch: git checkout $PLAN_BRANCH
• Otherwise continue to Step 3 normally

Summary:

• Worktree exists → Execute there automatically ✅
• Worktree missing → Offer to create ✅
• No worktree → Execute here (with branch check) ✅
• All seamless, no manual cd required! ✅

Step 3: Validate Implementation Files

Before starting execution, verify all implementation files exist:

1. Count phases in plan.md:

- Parse .codevoyant/plans/{plan-name}/plan.md - Count lines matching: ^### Phase (\d+) - Store total phase count - Note whether ### Phase 0 exists (prerequisites gate) — store as HAS_PHASE_0

1. Check each implementation file exists:

- Phase 0 is a manual prerequisites gate — it has no implementation file. Skip it. - For phase 1 to total phases: - Check .codevoyant/plans/{plan-name}/implementation/phase-{N}.md exists - Check file size > 100 bytes (not empty)

1. If any files missing: ❌ Cannot start execution - implementation files missing! Missing implementation files: - phase-3.md - phase-5.md Implementation files are required for all phases before execution. These files should have been created during /spec:new. To fix: 1. Create the missing files in.codevoyant/plans/{plan-name}/implementation/ 2. Use the template structure from /spec:new Step 5.5 3. Or recreate the plan with /spec:new Cannot proceed with background execution. Exit and do not continue to Step 4.
2. If all files exist: ✓ Validated {N} implementation files (phase-1.md through phase-{N}.md)

- Report validation success: - Continue to Step 4

Step 4: Confirm Background Execution

If AUTO_APPROVE is true:

• Skip confirmation
• Report: → Starting background execution with --yes flag
• Proceed directly to Step 5

If AUTO_APPROVE is false:

IMMEDIATELY call the AskUserQuestion tool with exactly these parameters — do NOT print the options as text:

question: "Start background execution for '{plan-name}'? ({N} phases, {M} tasks)\n\nThe agent will:\n✓ Execute all tasks autonomously\n✓ Update plan.md checkboxes in real-time\n✓ Run tests at phase boundaries\n✓ Pause on errors\n[ALLOW_COMMITS=false] ⚠️ Will NOT commit (pass --commit to enable)\n[ALLOW_COMMITS=true] ✓ Will commit as tasks complete\n\nMonitor: /status {plan-name}  |  Stop: /stop {plan-name}"
header: "Start execution?"
multiSelect: false
options:
  - label: "Start execution"
    description: "Launch autonomous agent — you can continue other work while it runs"
  - label: "Cancel"
    description: "Return to prompt without starting"

Wait for the user's response via the tool — do NOT output a numbered list, do NOT print "Please reply with your choice".

Step 5: Initialize Execution Tracking

1. Create or clear .codevoyant/plans/{plan-name}/execution-log.md:

# Execution Log - {plan-name}

Started: [timestamp]
Plan: [plan objective]
Status: RUNNING

## Progress

- Current Phase: [phase name]
- Completed Tasks: 0/[total]
- Errors: 0

## Timeline

[timestamp] - Execution started

1. Update the registry: npx @codevoyant/agent-kit plans update-status --name "$PLAN_NAME" --status Executing
2. Optionally add execution status to plan.md Insights section (if it exists):

## Insights

### Background Execution

- Status: RUNNING
- Started: [timestamp]
- Check progress: /status {plan-name}
- Stop execution: /stop {plan-name}

Step 6: Launch Background Agent

Determine execution directory:

# If worktree exists and should be used (from Step 2.5)
if [ "$WORKTREE_EXISTS" = "true" ] && [ -d "$PLAN_WORKTREE" ]; then
  EXECUTION_DIR="$PLAN_WORKTREE"
  EXECUTION_MODE="worktree"
else
  EXECUTION_DIR=$(pwd)
  EXECUTION_MODE="current"
fi

Important: Before launching agent, change to execution directory:

cd "$EXECUTION_DIR"

Use the Task tool to spawn a spec-executor agent for each phase in sequence:

Agent:
  subagent_type: spec-executor
  description: "spec-executor: Phase {N} — {phase-name}"
  prompt: [agent-prompt.md content with variables substituted]

Read references/agent-prompt.md and substitute {EXECUTION_DIR}, {PLAN_BRANCH}, {PLAN_WORKTREE}, {ALLOW_COMMITS}, {SILENT}, and {plan-name} with their actual values before passing as the prompt.

Phase 0 gate — check before entering the loop:

If HAS_PHASE_0=true, read the Phase 0 task list from plan.md. If any Phase 0 tasks are unchecked ([]):

• Stop. Do not launch any executor agents.
• Present the unchecked tasks to the user: ⛔ Phase 0 — Prerequisites must be completed before execution can begin. The following actions require your attention: [] {task 1} [] {task 2}... Complete these steps, then run /spec:bg again to continue.
• Exit. Do not proceed to Phase 1.

If all Phase 0 tasks are checked ([x]), continue to the orchestration loop starting at Phase 1.

Orchestration loop — for each phase starting at Phase 1:

1. Launch phase Task (spec-executor) with the substituted prompt
2. Wait for completion: TaskOutput (block=true)
3. Parse the agent's summary report
4. Orchestrator writes a phase summary to execution-log.md (reliable fallback): [{timestamp}] ORCHESTRATOR: Phase {N} — {phase-name} summary Status: {COMPLETE | FAILED | PARTIAL} Agent report: {first 3 lines of agent summary}
5. If phase failed: stop loop, send failure notification (see below), report to user
6. If phase succeeded: continue to Phase N+1

After the loop completes (all phases done OR a phase failed), send a desktop notification unless SILENT=true. Use the Bash tool to run:

if [ "$SILENT" != "true" ]; then
  npx @codevoyant/agent-kit notify \
    --title "Claude Code — Spec" \
    --message "{ALL_DONE: Plan '{plan-name}' complete | FAILED: Plan '{plan-name}' stopped at Phase {N}}"
fi

Step 7: Notify User

After launching all phases:

✓ Background execution started for plan "{plan-name}"!

Agent is now working through your plan autonomously.

Monitor progress:
- /status {plan-name} - Check current progress
- /status - View all plans overview
- Watch .codevoyant/plans/{plan-name}/plan.md - See checkboxes update in real-time
- View .codevoyant/plans/{plan-name}/execution-log.md - See detailed execution log

Control execution:
- /stop {plan-name} - Halt execution gracefully
- /pause {plan-name} - Same as /stop (saves state)

You will receive a desktop notification when execution completes or fails.
(Suppress with --silent)

Notes

• The background agent works independently - you can continue chatting
• Progress is saved continuously in.codevoyant/plans/{plan-name}/plan.md and the registry
• If the agent encounters errors, it will pause and preserve state
• Resume with /bg {plan-name} again or use /go {plan-name} for interactive execution
• Check execution status anytime with /status {plan-name} or /status for all plans