spec-starter 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# spec-starter
+
+A Claude Code project template for structured feature development. Drop the `.claude/` folder into any project to get a repeatable workflow for taking features from raw idea to tested implementation.
+
+## How it works
+
+Every feature lives in `.claude/_features/<slug>/` and moves through five stages tracked as checkboxes in `1-feature.md`:
+
+```
+- [ ] Brief      ← define what to build (non-technical)
+- [ ] Blueprint  ← define how to build it (technical)
+- [ ] Implement  ← write the code (TDD)
+- [ ] Review     ← manual e2e testing
+- [ ] Done
+```
+
+Each stage has a matching slash command. Commands are interactive: called without arguments they show what is available at that stage rather than failing silently.
+
+## Commands
+
+| Command | No args | With arg |
+|---|---|---|
+| `/task` | List backlog tasks | Add idea to `.claude/tasks.md` |
+| `/feature:start` | List backlog tasks | Create feature folder + `2-brief.md` |
+| `/feature:review` | List `[?]` features | Review current state and take next action |
+| `/feature:blueprint` | List `[x]` Brief features ready to blueprint | Generate `3-blueprint.md` |
+| `/feature:implement` | List `[x]` Blueprint features ready to implement | Implement + generate `4-e2e-checklist.md` |
+| `/feature:finish` | List `[o]` Review features | Push branch, create PR into `dev`, optionally merge, mark Done |
+| `/feature:test` | List `[x]` Done features | Walk through `4-e2e-checklist.md` interactively, marking pass/fail |
+| `/feature:status` | List all features and their states | — |
+| `/project-init` | Bootstrap a new project — generates `CLAUDE.md`, asks context questions, writes `.claude/testing.md` | — |
+
+## Feature lifecycle
+
+```
+Backlog idea (.claude/tasks.md)
+    ↓
+/feature:start <idea>      → .claude/_features/<slug>/1-feature.md + 2-brief.md    [?] Brief
+/feature:review <slug>     → iterate on brief, marks [x] Brief when complete
+    ↓
+/feature:blueprint <slug>  → .claude/_features/<slug>/3-blueprint.md             [x] Blueprint
+    ↓
+/feature:implement <slug>  → writes code (TDD), generates 4-e2e-checklist.md     [x] Implement
+    ↓
+Manual review              → work through 4-e2e-checklist.md                     [x] Review
+    ↓
+/feature:finish <slug>     → push branch, PR into dev, merge, mark Done         [x] Done
+    ↓
+/feature:test <slug>       → walk e2e checklist interactively (post-merge QA)
+```
+
+After `/feature:start`, Claude writes a draft brief and flags it `[?] Brief` — meaning it needs your attention. Answer the questions Claude left in `2-brief.md`, then run `/feature:review <slug>` to iterate until the brief is complete.
+
+## Files per feature
+
+```
+.claude/_features/<slug>/
+  1-feature.md                  — state checkboxes, title, slug, branch name
+  2-brief.md                    — non-technical goals, requirements, Q&A
+  3-blueprint.md                — technical implementation plan (TDD tasks)
+  4-e2e-checklist.md            — manual testing scenarios (generated post-implement)
+  5-implementation-decisions.md — key technical decisions log (generated post-implement)
+```
+
+## State symbols
+
+| Symbol | Meaning |
+|---|---|
+| `[ ]` | Not started |
+| `[?]` | Needs attention — Claude or you flagged this for review |
+| `[o]` | In progress |
+| `[x]` | Complete |
+| `[!]` | Blocked |
+
+Either Claude or you can set `[?]` on any stage to trigger a review. Running `/feature:review <slug>` reads the current `[?]` state in `1-feature.md` and takes the appropriate next action automatically.
+
+## Hooks
+
+Two `PostToolUse` hooks run automatically (registered in `.claude/settings.json`):
+
+- **post-edit.sh** — auto-commits file edits to git with a `minor/moderate/major` size label based on lines changed
+- **post-write.sh** — auto-commits newly created files
+
+The hooks are no-ops outside of git repositories.
+
+## Shared testing instructions
+
+`/project-init` asks how to manually test the app and writes `.claude/testing.md` with the answers — start command, base URL, test accounts, browser requirements, etc. `/feature:test` reads this file automatically so it has the right context when walking through e2e scenarios.
+
+You can also create or edit `.claude/testing.md` by hand at any time.
+
+## Getting started
+
+1. Copy this repo's `.claude/` folder into your project root
+2. Run `/project-init` to generate `CLAUDE.md` with project context and `.claude/testing.md` with testing setup
+3. Add ideas to `.claude/tasks.md` (one per line), then run `/feature:start <idea>` to turn one into a feature
+
+## Design principle
+
+Every command owns its own state transitions in `1-feature.md`. Nothing relies on `CLAUDE.md` for workflow logic — `CLAUDE.md` is project-specific context that `/project-init` writes fresh for each project.

package/bin/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const src = path.join(__dirname, '..');
+const dest = process.cwd();
+
+// Always overwrite — these are the engine files
+const engineDirs = [
+  '.claude/commands',
+  '.claude/skills',
+  '.claude/_templates',
+  '.claude/hooks',
+];
+const engineFiles = [
+  '.claude/settings.json',
+];
+
+// Create only if missing — project seeds
+const seedFiles = [
+  ['.claude/tasks.md', ''],
+];
+
+// Never touch: .claude/_features/, CLAUDE.md, .claude/testing.md
+
+function copyDir(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+const isUpdate = fs.existsSync(path.join(dest, '.claude'));
+console.log(isUpdate ? 'Syncing spec-starter...\n' : 'Installing spec-starter...\n');
+
+fs.mkdirSync(path.join(dest, '.claude'), { recursive: true });
+
+for (const dir of engineDirs) {
+  copyDir(path.join(src, dir), path.join(dest, dir));
+  console.log(`  ✓ ${dir}`);
+}
+
+for (const file of engineFiles) {
+  fs.mkdirSync(path.dirname(path.join(dest, file)), { recursive: true });
+  fs.copyFileSync(path.join(src, file), path.join(dest, file));
+  console.log(`  ✓ ${file}`);
+}
+
+for (const [file, content] of seedFiles) {
+  const destFile = path.join(dest, file);
+  if (!fs.existsSync(destFile)) {
+    fs.writeFileSync(destFile, content);
+    console.log(`  ✓ ${file} (created)`);
+  } else {
+    console.log(`  - ${file} (kept existing)`);
+  }
+}
+
+console.log(isUpdate
+  ? '\nDone. Engine files updated, project data untouched.'
+  : '\nDone. Run /project-init in Claude Code to set up your project.'
+);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "spec-starter",
+  "version": "1.0.0",
+  "description": "Claude Code project template for structured feature development",
+  "bin": {
+    "spec-starter": "bin/index.js"
+  },
+  "files": [
+    "bin/",
+    ".claude/commands/",
+    ".claude/skills/",
+    ".claude/_templates/",
+    ".claude/hooks/",
+    ".claude/settings.json"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "template"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonesopolis/spec-starter.git"
+  }
+}