clevotics-claude-bootstrap 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clevotics-claude-bootstrap",
-  "version": "1.0.1",
+  "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

@@ -1,6 +1,6 @@
 ---
 name: project-bootstrap
-description: Turn a single project plan markdown file (e.g. "Project Plan.md") into a structured doc set - PRD.md, ARCHITECTURE.md, DESIGN.md, PLAN.md split into small numbered phases with exit criteria - and finish by writing a short CLAUDE.md that routes to them. Use when a repo has only a plan file and the user asks to bootstrap, split, structure or set up the project docs, or says "start this project from the plan".
+description: Turn a single project plan markdown file (e.g. "Project Plan.md") into a structured doc set - PRD.md, ARCHITECTURE.md, DESIGN.md, PLAN.md split into small numbered phases with exit criteria - and finish by writing a short CLAUDE.md that routes to them. Also restructures an existing project that already has a CLAUDE.md, code or docs, without losing any of it. Use when the user asks to bootstrap, split, structure, restructure or set up the project docs, or says "start this project from the plan".
 ---
 
 # Project Bootstrap
@@ -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,11 +36,23 @@ 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
 
+## Existing project mode
+
+Use this mode instead of steps 1 to 6 when the repo already has a `CLAUDE.md`, any of the target docs, or real code. The rule: restructure, never lose anything
+
+1. **Inventory first.** Read the existing `CLAUDE.md`, every `.md` under the root and `docs/`, the package / build files, and `git log --oneline -30`. Note what is already built
+2. **Show the mapping before writing.** Tell the user which existing section goes to which new doc, which files get created, and which get rewritten. Wait for a go-ahead, since this rewrites their instructions
+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. 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)
 
 A phase is the unit Claude finishes in one sitting, end to end
@@ -47,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
 
@@ -109,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>
 
 ---
 
@@ -124,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)
@@ -142,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
 
@@ -154,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>