spec-starter 1.0.1 → 1.1.1

package/.claude/_templates/blueprint.md

@@ -9,6 +9,8 @@
 
 **Tech Stack:** <Key technologies, libraries, frameworks>
 
+**E2E Tests:** <yes — checklist generated after implement | no — no checklist>
+
 ---
 
 ## Prerequisites

package/.claude/_templates/brief.md

@@ -47,6 +47,9 @@ _Claude needs answers to these to finalize the brief. Set feature to `[?] Brief`
 - <Question 1>
   - Answer:
 
+- **Does this feature need e2e test planning?** (answer: yes or no — required before brief can be finalised)
+  - Answer:
+
 ## Questions from User
 
 _User questions for Claude to research and answer._

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

@@ -3,6 +3,7 @@
 **Slug:** `<MM.DD-feature_slug>`
 **Branch:** `<branch_name>`
 **Last Tested:** —
+**E2E Tests:** —
 
 ## Progress
 
@@ -23,3 +24,7 @@
 - <Key point 1>
 - <Key point 2>
 - <Key point 3>
+
+## Diagram
+
+<!-- Generated by /feature:blueprint -->

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

@@ -100,16 +100,41 @@ The blueprint must be:
 - **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
 
+When filling the `**E2E Tests:**` field in the blueprint header, read the value of `**E2E Tests:**` from `1-feature.md`. Write `yes — checklist generated after implement` if yes, or `no — no checklist` if no.
+
 ### 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.
 
+### 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/implement.md

@@ -134,7 +134,12 @@ Key technical decisions made during implementation.
 
 If the file already exists (resuming), append new entries.
 
-### Step 7: Generate 4-e2e-checklist.md
+### Step 7: Generate 4-e2e-checklist.md (if needed)
+
+Read `**E2E Tests:**` from `1-feature.md`.
+
+- If `no`: skip this step entirely. Do not create `4-e2e-checklist.md`. Go directly to Step 8.
+- If `yes` or `—` (unanswered — treat as yes for safety): continue with the rest of this step.
 
 Create `.claude/_features/$ARGUMENTS/4-e2e-checklist.md` using `.claude/_templates/e2e-checklist.md` as structure.
 
@@ -160,7 +165,7 @@ Tasks completed: <N>
 
 Files created:
 - .claude/_features/$ARGUMENTS/5-implementation-decisions.md
-- .claude/_features/$ARGUMENTS/4-e2e-checklist.md
+- .claude/_features/$ARGUMENTS/4-e2e-checklist.md  _(omitted if E2E Tests: no)_
 
 Next: work through the e2e checklist manually, then mark [x] Review in 1-feature.md.
 ```

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

@@ -77,10 +77,13 @@ Find which checkbox has `[?]` and act accordingly:
 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`:
+5. **E2E gate:** Before marking the brief complete, verify the "Does this feature need e2e test planning?" question in `2-brief.md` has an answer of `yes` or `no`.
+   - If unanswered: surface it as a blocking question, keep `[?] Brief`, and stop — do not proceed to step 6.
+   - If answered: extract the value (`yes` or `no`) and update `**E2E Tests:**` in `1-feature.md` to that value.
+6. If the brief is otherwise complete (no other 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.
+7. **State update:** Always update `1-feature.md` after taking action.
+8. 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`

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/package.json

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