spec-starter 1.0.0

package/.claude/_templates/blueprint.md

@@ -0,0 +1,70 @@
+# <feature_title> — Blueprint
+
+**Brief:** `.claude/_features/<feature_slug>/2-brief.md`
+**Date:** <YYYY-MM-DD>
+
+**Goal:** <One sentence — what this builds>
+
+**Architecture:** <2-3 sentences on approach: layers, data flow, key abstractions>
+
+**Tech Stack:** <Key technologies, libraries, frameworks>
+
+---
+
+## Prerequisites
+
+- [ ] <Branch setup, env vars, or config needed before starting>
+- [ ] <Dependencies to install>
+
+---
+
+## Task 1: <Component or Layer Name>
+
+**What:** <One sentence — what this task delivers>
+
+**Files:**
+- `<exact/path/to/file>`
+- `<exact/path/to/test>`
+
+**Steps:**
+1. Write failing test
+2. Run test — confirm FAIL
+3. Write minimal implementation
+4. Run test — confirm PASS
+5. Commit: `<commit message>`
+
+---
+
+## Task 2: <Next Component>
+
+**What:** <One sentence>
+
+**Files:**
+- `<path>`
+
+**Steps:**
+1. Write failing test
+2. Run test — confirm FAIL
+3. Write minimal implementation
+4. Run test — confirm PASS
+5. Commit: `<commit message>`
+
+---
+
+## Final: Integration
+
+**Test:** `<full test suite command>`
+
+**Commit:** `<final commit message>`
+
+---
+
+## Key Decisions
+
+| Decision | Choice | Reason |
+|---|---|---|
+| <trade-off> | <chosen approach> | <why> |
+
+## Out of Scope
+
+- <What was explicitly not planned here>

package/.claude/_templates/brief.md

@@ -0,0 +1,55 @@
+# <feature_title> — Brief
+
+## Overview
+
+<What is this feature and why does it matter? 2-3 sentences, no technical details.>
+
+## Goals
+
+- <What outcome are we trying to achieve?>
+- <What user problem does this solve?>
+
+## Requirements
+
+### Must Have
+
+- <Core requirement 1>
+- <Core requirement 2>
+
+### Nice to Have
+
+- <Optional requirement 1>
+
+## User Experience
+
+<Describe what the user sees, does, and gets — from their perspective only. No implementation details.>
+
+## Edge Cases
+
+- <What happens when X is missing?>
+- <What happens when Y fails?>
+
+## Out of Scope
+
+- <Explicitly not included>
+
+## Success Criteria
+
+- <How do we know this is done? Verifiable, user-facing outcomes.>
+- <Criterion 2>
+
+---
+
+## Questions from Claude
+
+_Claude needs answers to these to finalize the brief. Set feature to `[?] Brief` when answered._
+
+- <Question 1>
+  - Answer:
+
+## Questions from User
+
+_User questions for Claude to research and answer._
+
+- <Question 1>
+  - Answer:

package/.claude/_templates/e2e-checklist.md

@@ -0,0 +1,32 @@
+# <feature_title> — E2E Checklist
+
+Generated after implementation. Work through each scenario manually.
+
+---
+
+## Happy Path
+
+- [ ] <Scenario 1: exact steps to follow, expected outcome>
+- [ ] <Scenario 2>
+
+## Edge Cases
+
+- [ ] <Edge case 1: what to do, what should happen>
+- [ ] <Edge case 2>
+
+## Error States
+
+- [ ] <Error scenario: how to trigger, what the user should see>
+
+## Integration Points
+
+- [ ] <Cross-feature or external dependency check>
+
+---
+
+## Sign-off
+
+- [ ] All scenarios above pass
+- [ ] No regressions in adjacent features
+
+Update `1-feature.md`: change `- [o] Review` to `- [x] Review` when complete.

package/.claude/_templates/feature.md

@@ -0,0 +1,25 @@
+# <feature_title>
+
+**Slug:** `<MM.DD-feature_slug>`
+**Branch:** `<branch_name>`
+**Last Tested:** —
+
+## Progress
+
+- [ ] Brief
+- [ ] Blueprint
+- [ ] Implement
+- [ ] Review
+- [ ] Done
+
+> `[ ]` not started · `[?]` needs attention · `[o]` in progress · `[x]` complete · `[!]` blocked
+
+## Description
+
+<A 2-3 sentence summary of what this feature does and why it's needed>
+
+## Key Points
+
+- <Key point 1>
+- <Key point 2>
+- <Key point 3>

package/.claude/commands/feature/blueprint.md

@@ -0,0 +1,117 @@
+---
+description: Generate a technical blueprint from a completed brief
+argument-hint: "<MM.DD-slug>"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+model: claude-opus-4-6
+---
+
+Generate `3-blueprint.md` — a detailed technical implementation plan — from a completed `2-brief.md`. Write the file and stop. Do not implement anything.
+
+**Arguments:** $ARGUMENTS
+
+## Progress Checkbox Format
+
+- `[ ]` not started · `[?]` needs attention · `[o]` in progress · `[x]` complete · `[!]` blocked
+
+A feature is **ready for blueprint** when: `- [x] Brief`
+
+---
+
+## Mode Detection
+
+- If empty or blank → **BROWSE MODE**
+- Otherwise → **GENERATE MODE**
+
+---
+
+## BROWSE MODE
+
+### Step 1: Find ready features
+
+Glob all `.claude/_features/*/1-feature.md`. Collect features where Progress shows `- [x] Brief` and `- [ ] Blueprint`.
+
+If none:
+
+```
+No features are ready for blueprint.
+
+Features need Brief complete before blueprinting.
+Run /feature:review <slug> to complete a brief.
+```
+
+Then stop.
+
+### Step 2: Display numbered list
+
+```
+Features ready for blueprint:
+
+1. <feature-title> (<MM.DD-slug>)
+2. <feature-title> (<MM.DD-slug>)
+
+Run /feature:blueprint <MM.DD-slug> to generate a blueprint.
+```
+
+Then stop.
+
+---
+
+## GENERATE MODE
+
+### Step 1: Read feature and brief
+
+Read `.claude/_features/$ARGUMENTS/1-feature.md` and `.claude/_features/$ARGUMENTS/2-brief.md`.
+
+If folder or brief doesn't exist, tell the user and stop.
+
+**Progress check:**
+- `[x] Brief` + `[ ] Blueprint` — proceed
+- `[?] Brief` — warn: _"Brief still needs review. Run /feature:review $ARGUMENTS first."_ Stop.
+- `[o] Brief` — warn: _"Brief still in progress."_ Stop.
+- `[ ] Brief` — warn: _"Brief not started."_ Stop.
+- `[x] Blueprint` — warn: _"Blueprint already exists. Re-running will overwrite 3-blueprint.md."_ Continue.
+
+### Step 2: Update Blueprint to `[o]`
+
+In `1-feature.md`, change `- [ ] Blueprint` to `- [o] Blueprint`.
+
+**State update:** Always do this before starting work.
+
+### Step 3: Explore the codebase
+
+Before writing the blueprint, understand the existing codebase:
+1. Root structure and folder layout
+2. Existing patterns similar to this feature
+3. Entry points this feature hooks into
+4. Available dependencies (package.json, etc.)
+5. Test setup — read one existing test file for framework/conventions
+
+Take notes on exact file paths — the blueprint must reference them precisely.
+
+### Step 4: Write blueprint.md
+
+Write `.claude/_features/$ARGUMENTS/3-blueprint.md` using `.claude/_templates/blueprint.md` as structure.
+
+The blueprint must be:
+- **Precise** — exact file paths, not "create a file for X"
+- **Complete** — every task includes failing test, implementation, and commit
+- **Ordered** — tasks build on each other sequentially
+- **TDD throughout** — Red → Green → Commit for every functional task
+- **Codebase-aware** — match existing naming, import styles, test patterns
+- **Self-contained** — a fresh Claude session with only this file should be able to implement the feature
+
+### Step 5: Update Blueprint to `[x]`
+
+In `1-feature.md`, change `- [o] Blueprint` to `- [x] Blueprint`.
+
+**State update:** Do this immediately after blueprint.md is written.
+
+Output:
+
+```
+Blueprint written: .claude/_features/$ARGUMENTS/3-blueprint.md
+
+Progress: [x] Brief  [x] Blueprint  [ ] Implement  [ ] Review  [ ] Done
+```
+
+**STOP. Do not implement the feature. Do not suggest next steps. Do not take any further action.**

package/.claude/commands/feature/finish.md

@@ -0,0 +1,177 @@
+---
+description: Finish a reviewed feature — create PR into dev, optionally merge, mark Done
+argument-hint: "<MM.DD-slug>"
+allowed-tools: Read, Edit, Glob, Bash
+---
+
+Finish a feature that has been manually reviewed. Creates a PR into `dev`, asks whether to merge, and marks the feature complete.
+
+**Arguments:** $ARGUMENTS
+
+## Progress Checkbox Format
+
+- `[ ]` not started · `[?]` needs attention · `[o]` in progress · `[x]` complete · `[!]` blocked
+
+A feature is **ready to finish** when: `- [o] Review`
+
+---
+
+## Mode Detection
+
+- If empty or blank → **BROWSE MODE**
+- Otherwise → **FINISH MODE**
+
+---
+
+## BROWSE MODE
+
+### Step 1: Find features in review
+
+Glob all `.claude/_features/*/1-feature.md`. Collect features where Progress shows `- [o] Review`.
+
+If none:
+```
+No features are in review.
+
+Features must be implemented before finishing.
+Run /feature:implement <slug> to implement one, or /feature:status to see all features.
+```
+Then stop.
+
+### Step 2: Display numbered list
+
+```
+Features ready to finish:
+
+1. <feature-title> (<MM.DD-slug>)
+2. <feature-title> (<MM.DD-slug>)
+
+Run /feature:finish <MM.DD-slug> to create a PR and mark complete.
+```
+
+Then stop.
+
+---
+
+## FINISH MODE
+
+### Step 1: Read feature
+
+Read `.claude/_features/$ARGUMENTS/1-feature.md`.
+
+If the folder doesn't exist:
+```
+No feature found: $ARGUMENTS
+```
+Then stop.
+
+Extract:
+- `branch_name` from the `**Branch:**` line
+- `feature_title` from the `#` heading
+
+**Progress check:**
+- `[o] Review` — proceed
+- `[ ] Review` or `[ ] Implement` — warn: _"Feature hasn't been implemented yet. Run /feature:implement $ARGUMENTS first."_ Stop.
+- `[x] Done` — warn: _"Feature is already marked Done."_ Stop.
+- `[x] Review` — warn: _"Review already marked complete but feature isn't Done. Continuing."_ Continue.
+
+### Step 2: Push the branch
+
+Push the feature branch to remote:
+
+```bash
+git push -u origin <branch_name>
+```
+
+If the push fails (e.g. no remote configured), warn the user and stop.
+
+### Step 3: Create the PR
+
+Create a PR from `<branch_name>` into `dev` using the `gh` CLI:
+
+```bash
+gh pr create --base dev --head <branch_name> --title "<feature_title>" --body "$(cat <<'EOF'
+## Summary
+
+Implements: <feature_title>
+
+Feature folder: `.claude/_features/$ARGUMENTS/`
+
+## Review checklist
+
+See `.claude/_features/$ARGUMENTS/4-e2e-checklist.md` for manual testing scenarios.
+EOF
+)"
+```
+
+If a PR already exists for this branch, retrieve its URL instead:
+
+```bash
+gh pr view <branch_name> --json url --jq '.url'
+```
+
+Output the PR URL to the user.
+
+### Step 4: Ask whether to merge
+
+Ask the user:
+```
+PR created: <pr-url>
+
+Merge this PR into dev now? (yes/no)
+```
+
+Wait for the user's response.
+
+### Step 5a: Merge if yes
+
+If the user says yes (or y):
+
+```bash
+gh pr merge <branch_name> --squash --delete-branch
+```
+
+Then switch to `dev` and fetch:
+
+```bash
+git checkout dev
+git fetch origin
+git pull origin dev
+```
+
+Output:
+```
+Merged and branch deleted. Switched to dev and pulled latest.
+```
+
+Then continue to Step 6.
+
+### Step 5b: Skip merge if no
+
+If the user says no:
+
+Output:
+```
+PR left open. Merge manually when ready.
+```
+
+Then continue to Step 6.
+
+### Step 6: Mark feature complete
+
+In `.claude/_features/$ARGUMENTS/1-feature.md`:
+- Change `- [o] Review` to `- [x] Review` (if not already `[x]`)
+- Change `- [ ] Done` to `- [x] Done`
+
+**State update:** Always update 1-feature.md regardless of whether the PR was merged.
+
+### Step 7: Output summary
+
+```
+Feature complete: <feature_title>
+
+Progress: [x] Brief  [x] Blueprint  [x] Implement  [x] Review  [x] Done
+
+PR: <pr-url>
+Branch: <merged/open>
+```

package/.claude/commands/feature/implement.md

@@ -0,0 +1,166 @@
+---
+description: Implement a feature from its blueprint, then generate e2e-checklist.md
+argument-hint: "<MM.DD-slug>"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+Implement a feature task-by-task using the blueprint, then generate the e2e checklist.
+
+**Arguments:** $ARGUMENTS
+
+## Progress Checkbox Format
+
+- `[ ]` not started · `[?]` needs attention · `[o]` in progress · `[x]` complete · `[!]` blocked
+
+A feature is **ready to implement** when: `- [x] Blueprint`
+
+---
+
+## Mode Detection
+
+- If empty or blank → **BROWSE MODE**
+- Otherwise → **IMPLEMENT MODE**
+
+---
+
+## BROWSE MODE
+
+### Step 1: Find ready features
+
+Glob all `.claude/_features/*/1-feature.md`. Collect features where Progress shows `- [x] Blueprint` and `- [ ] Implement`.
+
+If none:
+
+```
+No features are ready to implement.
+
+Features need Blueprint complete before implementing.
+Run /feature:blueprint <slug> to generate a blueprint first.
+```
+
+Then stop.
+
+### Step 2: Display numbered list
+
+```
+Features ready to implement:
+
+1. <feature-title> (<MM.DD-slug>)
+2. <feature-title> (<MM.DD-slug>)
+
+Run /feature:implement <MM.DD-slug> to implement one.
+```
+
+Then stop.
+
+---
+
+## IMPLEMENT MODE
+
+### Step 1: Read feature and blueprint
+
+Read `.claude/_features/$ARGUMENTS/1-feature.md` and `.claude/_features/$ARGUMENTS/3-blueprint.md`.
+
+If folder or blueprint doesn't exist, inform the user and stop.
+
+**Progress check:**
+- `[x] Blueprint` + `[ ] Implement` — proceed
+- `[?] Blueprint` — warn: _"Blueprint needs review. Run /feature:review $ARGUMENTS first."_ Stop.
+- `[ ] Blueprint` or `[o] Blueprint` — warn: _"No complete blueprint. Run /feature:blueprint $ARGUMENTS first."_ Stop.
+- `[o] Implement` — warn: _"Already implementing. Resuming from current progress."_ Continue.
+- `[x] Implement` — warn: _"Already implemented. Proceeding will regenerate the e2e checklist."_ Continue.
+- `[!] <stage>` — warn: _"Feature is blocked at <stage>."_ Stop.
+
+### Step 2: Update Implement to `[o]`
+
+In `1-feature.md`, change `- [ ] Implement` to `- [o] Implement`.
+
+**State update:** Do this before starting any implementation work.
+
+### Step 3: Create the feature branch
+
+Check if this is a git repo:
+
+```bash
+git status
+```
+
+If it is, create the branch from `1-feature.md`'s `**Branch:**` value:
+
+```bash
+git checkout -b <branch_name>
+```
+
+If the branch already exists: `git checkout <branch_name>`.
+If not a git repo, skip and note it.
+
+### Step 4: Implement the blueprint
+
+Read each task in `3-blueprint.md` in order. For each task:
+
+1. Dispatch a fresh subagent (via the Task tool) to implement that task
+2. The subagent must follow strict TDD: write the failing test first, confirm it fails, write minimal implementation, confirm it passes, then commit
+3. Review the subagent's output before moving to the next task — if it failed or skipped TDD, do not proceed
+4. Do not batch multiple tasks into one subagent
+
+### Step 5: Update Implement to `[x]`
+
+Once all tasks are complete:
+- Change `- [o] Implement` to `- [x] Implement` in `1-feature.md`
+- Change `- [ ] Review` to `- [o] Review` in `1-feature.md`
+
+**State update:** Do this immediately after all tasks pass.
+
+### Step 6: Write 5-implementation-decisions.md
+
+Create `.claude/_features/$ARGUMENTS/5-implementation-decisions.md`.
+
+Reflect on the session — patterns chosen, trade-offs made — and write 3-5 key decisions.
+
+```markdown
+# Implementation Decisions: $ARGUMENTS
+
+Key technical decisions made during implementation.
+
+---
+
+## <Short title> — YYYY-MM-DD
+- **Decision:** what was built or decided
+- **Reasoning:** why this approach
+- **Alternatives:** what was considered but not used
+
+---
+```
+
+If the file already exists (resuming), append new entries.
+
+### Step 7: Generate 4-e2e-checklist.md
+
+Create `.claude/_features/$ARGUMENTS/4-e2e-checklist.md` using `.claude/_templates/e2e-checklist.md` as structure.
+
+Populate it from:
+- The **User Experience** section of `2-brief.md`
+- The **Success Criteria** section of `2-brief.md`
+- The **Edge Cases** section of `2-brief.md`
+- Integration points from `3-blueprint.md`
+
+Every scenario must be specific enough to follow without reading the brief — include exact UI labels, URLs, endpoints, or CLI commands as appropriate.
+
+**State update:** After writing the checklist, confirm `1-feature.md` shows `[x] Implement` and `[o] Review`.
+
+### Step 8: Output summary
+
+```
+Implementation complete: $ARGUMENTS
+
+Progress: [x] Brief  [x] Blueprint  [x] Implement  [o] Review  [ ] Done
+
+Branch: <branch_name>
+Tasks completed: <N>
+
+Files created:
+- .claude/_features/$ARGUMENTS/5-implementation-decisions.md
+- .claude/_features/$ARGUMENTS/4-e2e-checklist.md
+
+Next: work through the e2e checklist manually, then mark [x] Review in 1-feature.md.
+```