clevotics-claude-bootstrap 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clevotics-claude-bootstrap",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Claude Code skill that splits one Project Plan.md into PRD, ARCHITECTURE, DESIGN, a phased PLAN and a CLAUDE.md",
   "bin": {
     "clevotics-claude-bootstrap": "bin/cli.js"

package/project-bootstrap/SKILL.md

@@ -21,10 +21,14 @@ CLAUDE.md                short router + hard rules (written LAST)
 docs/PRD.md              product only: what and for whom, no tech
 docs/ARCHITECTURE.md     tech only: stack, data model, modules, APIs
 docs/DESIGN.md           UI only: tokens, components, copy rules  (skip if no UI)
-docs/PLAN.md             phases, status, exit criteria, results
+docs/PLAN.md             phases, status, exit criteria (open phases only)
+docs/plan-archive.md     DONE phases moved here in full, with their Result paragraphs
+docs/testing/            one manual test plan per phase: docs/testing/<phase-id>.md
 docs/<source file>       moved here unchanged as the original record
 ```
 
+Create `docs/plan-archive.md` (header only) and `docs/testing/` (with a `.gitkeep`) at bootstrap time, so they exist before the first phase finishes
+
 Add an extra doc only when the source has a large self-contained topic (an external API integration, a deployment runbook). Name it by topic (`docs/whatsapp-api.md`, `docs/DEPLOY.md`), never `notes.md` or `misc.md`
 
 ## Process
@@ -32,7 +36,7 @@ Add an extra doc only when the source has a large self-contained topic (an exter
 1. **Read the whole source plan.** Sort every statement into one bucket: product (PRD), technical (ARCHITECTURE), UI (DESIGN), sequencing / tasks (PLAN), or rule (CLAUDE.md). Nothing gets dropped; nothing appears in two docs - other docs link to the owner instead
 2. **Find the gaps.** List decisions the source leaves open that change the work materially (stack, auth method, hosting, multi-tenant or not). Ask them with the AskUserQuestion tool, max 4 per call, recommended option first. Do not ask about anything you can decide sensibly yourself - pick it and write it down as a decision
 3. **Write PRD.md, ARCHITECTURE.md, DESIGN.md** using the templates below
-4. **Write PLAN.md** - the most important file. Follow the phase rules strictly
+4. **Write PLAN.md** - the most important file. Follow the phase rules strictly. Also create `docs/plan-archive.md` and `docs/testing/`
 5. **Write CLAUDE.md last**, once the other docs exist, because it routes to them
 6. **Move the source plan** into `docs/` unchanged (`git mv` if tracked)
 7. Report: files created, phase count, decisions you made on the user's behalf, open questions left
@@ -46,7 +50,7 @@ Use this mode instead of steps 1 to 6 when the repo already has a `CLAUDE.md`, a
 3. **Back up before rewriting.** Copy the current `CLAUDE.md` to `docs/CLAUDE.md.bak` (and any doc you will restructure, same pattern). The user deletes the backups once happy
 4. **Keep every rule.** Each rule, command and convention in the old `CLAUDE.md` either stays in the new `CLAUDE.md` or moves to the doc that owns it with a link back. Product and architecture explanations move out; hard rules, commands and routing stay
 5. **Keep existing docs that already fit.** If a doc already covers one bucket (e.g. an `API.md` that is the architecture), keep its name and route to it from `CLAUDE.md` instead of creating a duplicate
-6. **Plan from where the code is, not from zero.** Work already in the code and git history becomes DONE phases at the top of `PLAN.md`, each with a short Result line ("existing before bootstrap"). Remaining work from the plan or the old docs becomes TODO phases following the phase rules below
+6. **Plan from where the code is, not from zero.** Work already in the code and git history becomes DONE phases at the top of `PLAN.md`, each with a short Result line ("existing before bootstrap"). Remaining work from the plan or the old docs becomes TODO phases following the phase rules below. Existing DONE phases go straight into `docs/plan-archive.md`, leaving only their Overview row in `PLAN.md`. Create `docs/testing/` if missing, and add the Phase Completion Protocol to the new `CLAUDE.md` even if the old one had none
 7. **Verify nothing was dropped.** Before reporting, list each heading of the old `CLAUDE.md` and where its content now lives. Any heading without a home is a bug - fix it before reporting
 
 ## Phase rules (PLAN.md)
@@ -59,7 +63,9 @@ A phase is the unit Claude finishes in one sitting, end to end
 - **Each phase has:** Goal (one line), Tasks (checklist), Exit criteria (observable, testable - "GET /bookings returns 50 rows under 300 ms", never "bookings work"), Depends on
 - **Status keys:** `TODO` `IN PROGRESS` `PARKED` `DONE`. One phase IN PROGRESS at a time
 - **Production hardening** (security audit, load test, backups, monitoring) is its own final phase, PARKED until all features are DONE
-- When a phase finishes, append a `Result (date)` paragraph: what was built, test results, deferred items with the reason
+- When a phase finishes, append a `Result (date)` paragraph: what was built, test results, review outcome, link to its test plan, deferred items with the reason
+- **Archive on DONE:** once the Result paragraph is written, move the whole phase section (Goal, Tasks, Exit criteria, Result) to the end of `docs/plan-archive.md`. In `PLAN.md` keep only its Overview row, set to DONE and linking to the archive entry. `PLAN.md` then holds only TODO, IN PROGRESS and PARKED phases
+- **Test plan on DONE:** every finished phase gets `docs/testing/<phase-id>.md` (for example `docs/testing/B1.md`). It has setup once at the top (how to start, URL, login), then a numbered table of steps with do this / expect that, covering only what the phase changed and using real seed data. Mark the two or three steps where a bug would most likely hide
 
 ## Templates
 
@@ -121,7 +127,9 @@ One phase at a time. A phase starts only when the previous one meets its exit cr
 | ... | ... | ... |
 | B99 | Production hardening (last, before go-live) | PARKED |
 
-**Every phase exit also requires:** tests green, docs updated in the same change, <project-wide checks>
+DONE phases keep their row here and link to [plan-archive.md](plan-archive.md); their full sections live there
+
+**Every phase exit also requires:** tests green, docs updated in the same change, the Phase Completion Protocol in CLAUDE.md, <project-wide checks>
 
 ---
 
@@ -136,7 +144,73 @@ One phase at a time. A phase starts only when the previous one meets its exit cr
 **Exit criteria**
 - <observable, testable>
 
-**Result:** (filled in when DONE)
+**Result:** (filled in when DONE, then the section moves to plan-archive.md)
+Code review: <outcome>
+Security review: <outcome>
+```
+
+## Review gate hook
+
+Instructions alone can be skipped in a long session, so every bootstrap (new or existing project) also installs a hook that refuses to archive a phase whose Result does not record both reviews
+
+1. Write `.claude/hooks/check-phase-reviews.js` with exactly this content:
+
+```js
+#!/usr/bin/env node
+// Refuses to archive a phase whose Result does not record both reviews
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  const input = JSON.parse(Buffer.concat(chunks).toString()).tool_input;
+  if (!input.file_path.replace(/\\/g, "/").endsWith("docs/plan-archive.md")) return;
+  const text = input.content ?? input.new_string ?? (input.edits ?? []).map((edit) => edit.new_string).join("\n");
+  if (!text.includes("**Result")) return;
+  const missing = ["Code review:", "Security review:"].filter((label) => !text.includes(label));
+  if (missing.length === 0) return;
+  process.stderr.write(`Blocked: the phase Result is missing ${missing.join(" and ")}. Run /code-review and /security-review, record each outcome in the Result, then archive the phase\n`);
+  process.exit(2);
+});
+```
+
+2. Add this to `.claude/settings.json`, merging into any existing `hooks.PreToolUse` list instead of replacing it:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-phase-reviews.js\"" }]
+      }
+    ]
+  }
+}
+```
+
+3. Mention in the report that both files should be committed so the gate applies to everyone on the repo
+
+### docs/plan-archive.md
+
+```markdown
+# <Project> - Plan Archive
+
+DONE phases, moved here from [PLAN.md](PLAN.md) in full, oldest first. Never edit an archived phase; new work goes in a new phase
+
+---
+```
+
+### docs/testing/<phase-id>.md
+
+```markdown
+# <Phase id> - <Phase name>: Manual Test Plan
+
+**Setup:** <how to start, URL, login, seed data>
+
+| # | Do this | Expect |
+|---|---|---|
+| 1 | ... | ... |
+
+**Sharp steps:** <step numbers and why a bug would hide there>
 ```
 
 ### CLAUDE.md (keep under ~120 lines)
@@ -154,6 +228,8 @@ One phase at a time. A phase starts only when the previous one meets its exit cr
 | Data model, modules, APIs | `docs/ARCHITECTURE.md` |
 | UI tokens, components, copy | `docs/DESIGN.md` |
 | Current phase, exit criteria | `docs/PLAN.md` |
+| Finished phases and their results | `docs/plan-archive.md` |
+| Manual test plan for a phase | `docs/testing/<phase-id>.md` |
 
 Update the relevant doc in the same change when a decision changes
 
@@ -166,7 +242,20 @@ Update the relevant doc in the same change when a decision changes
 Status lives only in `docs/PLAN.md` (never log phases here)
 
 - Follow `docs/PLAN.md` strictly: one phase at a time, meet exit criteria before the next
-- When a phase passes its exit criteria: review the changes, then mark it DONE in PLAN.md with its Result paragraph before reporting
+- When a phase passes its exit criteria, run the Phase Completion Protocol below before reporting
+
+## Phase Completion Protocol (automatic, every phase)
+
+When a phase's exit criteria pass, before reporting it done, run in order without being asked:
+
+1. `code-review` skill on all changes of the phase
+2. `security-review` skill on the same changes
+3. Fix the findings, or record each accepted one with its reason. A phase is not DONE while a critical or high finding is open
+4. Write the manual test plan to `docs/testing/<phase-id>.md`
+5. Mark the phase DONE in `docs/PLAN.md` with its **Result (date)** paragraph: what was built, tests, test plan link, deferred items, plus one `Code review: <outcome>` line and one `Security review: <outcome>` line
+6. Move the full phase section to `docs/plan-archive.md`, leaving only its DONE row in the PLAN.md Overview. A hook blocks this move if either review line is missing
+
+Then report: exit criteria pass / fail, findings from each review ranked by severity, and the test plan steps
 
 ## Hard Rules
 <architecture / security / performance rules pulled from the source plan - each one checkable in a diff>