spec-starter 1.0.0 → 1.1.0

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

@@ -1,26 +1,50 @@
 # <feature_title> — E2E Checklist
 
-Generated after implementation. Work through each scenario manually.
+Generated after implementation. UI scenarios with a URL will run automatically via Playwright MCP if available; others require manual confirmation.
 
 ---
 
 ## Happy Path
 
-- [ ] <Scenario 1: exact steps to follow, expected outcome>
-- [ ] <Scenario 2>
+- [ ] **<Scenario 1 title>**
+  - **URL:** `/<path>`
+  - **Steps:**
+    1. <action using visible label or element description>
+    2. <action>
+  - **Expected:** <what should be visible or true when done>
+
+- [ ] **<Scenario 2 title>**
+  - **URL:** `/<path>`
+  - **Steps:**
+    1. <action>
+  - **Expected:** <outcome>
 
 ## Edge Cases
 
-- [ ] <Edge case 1: what to do, what should happen>
-- [ ] <Edge case 2>
+- [ ] **<Edge case 1 title>**
+  - **URL:** `/<path>`
+  - **Steps:**
+    1. <how to trigger the edge case>
+  - **Expected:** <what the user should see>
+
+- [ ] **<Non-browser check title>**
+  - <Describe what to run or check — no URL needed for non-browser scenarios>
 
 ## Error States
 
-- [ ] <Error scenario: how to trigger, what the user should see>
+- [ ] **<Error scenario title>**
+  - **URL:** `/<path>`
+  - **Steps:**
+    1. <how to trigger the error>
+  - **Expected:** <error message or fallback the user should see>
 
 ## Integration Points
 
-- [ ] <Cross-feature or external dependency check>
+- [ ] **<Cross-feature or external dependency check>**
+  - **URL:** `/<path>`
+  - **Steps:**
+    1. <check to perform>
+  - **Expected:** <expected integration behavior>
 
 ---
 

package/.claude/_templates/feature.md

@@ -23,3 +23,7 @@
 - <Key point 1>
 - <Key point 2>
 - <Key point 3>
+
+## Diagram
+
+<!-- Generated by /feature:blueprint -->

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

@@ -106,10 +106,33 @@ In `1-feature.md`, change `- [o] Blueprint` to `- [x] Blueprint`.
 
 **State update:** Do this immediately after blueprint.md is written.
 
+### Step 6: Generate Mermaid diagram and update 1-feature.md
+
+Based on the blueprint you just wrote, generate a Mermaid architecture diagram that shows the key components or layers and data flow between them. Use `graph TD` orientation (top-down) unless the feature is a linear pipeline, in which case `graph LR` (left-right) is clearer.
+
+Guidelines:
+- 5 to 12 nodes is ideal — keep it concise
+- Label edges with the action or data being passed: `-->|user input|`, `-->|SQL query|`, etc.
+- Use subgraphs only if there are clearly distinct tiers (e.g. Frontend / Backend)
+- No commentary inside the `## Diagram` section — only the fenced code block
+
+Open `1-feature.md` for this feature. Find the `## Diagram` section. If the section is not present (feature created before this template update), append the `## Diagram` section to the end of the file instead. Replace from `## Diagram` to the end of the file with:
+
+````markdown
+## Diagram
+
+```mermaid
+<your generated diagram here>
+```
+````
+
+Use the Edit tool to make this replacement.
+
 Output:
 
 ```
-Blueprint written: .claude/_features/$ARGUMENTS/3-blueprint.md
+Blueprint written:  .claude/_features/$ARGUMENTS/3-blueprint.md
+Diagram updated:    .claude/_features/$ARGUMENTS/1-feature.md (## Diagram)
 
 Progress: [x] Brief  [x] Blueprint  [ ] Implement  [ ] Review  [ ] Done
 ```

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

@@ -1,7 +1,7 @@
 ---
 description: Run through the e2e checklist for a completed feature
 argument-hint: "<MM.DD-slug>"
-allowed-tools: Read, Edit, Glob, Bash
+allowed-tools: Read, Edit, Glob, Bash, mcp__playwright__*
 ---
 
 Walk through the e2e checklist for a feature interactively. The feature must be marked `[x] Done` before testing is allowed.
@@ -89,6 +89,11 @@ 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.
 
+**Playwright check:** Use the Skill tool to invoke the `playwright-test` skill. It will check whether Playwright MCP tools are available and report back.
+
+- If available → use Playwright automatically for all UI scenarios (those with a **URL** field). Note this as `playwright_available = true`.
+- If not available → fall back to manual for all UI scenarios. Note this as `playwright_available = false`.
+
 ### Step 2: Present the checklist and run scenarios
 
 Output a summary of what you're about to test:
@@ -104,10 +109,16 @@ 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
+2. For CLI/script scenarios: run with Bash and report the result
+3. For UI scenarios (those with **URL**, **Steps**, and **Expected** fields):
+   - If `playwright_available = true`: run the scenario automatically using the `playwright-test` skill.
+     - PASS → mark the item `[x]`
+     - FAIL → mark the item `[!]`, note what failed, continue
+     - `[!] ERROR` → mark the item `[!]`, record the error evidence, continue
+   - If `playwright_available = false`: describe exactly what to check and ask the user: `Pass or fail?`
+4. For manual scenarios (no URL field): describe exactly what to check and ask the user: `Pass or fail?`
+5. If the user confirms pass: mark the item `- [x]` in `e2e-checklist.md` using the Edit tool
+6. 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.
 

package/.claude/skills/playwright-test.md

@@ -0,0 +1,112 @@
+---
+name: playwright-test
+description: Run UI scenarios automatically using Playwright MCP browser automation tools.
+---
+
+# Playwright Test
+
+Automate UI e2e scenario execution using Playwright MCP browser tools.
+
+## Availability check
+
+Before using this skill, confirm that Playwright MCP tools are present in your tool list (look for tools prefixed with `mcp__playwright__` or similar browser automation tools). If they are available, proceed with this skill. If they are not available, stop immediately and report to the caller: "Playwright MCP not available." Do not execute any scenarios. The caller is responsible for handling unavailability (typically by asking the user to confirm each scenario manually).
+
+## Scenario structure
+
+Each UI scenario in `4-e2e-checklist.md` follows this format:
+
+```
+- [ ] **<Scenario title>**
+  - **URL:** `/<path>`
+  - **Steps:** numbered list of actions
+  - **Expected:** what should be visible/true when done
+```
+
+Scenarios that have a URL, Steps, and Expected field are in scope for this skill. Scenarios without a URL (CLI checks, API checks, or manual-only verifications) are out of scope — the caller handles those via Bash or manual confirmation.
+
+## Building full URLs
+
+The `## Base URL` section in `.claude/testing.md` provides the origin. If a scenario URL is relative (starts with `/`), prepend the base URL.
+
+Example: base URL `http://localhost:3000` + scenario URL `/dashboard` = `http://localhost:3000/dashboard`.
+
+If `testing.md` has no base URL, ask the user to provide it before proceeding.
+
+## Test accounts
+
+If `.claude/testing.md` defines test credentials under `## Test accounts`, use them for any login flow before navigating to a protected route. Log in once at the start of the test run and reuse the session for subsequent scenarios where possible.
+
+## Running a scenario
+
+For each in-scope scenario:
+
+### 1. Navigate
+
+Navigate to the full URL using the Playwright navigation tool.
+
+### 2. Execute steps
+
+Work through the numbered steps in order:
+
+- **Clicks:** locate the element by its visible label, text, or ARIA role — not by CSS selector. Then click it.
+- **Form inputs:** use fill tools to enter values into fields, identified by their visible label or placeholder text.
+- **Keyboard actions** (Enter, Tab, Escape, etc.): use key press tools.
+
+After all steps are complete, take a screenshot to capture the final state.
+
+### 3. Verify expected outcome
+
+Use page content reading tools (accessibility tree or page text) to check whether the expected text or elements are present.
+
+- If the expected outcome is present: **PASS**.
+- If the expected outcome is absent or an error is visible: **FAIL**.
+
+## Result reporting format
+
+After each scenario, report the result in this format:
+
+```
+Scenario: <title>
+Result: PASS
+Evidence: <what was observed>
+```
+
+or
+
+```
+Scenario: <title>
+Result: FAIL
+Evidence: <what was observed>
+```
+
+Include specific observed text, element presence, or error messages as evidence. Do not report vague evidence like "page loaded correctly."
+
+This skill reports results to the conversation only. It does not modify `4-e2e-checklist.md`. The caller is responsible for marking scenarios `[x]` (pass) or `[!]` (fail) based on this skill's reported outcomes.
+
+## Error handling
+
+If navigation fails or an element cannot be found, try once more using an alternate approach (e.g. a different locator strategy or a short wait before retrying).
+
+If the scenario still cannot be completed after the second attempt, mark it with `[!]`, report the specific error and evidence, and continue to the next scenario. Never hang or retry infinitely.
+
+```
+Scenario: <title>
+Result: [!] ERROR
+Evidence: <specific error message or what was observed>
+```
+
+## Output summary
+
+After all scenarios are complete, output a summary table:
+
+```
+## E2E Results
+
+| Scenario | Result |
+|----------|--------|
+| <title>  | PASS   |
+| <title>  | FAIL   |
+| <title>  | [!] ERROR |
+```
+
+Then list any FAIL or ERROR scenarios with their full evidence for follow-up.

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

@@ -34,6 +34,7 @@ Ask one question about manual/e2e testing setup:
 - Are there test accounts or credentials needed?
 - Any browser or device requirements?
 - Anything else needed to run through features manually?
+- Is this a web app? If yes, what is the local dev base URL? (e.g. `http://localhost:3000`)
 
 ### 3. Update CLAUDE.md
 
@@ -57,7 +58,10 @@ Write `.claude/testing.md` with the manual testing setup gathered in Step 2. Thi
 # Testing
 
 ## How to start the app
-<dev server command and URL, or staging URL>
+<dev server command>
+
+## Base URL
+<base URL for the running app, e.g. http://localhost:3000 — or "N/A" if not a web app>
 
 ## Test accounts
 <credentials or "none required">

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.1.0",
   "description": "Claude Code project template for structured feature development",
   "bin": {
     "spec-starter": "bin/index.js"