clevotics-claude-bootstrap 0.0.0-stage → 1.0.0

package/bin/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Installs the project-bootstrap skill for Claude Code on macOS, Linux and Windows
+//   npx clevotics-claude-bootstrap            -> global, all projects (~/.claude/skills)
+//   npx clevotics-claude-bootstrap project    -> this repo only (./.claude/skills), commit it to share
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const scope = process.argv[2] || "global";
+if (scope !== "global" && scope !== "project") {
+  console.error(`Unknown option "${scope}". Use "global" (default) or "project"`);
+  process.exit(1);
+}
+
+const base = scope === "project" ? process.cwd() : os.homedir();
+const dest = path.join(base, ".claude", "skills", "project-bootstrap");
+const src = path.join(__dirname, "..", "project-bootstrap", "SKILL.md");
+
+fs.mkdirSync(dest, { recursive: true });
+fs.copyFileSync(src, path.join(dest, "SKILL.md"));
+
+console.log(`Installed project-bootstrap to ${dest}`);
+console.log("Restart Claude Code, then run /project-bootstrap in a folder that has your Project Plan.md");

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "clevotics-claude-bootstrap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.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"
+  },
+  "files": [
+    "bin",
+    "project-bootstrap"
+  ],
+  "keywords": ["claude", "claude-code", "skill", "project-plan"],
+  "author": "Clevotics",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/project-bootstrap/SKILL.md

@@ -0,0 +1,171 @@
+---
+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".
+---
+
+# Project Bootstrap
+
+Expand one plan file into a doc set Claude can work from phase by phase, then write `CLAUDE.md` last
+
+The structure exists for one reason: Claude loads only the doc a task needs, and `PLAN.md` hands it one small, verifiable phase at a time
+
+## Inputs
+
+- The source plan: look for `Project Plan.md`, `PLAN.md`, `plan.md` or any single `.md` at repo root or `docs/`. If several exist, ask which one is the source
+- Anything else in the repo (package files, existing code) - read it so the docs describe what is real, not assumed
+
+## Output layout
+
+```
+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/<source file>       moved here unchanged as the original record
+```
+
+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
+
+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
+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
+
+## Phase rules (PLAN.md)
+
+A phase is the unit Claude finishes in one sitting, end to end
+
+- **Small:** one module or one screen group per phase. A phase that touches backend + web + mobile is three phases. Aim for something finishable and reviewable in one session
+- **Numbered with a prefix per track:** `B1, B2` backend, `F1, F2` frontend, `M1` mobile, or `F3.1, F3.2` for sub phases of one feature. Numbers never get reused or renumbered
+- **Ordered by dependency:** schema and API before the screens that use them. Foundation (repo, CI, auth) is phase 1
+- **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
+
+## Templates
+
+### docs/PRD.md
+
+```markdown
+# <Project> - Product Requirements
+
+Product only. No technology decisions here (see [ARCHITECTURE.md](ARCHITECTURE.md))
+
+## 1. What It Is
+## 2. Who It Is For        (table: user | who | main need)
+## 3. Features             (numbered subsections, each with must / should / later)
+## 4. Out of Scope         (explicit list, with decision dates)
+## 5. Terminology          (domain terms the UI must use)
+```
+
+### docs/ARCHITECTURE.md
+
+```markdown
+# <Project> - Architecture
+
+## 1. Stack               (table: layer | choice | why)
+## 2. Repo Layout
+## 3. Data Model           (tables / entities, key fields, relations)
+## 4. Modules              (one per domain, what it owns, who may call it)
+## 5. APIs                 (contract location, auth, error shape, pagination)
+## 6. Security             (authn, authz, secrets, input validation)
+## 7. Performance Budgets  (p95 latency, payload size, query rules)
+## 8. Decisions Log        (date | decision | reason)
+```
+
+### docs/DESIGN.md (only if the project has a UI)
+
+```markdown
+# <Project> - Design
+
+## 1. Tokens              (colors, spacing, radii, type scale)
+## 2. Components          (list, states: loading, empty, error)
+## 3. Layout and Navigation
+## 4. Copy Rules          (tone, terminology, error messages)
+## 5. Loading and Errors  (skeletons, per-section retry)
+```
+
+### docs/PLAN.md
+
+```markdown
+# <Project> - Development Plan
+
+One phase at a time. A phase starts only when the previous one meets its exit criteria
+
+**Status keys:** `TODO` · `IN PROGRESS` · `PARKED` · `DONE`
+
+## Overview
+
+| Phase | Name | Status |
+|---|---|---|
+| B1 | Foundation: repo, CI, database, auth | TODO |
+| ... | ... | ... |
+| B99 | Production hardening (last, before go-live) | PARKED |
+
+**Every phase exit also requires:** tests green, docs updated in the same change, <project-wide checks>
+
+---
+
+## B1 - Foundation
+
+**Goal:** <one line>
+**Depends on:** -
+
+**Tasks**
+- [ ] ...
+
+**Exit criteria**
+- <observable, testable>
+
+**Result:** (filled in when DONE)
+```
+
+### CLAUDE.md (keep under ~120 lines)
+
+```markdown
+# <Project>
+
+<two-line summary>
+
+## Read When Needed (do not load all by default)
+
+| Task | Read |
+|---|---|
+| Product scope, features | `docs/PRD.md` |
+| Data model, modules, APIs | `docs/ARCHITECTURE.md` |
+| UI tokens, components, copy | `docs/DESIGN.md` |
+| Current phase, exit criteria | `docs/PLAN.md` |
+
+Update the relevant doc in the same change when a decision changes
+
+## Stack
+## Layout
+## Commands          (only commands that exist; add as they are created)
+
+## Current Phase
+
+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
+
+## Hard Rules
+<architecture / security / performance rules pulled from the source plan - each one checkable in a diff>
+
+## Conventions
+```
+
+## Rules for the content
+
+- Each fact lives in exactly one doc. Others link to it
+- CLAUDE.md never holds phase status or long explanations - it routes and states hard rules
+- Write rules as checkable statements ("every query filters by tenant_id"), never vibes ("write clean code")
+- Keep the user's own words for product intent; tighten, do not reinterpret
+- Never invent requirements the source does not support. If something is needed but missing, list it under open questions in the report

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.