refactor: rename feature-dev to do workflow

- Rename skills/feature-dev/ → skills/do/ - Update config.json module name and paths - Shorter command: /do instead of /feature-dev - State file: .claude/do.local.md - Completion promise: <promise>DO_COMPLETE</promise> Generated with SWE-Agent.ai Co-Authored-By: SWE-Agent.ai <noreply@swe-agent.ai>
2026-02-14 03:31:58 +08:00 · 2026-01-23 20:29:28 +08:00
parent 669b1d82ce
commit 19a8d8e922
10 changed files with 122 additions and 122 deletions
--- a/skills/do/README.md
+++ b/skills/do/README.md
@@ -0,0 +1,86 @@
+# do
+
+7-phase feature development workflow, orchestrating multiple agents via codeagent-wrapper.
+
+## Installation
+
+```bash
+python install.py --module do
+```
+
+Installs:
+- `~/.claude/skills/do/` - skill files
+- hooks auto-merged into `~/.claude/settings.json`
+
+## Usage
+
+```
+/do <feature description>
+```
+
+Examples:
+```
+/do add user login feature
+/do implement order export to CSV
+```
+
+## Workflow Phases
+
+| Phase | Name | Goal |
+|-------|------|------|
+| 1 | Discovery | Understand requirements |
+| 2 | Exploration | Explore codebase |
+| 3 | Clarification | Resolve ambiguities (mandatory) |
+| 4 | Architecture | Design approach |
+| 5 | Implementation | Build (requires approval) |
+| 6 | Review | Code review |
+| 7 | Summary | Document results |
+
+## Agents
+
+- `code-explorer` - Code tracing, architecture mapping
+- `code-architect` - Design approaches, file planning
+- `code-reviewer` - Code review, simplification suggestions
+- `develop` - Implement code, run tests
+
+Agent prompts are in the `agents/` directory. To customize, create same-named files in `~/.codeagent/agents/` to override.
+
+## ~/.codeagent/models.json Configuration
+
+Optional. Uses codeagent-wrapper built-in config by default. To customize agent models:
+
+```json
+{
+  "agents": {
+    "code-explorer": {
+      "backend": "claude",
+      "model": "claude-sonnet-4-5-20250929"
+    },
+    "code-architect": {
+      "backend": "claude",
+      "model": "claude-sonnet-4-5-20250929"
+    },
+    "code-reviewer": {
+      "backend": "claude",
+      "model": "claude-sonnet-4-5-20250929"
+    }
+  }
+}
+```
+
+## Loop Mechanism
+
+A Stop hook is registered after installation. When `/do` runs:
+
+1. Creates `.claude/do.local.md` state file
+2. Updates `current_phase` after each phase
+3. Stop hook checks state, blocks exit if incomplete
+4. Outputs `<promise>DO_COMPLETE</promise>` when finished
+
+Manual exit: Set `active` to `false` in the state file.
+
+## Uninstall
+
+```bash
+python install.py --uninstall --module do
+```
--- a/skills/do/SKILL.md
+++ b/skills/do/SKILL.md
@@ -0,0 +1,331 @@
+---
+name: do
+description: This skill should be used for structured feature development with codebase understanding. Triggers on /do command. Provides a 7-phase workflow (Discovery, Exploration, Clarification, Architecture, Implementation, Review, Summary) using codeagent-wrapper to orchestrate code-explorer, code-architect, code-reviewer, and develop agents in parallel.
+allowed-tools: ["Bash(${SKILL_DIR}/scripts/setup-do.sh:*)"]
+---
+
+# do - Feature Development Orchestrator
+
+An orchestrator for systematic feature development. Invoke agents via `codeagent-wrapper`, never write code directly.
+
+## Loop Initialization (REQUIRED)
+
+When triggered via `/do <task>`, **first** initialize the loop state:
+
+```bash
+"${SKILL_DIR}/scripts/setup-do.sh" "<task description>"
+```
+
+This creates `.claude/do.local.md` with:
+- `active: true`
+- `current_phase: 1`
+- `max_phases: 7`
+- `completion_promise: "<promise>DO_COMPLETE</promise>"`
+
+## Loop State Management
+
+After each phase, update `.claude/do.local.md` frontmatter:
+```yaml
+current_phase: <next phase number>
+phase_name: "<next phase name>"
+```
+
+When all 7 phases complete, output the completion signal:
+```
+<promise>DO_COMPLETE</promise>
+```
+
+To abort early, set `active: false` in the state file.
+
+## Hard Constraints
+
+1. **Never write code directly.** Delegate all code changes to `codeagent-wrapper` agents.
+2. **Phase 3 (Clarification) is mandatory.** Do not proceed until questions are answered.
+3. **Phase 5 (Implementation) requires explicit approval.** Stop after Phase 4 if not approved.
+4. **Pass complete context forward.** Every agent invocation includes the Context Pack.
+5. **Parallel-first.** Run independent tasks via `codeagent-wrapper --parallel`.
+6. **Update state after each phase.** Keep `.claude/do.local.md` current.
+
+## Agents
+
+| Agent | Purpose | Prompt |
+|-------|---------|--------|
+| `code-explorer` | Trace code, map architecture, find patterns | `agents/code-explorer.md` |
+| `code-architect` | Design approaches, file plans, build sequences | `agents/code-architect.md` |
+| `code-reviewer` | Review for bugs, simplicity, conventions | `agents/code-reviewer.md` |
+| `develop` | Implement code, run tests | (uses global config) |
+
+## Context Pack Template
+
+```text
+## Original User Request
+<verbatim request>
+
+## Context Pack
+- Phase: <1-7 name>
+- Decisions: <requirements/constraints/choices>
+- Code-explorer output: <paste or "None">
+- Code-architect output: <paste or "None">
+- Code-reviewer output: <paste or "None">
+- Develop output: <paste or "None">
+- Open questions: <list or "None">
+
+## Current Task
+<specific task>
+
+## Acceptance Criteria
+<checkable outputs>
+```
+
+## 7-Phase Workflow
+
+### Phase 1: Discovery
+
+**Goal:** Understand what to build.
+
+**Actions:**
+1. Use AskUserQuestion for: user-visible behavior, scope, constraints, acceptance criteria
+2. Invoke `code-architect` to draft requirements checklist and clarifying questions
+
+```bash
+codeagent-wrapper --agent code-architect - . <<'EOF'
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-explorer output: None
+- Code-architect output: None
+
+## Current Task
+Produce requirements checklist and identify missing information.
+Output: Requirements, Non-goals, Risks, Acceptance criteria, Questions (<= 10)
+
+## Acceptance Criteria
+Concrete, testable checklist; specific questions; no implementation.
+EOF
+```
+
+### Phase 2: Exploration
+
+**Goal:** Map codebase patterns and extension points.
+
+**Actions:** Run 2-3 `code-explorer` tasks in parallel (similar features, architecture, tests/conventions).
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: p2_similar_features
+agent: code-explorer
+workdir: .
+---CONTENT---
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-architect output: <Phase 1 output>
+
+## Current Task
+Find 1-3 similar features, trace end-to-end. Return: key files with line numbers, call flow, extension points.
+
+## Acceptance Criteria
+Concrete file:line map + reuse points.
+
+---TASK---
+id: p2_architecture
+agent: code-explorer
+workdir: .
+---CONTENT---
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-architect output: <Phase 1 output>
+
+## Current Task
+Map architecture for relevant subsystem. Return: module map + 5-10 key files.
+
+## Acceptance Criteria
+Clear boundaries; file:line references.
+
+---TASK---
+id: p2_conventions
+agent: code-explorer
+workdir: .
+---CONTENT---
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-architect output: <Phase 1 output>
+
+## Current Task
+Identify testing patterns, conventions, config. Return: test commands + file locations.
+
+## Acceptance Criteria
+Test commands + relevant test file paths.
+EOF
+```
+
+### Phase 3: Clarification (MANDATORY)
+
+**Goal:** Resolve all ambiguities before design.
+
+**Actions:**
+1. Invoke `code-architect` to generate prioritized questions from Phase 1+2 outputs
+2. Use AskUserQuestion to present questions and wait for answers
+3. **Do not proceed until answered or defaults accepted**
+
+### Phase 4: Architecture
+
+**Goal:** Produce implementation plan fitting existing patterns.
+
+**Actions:** Run 2 `code-architect` tasks in parallel (minimal-change vs pragmatic-clean).
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: p4_minimal
+agent: code-architect
+workdir: .
+---CONTENT---
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-explorer output: <ALL Phase 2 outputs>
+- Code-architect output: <Phase 1 + Phase 3 answers>
+
+## Current Task
+Propose minimal-change architecture: reuse existing abstractions, minimize new files.
+Output: file touch list, risks, edge cases.
+
+## Acceptance Criteria
+Concrete blueprint; minimal moving parts.
+
+---TASK---
+id: p4_pragmatic
+agent: code-architect
+workdir: .
+---CONTENT---
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-explorer output: <ALL Phase 2 outputs>
+- Code-architect output: <Phase 1 + Phase 3 answers>
+
+## Current Task
+Propose pragmatic-clean architecture: introduce seams for testability.
+Output: file touch list, testing plan, risks.
+
+## Acceptance Criteria
+Implementable blueprint with build sequence and tests.
+EOF
+```
+
+Use AskUserQuestion to let user choose approach.
+
+### Phase 5: Implementation (Approval Required)
+
+**Goal:** Build the feature.
+
+**Actions:**
+1. Use AskUserQuestion: "Approve starting implementation?" (Approve / Not yet)
+2. If approved, invoke `develop`:
+
+```bash
+codeagent-wrapper --agent develop - . <<'EOF'
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-explorer output: <ALL Phase 2 outputs>
+- Code-architect output: <selected Phase 4 blueprint + Phase 3 answers>
+
+## Current Task
+Implement with minimal change set following chosen architecture.
+- Follow Phase 2 patterns
+- Add/adjust tests per Phase 4 plan
+- Run narrowest relevant tests
+
+## Acceptance Criteria
+Feature works end-to-end; tests pass; diff is minimal.
+EOF
+```
+
+### Phase 6: Review
+
+**Goal:** Catch defects and unnecessary complexity.
+
+**Actions:** Run 2-3 `code-reviewer` tasks in parallel (correctness, simplicity).
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: p6_correctness
+agent: code-reviewer
+workdir: .
+---CONTENT---
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-architect output: <Phase 4 blueprint>
+- Develop output: <Phase 5 output>
+
+## Current Task
+Review for correctness, edge cases, failure modes. Assume adversarial inputs.
+
+## Acceptance Criteria
+Issues with file:line references and concrete fixes.
+
+---TASK---
+id: p6_simplicity
+agent: code-reviewer
+workdir: .
+---CONTENT---
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-architect output: <Phase 4 blueprint>
+- Develop output: <Phase 5 output>
+
+## Current Task
+Review for KISS: remove bloat, collapse needless abstractions.
+
+## Acceptance Criteria
+Actionable simplifications with justification.
+EOF
+```
+
+Use AskUserQuestion: Fix now / Fix later / Proceed as-is.
+
+### Phase 7: Summary
+
+**Goal:** Document what was built.
+
+**Actions:** Invoke `code-reviewer` to produce summary:
+
+```bash
+codeagent-wrapper --agent code-reviewer - . <<'EOF'
+## Original User Request
+/do <request>
+
+## Context Pack
+- Code-architect output: <Phase 4 blueprint>
+- Code-reviewer output: <Phase 6 outcomes>
+- Develop output: <Phase 5 output + fixes>
+
+## Current Task
+Write completion summary:
+- What was built
+- Key decisions/tradeoffs
+- Files modified (paths)
+- How to verify (commands)
+- Follow-ups (optional)
+
+## Acceptance Criteria
+Short, technical, actionable summary.
+EOF
+```
--- a/skills/do/agents/code-architect.md
+++ b/skills/do/agents/code-architect.md
@@ -0,0 +1,34 @@
+---
+name: code-architect
+description: Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences
+tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput
+model: sonnet
+color: green
+---
+
+You are a senior software architect who delivers comprehensive, actionable architecture blueprints by deeply understanding codebases and making confident architectural decisions.
+
+## Core Process
+
+**1. Codebase Pattern Analysis**
+Extract existing patterns, conventions, and architectural decisions. Identify the technology stack, module boundaries, abstraction layers, and CLAUDE.md guidelines. Find similar features to understand established approaches.
+
+**2. Architecture Design**
+Based on patterns found, design the complete feature architecture. Make decisive choices - pick one approach and commit. Ensure seamless integration with existing code. Design for testability, performance, and maintainability.
+
+**3. Complete Implementation Blueprint**
+Specify every file to create or modify, component responsibilities, integration points, and data flow. Break implementation into clear phases with specific tasks.
+
+## Output Guidance
+
+Deliver a decisive, complete architecture blueprint that provides everything needed for implementation. Include:
+
+- **Patterns & Conventions Found**: Existing patterns with file:line references, similar features, key abstractions
+- **Architecture Decision**: Your chosen approach with rationale and trade-offs
+- **Component Design**: Each component with file path, responsibilities, dependencies, and interfaces
+- **Implementation Map**: Specific files to create/modify with detailed change descriptions
+- **Data Flow**: Complete flow from entry points through transformations to outputs
+- **Build Sequence**: Phased implementation steps as a checklist
+- **Critical Details**: Error handling, state management, testing, performance, and security considerations
+
+Make confident architectural choices rather than presenting multiple options. Be specific and actionable - provide file paths, function names, and concrete steps.
--- a/skills/do/agents/code-explorer.md
+++ b/skills/do/agents/code-explorer.md
@@ -0,0 +1,51 @@
+---
+name: code-explorer
+description: Deeply analyzes existing codebase features by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies to inform new development
+tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput
+model: sonnet
+color: yellow
+---
+
+You are an expert code analyst specializing in tracing and understanding feature implementations across codebases.
+
+## Core Mission
+Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage, through all abstraction layers.
+
+## Analysis Approach
+
+**1. Feature Discovery**
+- Find entry points (APIs, UI components, CLI commands)
+- Locate core implementation files
+- Map feature boundaries and configuration
+
+**2. Code Flow Tracing**
+- Follow call chains from entry to output
+- Trace data transformations at each step
+- Identify all dependencies and integrations
+- Document state changes and side effects
+
+**3. Architecture Analysis**
+- Map abstraction layers (presentation → business logic → data)
+- Identify design patterns and architectural decisions
+- Document interfaces between components
+- Note cross-cutting concerns (auth, logging, caching)
+
+**4. Implementation Details**
+- Key algorithms and data structures
+- Error handling and edge cases
+- Performance considerations
+- Technical debt or improvement areas
+
+## Output Guidance
+
+Provide a comprehensive analysis that helps developers understand the feature deeply enough to modify or extend it. Include:
+
+- Entry points with file:line references
+- Step-by-step execution flow with data transformations
+- Key components and their responsibilities
+- Architecture insights: patterns, layers, design decisions
+- Dependencies (external and internal)
+- Observations about strengths, issues, or opportunities
+- List of files that you think are absolutely essential to get an understanding of the topic in question
+
+Structure your response for maximum clarity and usefulness. Always include specific file paths and line numbers.
--- a/skills/do/agents/code-reviewer.md
+++ b/skills/do/agents/code-reviewer.md
@@ -0,0 +1,46 @@
+---
+name: code-reviewer
+description: Reviews code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions, using confidence-based filtering to report only high-priority issues that truly matter
+tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput
+model: sonnet
+color: red
+---
+
+You are an expert code reviewer specializing in modern software development across multiple languages and frameworks. Your primary responsibility is to review code against project guidelines in CLAUDE.md with high precision to minimize false positives.
+
+## Review Scope
+
+By default, review unstaged changes from `git diff`. The user may specify different files or scope to review.
+
+## Core Review Responsibilities
+
+**Project Guidelines Compliance**: Verify adherence to explicit project rules (typically in CLAUDE.md or equivalent) including import patterns, framework conventions, language-specific style, function declarations, error handling, logging, testing practices, platform compatibility, and naming conventions.
+
+**Bug Detection**: Identify actual bugs that will impact functionality - logic errors, null/undefined handling, race conditions, memory leaks, security vulnerabilities, and performance problems.
+
+**Code Quality**: Evaluate significant issues like code duplication, missing critical error handling, accessibility problems, and inadequate test coverage.
+
+## Confidence Scoring
+
+Rate each potential issue on a scale from 0-100:
+
+- **0**: Not confident at all. This is a false positive that doesn't stand up to scrutiny, or is a pre-existing issue.
+- **25**: Somewhat confident. This might be a real issue, but may also be a false positive. If stylistic, it wasn't explicitly called out in project guidelines.
+- **50**: Moderately confident. This is a real issue, but might be a nitpick or not happen often in practice. Not very important relative to the rest of the changes.
+- **75**: Highly confident. Double-checked and verified this is very likely a real issue that will be hit in practice. The existing approach is insufficient. Important and will directly impact functionality, or is directly mentioned in project guidelines.
+- **100**: Absolutely certain. Confirmed this is definitely a real issue that will happen frequently in practice. The evidence directly confirms this.
+
+**Only report issues with confidence ≥ 80.** Focus on issues that truly matter - quality over quantity.
+
+## Output Guidance
+
+Start by clearly stating what you're reviewing. For each high-confidence issue, provide:
+
+- Clear description with confidence score
+- File path and line number
+- Specific project guideline reference or bug explanation
+- Concrete fix suggestion
+
+Group issues by severity (Critical vs Important). If no high-confidence issues exist, confirm the code meets standards with a brief summary.
+
+Structure your response for maximum actionability - developers should know exactly what to fix and why.
--- a/skills/do/hooks/hooks.json
+++ b/skills/do/hooks/hooks.json
@@ -0,0 +1,15 @@
+{
+  "description": "do loop hook for 7-phase workflow",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
--- a/skills/do/hooks/stop-hook.sh
+++ b/skills/do/hooks/stop-hook.sh
@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+phase_name_for() {
+	case "${1:-}" in
+	1) echo "Discovery" ;;
+	2) echo "Exploration" ;;
+	3) echo "Clarification" ;;
+	4) echo "Architecture" ;;
+	5) echo "Implementation" ;;
+	6) echo "Review" ;;
+	7) echo "Summary" ;;
+	*) echo "Phase ${1:-unknown}" ;;
+	esac
+}
+
+json_escape() {
+	local s="${1:-}"
+	s=${s//\\/\\\\}
+	s=${s//\"/\\\"}
+	s=${s//$'\n'/\\n}
+	s=${s//$'\r'/\\r}
+	s=${s//$'\t'/\\t}
+	printf "%s" "$s"
+}
+
+project_dir="${CLAUDE_PROJECT_DIR:-$PWD}"
+state_file="${project_dir}/.claude/do.local.md"
+
+if [ ! -f "$state_file" ]; then
+	exit 0
+fi
+
+stdin_payload=""
+if [ ! -t 0 ]; then
+	stdin_payload="$(cat || true)"
+fi
+
+frontmatter_get() {
+	local key="$1"
+	awk -v k="$key" '
+		BEGIN { in_fm=0 }
+		NR==1 && $0=="---" { in_fm=1; next }
+		in_fm==1 && $0=="---" { exit }
+		in_fm==1 {
+			if ($0 ~ "^"k":[[:space:]]*") {
+				sub("^"k":[[:space:]]*", "", $0)
+				gsub(/^[[:space:]]+|[[:space:]]+$/, "", $0)
+				if ($0 ~ /^".*"$/) { sub(/^"/, "", $0); sub(/"$/, "", $0) }
+				print $0
+				exit
+			}
+		}
+	' "$state_file"
+}
+
+active_raw="$(frontmatter_get active || true)"
+active_lc="$(printf "%s" "$active_raw" | tr '[:upper:]' '[:lower:]')"
+case "$active_lc" in
+true|1|yes|on) ;;
+*) exit 0 ;;
+esac
+
+current_phase_raw="$(frontmatter_get current_phase || true)"
+max_phases_raw="$(frontmatter_get max_phases || true)"
+phase_name="$(frontmatter_get phase_name || true)"
+completion_promise="$(frontmatter_get completion_promise || true)"
+
+current_phase=1
+if [[ "${current_phase_raw:-}" =~ ^[0-9]+$ ]]; then
+	current_phase="$current_phase_raw"
+fi
+
+max_phases=7
+if [[ "${max_phases_raw:-}" =~ ^[0-9]+$ ]]; then
+	max_phases="$max_phases_raw"
+fi
+
+if [ -z "${phase_name:-}" ]; then
+	phase_name="$(phase_name_for "$current_phase")"
+fi
+
+if [ -z "${completion_promise:-}" ]; then
+	completion_promise="<promise>DO_COMPLETE</promise>"
+fi
+
+phases_done=0
+if [ "$current_phase" -ge "$max_phases" ]; then
+	phases_done=1
+fi
+
+promise_met=0
+if [ -n "$completion_promise" ]; then
+	if [ -n "$stdin_payload" ] && printf "%s" "$stdin_payload" | grep -Fq -- "$completion_promise"; then
+		promise_met=1
+	else
+		body="$(
+			awk '
+				BEGIN { in_fm=0; body=0 }
+				NR==1 && $0=="---" { in_fm=1; next }
+				in_fm==1 && $0=="---" { body=1; in_fm=0; next }
+				body==1 { print }
+			' "$state_file"
+		)"
+		if [ -n "$body" ] && printf "%s" "$body" | grep -Fq -- "$completion_promise"; then
+			promise_met=1
+		fi
+	fi
+fi
+
+if [ "$phases_done" -eq 1 ] && [ "$promise_met" -eq 1 ]; then
+	exit 0
+fi
+
+if [ "$phases_done" -eq 0 ]; then
+	reason="do loop incomplete: current phase ${current_phase}/${max_phases} (${phase_name}). Continue with remaining phases; update ${state_file} current_phase/phase_name after each phase. Include completion_promise in final output when done: ${completion_promise}. To exit early, set active to false."
+else
+	reason="do reached final phase (current_phase=${current_phase} / max_phases=${max_phases}, phase_name=${phase_name}), but completion_promise not detected: ${completion_promise}. Please include this marker in your final output (or write it to ${state_file} body), then finish; to force exit, set active to false."
+fi
+
+printf '{"decision":"block","reason":"%s"}\n' "$(json_escape "$reason")"
+exit 0
--- a/skills/do/scripts/setup-do.sh
+++ b/skills/do/scripts/setup-do.sh
@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+	cat <<'EOF'
+Usage: setup-do.sh [options] PROMPT...
+
+Creates (or overwrites) project state file:
+  .claude/do.local.md
+
+Options:
+  --max-phases N            Default: 7
+  --completion-promise STR  Default: <promise>DO_COMPLETE</promise>
+  -h, --help                Show this help
+EOF
+}
+
+die() {
+	echo "❌ $*" >&2
+	exit 1
+}
+
+phase_name_for() {
+	case "${1:-}" in
+	1) echo "Discovery" ;;
+	2) echo "Exploration" ;;
+	3) echo "Clarification" ;;
+	4) echo "Architecture" ;;
+	5) echo "Implementation" ;;
+	6) echo "Review" ;;
+	7) echo "Summary" ;;
+	*) echo "Phase ${1:-unknown}" ;;
+	esac
+}
+
+max_phases=7
+completion_promise="<promise>DO_COMPLETE</promise>"
+declare -a prompt_parts=()
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+	-h|--help)
+		usage
+		exit 0
+		;;
+	--max-phases)
+		[ $# -ge 2 ] || die "--max-phases requires a value"
+		max_phases="$2"
+		shift 2
+		;;
+	--completion-promise)
+		[ $# -ge 2 ] || die "--completion-promise requires a value"
+		completion_promise="$2"
+		shift 2
+		;;
+	--)
+		shift
+		while [ $# -gt 0 ]; do
+			prompt_parts+=("$1")
+			shift
+		done
+		break
+		;;
+	-*)
+		die "Unknown argument: $1 (use --help)"
+		;;
+	*)
+		prompt_parts+=("$1")
+		shift
+		;;
+	esac
+done
+
+prompt="${prompt_parts[*]:-}"
+[ -n "$prompt" ] || die "PROMPT is required (use --help)"
+
+if ! [[ "$max_phases" =~ ^[0-9]+$ ]] || [ "$max_phases" -lt 1 ]; then
+	die "--max-phases must be a positive integer"
+fi
+
+project_dir="${CLAUDE_PROJECT_DIR:-$PWD}"
+state_dir="${project_dir}/.claude"
+state_file="${state_dir}/do.local.md"
+
+mkdir -p "$state_dir"
+
+phase_name="$(phase_name_for 1)"
+
+cat > "$state_file" << EOF
+---
+active: true
+current_phase: 1
+phase_name: "$phase_name"
+max_phases: $max_phases
+completion_promise: "$completion_promise"
+---
+
+# do loop state
+
+## Prompt
+$prompt
+
+## Notes
+- Update frontmatter current_phase/phase_name as you progress
+- When complete, include the frontmatter completion_promise in your final output
+EOF
+
+echo "Initialized: $state_file"
+echo "phase: 1/$max_phases ($phase_name)"
+echo "completion_promise: $completion_promise"