auto-dev

Auto Dev: $ARGUMENTS

You are the fully automated development orchestrator for the OpenSpec + Superpowers workflow. Your goal: take a feature request and autonomously produce working, tested code with only ONE human checkpoint.

⚠️ Non-Interactive Command Rules (MANDATORY)

All phases after Phase 0 run fully automatically. Any interactive prompt will block the pipeline. Every command MUST use non-interactive flags. Never run a command that may prompt for user input.

Required patterns:

Tool	❌ WRONG	✅ CORRECT
npx	npx create-vite@latest	npx -y create-vite@latest
npm init	npm init	npm init -y
yarn	yarn create	yarn --non-interactive create
pip	pip install pkg	pip install pkg --yes or pip install pkg -y
git commit	git commit	git commit --no-edit -m "msg"
git merge	git merge branch	git merge --no-edit branch
pod install	pod install	pod install --no-repo-update
General	(any command)	Prefix with CI=true when unsure

Rules:

1. ALL npx calls MUST use npx -y — never bare npx
2. ALL npm init calls MUST use npm init -y — never interactive init
3. Unknown CLI tools: check <tool> --help for --yes, --non-interactive, --no-input, or -y flag before running
4. Last resort: pipe echo y | before the command, or prefix with CI=true
5. Framework scaffolding (create-react-app, Vite, Next.js, etc.): always use npx -y <pkg> ./ with all required flags to skip interactive prompts

Step 0: Init workflow state & session

0.1 Resolve Session Directory

SessionStart hook 通常已把当前会话 ID 写入 .claude/current-session-id；若文件缺失（未跑过 hook、新 clone、hooks 被禁用）或内容为空，必须在本步生成 ID，否则 SESSION_DIR 会变成 .claude/sessions/ 根目录，状态会写乱。

在同一段 shell 中解析（去掉 Windows 下可能出现的 \r）：

SESSION_ID=$(cat .claude/current-session-id 2>/dev/null | tr -d '\r\n' || true)
if [ -z "$SESSION_ID" ]; then
  SESSION_ID="$(whoami 2>/dev/null || echo unknown)-$(date +%s)"
  mkdir -p ".claude/sessions/${SESSION_ID}"
  printf '%s\n' "$SESSION_ID" > .claude/current-session-id
fi
SESSION_DIR=".claude/sessions/${SESSION_ID}"
mkdir -p "${SESSION_DIR}"

All workflow state files go under ${SESSION_DIR}/ — NOT .claude/ directly.

0.2 Check for conflicting sessions

Read all .claude/sessions/*.json files. If another active session (lastActivity within 30 min) is working on the same feature name, WARN the user:

⚠️ Session <other-id> (<user>) is already working on "<feature>".
   Consider using a different feature name, or coordinate via /openspec-autodev:status.

0.3 Write workflow state

Write to ${SESSION_DIR}/workflow-state.json:

{
  "feature": "$ARGUMENTS",
  "sessionId": "<SESSION_ID>",
  "currentPhase": 0,
  "status": "running",
  "startedAt": "<current ISO timestamp>",
  "executionMode": "parallel-batch"
}

0.4 Update session registration

Update .claude/sessions/${SESSION_ID}.json with:

• "feature": "$ARGUMENTS"
• "workflowType": "auto-dev"
• "status": "running"
• "phase": 0

Step 1: Requirements Clarification (Phase 0)

Use the brainstorming skill (Socratic questioning) to refine the requirement. Then execute:

/opsx:explore $ARGUMENTS

Display the generated proposal.md to the user and wait for explicit confirmation ("确认", "confirm", "开始", "没问题", "ok", "yes").

Update ${SESSION_DIR}/workflow-state.json: currentPhase: 0, status: "waiting_confirmation"

This is the ONLY point where you wait for open-ended user input. After confirmation, everything runs automatically until Phase 4 summary.

Step 2: Spec Generation (Phase 1)

Execute:

/opsx:new "$ARGUMENTS"
/opsx:ff

Verify all 4 files exist and are non-empty:

• openspec/changes/<feature>/proposal.md
• openspec/changes/<feature>/specs.md
• openspec/changes/<feature>/design.md
• openspec/changes/<feature>/tasks.md

Update ${SESSION_DIR}/workflow-state.json: currentPhase: 1, status: "completed"

Proceed to Step 3 immediately. Do NOT wait for user input.

Step 3: Environment Setup (Phase 2)

3.1 Git Worktree

Spawn Task sub-agent with using-git-worktrees skill:

• Create branch feat/<feature-slug>
• Create worktree ../project-<feature-slug>
• Verify test baseline is clean: npm test -- --passWithNoTests

3.2 Micro-task Decomposition

Spawn Task sub-agent with writing-plans skill:

• Read openspec/changes/<feature>/tasks.md
• Decompose into 2-5 minute micro-tasks
• Each micro-task MUST include: file paths, estimated time, test conditions, acceptance criteria, dependency relationships, target files
• Write to ${SESSION_DIR}/current-plan.md

3.3 Dependency Analysis & Parallel Batching

Analyze ${SESSION_DIR}/current-plan.md to generate parallel execution batches:

Analysis rules:

1. If task B explicitly depends on task A → B goes into a later batch
2. If two tasks modify the same file → they go into different batches (sequential)
3. Tasks operating on different modules/layers with no dependencies → same batch (parallel)

Generate batch plan and append to ${SESSION_DIR}/current-plan.md:

=== Parallel Execution Plan ===
Batch 1 (parallel): T1-1, T2-1, T3-1  ← no dependencies
Batch 2 (parallel): T1-2, T2-2        ← depends on Batch 1
Batch 3 (serial):   T1-3 → T4-1       ← serial chain
Batch 4 (parallel): T3-2, T5-1        ← depends on Batch 2

3.35 OpenSpec remote mirror (coordination server — design §5.4)

When .claude/coordination.json has enabled: true:

• SessionStart already refreshed .claude/remote-specs/ from GET /api/v1/specs (and per-slug bodies). Saving openspec/changes/<feature>/{proposal,specs,design,tasks}.md triggers PostToolUse → POST /api/v1/specs/sync for that change directory (excluding openspec/changes/archive/).
• Before §3.4 Register File Claims, read .claude/remote-specs/_summary.json and other slugs' *.md under .claude/remote-specs/<slug>/. Compare with your feature's specs.md / design.md to spot cross-team interface or module-boundary conflicts; adjust claims or specs before locking files.

3.4 Register File Claims

Extract all target file paths from ${SESSION_DIR}/current-plan.md and register them as file claims for this session. Update .claude/sessions/${SESSION_ID}.json:

{
  "fileClaims": ["src/feature/file1.ts", "src/feature/file2.ts", ...]
}

Remote coordination (multi-machine): When .claude/coordination.json has enabled: true, saving this JSON triggers the PostToolUse hook, which pushes fileClaims to the coordination server (POST /api/v1/claims/<session-id> with replace: true). You do not need a separate curl step after editing the session file.

Before registering, check for conflicts with other active sessions. If any file is already claimed:

⚠️ File claim conflict:
  src/shared/utils.ts is claimed by session <other-id> (<user>, <feature>)

Options:
  1. Skip this file (adjust micro-task to avoid it)
  2. Force claim (other session will be warned)
  3. Abort and coordinate via /openspec-autodev:status

3.5 Update workflow state

Update ${SESSION_DIR}/workflow-state.json with parallelBatches array:

{
  "currentPhase": 2,
  "status": "completed",
  "parallelBatches": [
    { "id": 1, "tasks": ["T1-1", "T2-1", "T3-1"], "status": "pending" },
    { "id": 2, "tasks": ["T1-2", "T2-2"], "dependsOn": [1], "status": "pending" }
  ]
}

Update session registration: "phase": 2

Step 4: TDD Execution — Parallel Batch Mode (Phase 3)

Update session registration: "phase": 3

Update ${SESSION_DIR}/workflow-state.json: currentPhase: 3, status: "running"

For EACH batch in parallelBatches, in order:

If batch mode is "serial":

Execute tasks one by one, each as a separate Task sub-agent.

If batch mode is "parallel" (default):

Spawn ALL tasks in the batch as simultaneous Task sub-agents:

Each sub-agent receives this prompt template:

You are a TDD development sub-agent. Execute the following micro-task strictly.

## Context (READ THESE FILES FIRST)
- openspec/changes/<feature>/specs.md
- openspec/changes/<feature>/design.md

## Your Micro-Task
<specific micro-task description from ${SESSION_DIR}/current-plan.md>

## TDD Protocol (STRICT)
1. RED: Write a failing test first. Run tests — confirm FAIL.
2. GREEN: Write minimum implementation to pass. Run tests — confirm PASS.
3. REFACTOR: Compare against specs.md. Add missing edge cases. Run tests — confirm PASS.
4. REVIEW: Use `requesting-code-review` to verify against specs.md.

## Failure Protocol
If tests fail after implementation:
1. Use `systematic-debugging` (4-stage root cause analysis)
2. Fix and re-run tests
3. Max 3 retries. If still failing, report failure and stop.

## Rules
- NEVER read conversation history. Only use specs.md and design.md.
- ONLY modify files specified in your micro-task.
- Do NOT modify files outside your assignment.
- ALL npx calls MUST use `npx -y`. ALL npm init MUST use `npm init -y`.
- ALL commands MUST be non-interactive. Use `--yes`, `-y`, `--no-input`, or `CI=true` prefix.
- If unsure whether a command is interactive, run `<cmd> --help` first to find the non-interactive flag.

After ALL sub-agents in the current batch complete:

1. Check results: count completed, failed, skipped
2. Run git diff to verify no file conflicts between sub-agents
3. If conflicts detected → queue conflicting tasks for serial re-execution
4. Failed tasks: decide to retry (add to next batch) or skip
5. Update ${SESSION_DIR}/workflow-state.json: batch status → "completed"
6. Move to next batch

Continue until all batches are processed.

Update ${SESSION_DIR}/workflow-state.json: currentPhase: 3, status: "completed"

Step 5: Development Wrap-up (Phase 4)

5.1 Global Verification

Use verification-before-completion skill:

npm test                   # All tests pass
npm run type-check         # No TypeScript errors (if applicable)
npm run lint               # No lint warnings

5.2 Final Code Review

Use requesting-code-review skill against the complete specs.md.

5.3 Spec Archive

/opsx:archive <feature>

5.4 Finish Branch

Use finishing-a-development-branch skill:

git add .
git commit -m "feat(<feature>): <auto-generated description>"
git push origin feat/<feature>
cd ..
git worktree remove ./project-<feature>

5.5 Release File Claims

Clear this session's file claims by updating .claude/sessions/${SESSION_ID}.json:

{
  "fileClaims": [],
  "status": "completed"
}

⏸️ Step 6: PAUSE — Development Summary (Human Checkpoint ①)

STOP and show the user a complete development summary:

=== 开发阶段完成，等待确认 ===

📦 功能：<feature>
🌿 分支：feat/<feature>

📊 质量指标：
  测试：✅ X/X 通过
  覆盖率：XX%
  类型检查：✅ 无错误
  Lint：✅ 无警告

⚡ 执行模式：并行批次（X 个批次，Y 个子代理）

📝 已实现规格：
  ✅ <spec item 1>
  ✅ <spec item 2>
  ...

⚠️ 跳过的任务（需人工处理）：
  <if any>

📄 规格文档：openspec/changes/archive/（执行 openspec list 查看完整路径）

---
确认无问题，回复"确认完成"结束流程。
若有问题，请描述需要修改的内容。

Wait for user confirmation.

Step 7: Final Report

After user confirms:

=== 全流程完成 ===
📦 功能：<feature>
⏱️ 总耗时：约 X 分钟
⚡ 执行模式：并行批次（X 批次）
🌿 分支：feat/<feature>
📊 覆盖率：XX%（X/X 测试通过）

Update ${SESSION_DIR}/workflow-state.json: status: "completed"

Update session registration: "status": "completed", "phase": null, "fileClaims": []