claude-sprint-gate 2.1.0 → 2.3.0

package/.claude/commands/sprint.md

@@ -5,48 +5,87 @@ allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
 
 # Sprint — Autonomous Product Development
 
-You are entering an autonomous sprint cycle.
+You are entering an autonomous sprint cycle. This cycle will iterate the product toward maturity until the mission is fulfilled.
+
+## What is maturity?
+
+If `mission.md` defines a north star, that is the target. If not, maturity means: **benchmark against the best product in this category and exceed expectations.** The product is mature when a customer would choose it over the incumbent — not because it's cheaper, but because it's better.
+
+Always develop from first principles. Do not copy competitors. Apply design thinking — understand the user's real problem, prototype the simplest solution, test it, iterate. The result should be the best there is, not the best you could manage.
 
 ## Step 1 — Load your context
 
 1. Read `mission.md` — this defines who you are, what you're building, and your constraints. Adopt the persona and objectives defined there. If no mission file exists, your objective is to complete the current sprint.
 2. Read `CLAUDE.md` if it exists — these are rules that carry forward to every sprint.
-3. Check `goals-open/` for the active goal file (most recent `goal-*.md`).
+3. Read `stop-condition.md` if it exists — these are the quality gates every sprint must pass.
+4. Check `goals-open/` for the active goal file (most recent `goal-*.md`).
+
+## Step 2 — Execute or Plan
+
+**If a goal file exists**: read it, execute every unchecked item, check them off (`- [x]`) as you complete and verify each one.
+
+**If no goal file exists**: you need to plan the next sprint. Follow this process:
+
+### Sprint Planning — The 7-Step Method
+
+Before writing a single checkbox, answer these questions in order:
+
+1. **What is the business value?** Not the feature — the outcome. Strip away technical jargon. What problem disappears for the customer?
+
+2. **Does this align with the mission?** Re-read `mission.md`. Does this sprint make the product's core thesis more true, more visible, more demonstrable? Four outcomes: reinforces mission (ship it), neutral but needed (table stakes), contradicts mission (drop or re-scope), already delivered architecturally (just prove it).
+
+3. **First principles implementation.** Don't copy competitors. Start from your architecture. What is the minimum mechanism that delivers the business value within your constraints?
 
-## Step 2 — Execute
+4. **Who benefits?** Every sprint should deliver value to at least 3 stakeholders — investors, customers, end users, operators, developers. If fewer than 3 benefit, the scope is wrong.
 
-- **If a goal file exists**: read it, execute every unchecked item, check them off (`- [x]`) as you complete and verify each one.
-- **If no goal file exists**: read `goals-completed/` to understand what has been delivered so far, then create the next sprint file based on your mission objectives. Define concrete, verifiable deliverables as checkboxes. Then execute it.
+5. **What is the Minimum Demonstrable Increment?** The smallest slice that (a) advances the mission, (b) is visible to an end user, and (c) has a screenshot a salesperson can show in a demo. If you can't describe the screenshot that proves it works, the scope is wrong.
+
+6. **Acceptance criteria with evidence.** Each deliverable gets checkbox criteria with verifiable evidence — build output, screenshots reviewed by you, API responses, end-to-end user journeys.
+
+7. **Four-Gate Filter** before committing to the sprint:
+   - **Thesis gate**: Does this make the product's core value proposition stronger?
+   - **Customer gate**: Would the first 10 customers refuse to buy without this?
+   - **Architecture gate**: Does this fit naturally, or does it bend the architecture?
+   - **Demo gate**: Can someone show this in a 5-minute demo and close a deal?
+
+   If a deliverable fails any gate, drop it or re-scope it.
+
+### Write the sprint file
+
+Create `goals-open/goal-{name}-v{N}.md` with:
+- Sprint title and context (what was delivered before, what this sprint advances)
+- Concrete, verifiable deliverables as checkboxes
+- Not "improve the UI" — instead "Add error states to all forms, loading indicators to async actions, test each page at mobile width"
+- Early sprints: foundation, architecture, core data model
+- Middle sprints: features customers interact with
+- Late sprints: polish, error handling, edge cases, documentation
+
+Then start executing immediately.
 
 ## Step 3 — The cycle
 
 When you try to stop, the stop hook will:
 - **Block** if unchecked items remain — re-prompting you with the full goal
-- **Generate a verification sprint** when all items are checked — you must prove everything works end-to-end
-- **Prompt the next sprint** after verification if a mission is active — you plan it based on your mission, then execute it
+- **Generate a verification sprint** when all items are checked — you must prove everything works end-to-end, with screenshots and evidence
+- **Prompt the next sprint** after verification if a mission is active — you plan it using the 7-step method above, then execute it
 - **Allow stop** only when the mission's sprint cap is reached or no mission is active
 
-This cycle repeats autonomously: build, verify, plan, build, verify, plan.
-
-## Sprint planning guidance
+This cycle repeats autonomously: plan, build, verify, plan, build, verify.
 
-When creating a new sprint, decide what the product needs most right now:
-- Early sprints: foundation, architecture, core data model
-- Middle sprints: features that users interact with
-- Late sprints: polish, error handling, edge cases, documentation
-- Every sprint should leave the product in a state you would demonstrate
-- Write concrete deliverables, not vague goals — "Add error states to all forms" not "improve UX"
+Each sprint must iterate the product closer to maturity. If the product isn't better after a sprint than it was before, the sprint was wrong.
 
 ## Rules
 
 - Execute continuously. Do not pause to ask for confirmation.
 - Do not skip items. Work through them in order.
 - Test each deliverable the way its end user would use it.
-- Constraints from `CLAUDE.md` and `mission.md` carry forward to every sprint.
+- Constraints from `CLAUDE.md`, `mission.md`, and `stop-condition.md` carry forward to every sprint.
 - Never trade correctness for speed.
 - No sprint should leave the product in a state you would not demonstrate.
 - If stuck on an item, try a different approach. Do not abandon it.
+- Every sprint must make the product's core thesis more true, more visible, and more demonstrable. If it doesn't, it's the wrong sprint.
+- First principles always. Design thinking always. The result must be the best there is.
 
 ## Begin
 
-Read `mission.md`, then `CLAUDE.md`, then the active goal file. Start executing. Go.
+Read `mission.md`, then `CLAUDE.md`, then `stop-condition.md`, then the active goal file. Start executing. Go.

package/.claude/hooks/ccsg.sh

@@ -276,6 +276,12 @@ while IFS= read -r item; do
 - [ ] VERIFY: ${item}"
 done <<< "$DELIVERED"
 
+# Check if project has a custom stop-condition.md with gates
+STOP_CONDITION_CONTENT=""
+if [ -f "$ROOT/stop-condition.md" ]; then
+  STOP_CONDITION_CONTENT=$(sed -n '/^## /,$p' "$ROOT/stop-condition.md")
+fi
+
 # Write the verification sprint
 cat > "$VERIFY_FILE" <<SPRINT
 # Verification — ${SPRINT_TITLE}
@@ -288,45 +294,50 @@ Your job now is to prove — through actual testing — that everything
 delivered in the previous sprint is real, working, and ready for a
 real user to depend on.
 
-## Work Ethic
+## What "tested" means
 
-Compilation is not verification. Test each thing the way its end user would use it:
+- **UI feature** — open it in a browser (Playwright with real clicks, not just \`page.goto\`). Click the button. Fill the form. Submit it. Verify the result on screen. Follow every path a user would take. If you can't show a screenshot of the feature working, it's not tested.
+- **API endpoint** — call it with real payloads the way its consumer would. Check the response body, status code, and side effects. Not just "returns 200."
+- **CLI tool** — run the commands with real arguments, read the real output.
+- **Pipeline/service** — connect with the actual client. Verify data flows end-to-end.
 
-- **A UI** — open it in a browser, click every button, fill every form, walk every path
-- **An API** — call every endpoint with real requests, check the actual responses
-- **A CLI** — run the commands with real arguments, read the real output
-- **A pipeline** — feed it real data, verify what comes out the other end
+## What "tested" does NOT mean
 
-Whatever it is, use it the way a customer would — not the way the developer who
-wrote it imagines it works. If you cannot show real output proving it works
-end-to-end, it is not done. Never trade correctness for speed. One properly
-verified feature is worth more than ten that "should work."
+- \`tsc --noEmit\` passes (that's compilation, not testing)
+- \`curl\` returns 200 (that's a health check, not a user journey)
+- "No errors in the log" (absence of failure is not presence of success)
+- Checking off items you haven't personally verified
 
-## Build Verification
+## Build Gate
 
 - [ ] Delete all cached/compiled artifacts and rebuild from a clean state
 - [ ] All dependencies resolve cleanly — no warnings, no version conflicts
 - [ ] Build completes without warnings that could indicate runtime issues
 
-## Full Test Suite
+## Test Suite Gate
 
 - [ ] Run the COMPLETE test suite — every test file, not just the new ones
 - [ ] Zero failures, zero skipped tests without documented justification
 - [ ] If there are integration tests, run those too — they catch what unit tests miss
 
-## End-to-End Feature Verification
+## Consumer Gate — End-to-End Feature Verification
 
 Walk through every feature delivered in the sprint as a real user would.
 Do not just call functions — use the actual UI/CLI/API entry points.
 ${VERIFY_ITEMS}
 
-## Regression Testing
+## Regression Gate
 
 - [ ] Features from prior sprints still work — spot check at least 3
 - [ ] No existing functionality broken by the new changes
 - [ ] Trigger error cases intentionally and verify they are handled gracefully
 - [ ] Check edge cases: empty inputs, missing data, concurrent access, large payloads
 
+## Evidence Gate
+
+- [ ] Each checked item above has real output proving it works — command output, screenshot path, API response, or browser verification
+- [ ] No item was checked without personally verifying the evidence
+
 ## Deployment Readiness
 
 - [ ] No hardcoded development/debug values in production code
@@ -336,6 +347,19 @@ ${VERIFY_ITEMS}
 - [ ] Dependencies are locked — no floating versions that could break tomorrow
 - [ ] No new security vulnerabilities introduced (review dependency changes)
 
+## Visual Verification Gate
+
+If this sprint changed anything a user or system interacts with:
+
+- [ ] Screenshots captured for every feature changed (in demo-screenshots/ or pasted below)
+- [ ] Each screenshot reviewed — correct data, no errors, layout not broken
+- [ ] Findings listed: "Screenshot XX: [description]. PASS/FAIL"
+- [ ] Any FAIL items fixed, re-screenshotted, and re-verified
+
+**If you cannot show a screenshot of it working, it is not done.
+If you showed a screenshot but didn't read it yourself, it is not verified.
+If you read it and saw a problem but didn't fix it, it is not shipped.**
+
 ## Final Verdict
 
 - [ ] The product works. Not "should work." Works. You tested it yourself and saw it work.

package/bin/ccsg.js

@@ -176,14 +176,25 @@ First sprint. Define what needs to be built and verify it works.
       info("Created starter goal: goals-open/goal-sprint-v1.md");
     }
 
+    // Mission
     const missionDest = path.join(root, "mission.md");
     if (!fs.existsSync(missionDest)) {
       const missionContent = await download("mission-template.md");
       fs.writeFileSync(missionDest, missionContent);
-      info("Created mission.md — edit to set your product vision");
+      info("Created mission.md");
     } else {
       warn("mission.md already exists, skipping");
     }
+
+    // Stop condition (quality gates)
+    const stopDest = path.join(root, "stop-condition.md");
+    if (!fs.existsSync(stopDest)) {
+      const stopContent = await download("stop-condition-template.md");
+      fs.writeFileSync(stopDest, stopContent);
+      info("Created stop-condition.md");
+    } else {
+      warn("stop-condition.md already exists, skipping");
+    }
   }
 
   // 5. Summary
@@ -197,12 +208,26 @@ First sprint. Define what needs to be built and verify it works.
     console.log("  Commands: .claude/commands/");
     console.log("  Settings: .claude/settings.json");
     console.log("  Goals:    goals-open/ \u2192 goals-completed/");
-    console.log("  Mission:  mission.md (edit to set your product vision)");
+    console.log("  Mission:  mission.md");
+    console.log("  Gates:    stop-condition.md");
   }
   console.log("\n  Commands: /sprint, /sprint-status, /sprint-cancel");
-  console.log(
-    "\n  Edit goals-open/goal-sprint-v1.md, then: claude\n  Type /sprint to begin.\n"
-  );
+  console.log(`
+  \x1b[1mBefore you start, review and customize:\x1b[0m
+
+    mission.md          \x1b[2mYour product vision, persona, and constraints\x1b[0m
+    stop-condition.md   \x1b[2mQuality gates — what "tested" means for your project\x1b[0m
+    goals-open/*.md     \x1b[2mYour first sprint deliverables\x1b[0m
+
+  These files work out of the box but are most powerful when
+  tailored to your product. Then start Claude Code and run:
+
+    /loop 15m /sprint
+
+  This starts a 15-minute heartbeat that keeps the agent working
+  through sprints until the product is mature. The stop hook
+  prevents escape, the loop prevents silence.
+`);
 }
 
 install().catch((err) => {

package/deploy.sh

@@ -163,7 +163,7 @@ STARTER
     info "Created starter goal: goals-open/goal-sprint-v1.md"
   fi
 
-  # Mission template (always included)
+  # Mission
   MISSION_DEST="$PROJECT_ROOT/mission.md"
   if [ ! -f "$MISSION_DEST" ]; then
     if command -v curl &>/dev/null; then
@@ -171,10 +171,23 @@ STARTER
     else
       wget -qO "$MISSION_DEST" "$REPO_RAW/mission-template.md"
     fi
-    info "Created mission.md — edit to set your product vision"
+    info "Created mission.md"
   else
     warn "mission.md already exists, skipping"
   fi
+
+  # Stop condition (quality gates)
+  STOP_DEST="$PROJECT_ROOT/stop-condition.md"
+  if [ ! -f "$STOP_DEST" ]; then
+    if command -v curl &>/dev/null; then
+      curl -fsSL "$REPO_RAW/stop-condition-template.md" -o "$STOP_DEST"
+    else
+      wget -qO "$STOP_DEST" "$REPO_RAW/stop-condition-template.md"
+    fi
+    info "Created stop-condition.md"
+  else
+    warn "stop-condition.md already exists, skipping"
+  fi
 fi
 
 # Step 5: Summary
@@ -192,16 +205,26 @@ else
   echo -e "  ${DIM}Commands:${RESET} .claude/commands/"
   echo -e "  ${DIM}Settings:${RESET} .claude/settings.json"
   echo -e "  ${DIM}Goals:${RESET}    goals-open/ → goals-completed/"
-  echo -e "  ${DIM}Mission:${RESET}  mission.md (edit to set your product vision)"
+  echo -e "  ${DIM}Mission:${RESET}  mission.md"
+  echo -e "  ${DIM}Gates:${RESET}    stop-condition.md"
 fi
 
 echo ""
 echo -e "  ${DIM}Commands:${RESET} /sprint, /sprint-status, /sprint-cancel"
 echo ""
-echo -e "  ${DIM}Next:${RESET}"
-echo "    1. Edit mission.md with your product vision"
-echo "    2. Edit goals-open/goal-sprint-v1.md with your sprint items"
-echo "    3. Start Claude Code, type /sprint to begin"
+echo -e "  ${BOLD}Before you start, review and customize:${RESET}"
+echo ""
+echo -e "    mission.md          ${DIM}Your product vision, persona, and constraints${RESET}"
+echo -e "    stop-condition.md   ${DIM}Quality gates — what 'tested' means for your project${RESET}"
+echo -e "    goals-open/*.md     ${DIM}Your first sprint deliverables${RESET}"
+echo ""
+echo "  These files work out of the box but are most powerful when"
+echo "  tailored to your product. Then start Claude Code and run:"
+echo ""
+echo "    /loop 15m /sprint"
+echo ""
+echo "  This starts a 15-minute heartbeat that keeps the agent working"
+echo "  through sprints until the product is mature."
 echo ""
 echo -e "  ${DIM}Repo:${RESET} https://github.com/panbergco/claude-code-sprint-gate"
 echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-sprint-gate",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Claude Code Sprint Gate — sprint lifecycle manager with verification gates",
   "bin": {
     "ccsg": "bin/ccsg.js"

package/plugin/commands/sprint.md

@@ -5,48 +5,87 @@ allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
 
 # Sprint — Autonomous Product Development
 
-You are entering an autonomous sprint cycle.
+You are entering an autonomous sprint cycle. This cycle will iterate the product toward maturity until the mission is fulfilled.
+
+## What is maturity?
+
+If `mission.md` defines a north star, that is the target. If not, maturity means: **benchmark against the best product in this category and exceed expectations.** The product is mature when a customer would choose it over the incumbent — not because it's cheaper, but because it's better.
+
+Always develop from first principles. Do not copy competitors. Apply design thinking — understand the user's real problem, prototype the simplest solution, test it, iterate. The result should be the best there is, not the best you could manage.
 
 ## Step 1 — Load your context
 
 1. Read `mission.md` — this defines who you are, what you're building, and your constraints. Adopt the persona and objectives defined there. If no mission file exists, your objective is to complete the current sprint.
 2. Read `CLAUDE.md` if it exists — these are rules that carry forward to every sprint.
-3. Check `goals-open/` for the active goal file (most recent `goal-*.md`).
+3. Read `stop-condition.md` if it exists — these are the quality gates every sprint must pass.
+4. Check `goals-open/` for the active goal file (most recent `goal-*.md`).
+
+## Step 2 — Execute or Plan
+
+**If a goal file exists**: read it, execute every unchecked item, check them off (`- [x]`) as you complete and verify each one.
+
+**If no goal file exists**: you need to plan the next sprint. Follow this process:
+
+### Sprint Planning — The 7-Step Method
+
+Before writing a single checkbox, answer these questions in order:
+
+1. **What is the business value?** Not the feature — the outcome. Strip away technical jargon. What problem disappears for the customer?
+
+2. **Does this align with the mission?** Re-read `mission.md`. Does this sprint make the product's core thesis more true, more visible, more demonstrable? Four outcomes: reinforces mission (ship it), neutral but needed (table stakes), contradicts mission (drop or re-scope), already delivered architecturally (just prove it).
+
+3. **First principles implementation.** Don't copy competitors. Start from your architecture. What is the minimum mechanism that delivers the business value within your constraints?
 
-## Step 2 — Execute
+4. **Who benefits?** Every sprint should deliver value to at least 3 stakeholders — investors, customers, end users, operators, developers. If fewer than 3 benefit, the scope is wrong.
 
-- **If a goal file exists**: read it, execute every unchecked item, check them off (`- [x]`) as you complete and verify each one.
-- **If no goal file exists**: read `goals-completed/` to understand what has been delivered so far, then create the next sprint file based on your mission objectives. Define concrete, verifiable deliverables as checkboxes. Then execute it.
+5. **What is the Minimum Demonstrable Increment?** The smallest slice that (a) advances the mission, (b) is visible to an end user, and (c) has a screenshot a salesperson can show in a demo. If you can't describe the screenshot that proves it works, the scope is wrong.
+
+6. **Acceptance criteria with evidence.** Each deliverable gets checkbox criteria with verifiable evidence — build output, screenshots reviewed by you, API responses, end-to-end user journeys.
+
+7. **Four-Gate Filter** before committing to the sprint:
+   - **Thesis gate**: Does this make the product's core value proposition stronger?
+   - **Customer gate**: Would the first 10 customers refuse to buy without this?
+   - **Architecture gate**: Does this fit naturally, or does it bend the architecture?
+   - **Demo gate**: Can someone show this in a 5-minute demo and close a deal?
+
+   If a deliverable fails any gate, drop it or re-scope it.
+
+### Write the sprint file
+
+Create `goals-open/goal-{name}-v{N}.md` with:
+- Sprint title and context (what was delivered before, what this sprint advances)
+- Concrete, verifiable deliverables as checkboxes
+- Not "improve the UI" — instead "Add error states to all forms, loading indicators to async actions, test each page at mobile width"
+- Early sprints: foundation, architecture, core data model
+- Middle sprints: features customers interact with
+- Late sprints: polish, error handling, edge cases, documentation
+
+Then start executing immediately.
 
 ## Step 3 — The cycle
 
 When you try to stop, the stop hook will:
 - **Block** if unchecked items remain — re-prompting you with the full goal
-- **Generate a verification sprint** when all items are checked — you must prove everything works end-to-end
-- **Prompt the next sprint** after verification if a mission is active — you plan it based on your mission, then execute it
+- **Generate a verification sprint** when all items are checked — you must prove everything works end-to-end, with screenshots and evidence
+- **Prompt the next sprint** after verification if a mission is active — you plan it using the 7-step method above, then execute it
 - **Allow stop** only when the mission's sprint cap is reached or no mission is active
 
-This cycle repeats autonomously: build, verify, plan, build, verify, plan.
-
-## Sprint planning guidance
+This cycle repeats autonomously: plan, build, verify, plan, build, verify.
 
-When creating a new sprint, decide what the product needs most right now:
-- Early sprints: foundation, architecture, core data model
-- Middle sprints: features that users interact with
-- Late sprints: polish, error handling, edge cases, documentation
-- Every sprint should leave the product in a state you would demonstrate
-- Write concrete deliverables, not vague goals — "Add error states to all forms" not "improve UX"
+Each sprint must iterate the product closer to maturity. If the product isn't better after a sprint than it was before, the sprint was wrong.
 
 ## Rules
 
 - Execute continuously. Do not pause to ask for confirmation.
 - Do not skip items. Work through them in order.
 - Test each deliverable the way its end user would use it.
-- Constraints from `CLAUDE.md` and `mission.md` carry forward to every sprint.
+- Constraints from `CLAUDE.md`, `mission.md`, and `stop-condition.md` carry forward to every sprint.
 - Never trade correctness for speed.
 - No sprint should leave the product in a state you would not demonstrate.
 - If stuck on an item, try a different approach. Do not abandon it.
+- Every sprint must make the product's core thesis more true, more visible, and more demonstrable. If it doesn't, it's the wrong sprint.
+- First principles always. Design thinking always. The result must be the best there is.
 
 ## Begin
 
-Read `mission.md`, then `CLAUDE.md`, then the active goal file. Start executing. Go.
+Read `mission.md`, then `CLAUDE.md`, then `stop-condition.md`, then the active goal file. Start executing. Go.