myclaude/dev-workflow/README.md

# /dev - Minimal Dev Workflow

## Overview

A freshly designed lightweight development workflow with no legacy baggage, focused on delivering high-quality code fast.

## Flow

```
/dev trigger
  ↓
AskUserQuestion (backend selection)
  ↓
AskUserQuestion (requirements clarification)
  ↓
codeagent analysis (plan mode + task typing + UI auto-detection)
  ↓
dev-plan-generator (create dev doc)
  ↓
codeagent concurrent development (2–5 tasks, backend routing)
  ↓
codeagent testing & verification (≥90% coverage)
  ↓
Done (generate summary)
```

## Step 0 + The 6 Steps

### 0. Select Allowed Backends (FIRST ACTION)
- Use **AskUserQuestion** with multiSelect to ask which backends are allowed for this run
- Options (user can select multiple):
  - `codex` - Stable, high quality, best cost-performance (default for most tasks)
  - `claude` - Fast, lightweight (for quick fixes and config changes)
  - `gemini` - UI/UX specialist (for frontend styling and components)
- If user selects ONLY `codex`, ALL subsequent tasks must use `codex` (including UI/quick-fix)

### 1. Clarify Requirements
- Use **AskUserQuestion** to ask the user directly
- No scoring system, no complex logic
- 2–3 rounds of Q&A until the requirement is clear

### 2. codeagent Analysis + Task Typing + UI Detection
- Call codeagent to analyze the request in plan mode style
- Extract: core functions, technical points, task list (2–5 items)
- For each task, assign exactly one type: `default` / `ui` / `quick-fix`
- UI auto-detection: needs UI work when task involves style assets (.css, .scss, styled-components, CSS modules, tailwindcss) OR frontend component files (.tsx, .jsx, .vue); output yes/no plus evidence

### 3. Generate Dev Doc
- Call the **dev-plan-generator** agent
- Produce a single `dev-plan.md`
- Append a dedicated UI task when Step 2 marks `needs_ui: true`
- Include: task breakdown, `type`, file scope, dependencies, test commands

### 4. Concurrent Development
- Work from the task list in dev-plan.md
- Route backend per task type (with user constraints + fallback):
  - `default` → `codex`
  - `ui` → `gemini` (enforced when allowed)
  - `quick-fix` → `claude`
  - Missing `type` → treat as `default`
  - If the preferred backend is not allowed, fallback to an allowed backend by priority: `codex` → `claude` → `gemini`
- Independent tasks → run in parallel
- Conflicting tasks → run serially

### 5. Testing & Verification
- Each codeagent task:
  - Implements the feature
  - Writes tests
  - Runs coverage
  - Reports results (≥90%)

### 6. Complete
- Summarize task status
- Record coverage

## Usage

```bash
/dev "Implement user login with email + password"
```

No CLI flags required; workflow starts with an interactive backend selection.

## Output Structure

```
.claude/specs/{feature_name}/
└──  dev-plan.md      # Dev document generated by agent
```

Only one file—minimal and clear.

## Core Components

### Tools
- **AskUserQuestion**: interactive requirement clarification
- **codeagent skill**: analysis, development, testing; supports `--backend` for `codex` / `claude` / `gemini`
- **dev-plan-generator agent**: generate dev doc (subagent via Task tool, saves context)

## Backend Selection & Routing
- **Step 0**: user selects allowed backends; if `仅 codex`, all tasks use codex
- **UI detection standard**: style files (.css, .scss, styled-components, CSS modules, tailwindcss) OR frontend component code (.tsx, .jsx, .vue) trigger `needs_ui: true`
- **Task type field**: each task in `dev-plan.md` must have `type: default|ui|quick-fix`
- **Routing**: `default`→codex, `ui`→gemini, `quick-fix`→claude; if disallowed, fallback to an allowed backend by priority: codex→claude→gemini

## Key Features

### ✅ Fresh Design
- No legacy project residue
- No complex scoring logic
- No extra abstraction layers

### ✅ Minimal Orchestration
- Orchestrator controls the flow directly
- Only three tools/components
- Steps are straightforward

### ✅ Concurrency
- Tasks split based on natural functional boundaries
- Auto-detect dependencies and conflicts
- codeagent executes independently with optimal backend

### ✅ Quality Assurance
- Enforces 90% coverage
- codeagent tests and verifies its own work
- Automatic retry on failure

## Example

```bash
# Trigger
/dev "Add user login feature"

# Step 0: Select backends
Q: Which backends are allowed? (multiSelect)
A: Selected: codex, claude

# Step 1: Clarify requirements
Q: What login methods are supported?
A: Email + password
Q: Should login be remembered?
A: Yes, use JWT token

# Step 2: codeagent analysis
Output:
- Core: email/password login + JWT auth
- Task 1: Backend API (type=default)
- Task 2: Password hashing (type=default)
- Task 3: Frontend form (type=ui)
UI detection: needs_ui = true (tailwindcss classes in frontend form)

# Step 3: Generate doc
dev-plan.md generated with typed tasks ✓

# Step 4-5: Concurrent development (routing + fallback)
[task-1] Backend API (codex) → tests → 92% ✓
[task-2] Password hashing (codex) → tests → 95% ✓
[task-3] Frontend form (fallback to codex; gemini not allowed) → tests → 91% ✓
```

## Directory Structure

```
dev-workflow/
├── README.md                          # This doc
├── commands/
│   └── dev.md                         # /dev workflow orchestrator definition
└── agents/
    └── dev-plan-generator.md          # Dev plan document generator agent
```

Minimal structure, only three files.

## When to Use

✅ **Good for**:
- Any feature size
- Fast iterations
- High test coverage needs
- Wanting concurrent speed-up

## Design Principles

1. **KISS**: keep it simple
2. **Disposable**: no persistent config
3. **Quality first**: enforce 90% coverage
4. **Concurrency first**: leverage codeagent
5. **No legacy baggage**: clean-slate design

---

**Philosophy**: zero tolerance for complexity—ship the smallest usable solution, like Linus would.