spec-starter 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+A Claude Code project template for structured feature development. Run `npx spec-starter` in any project to get a repeatable workflow for taking features from raw idea to tested implementation.
 
 ## How it works
 
@@ -21,7 +21,7 @@ Each stage has a matching slash command. Commands are interactive: called withou
 | 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:start` | List backlog tasks | Create feature folder + `1-feature.md` + `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` |
@@ -41,10 +41,11 @@ Backlog idea (.claude/tasks.md)
 /feature:blueprint <slug>  → .claude/_features/<slug>/3-blueprint.md             [x] Blueprint
     ↓
 /feature:implement <slug>  → writes code (TDD), generates 4-e2e-checklist.md     [x] Implement
+    ↓                                                                             [o] Review
+    · manually work through 4-e2e-checklist.md
     ↓
-Manual review              → work through 4-e2e-checklist.md                     [x] Review
-    ↓
-/feature:finish <slug>     → push branch, PR into dev, merge, mark Done         [x] Done
+/feature:finish <slug>     → push branch, PR into dev, merge, mark Done         [x] Review
+    ↓                                                                             [x] Done
     ↓
 /feature:test <slug>       → walk e2e checklist interactively (post-merge QA)
 ```
@@ -91,9 +92,23 @@ 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
+In your project root:
+
+```bash
+npx spec-starter
+```
+
+Then open Claude Code — `project-init` runs automatically on first open, generating `CLAUDE.md` and `.claude/testing.md`.
+
+Add ideas to `.claude/tasks.md` (one per line), then run `/feature:start <idea>` to turn one into a feature.
+
+## Updating
+
+Run the same command again to sync the latest engine files. Your project data (`_features/`, `tasks.md`, `testing.md`, `CLAUDE.md`) is never touched. Claude will announce the update next time you open the project.
+
+```bash
+npx spec-starter
+```
 
 ## Design principle
 

package/bin/index.js

@@ -3,32 +3,26 @@
 const fs = require('fs');
 const path = require('path');
 
-const src = path.join(__dirname, '..');
-const dest = process.cwd();
+const PKG_DIR = path.join(__dirname, '..');
+const TARGET_DIR = process.cwd();
+const VERSION = require('../package.json').version;
 
-// Always overwrite — these are the engine files
-const engineDirs = [
+const SCAFFOLD_DIRS = [
   '.claude/commands',
   '.claude/skills',
   '.claude/_templates',
   '.claude/hooks',
 ];
-const engineFiles = [
-  '.claude/settings.json',
-];
 
-// Create only if missing — project seeds
-const seedFiles = [
-  ['.claude/tasks.md', ''],
+const SCAFFOLD_FILES = [
+  '.claude/settings.json',
 ];
 
-// 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);
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
     if (entry.isDirectory()) {
       copyDir(srcPath, destPath);
     } else {
@@ -37,33 +31,85 @@ function copyDir(srcDir, destDir) {
   }
 }
 
-const isUpdate = fs.existsSync(path.join(dest, '.claude'));
-console.log(isUpdate ? 'Syncing spec-starter...\n' : 'Installing spec-starter...\n');
+// Copy scaffold
+for (const dir of SCAFFOLD_DIRS) {
+  const src = path.join(PKG_DIR, dir);
+  const dest = path.join(TARGET_DIR, dir);
+  if (fs.existsSync(src)) copyDir(src, dest);
+}
 
-fs.mkdirSync(path.join(dest, '.claude'), { recursive: true });
+for (const file of SCAFFOLD_FILES) {
+  const src = path.join(PKG_DIR, file);
+  const dest = path.join(TARGET_DIR, file);
+  if (fs.existsSync(src)) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
 
-for (const dir of engineDirs) {
-  copyDir(path.join(src, dir), path.join(dest, dir));
-  console.log(`  ✓ ${dir}`);
+// Version tracking
+const VERSION_FILE = path.join(TARGET_DIR, '.claude', '.spec-starter-version');
+const CLAUDE_MD = path.join(TARGET_DIR, 'CLAUDE.md');
+
+function readInstalledVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(VERSION_FILE, 'utf8')).version;
+  } catch {
+    return null;
+  }
 }
 
-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}`);
+function writeInstalledVersion() {
+  fs.writeFileSync(VERSION_FILE, JSON.stringify({ version: VERSION }, null, 2));
 }
 
-for (const [file, content] of seedFiles) {
-  const destFile = path.join(dest, file);
-  if (!fs.existsSync(destFile)) {
-    fs.writeFileSync(destFile, content);
-    console.log(`  ✓ ${file} (created)`);
+// Bootstrap CLAUDE.md for fresh installs
+function writeBootstrapClaudeMd() {
+  const content = `<!-- spec-starter:bootstrap -->
+Run the \`project-init\` skill now. Do not do anything else first.
+<!-- /spec-starter:bootstrap -->
+`;
+  fs.writeFileSync(CLAUDE_MD, content);
+}
+
+// Inject update notice into existing CLAUDE.md
+const NOTICE_START = '<!-- spec-starter:notice -->';
+const NOTICE_END = '<!-- /spec-starter:notice -->';
+
+function injectUpdateNotice() {
+  const notice = `${NOTICE_START}
+spec-starter was updated to v${VERSION}. Let the user know what changed, then remove this notice block from CLAUDE.md.
+${NOTICE_END}`;
+
+  const existing = fs.readFileSync(CLAUDE_MD, 'utf8');
+
+  if (existing.includes(NOTICE_START)) {
+    // Replace existing notice
+    const updated = existing.replace(
+      new RegExp(`${NOTICE_START}[\\s\\S]*?${NOTICE_END}`),
+      notice
+    );
+    fs.writeFileSync(CLAUDE_MD, updated);
   } else {
-    console.log(`  - ${file} (kept existing)`);
+    // Prepend notice
+    fs.writeFileSync(CLAUDE_MD, notice + '\n\n' + existing);
   }
 }
 
-console.log(isUpdate
-  ? '\nDone. Engine files updated, project data untouched.'
-  : '\nDone. Run /project-init in Claude Code to set up your project.'
-);
+// Main
+const installedVersion = readInstalledVersion();
+const claudeMdExists = fs.existsSync(CLAUDE_MD);
+
+if (!claudeMdExists) {
+  writeBootstrapClaudeMd();
+  console.log(`spec-starter v${VERSION} installed.`);
+  console.log('Open Claude Code — project-init will run automatically.');
+} else if (installedVersion !== VERSION) {
+  injectUpdateNotice();
+  console.log(`spec-starter updated to v${VERSION}.`);
+  console.log('Claude will announce the update next time you open this project.');
+} else {
+  console.log(`spec-starter v${VERSION} refreshed.`);
+}
+
+writeInstalledVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-starter",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Claude Code project template for structured feature development",
   "bin": {
     "spec-starter": "bin/index.js"