Build Next

# Build Next

Pick the next pending feature from the roadmap and build it through the full TDD cycle.

> See `.cursor/commands/build-next.md` for full spec including Jira MCP syntax.

## Usage

/build-next /build-next --skip-jira

---

## What This Command Does

1. **Select** - Find the next buildable feature (pending, dependencies met)
2. **Spec** - Create or update feature spec with `/spec-first --full`
3. **Build** - Implement through TDD cycle (includes self-check drift)
4. **Update** - Mark roadmap as complete, sync Jira
5. **Build Check** - Shell verifies compilation (auto-detected or `BUILD_CHECK_CMD`)
6. **Test Suite** - Shell runs tests (auto-detected or `TEST_CHECK_CMD`) — failures retry the build
7. **Drift Check** - Fresh agent verifies spec↔code alignment, runs tests, iterates until passing
8. **Code Review** - Fresh agent reviews quality, runs tests, iterates until passing (optional)
9. **PR** - Create PR (if in overnight mode)

All agents receive the test command and are told to iterate until tests pass. The retry agent also receives the actual build/test failure output so it knows exactly what to fix.

### Manual vs Automated Flow

- **Manual** (interactive): You run `/spec-first {feature} --full` in one call — spec, tests, implement, compound, commit. Steps 5–8 are run by the build loop scripts when you use them.
- **Automated** (scripts): `build-loop-local.sh` and `overnight-autonomous.sh` use a **two-phase** flow — they do not invoke this command. Phase 1: spec-only (no `--full`). Phase 2: implement from spec. Each phase gets a fresh context window. Why two-phase: spec can be reviewed before implementation; implement phase can retry independently.

---

## Step 1: Read the Roadmap

Read `.specs/roadmap.md` and `.specs/vision.md` to understand:
- What's been built (✅)
- What's in progress (🔄) - should only be one
- What's pending (⬜)
- What's blocked (⏸️)

---

## Step 2: Select Next Feature

**Priority 1**: Resume any feature marked 🔄 (in progress). It was started in a previous run but not finished — pick it up and complete it.

**Priority 2**: If no in-progress feature, find the first feature where:
1. Status is ⬜ (pending)
2. All dependencies are ✅ (completed)

### Selection Logic

// Priority 1: Resume in-progress work for each phase in order: for each feature in phase: if feature.status == 🔄: return feature // Resume unfinished work

// Priority 2: Start next pending feature for each phase in order: for each feature in phase: if feature.status == ⬜: if all(dep.status == ✅ for dep in feature.deps): return feature

return null // Nothing ready to build

### If Nothing is Ready

If no features are ready:
- Check if there are ⏸️ blocked items and report why
- Check if all features are ✅ complete
- Report status to user

---

## Step 3: Load Context

Before building, load relevant context:

### Read Personas

Read .specs/personas/*.md for:

• Primary persona: vocabulary, patience level, frustrations, success metric
• Anti-persona: what NOT to build (prevents scope creep) These drive Gherkin language, flow complexity, and UI labels.

### Read Strategy

Read .specs/strategy.md (if exists) for:

• Target customer segment and buying motion
• Success metrics (what should this feature move?)
• Anti-goals (features to avoid or defer)

### Read Vision

Read .specs/vision.md for:

• App purpose
• Tech stack
• Design principles

### Read Design System

Read .specs/design-system/tokens.md for:

• Personality (Professional/Friendly/Minimal/Bold/Technical)
• Token names and values

### Read Related Specs

For each completed dependency: Read .specs/features/{domain}/{feature}.feature.md Note: patterns used, components created, API shape

### Read Learnings

Read .specs/learnings/index.md for relevant cross-cutting patterns

---

## Step 4: Update Roadmap Status

Mark the feature as in-progress:

```markdown
| 5 | Dashboard | clone-app | PROJ-105 | L | 1,2 | 🔄 |

Commit: chore: start feature #5 - Dashboard

---

Step 5: Sync Jira (if configured)

If the feature has a Jira ticket and Jira integration is enabled:

• Transition issue to "In Progress"
• Use available Jira MCP tools

---

Step 6: Run /spec-first --full

Execute the full TDD cycle for this feature:

/spec-first {feature name} --full

The --full flag means:

• Create or update spec (no pause)
• Write tests (no pause)
• Implement until tests pass
• Commit changes

Spec Location

Place spec at: .specs/features/{domain}/{feature-slug}.feature.md

Where:

• domain = derived from feature name (e.g., "Auth: Signup" → "auth")
• feature-slug = kebab-case (e.g., "auth-signup")

---

Step 7: Update Roadmap and Mapping on Completion

After /spec-first --full completes:

| 5 | Dashboard | clone-app | PROJ-105 | L | 1,2 | ✅ |

Update the Progress section:

## Progress

| Status | Count |
|--------|-------|
| ✅ Completed | [+1] |
| 🔄 In Progress | 0 |
| ⬜ Pending | [-1] |
| ⏸️ Blocked | 0 |

**Last updated**: [current timestamp]

Regenerate the mapping file:

./scripts/generate-mapping.sh

Commit: chore: complete feature #5 - Dashboard

---

Step 8: Sync Jira on Completion

If feature has Jira ticket:

• Transition to Done (or "Ready for Review")
• Add comment with PR link

---

Step 9: Mark Source Complete (Slack)

If feature source is Slack (slack:CHANNEL/TIMESTAMP):

• Reply to thread confirming completion
• Include PR link

---

Step 10: Create PR (Overnight Mode)

If running in overnight/automated mode, create a draft PR:

git checkout -b feature/{feature-slug}
git push -u origin HEAD
gh pr create --draft --title "feat: {feature name}" --body "..."

---

Step 11: Learnings (handled by /spec-first --full)

Note: /spec-first --full already runs /compound at the end of implementation. No additional action needed here - learnings ```