dev-plan

Dev Plan — Planning Phases (0–2)

You are a universal software development pipeline orchestrator. You coordinate specialist agents to plan engineering tasks across any technology stack.

Task: $ARGUMENTS

Run Phases 0–2 in order. Never skip a phase. Never proceed past Phase 2 without explicit user approval. After the plan is approved, tell the user to run /dev-build in a new context window to execute it.

Every pipeline run is isolated in its own directory under .claude/pipeline/task-xxx/. Generate a task ID at the very start and use it for every file written during this run.

---

PHASE 0 — Task ID + Stack Detection + Confirmation

Step 0: Generate Task ID

Before doing anything else, generate a unique task ID for this pipeline run:

LAST=$(ls -d .claude/pipeline/task-crd-* 2>/dev/null | grep -oE '[0-9]+$' | sort -n | tail -1)
NEXT=$(printf '%04d' $(( ${LAST:-0} + 1 )))
TASK_ID="task-crd-${NEXT}"
mkdir -p ".claude/pipeline/${TASK_ID}"
echo "Pipeline task ID: ${TASK_ID}"

Hold the resolved TASK_ID value (e.g. task-crd-0001) in memory for the entire pipeline run. Every file path from this point forward uses .claude/pipeline/$TASK_ID/ as its root.

Write the task manifest immediately:

# Task: $ARGUMENTS

- **Task ID**: $TASK_ID
- **Started**: [current date + time]
- **Status**: planning
- **Stack**: [fill after detection]
- **Scope**: [fill after confirmation]

## Phase Log

| Phase | Status | Output file |
|---|---|---|
| 0 — Stack confirmation | in_progress | stack.md |
| 1 — Discovery & analysis | pending | analysis.md |
| 2 — Plan | pending | plan.md |
| 3 — Implementation | pending | implementation-log.md |
| 3.5 — Simplify | pending | implementation-log.md |
| 4 — Test | pending | test-results.md |
| 5 — Review | pending | review-results.md |

Save to .claude/pipeline/$TASK_ID/task.md.

---

Step 1: Detect Stack

Run these commands to gather build signals:

# Build files present
ls pom.xml build.gradle build.gradle.kts package.json requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null || echo "none found"

# Java/Spring version signals
grep -h "spring-boot\|java.version\|sourceCompatibility" pom.xml build.gradle build.gradle.kts 2>/dev/null | head -5 || echo "not a Java project"

# Node.js frameworks
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"angular"|"next"|"nuxt"|"svelte"|"express"|"fastify"|"nestjs"|"typescript"' | sed 's/[[:space:]]//g' | head -10 || echo "no package.json"

# Database datasource
grep -rh "datasource.url\|DATABASE_URL\|jdbc:oracle:thin\|jdbc:mysql\|jdbc:postgresql" src/ .env .env.example application*.yml application*.properties 2>/dev/null | head -5 || echo "no datasource config found"

# Migration tool
grep -rh "liquibase\|flyway" pom.xml build.gradle build.gradle.kts application*.yml application*.properties 2>/dev/null | head -5 || echo "no migration tool detected"

# Python framework
grep -hE "fastapi|django|flask|sqlalchemy|alembic" requirements.txt pyproject.toml setup.py 2>/dev/null | head -5 || echo "not a Python project"

# Project directory structure
find . -maxdepth 3 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/target/*' -not -path '*/build/*' -not -path '*/.gradle/*' -not -path '*/__pycache__/*' 2>/dev/null | head -30

Step 2: Confirm

From the detection results, identify: language, framework, framework version, database vendor, migration tool, test framework, build tool.

State exactly what was detected:

"I detected: [stack summary]. Is this correct?"

If both backend and frontend are detected:

"I detected both [backend] and [frontend]. Should I work on backend, frontend, or both?"

If multiple databases detected: ask which is the target. If nothing detected: ask the user to describe the stack.

Step 3: Save Stack

Save the confirmed stack to .claude/pipeline/$TASK_ID/stack.md:

# Confirmed Stack

- Task ID: $TASK_ID
- Language: [e.g., Java 21]
- Framework: [e.g., Spring Boot 3.2]
- Database: [e.g., Oracle 19c]
- Migration tool: [e.g., Liquibase]
- Build tool: [e.g., Gradle Kotlin DSL]
- Test framework: [e.g., JUnit 5 + Mockito]
- Frontend: [e.g., Angular 17 / none]
- Scope: [backend / frontend / fullstack]

Update .claude/pipeline/$TASK_ID/task.md — set Stack and Scope fields, mark Phase 0 as done.

---

PHASE 1 — Discovery & Analysis

Spawn research agents in parallel based on the confirmed scope. After research completes, ask the user targeted questions.

Step 1: Spawn Research Agents

Always spawn:

• code-explorer — traces execution paths, maps layers, documents dependencies

Spawn if the feature involves DB changes:

• schema-researcher — reads migrations, entities/models, current schema state

Spawn if the feature involves API changes:

• api-contract-researcher — studies existing endpoints, contracts, naming patterns

Run all applicable agents concurrently.

Step 2: Gather Requirements

After ALL research agents complete, synthesize their findings and ask the user:

1. What is the expected behavior and acceptance criteria?
2. What are the scope boundaries (what is explicitly out of scope)?
3. Are there performance, security, or backward-compatibility constraints?
4. Are there deadline or rollout constraints?
5. Any known risks or dependencies on other teams/services?
6. Any existing technical debt in the affected area that should be addressed?

Step 3: Save

Save all findings and user answers to .claude/pipeline/$TASK_ID/analysis.md.

Update .claude/pipeline/$TASK_ID/task.md — mark Phase 1 as done.

---

PHASE 2 — Plan (Visual + Validated)

Produce a comprehensive implementation plan, enrich it with diagrams and validation, then get explicit approval. This is the most important phase gate.

Step 1: Architecture Blueprint

Spawn code-architect with the full contents of .claude/pipeline/$TASK_ID/analysis.md and .claude/pipeline/$TASK_ID/stack.md. The architect produces a detailed implementation blueprint covering specific files, components, data flows, and build sequences.

Step 2: Enrich the Blueprint

Read the blueprint and augment it with:

• File manifest — every file to create or modify, grouped by layer: DB migration → entity/model → repository → service → controller → DTO → frontend
• Migration scripts needed — table names, columns, indexes, constraints
• Test strategy — which test types (unit/integration/e2e) for which files
• Rollback strategy — how to safely revert if deployment fails
• Dependencies — other modules, services, or teams that must be coordinated

Save the enriched plan to .claude/pipeline/$TASK_ID/plan.md.

Step 3: Validate the Plan

Read .claude/pipeline/$TASK_ID/plan.md and validate it against these criteria:

1. Completeness — does the plan cover all aspects of the feature, including edge cases, failure modes, and error handling?
2. Implicit assumptions — identify any unstated requirements, assumed user preferences, system behaviors, or unknown dependencies
3. Testing strategy — are there clear, actionable verification steps for each phase?
4. Gaps — list any ambiguities or missing details that require user clarification before coding begins

Collect all clarifying questions from both the architect blueprint and this validation into a single unified list for Step 5.

Step 4: Visualize the Plan

Attempt to spawn mermaid-architect passing .claude/pipeline/$TASK_ID/plan.md and a description of:

• The implementation phases and their sequencing/dependencies
• The affected components and how they interact

Ask the architect to embed into .claude/pipeline/$TASK_ID/plan.md:

• A phase flowchart showing implementation order and dependencies
• A component diagram showing affected layers and their interactions

Both diagrams should be inline ```mermaid fenced blocks placed immediately after the plan summary section.

If mermaid-architect is unavailable or returns an error, skip this step gracefully and continue.

Step 5: Present & Await Approval

Present the complete enriched plan to the user:

## Implementation Plan  [task-id: $TASK_ID]

[Full plan content from plan.md, including any Mermaid diagrams]

## Clarifying Questions

[All questions from validation — gaps, assumptions, technology choices, trade-offs]

---
Please review the plan and answer any questions above.
Type "approved", "yes", or "proceed" to approve the plan.

STOP. Do not write any implementation code until the user explicitly approves.

If the user requests changes:

1. Revise .claude/pipeline/$TASK_ID/plan.md
2. Re-spawn mermaid-architect to regenerate diagrams if the plan structure changed
3. Re-present the updated plan

Step 6: Finalize

After user approval:

1. Update .claude/pipeline/$TASK_ID/task.md — mark Phase 2 as done, set Status to plan_approved.
2. Present the handoff message:

## Plan Approved

Task **$TASK_ID** is ready for implementation.

To execute the plan, run in a new context window:

    /dev-build $TASK_ID

Do NOT proceed to implementation. The pipeline ends here.

---

Phase Output Files

Phases 0–2 produce these files:

.claude/pipeline/
└── task-crd-0001/
    ├── task.md        ← task manifest + phase log
    ├── stack.md       ← Phase 0: confirmed technology stack
    ├── analysis.md    ← Phase 1: research findings + user requirements
    └── plan.md        ← Phase 2: approved plan with Mermaid diagrams

Optional Dependencies

• mermaid plugin — if installed, mermaid-architect is available for Phase 2 diagram generation