wf-init

name	wf-init
description	Initialize the feature workflow for a project — detects tech stack, proposes review agents (asks user to confirm), creates agent files and project-config.json.
allowed-tools	Read, Glob, Grep, Bash, Write, AskUserQuestion
model	sonnet

Workflow Init: Bootstrap Project Workflow

Set up the 6-phase feature development workflow for this project by detecting the tech stack, proposing appropriate review agents, and creating the necessary config files.

Instructions

Step 0: Check for Existing Setup

1. Check if .claude/workflow/project-config.json exists
2. Check if .claude/agents/ directory has any .md files

If both exist:

• Use AskUserQuestion:
  • header: "Already configured"
  • question: "This project already has workflow config and agents. What would you like to do?"
  • option1: label="Add missing agents only", description="Keep existing agents, generate any that are missing"
  • option2: label="Re-run full setup", description="Regenerate all agents and overwrite project-config.json"
  • option3: label="Cancel", description="Exit without changes"
• Exit if user selects "Cancel"
• Set a flag replaceAgents=true if user selects "Re-run full setup"

Step 1: Detect Tech Stack

Read as many of these as exist (use Glob and Read in parallel):

• package.json — Node/TypeScript stack, frontend framework, scripts
• pom.xml — Java/Maven, Spring Boot version
• build.gradle or build.gradle.kts — Java/Gradle
• requirements.txt or pyproject.toml — Python stack
• go.mod — Go
• Cargo.toml — Rust
• CLAUDE.md — Project-specific conventions and patterns
• README.md — High-level project description

Also glob to confirm languages present:

• find . -name "*.java" -not -path "*/target/*" | head -5
• find . -name "*.ts" -not -path "*/node_modules/*" | head -5
• find . -name "*.py" | head -5
• find . -name "*.go" | head -5

Note frameworks detected (Spring Boot, React, FastAPI, Django, Express, Vue, etc.). Note if this is a game project (look for: tick, game loop, mechanics, combat, etc. in CLAUDE.md or README).

Step 2: Propose Agents to User

Based on the detected tech stack, build a candidate agent list. Show only agents that are relevant — don't list all 9 for a simple single-language project.

Candidate signals:

• backend-dev — Java/Spring, Python/FastAPI, Node/Express, Go, Rust server code
• frontend-dev — React, Vue, Angular, .tsx/.jsx files, TypeScript frontend
• database-dev — SQL migration files (Flyway, Alembic, etc.), ORM config, schema files
• api-designer — REST controllers, OpenAPI/Swagger, HTTP endpoint definitions
• game-engine-dev — Game loop, tick system, game mechanics (in CLAUDE.md or README)
• game-designer — Game balance formulas, rule documentation, mechanics docs
• devops — Dockerfile, docker-compose.yml, CI/CD config (.github/workflows/, etc.)
• ux-designer — Frontend project + user-facing flows, forms, UI components
• qa-engineer — Always included unless user removes it

Use AskUserQuestion with multiSelect: true:

• header: "Review agents"
• question: "I detected [summarize stack in 1 line]. Which agents should review features in this project? (qa-engineer is recommended for all projects)"
• List each relevant candidate as an option with a 1-line description of what it reviews
• Pre-select the candidates that match detected signals (pre-select qa-engineer always)

Step 3: Generate Agent Files

For each confirmed agent, check if .claude/agents/{name}.md already exists.

• Skip if it exists AND replaceAgents is not set
• Otherwise generate it

To generate an agent file, write .claude/agents/{name}.md with this structure:

---
name: {agent-name}
description: {agent focus area — used to decide relevance in phase2 agent selection}
tools: Read, Glob, Grep
model: opus
---

# {Agent Role} Review Agent

Review implementation plans for {focus area} in this project.

## Project Context

{Summarize the relevant tech stack for this agent — e.g. for backend-dev: "Spring Boot 3.x,
Java 25, NATS messaging, PostgreSQL" or for frontend-dev: "React 18, TypeScript, Vite".
Pull from what you detected in Step 1. If CLAUDE.md exists, pull the most relevant
conventions for this agent's domain.}

## Focus Areas

{List 4-6 specific things this agent should check, tailored to the detected stack.
Examples for backend-dev in a Spring Boot project:
- Service layer design and transaction boundaries
- REST API contract correctness
- Spring patterns (constructor injection, @Transactional, etc.)
- Error handling and HTTP status codes
- Security (JWT validation, input sanitization)}

## Key Patterns to Enforce

{List 3-5 project-specific patterns from CLAUDE.md that this agent should watch for,
or generic best practices for the stack if CLAUDE.md is absent.}

## Review Process

1. Read the spec thoroughly
2. Identify concerns in your focus areas
3. Check against key patterns above
4. Provide structured feedback

## Output Format

**Strengths**: What's done well in the spec
**Concerns**: Issues to address (mark CRITICAL for blocking issues)
**Recommendations**: Suggestions for improvement
**Verdict**: APPROVED / APPROVED WITH REVISIONS / NEEDS REVISION

Generate content for each agent using what you know about the detected stack and any conventions in CLAUDE.md. Make the agent content specific to this project's tech stack, not generic boilerplate.

Step 4: Write Project Config

Ask the user to confirm path defaults:

Use AskUserQuestion:

• header: "Project paths"
• question: "Confirm or adjust the workflow paths for this project:"
• option1: label="Use defaults (docs/specs, ROADMAP.md)", description="specDir=docs/specs, archiveDir=docs/specs/archive, roadmapFile=ROADMAP.md"
• option2: label="Customize paths", description="Enter custom paths for spec directory, archive, and roadmap file"

If "Use defaults" — write config with defaults. If "Customize paths" — ask a follow-up for each path (or accept an "Other" text input).

Before writing, check:

• Does {specDir} directory exist? Warn if not (it will be created by wf-phase1-spec)
• Does {roadmapFile} exist? Warn if not (wf-phase1-spec needs it to suggest features)

Write .claude/workflow/project-config.json:

{
  "specDir": "{specDir}",
  "archiveDir": "{archiveDir}",
  "roadmapFile": "{roadmapFile}"
}

Step 5: Output Summary

Display:

## Workflow initialized for {project name or directory}

### Agents created
{list each .claude/agents/{name}.md created or skipped}

### Config
- Spec directory: {specDir}
- Archive directory: {archiveDir}
- Roadmap file: {roadmapFile}

### Available commands
- /wf-phase1-spec       Create a feature spec from the roadmap
- /wf-phase1-iterate    Quick pre-review of a DRAFT spec
- /wf-phase2-review     Full design review with selected agents
- /wf-phase3-consolidate Address feedback, finalize spec
- /wf-phase4-implement  Implement the feature (Opus, thorough)
- /wf-phase4-implement-sonnet  Implement (Sonnet, faster)
- /wf-phase5-verify     Verify implementation matches spec
- /wf-phase5-6-complete Verify + retrospective in one session
- /wf-phase6-retrospective Document lessons learned
- /wf-clear-context     Clear workflow context to start fresh