developer

What this skill does

# Developer Skill

Handle post-completion adjustments by analyzing change requests, creating tracked tasks in `changes.json`, and spawning coder agents in parallel.

---

## When to Use

Use `/developer` when:
- All phases are **already completed** via `/execute-phase`
- You need **adjustments, fixes, or tweaks** to existing code
- You want changes **tracked separately** from the original progress.json

Use `/execute-phase` instead when:
- You're still building the initial project phases
- Tasks come from progress.json

---

## How It Works

```
/developer [change description]
      |
      v
+----------------------------------------------------------+
|  STEP 1: Get change request                               |
|  - From argument: /developer fix the login button         |
|  - OR from AskUserQuestion if not provided                |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 2: Read project context                             |
|  - docs/progress.json (understand what was built)         |
|  - docs/dev-plan.md (original plan)                       |
|  - docs/frontend-plan.md (component specs)                |
|  - docs/backend-plan.md (schema specs)                    |
|  - Scan existing codebase (src/**)                        |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 3: Analyze & create change tasks                    |
|  - Break the request into concrete tasks                  |
|  - Classify each: low (small-coder) / high (high-coder)  |
|  - Identify affected files                                |
|  - Determine dependencies between change tasks            |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 4: Write docs/changes.json                          |
|  - Create or APPEND to changes.json                       |
|  - Each change request = a new "batch"                    |
|  - Tasks inside the batch have IDs like "C1.1", "C1.2"   |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 5: Spawn agents in PARALLEL                         |
|                                                           |
|  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       |
|  │ small-coder │  │ high-coder  │  │ small-coder │       |
|  │  Task C1.1  │  │  Task C1.2  │  │  Task C1.3  │       |
|  └─────────────┘  └─────────────┘  └─────────────┘       |
|                                                           |
|  One agent per task — all run simultaneously              |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 6: Update changes.json with results                 |
|  - Mark completed / blocked tasks                         |
|  - Recalculate batch and global summary                   |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 7: Report results                                   |
+----------------------------------------------------------+
```

---

## Step 1: Get Change Request

### Option A: From arguments

If the user provides a description:
```
/developer fix the login button hover state
/developer add dark mode toggle to settings
/developer refactor the user card to use the new design tokens
/developer the sidebar collapses incorrectly on mobile
```

Extract the change request directly. **Do NOT ask questions — proceed to Step 2.**

### Option B: No argument provided

If the user invokes with no argument (`/developer`), you MUST use AskUserQuestion:

```
AskUserQuestion:
  question: "What change or adjustment do you need?"
  header: "Change Type"
  options:
    - label: "Bug fix"
      description: "Something is broken or behaving incorrectly"
    - label: "UI/UX adjustment"
      description: "Visual or interaction changes"
    - label: "Feature tweak"
      description: "Modify existing functionality"
    - label: "I'll describe it"
      description: "Provide detailed description"
```

Then follow up to get specifics:

```
AskUserQuestion:
  question: "Describe the change you need. Be specific about what should happen."
  header: "Details"
  options:
    - label: "I'll type it out"
      description: "Let me describe the change in detail"
```

### Question Rules
- Maximum **2 questions** to gather the change request
- If the user provided arguments, ask **ZERO questions**
- Capture the full request as `{change_request}`

---

## Step 2: Read Project Context

Read all available context to understand the current state of the project:

```
Glob: **/progress.json
Read: [found path] — understand what was built and task structure

Glob: **/dev-plan.md
Read: [found path] — original plan and architecture

Glob: **/frontend-plan.md
Read: [found path] — component specs, file paths, patterns

Glob: **/backend-plan.md
Read: [found path] — schema, queries, RLS policies

Glob: **/changes.json
Read: [found path] — previous change batches (if any)
```

Also scan the codebase to understand what files exist:

```
Glob: src/**/*.{ts,tsx}
```

**If progress.json does NOT exist:**

Warn the user but proceed anyway — changes.json can work independently:

> Note: `progress.json` not found. Operating without original task context. Changes will still be tracked in `changes.json`.

---

## Step 3: Analyze & Create Change Tasks

Break the user's change request into concrete, implementable tasks.

### 3.1 Identify affected areas

From the change request, determine:
- **Which files** need to be modified (grep/glob existing code)
- **Which domain** is affected (frontend, backend, fullstack)
- **What type** of change (bug fix, style change, logic change, new addition)

### 3.2 Break into tasks

Each distinct unit of work becomes a task. One task = one logical change.

**Examples:**

User request: "Fix the login button hover state and add a loading spinner"
```
Task C1.1: Fix login button hover state (1 file — low → small-coder)
Task C1.2: Add loading spinner to login button (1 file — low → small-coder)
```

User request: "Add dark mode toggle with persistent preference"
```
Task C1.1: Create dark mode Zustand store (1 file — low → small-coder)
Task C1.2: Add theme toggle component (1 file — low → small-coder)
Task C1.3: Wire dark mode across layout + providers + store (4 files — high → high-coder)
```

### 3.3 Classify complexity

Use the same rules as progress.json:

| Complexity | Criteria | Agent |
|------------|----------|-------|
| `low` | 1-2 files, single concern, no cross-file logic | `small-coder` |
| `high` | 3+ files, cross-file coordination, multi-concern | `high-coder` |

### 3.4 Determine dependencies

If tasks within the same batch depend on each other:
- Task C1.3 depends on C1.1 and C1.2 → `blocked_by: ["C1.1", "C1.2"]`
- Independent tasks have empty `blocked_by`

**Only spawn tasks where `blocked_by` is empty.** Blocked tasks wait for a re-run.

---

## Step 4: Write changes.json

### 4.1 Structure

If `changes.json` does NOT exist — create it fresh.
If `changes.json` ALREADY exists — read it and APPEND a new batch.

### 4.2 Batch numbering

Each invocation of `/developer` creates a new batch:
- First run: Batch `C1` with tasks `C1.1`, `C1.2`, ...
- Second run: Batch `C2` with tasks `C2.1`, `C2.2`, ...
- Nth run: Batch `CN` with tasks `CN.1`, `CN.2`, ...

If `changes.json` already has batches, find the highest batch number and increment.

### 4.3 Format

```json
{
  "project": "[from progress.json or dev-plan.md]",
  "generated": "[ISO date of first creation]",
  "last_updated": "[ISO date of latest update]",
  "summary": {
    "total_batches": 1,