spec-starter 1.0.0

package/.claude/commands/feature/review.md

@@ -0,0 +1,107 @@
+---
+description: Review a feature in its current state and take the appropriate next action
+argument-hint: "<MM.DD-slug>"
+allowed-tools: Read, Write, Edit, Glob
+---
+
+Review a feature and take the next appropriate action based on its current state. Either Claude or the user can set `[?]` on any stage to flag it for review.
+
+**Arguments:** $ARGUMENTS
+
+## Progress Checkbox Format
+
+- `[ ]` not started · `[?]` needs attention · `[o]` in progress · `[x]` complete · `[!]` blocked
+
+---
+
+## Mode Detection
+
+- If empty or blank → **BROWSE MODE**
+- Otherwise → **REVIEW MODE**
+
+---
+
+## BROWSE MODE
+
+### Step 1: Find flagged features
+
+Use Glob to find all `.claude/_features/*/1-feature.md`. Read each one and collect features that have any `[?]` checkbox.
+
+If none:
+
+```
+No features are flagged for review.
+
+To flag a feature: set any checkbox to [?] in its 1-feature.md,
+or run /feature:start <idea> to create a new one.
+```
+
+Then stop.
+
+### Step 2: Display numbered list
+
+```
+Features needing review:
+
+1. <feature-title> (<MM.DD-slug>) — [?] <stage>
+2. <feature-title> (<MM.DD-slug>) — [?] <stage>
+
+Run /feature:review <MM.DD-slug> to review one.
+```
+
+Then stop.
+
+---
+
+## REVIEW MODE
+
+### Step 1: Read feature state
+
+Read `.claude/_features/$ARGUMENTS/1-feature.md`.
+
+If the folder doesn't exist:
+
+```
+No feature found: $ARGUMENTS
+Run /feature:start <idea> to create one.
+```
+
+Then stop.
+
+### Step 2: Determine active state and act
+
+Find which checkbox has `[?]` and act accordingly:
+
+**`[?] Brief`:**
+1. Read `.claude/_features/$ARGUMENTS/2-brief.md`
+2. Answer any unanswered "Questions from User" using codebase research
+3. Review "Questions from Claude" — if the user has answered them, incorporate those answers into the relevant brief sections (Overview, Goals, Requirements, etc.)
+4. Identify any remaining gaps — if the brief is still incomplete, add new questions and keep `[?] Brief`
+5. If the brief is complete (no unanswered Questions from Claude remain), update `1-feature.md`:
+   - Change `- [?] Brief` to `- [x] Brief`
+6. **State update:** Always update `1-feature.md` after taking action.
+7. Output what changed and what the next step is.
+
+**`[?] Blueprint`:**
+1. Read `.claude/_features/$ARGUMENTS/2-brief.md` and `.claude/_features/$ARGUMENTS/3-blueprint.md`
+2. Review the blueprint for completeness, gaps, or errors
+3. Update `3-blueprint.md` with corrections or additions
+4. If complete, change `- [?] Blueprint` to `- [x] Blueprint` in `1-feature.md`
+5. **State update:** Always update `1-feature.md` after taking action.
+
+**`[?] Implement`:**
+1. Read `.claude/_features/$ARGUMENTS/1-feature.md` and relevant implementation files
+2. Surface any issues found — summarize what needs attention
+3. Suggest next action to the user
+
+**Any other `[?]` state:**
+1. Read the relevant artifact for that stage
+2. Surface what needs attention
+3. Suggest next action
+
+**No `[?]` found:**
+Summarize the feature's current state and suggest the logical next command:
+- `[x] Brief` + no blueprint → suggest `/feature:blueprint $ARGUMENTS`
+- `[x] Blueprint` + no implement → suggest `/feature:implement $ARGUMENTS`
+- `[x] Implement` → suggest running the e2e checklist
+- `[x] Done` → feature is complete, nothing to do

package/.claude/commands/feature/start.md

@@ -0,0 +1,126 @@
+---
+description: Start a feature — create folder, 2-brief.md, and 1-feature.md from a backlog task
+argument-hint: "<idea or task number>"
+allowed-tools: Read, Write, Edit, Glob, Bash
+---
+
+Turn a backlog task into a feature folder with `1-feature.md` and `2-brief.md`.
+
+**Arguments:** $ARGUMENTS
+
+## Mode Detection
+
+- If empty or blank → **BROWSE MODE**
+- Otherwise → **CREATE MODE**
+
+---
+
+## BROWSE MODE
+
+### Step 1: Read the backlog
+
+Read `.claude/tasks.md`.
+
+If no items exist:
+
+```
+No backlog tasks found.
+
+Add ideas to .claude/tasks.md or run /feature:start <idea> directly.
+```
+
+Then stop.
+
+### Step 2: Display numbered options
+
+```
+Backlog tasks (pick one to start):
+
+1. <task>
+2. <task>
+...
+
+Run /feature:start <number> to create a feature, or /feature:start <new idea> to start fresh.
+```
+
+Then stop.
+
+---
+
+## CREATE MODE
+
+### Step 1: Resolve the idea
+
+If `$ARGUMENTS` is a number, read `.claude/tasks.md` and use the item at that position as the idea.
+Otherwise use `$ARGUMENTS` directly as the idea.
+
+### Step 2: Derive names
+
+From the idea, derive:
+- `feature_title` — short, Title Case, human readable
+- `feature_slug` — lowercase kebab-case, only `a-z 0-9 -`, max 40 chars
+- `branch_name` — `feature/<feature_slug>`
+- `folder_name` — `MM.DD-<feature_slug>` using today's date (e.g. `02.22-my-feature`)
+
+If you cannot infer a clear title and slug, ask the user to clarify.
+
+### Step 3: Create the feature folder
+
+```bash
+mkdir -p .claude/_features/<folder_name>
+```
+
+### Step 4: Write 1-feature.md
+
+Create `.claude/_features/<folder_name>/1-feature.md` using `.claude/_templates/feature.md` as the structure.
+
+Fill in:
+- Title, slug set to `<folder_name>`, branch name
+- A 2-3 sentence description based on the idea
+- 2-3 key points
+
+Set Progress to:
+
+```
+- [?] Brief
+- [ ] Blueprint
+- [ ] Implement
+- [ ] Review
+- [ ] Done
+```
+
+**State update:** Setting `[?] Brief` signals that Claude has written the brief and it needs review.
+
+### Step 5: Write 2-brief.md
+
+Create `.claude/_features/<folder_name>/2-brief.md` using `.claude/_templates/brief.md` as the structure.
+
+Fill in:
+- Overview based on the idea
+- Goals inferred from the idea
+- Draft Requirements (must-have only — keep it lean)
+- Placeholder User Experience
+- 2-3 likely Edge Cases
+- Out of Scope (anything clearly not included)
+- Draft Success Criteria
+- 2-4 Questions from Claude (things you genuinely need answered to finalize the brief)
+
+### Step 6: Remove from backlog
+
+If this idea came from a numbered item in `.claude/tasks.md`, remove that line using the Edit tool.
+
+### Step 7: Output
+
+```
+Feature created: <feature_title>
+Folder: .claude/_features/<folder_name>/
+Branch (not created yet): <branch_name>
+
+Progress: [?] Brief  [ ] Blueprint  [ ] Implement  [ ] Review  [ ] Done
+
+Files:
+- 1-feature.md (state + description)
+- 2-brief.md (non-technical goals + questions)
+
+Next: answer the questions in 2-brief.md, then run /feature:review <folder_name>.
+```

package/.claude/commands/feature/status.md

@@ -0,0 +1,76 @@
+---
+description: List all features and their current states
+allowed-tools: Glob, Read
+---
+
+List all features in `.claude/_features/` with their current progress.
+
+## Step 1: Find all feature folders
+
+Glob all `.claude/_features/*/1-feature.md`.
+
+If none:
+
+```
+No features found.
+
+Run /feature:start <idea> to create one, or /task to browse the backlog.
+```
+
+Then stop.
+
+## Step 2: Read each 1-feature.md
+
+For each, extract:
+- Feature title (first `#` heading)
+- Folder name (the directory name from the path, e.g. `02.22-my-feature`)
+- Branch (from `**Branch:**` line)
+- Progress checkboxes (Brief, Blueprint, Implement, Review, Done lines)
+
+## Step 3: Determine active stage
+
+For each feature:
+- Active stage = checkbox marked `[o]`, `[?]`, or `[!]`
+- If all `[x]` → Done
+- If all `[ ]` → Not started
+
+## Step 4: Output
+
+Group by active stage in lifecycle order. Omit empty groups.
+
+```
+Feature Status
+──────────────────────────────────────────────────
+
+[?] Brief — needs your attention
+  1. <feature-title> (<MM.DD-slug>)
+     [?]Brief  [ ]Blueprint  [ ]Implement  [ ]Review  [ ]Done
+
+[x] Brief — ready to blueprint
+  2. <feature-title> (<MM.DD-slug>)
+     [x]Brief  [ ]Blueprint  [ ]Implement  [ ]Review  [ ]Done
+
+[o] Blueprint
+  3. <feature-title> (<MM.DD-slug>)
+     [x]Brief  [o]Blueprint  [ ]Implement  [ ]Review  [ ]Done
+
+[x] Blueprint — ready to implement
+  ...
+
+[o] Implement
+  ...
+
+[o] Review
+  ...
+
+Done
+  ...
+
+Blocked
+  <feature-title> (<MM.DD-slug>) — blocked at <stage>
+
+──────────────────────────────────────────────────
+<N> features total
+```
+
+Show folder names (e.g. `02.22-my-feature`) in parentheses — that is what the user passes to all other commands.

package/.claude/commands/feature/test.md

@@ -0,0 +1,144 @@
+---
+description: Run through the e2e checklist for a completed feature
+argument-hint: "<MM.DD-slug>"
+allowed-tools: Read, Edit, Glob, Bash
+---
+
+Walk through the e2e checklist for a feature interactively. The feature must be marked `[x] Done` before testing is allowed.
+
+**Arguments:** $ARGUMENTS
+
+## Progress Checkbox Format
+
+- `[ ]` not started · `[?]` needs attention · `[o]` in progress · `[x]` complete · `[!]` blocked
+
+A feature is **ready to test** when: `- [x] Done`
+
+---
+
+## Mode Detection
+
+- If empty or blank → **BROWSE MODE**
+- Otherwise → **TEST MODE**
+
+---
+
+## BROWSE MODE
+
+### Step 1: Find done features
+
+Glob all `.claude/_features/*/1-feature.md`. Collect features where Progress shows `- [x] Done`.
+
+If none:
+```
+No features are marked Done.
+
+Only completed features can be e2e tested.
+Run /feature:finish <MM.DD-slug> to complete a feature first.
+```
+Then stop.
+
+### Step 2: Display numbered list
+
+```
+Features ready for e2e testing:
+
+1. <feature-title> (<MM.DD-slug>)
+2. <feature-title> (<MM.DD-slug>)
+
+Run /feature:test <MM.DD-slug> to run through the checklist.
+```
+
+Then stop.
+
+---
+
+## TEST MODE
+
+### Step 1: Read feature, checklist, and testing instructions
+
+Read `.claude/_features/$ARGUMENTS/1-feature.md`.
+
+If the folder doesn't exist:
+```
+No feature found: $ARGUMENTS
+```
+Then stop.
+
+**Progress check:**
+- `[x] Done` — proceed
+- Anything else — stop and output:
+```
+Feature is not marked Done yet.
+
+Only completed features can be e2e tested.
+Current state: <active stage>
+
+Run /feature:finish $ARGUMENTS to complete the feature first.
+```
+
+Read `.claude/_features/$ARGUMENTS/4-e2e-checklist.md`.
+
+If the checklist doesn't exist:
+```
+No e2e checklist found for: $ARGUMENTS
+
+The checklist is generated by /feature:implement. If it's missing, re-run /feature:implement $ARGUMENTS.
+```
+Then stop.
+
+**Read shared testing instructions:** Check if `.claude/testing.md` exists. If it does, read it and use it throughout — it contains app-specific context like how to start the app, base URLs, test accounts, browser/device preferences, and any other setup needed to run scenarios correctly.
+
+### Step 2: Present the checklist and run scenarios
+
+Output a summary of what you're about to test:
+```
+E2E Testing: <feature-title>
+Checklist: .claude/_features/$ARGUMENTS/4-e2e-checklist.md
+
+Working through each scenario. Confirm pass or fail as you go.
+──────────────────────────────────────────────────
+```
+
+Then work through each section of the checklist in order:
+
+For each unchecked scenario (`- [ ]`):
+1. Present the scenario clearly — what to do and what to expect
+2. For any scenario involving CLI commands or scripts, run them using Bash and report the result
+3. For UI or manual scenarios, describe exactly what to check and ask the user to confirm: `Pass or fail?`
+4. If the user confirms pass: mark the item `- [x]` in `e2e-checklist.md` using the Edit tool
+5. If the user says fail: mark the item `- [!]` in `e2e-checklist.md`, note what failed, and continue to the next scenario
+
+Skip scenarios already marked `[x]` (previously passed) — report them as already passing.
+
+### Step 3: Output results
+
+After all scenarios:
+
+```
+E2E Test Results: <feature-title>
+──────────────────────────────────────────────────
+Passed:  <N>
+Failed:  <N>
+Skipped: <N>
+──────────────────────────────────────────────────
+```
+
+If all passed:
+
+Update `1-feature.md`: set `**Last Tested:**` to today's date in `MM.DD.YYYY` format.
+
+```
+✓ All scenarios passed. Feature fully validated.
+Last Tested updated in 1-feature.md.
+```
+
+If any failed:
+```
+✗ <N> scenario(s) failed. Review the failures in:
+  .claude/_features/$ARGUMENTS/4-e2e-checklist.md
+
+Failed items are marked [!]. Fix the issues and re-run /feature:test $ARGUMENTS.
+```
+
+**Note:** This command does not change the feature's Done state — it only updates the checklist file.

package/.claude/commands/project-init.md

@@ -0,0 +1 @@
+Use the Skill tool to invoke the skill named "project-init" with any arguments provided by the user: $ARGUMENTS

package/.claude/commands/task.md

@@ -0,0 +1,64 @@
+---
+description: List backlog tasks, or add a new idea to the backlog
+argument-hint: "[add] <idea>"
+allowed-tools: Read, Edit, Write
+---
+
+Manage the task backlog in `.claude/tasks.md`.
+
+**Arguments:** $ARGUMENTS
+
+## Mode Detection
+
+- If empty or blank → **LIST MODE**
+- If starts with `add ` (case-insensitive) → **ADD MODE** (strip the `add ` prefix, use the rest as the idea)
+- Otherwise → **ADD MODE** (use `$ARGUMENTS` as the idea directly)
+
+---
+
+## LIST MODE
+
+### Step 1: Read the backlog
+
+Read `.claude/tasks.md`.
+
+If it doesn't exist or has no items, output:
+
+```
+No backlog items found.
+
+Edit .claude/tasks.md to add ideas — one per line.
+Or run /feature:start <idea> to create a feature directly.
+```
+
+Then stop.
+
+### Step 2: Display numbered list
+
+```
+Backlog tasks:
+
+1. <task>
+2. <task>
+...
+
+Run /feature:start <number or idea> to turn one into a feature.
+```
+
+Then stop.
+
+---
+
+## ADD MODE
+
+### Step 1: Append to backlog
+
+Extract the idea: if `$ARGUMENTS` starts with `add ` (case-insensitive), strip that prefix. Otherwise use `$ARGUMENTS` as-is. Add the idea as a new line item to `.claude/tasks.md`.
+
+### Step 2: Output confirmation
+
+```
+Added to backlog: <idea>
+
+Run /task to see the full backlog.
+```

package/.claude/hooks/post-edit.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# post-edit.sh
+# Auto-commits file edits to git with a sized commit message.
+
+if git rev-parse --git-dir >/dev/null 2>&1 && [[ -n "$CLAUDE_TOOL_FILE_PATH" ]]; then
+  git add "$CLAUDE_TOOL_FILE_PATH" 2>/dev/null
+
+  CHANGED_LINES=$(git diff --cached --numstat "$CLAUDE_TOOL_FILE_PATH" 2>/dev/null | awk '{print $1+$2}')
+
+  if [[ $CHANGED_LINES -gt 0 ]]; then
+    FILENAME=$(basename "$CLAUDE_TOOL_FILE_PATH")
+
+    if [[ $CHANGED_LINES -lt 10 ]]; then
+      SIZE="minor"
+    elif [[ $CHANGED_LINES -lt 50 ]]; then
+      SIZE="moderate"
+    else
+      SIZE="major"
+    fi
+
+    git commit -m "Update $FILENAME: $SIZE changes ($CHANGED_LINES lines)" "$CLAUDE_TOOL_FILE_PATH" 2>/dev/null || true
+  fi
+fi

package/.claude/hooks/post-write.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# post-write.sh
+# Auto-commits newly written files to git.
+
+if git rev-parse --git-dir >/dev/null 2>&1 && [[ -n "$CLAUDE_TOOL_FILE_PATH" ]]; then
+  git add "$CLAUDE_TOOL_FILE_PATH" 2>/dev/null
+  FILENAME=$(basename "$CLAUDE_TOOL_FILE_PATH")
+  git commit -m "Add new file: $FILENAME" "$CLAUDE_TOOL_FILE_PATH" 2>/dev/null || true
+fi

package/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/post-edit.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/post-write.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/project-init.md

@@ -0,0 +1,104 @@
+---
+name: project-init
+description: Initialize a new project. Creates CLAUDE.md via /init, gathers context through dialogue, and seeds the task backlog.
+---
+
+# Project Init
+
+Bootstrap a new project with context and an initial backlog.
+
+## Steps
+
+### 1. Run /init
+
+Call the built-in `/init` command to scan the codebase and generate `CLAUDE.md` in the project root.
+
+### 2. Ask brainstorming questions — one at a time
+
+Ask questions one at a time to understand the project. Do not send multiple questions in one message.
+
+Cover (skip if already clear from `/init` output):
+- What is this project and what problem does it solve?
+- Who are the users?
+- What does a successful first version look like?
+- Any technical constraints or integration points?
+- What should NOT be in scope right now?
+
+Also confirm from the codebase (check package.json, Makefile, README, etc.):
+- Test command (e.g. `bun test`, `pytest`, `npm test`)
+- Run/dev command
+- Commit message convention (e.g. conventional commits, plain English)
+
+Ask one question about manual/e2e testing setup:
+- How do you manually test this app? (e.g. local dev server URL, staging URL, mobile device)
+- Are there test accounts or credentials needed?
+- Any browser or device requirements?
+- Anything else needed to run through features manually?
+
+### 3. Update CLAUDE.md
+
+Append a `## Project Context` section to `CLAUDE.md` with a summary of what you learned:
+
+```markdown
+## Project Context
+
+**Goal:** <one sentence>
+**Users:** <who uses this>
+**Stack:** <key tech>
+**Constraints:** <anything important>
+**Out of scope:** <what to avoid>
+```
+
+### 4. Write `.claude/testing.md`
+
+Write `.claude/testing.md` with the manual testing setup gathered in Step 2. This file is read by `/feature:test` to inform how e2e scenarios are run.
+
+```markdown
+# Testing
+
+## How to start the app
+<dev server command and URL, or staging URL>
+
+## Test accounts
+<credentials or "none required">
+
+## Browser / device
+<any requirements, or "any">
+
+## Other notes
+<anything else needed to test manually>
+```
+
+Only include sections that are relevant. Omit or mark "none" for anything that doesn't apply.
+
+### 5. Clear the README
+
+Overwrite `README.md` with a minimal stub so the generic starter content is gone:
+
+```markdown
+# <project name>
+
+<one sentence description>
+```
+
+### 6. Seed `.claude/tasks.md`
+
+Write the first few backlog items based on the conversation — one idea per line, plain text, no checkboxes:
+
+```
+<first task>
+<second task>
+<third task>
+```
+
+Keep it short and actionable. These should be the next real steps, not a full roadmap.
+
+### 7. Output
+
+```
+CLAUDE.md updated with project context.
+Testing instructions written: .claude/testing.md
+Backlog seeded: .claude/tasks.md
+
+Next: /feature:start <idea> to turn a backlog item into a feature.
+```