feature-dev

What this skill does

# Feature Development Workflow

> Systematic feature development: Discovery → Exploration → Documentation → Implementation → Review

## Overview

A comprehensive 5-phase workflow for feature development that emphasizes:
- **Documentation-first**: Spec documents before code
- **Progressive context**: Fork context prevents main session pollution
- **Progress persistence**: Resume interrupted work seamlessly
- **Multi-model agents**: Right model for each task (Haiku/Sonnet/Opus)

## Hard Rules

- Speak with user in **Simplified Chinese**, write all artifacts in **English**
- Do not skip decision gates without explicit user confirmation
- Keep diffs minimal; avoid unrelated refactors
- Update progress.md after each phase transition
- Run verification before marking tasks complete

## Workflow Overview

```
Phase 1: Discovery     ->  Phase 2: Exploration  ->  Phase 3: Documentation
   (clarify & decide)       (understand codebase)     (contracts & specs)
         |                         |                         |
         v                         v                         v
   [GATE: confirm]           [parallel agents]         [GATE: approve]
                                                             |
                                                             v
                              Phase 3c: Readiness Gate (NEW - 95% check)
                                 (structural + semantic scoring)
                                         |
                                         v
                              Phase 4: Implementation  <-  Phase 3b: Tasks
                                 (incremental, verified)    (breakdown)
                                         |
                                         v
                              Phase 5: Review & PR
```

## File Structure

All artifacts live under `.works/spec/{feature-name}/` (gitignored):

```
.works/spec/{feature-name}/
├── progress.md          # Progress tracking (YAML frontmatter + markdown)
├── README.md            # Index + core decisions
├── contracts.md         # Data contracts (input/output/API)
├── tasks.md             # Task breakdown with status
├── PR.md                # PR description template
├── qa.md                # Q&A log (Phase 3c question rounds)
├── score.json           # Readiness scoring results (Track A)
├── semantic-check.json  # Semantic check results (Track B)
├── verification.log     # Test/build output history
├── assumptions.md       # Assumptions pack (if question budget exhausted)
└── spec.lock            # Spec locked marker (created when gate passes)
```

Initialize with: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/init.sh {feature-name}`

---

## Phase 1: Discovery

**Goal**: Transform vague requirements into actionable decisions

**Agents**: `product-thinker` (Opus) for deep product analysis

**Actions**:
1. Initialize workspace with `init.sh {feature-name}`
2. Create progress.md with initial state
3. Ask clarifying questions using numbered format (Q1, Q2...)
4. Record decisions in README.md

**GATE**: Confirm all decisions with user before proceeding.

---

## Phase 2: Codebase Exploration

**Goal**: Understand relevant existing code and patterns

**Agents**: `codebase-explorer` (Haiku, fast) - launch 2-3 in parallel

**Actions**:
1. Launch parallel agents targeting:
   - Similar features and implementation patterns
   - Architecture and abstractions
   - UI patterns and state management
2. Read all key files identified by agents
3. Present comprehensive findings summary
4. Update progress.md
5. if the `ast-grep` tool is exsiting, please use it. here is the Command line usage example :
   ```bash
      ## ast-grep has following form.
      ast-grep --pattern 'var code = $PATTERN' --rewrite 'let code = new $PATTERN' --lang ts
      ## Example : Rewrite code in null coalescing operator
      ast-grep -p '$A && $A()' -l ts -r '$A?.()'
      ## Example : Rewrite Zodios
      ast-grep -p 'new Zodios($URL,  $CONF as const,)' -l ts -r 'new Zodios($URL, $CONF)' -i
   ```

---

## Phase 3: Documentation & Tasks

**Goal**: Create spec documents and task breakdown

**Agents**: `architect` (Sonnet) for implementation blueprint

### Sub-phase 3a: Documentation
1. Write contracts.md with field definitions, types, examples
2. Update README.md with decisions summary

**GATE**: User approves spec documents

### Sub-phase 3b: Task Breakdown
1. Launch `architect` agent for implementation design
2. Split feature into atomic, verifiable tasks in tasks.md
3. Each task: Goal, Size (S/M/L), Files, Acceptance criteria

**GATE**: User confirms task list

---

## Phase 3c: Readiness Gate (95% Confidence)

**Goal**: Verify specification completeness before implementation

**CRITICAL**: Do not proceed to implementation until this gate passes.

### Dual-Track Scoring

The readiness gate uses two complementary checks:

1. **Track A: Structural Scoring** (Deterministic)
   - Checks for required sections, type definitions, test commands
   - Scores 0-100 based on concrete rubric
   - Fast, consistent, no API calls needed

2. **Track B: Semantic Sufficiency** (LLM-based)
   - Checks for ambiguity, hidden assumptions, logical gaps
   - Requires evidence citations from spec
   - Uses semantic-checker agent (in-session model)

### Execution Steps

**1. Run structural scoring**:
```bash
bun run ${CLAUDE_PLUGIN_ROOT}/scripts/score-spec.ts \
  --feature {feature-name} \
  --threshold 95
```
Result written to `.works/spec/{feature}/score.json`

**2. Run semantic check**:
- Use Task tool to launch `semantic-checker` agent
- Provide README.md, contracts.md, tasks.md as context
- Write the JSON output to `.works/spec/{feature}/semantic-check.json`

**3. Evaluate gate condition**:
- `readiness_score >= 95` AND `semantic_ok == true`
- If **PASS**: Create `spec.lock` file, update progress, proceed to Phase 4
- If **FAIL**: Go to step 4

**4. Information Gathering (if gate fails)**:

a. Generate blocking questions list:
   - Combine gaps from `score.json` + `semantic-check.json`
   - Filter to blocking items only
   - Max 3-5 questions per round

b. Check question budget:
   - If `question_round < question_budget` (default: 2):
     - Use AskUserQuestion to ask targeted questions
     - Record Q&A in `qa.md`
     - Update `question_round` in progress.md
     - Re-run readiness gate (steps 1-3)
   - If budget exhausted: Go to step 5

**5. Assumptions Pack (budget exhausted)**:

Write to `.works/spec/{feature}/assumptions.md`:
```markdown
## Unresolved Gaps
[List blocking gaps from score.json + semantic-check.json]

## Proposed Assumptions
- Gap: [description]
  Assumption: [what we'll assume]
  Risk: [what could go wrong]

## Acceptance
[ ] User accepts assumptions (allows Phase 4)
[ ] User rejects (requires more info or cancels feature)
```

Use AskUserQuestion with 2 options:
- "Accept assumptions and proceed (Recommended if risks are acceptable)"
- "Provide more information (will ask targeted questions)"

**If accepted**: Mark `assumptions_accepted: true`, create `spec.lock`, proceed to Phase 4
**If rejected**: Output Stuck Report and mark `status: blocked`

**6. Stuck Report format** (if assumptions rejected):
```markdown
# Feature Blocked: {feature-name}

## Blocking Gaps
[List from score.json + semantic-check.json]

## Information Needed
[Specific questions that must be answered]

## Attempts Made
- Question rounds: {question_round}/{question_budget}
- Assumptions offered: Yes
- User response: Rejected assumptions

## Recommendation
Please provide answers to "Information Needed" section, then:
1. Update contracts.md and/or tasks.md with missing info
2. Re-run readiness gate: bun run scripts/score-spec.ts --feature {feature-name}
```

### Gate Pass Criteria

- **Track A**: `readiness_score >= confidence_threshold` (default 95)
- **Track B**: `semantic_ok == true`
- **Combined**: Both must pass

### Post-Gate Actions

When gate passes:
1. Create `.works/spec/{feature}/spec.lock` (empty file, tim