@dzhechkov/p-replicator 1.5.6 → 1.5.7

package/README/eng/03_admin_guide.md

@@ -0,0 +1,333 @@
+# 03. Admin Guide
+
+For users who want to understand and customize the `p-replicator`
+infrastructure: hooks, statusline, settings.json, insights, roadmap.
+
+## settings.json — main configuration
+
+**Location:** `.claude/settings.json` in the project root.
+
+**Default structure (after init):**
+
+```json
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_comment": "Default hooks + statusline shipped by @dzhechkov/p-replicator init.",
+  "statusLine": {
+    "type": "command",
+    "command": "node .claude/hooks/statusline.cjs"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/session-insights.cjs", "timeout": 5 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/autocommit-roadmap.cjs", "timeout": 10 },
+          { "type": "command", "command": "node .claude/hooks/autocommit-insights.cjs", "timeout": 10 },
+          { "type": "command", "command": "node .claude/hooks/autocommit-plans.cjs", "timeout": 10 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Customization:** add new hooks or event types — they will be **preserved**
+on `init --force` or `update` thanks to merge logic (`mergeSettingsJson` +
+`removeOrphanHooks`).
+
+**Full reset to defaults:**
+
+```bash
+npx @dzhechkov/p-replicator init --force --reset-settings
+```
+
+---
+
+## Hooks — lifecycle
+
+`p-replicator` ships **6 cross-platform Node scripts** in `.claude/hooks/`:
+
+| Hook | Event | Purpose |
+|---|---|---|
+| `session-insights.cjs` | SessionStart | Inject 3 recent insights from `.claude/insights/index.md` to stdout (Claude Code captures) |
+| `autocommit-roadmap.cjs` | Stop | Auto-commit `.claude/feature-roadmap.json` if changed |
+| `autocommit-insights.cjs` | Stop | Auto-commit `.claude/insights/` if changed |
+| `autocommit-plans.cjs` | Stop | Auto-commit `docs/plans/` if changed |
+| `statusline.cjs` | (statusLine) | Multi-line dashboard above the prompt |
+| `state-update.cjs` | (utility) | Argv-driven helper for writing `.claude/.p-replicator-state.json` |
+
+**Cross-platform discipline:** all 4 autocommit scripts use
+`execFileSync('git', [...])` (no shell pipes, no `2>/dev/null`/`|| true`).
+Works identically on Windows-cmd, bash, PowerShell.
+
+**Each script is defensive:** wrapped in try/catch, always exits 0
+(best-effort, never blocks the session).
+
+---
+
+## Statusline — dashboard
+
+**What it shows (6 lines):**
+
+```
+P-Replicator V1.5.0 ● user │ Sonnet 4.7
+🚀 Pipeline   /<cmd> ▓▓▓░░░░ 50%  │ Phase: VALIDATE (2/4)  │ Last: /replicate
+🎯 Roadmap    [●●●○○○○○] mvp 3/8   │ Done 5/12  │ ▶ auth-jwt  │ Domain: banking
+📊 SPARC      ●11/11  │ 🟢 78/100  │ Plans ●3  │ ADRs ●2  │ Harvest 2026-05-05
+🛠️ Toolkit   Skills ●10/10 │ Cmds ●11/11 │ Agents ●4+3 │ Rules ●5+2 │ Hooks ●6/6
+💡 Insights   ●12 (2026-05-06) │ Tests 85/85 ✓ │ MCP ●1/1 │ Settings ✓ │ 🧬 Keysarium ✓
+```
+
+**Sources (heuristic + state-file):**
+
+| Metric | Source |
+|---|---|
+| Pipeline command + phase + progress | `.claude/.p-replicator-state.json` |
+| Roadmap progress | `.claude/feature-roadmap.json` |
+| SPARC count | `docs/{PRD,Architecture,...}.md` |
+| Validation score | regex extract from `docs/validation-report.md` |
+| Plans count | `docs/plans/*.md` |
+| ADRs count | `docs/ADR.md` H2/H3 headings, or `docs/adr/*.md`, or `docs/ddd/adr/*.md` |
+| Insights count + last date | `## YYYY-MM-DD` in `.claude/insights/index.md` |
+| Toolkit counts | filesystem walks of `.claude/{skills,commands,agents,rules,hooks}/` |
+| Settings status | deep-equals current vs `manifest.shippedDefaults` |
+| MCP servers | `.mcp.json` |
+| Domain | keyword grep in `CLAUDE.md` |
+| Last harvest | `TOOLKIT_HARVEST.md` mtime |
+| Last test | optional `.claude/.last-test.json` cache |
+
+**Stale state:** state file older than 30 minutes is ignored (Pipeline
+section shows `idle`).
+
+**Defensive design:** every section wrapped in `safeRun()` with fallback —
+one parse error doesn't break the whole status bar.
+
+**Disable statusline:**
+
+Remove the `statusLine` field from `.claude/settings.json`. On next
+`update` with merge logic, the deletion is preserved.
+
+---
+
+## State file for live progress
+
+`.claude/.p-replicator-state.json` — ephemeral state, updated by commands
+during pipeline execution:
+
+```json
+{
+  "currentCommand": "/feature",
+  "currentPhase": {
+    "name": "VALIDATE",
+    "index": 2,
+    "total": 4,
+    "progress": 0.5
+  },
+  "lastCommand": "/replicate",
+  "lastFeature": "auth-jwt",
+  "updatedAt": "2026-05-07T..."
+}
+```
+
+**Updated via `state-update.cjs`:**
+
+```bash
+node .claude/hooks/state-update.cjs \
+  --command /feature \
+  --phase VALIDATE \
+  --index 2 \
+  --total 4 \
+  --progress 0.5
+```
+
+Pipeline commands optionally call this script (via Bash tool) so statusline
+shows real progress.
+
+**⚠️ Known limitation:** this file is not auto-gitignored. Recommended:
+
+```
+echo ".claude/.p-replicator-state.json" >> .gitignore
+echo ".claude/.last-test.json" >> .gitignore
+```
+
+See `KNOWN_LIMITATIONS.md` item L5.
+
+---
+
+## Insights system
+
+**Storage:** `.claude/insights/index.md` (markdown log).
+
+**Entry format:**
+
+```markdown
+## YYYY-MM-DD — short title
+
+**Tags:** tag1, tag2, tag3
+
+**Problem:**
+What happened (1-3 sentences).
+
+**Solution:**
+What fixed it (1-5 sentences with code if relevant).
+
+**References:** file:line or commit hash or external link
+
+---
+```
+
+**Lifecycle:**
+
+- ≤ 50 entries → single `index.md`
+- > 50 → split into archive `<YYYY-MM>.md` with `index.md` as TOC
+- Never delete — only supersede via `**Status:** superseded by <link>`
+
+**Tag conventions:**
+- ✅ `prisma-migration`, `postgres-timezone`, `docker-compose-network`
+- ❌ `bug`, `fix`, `important` (too generic — recall fails)
+
+**Auto-injection via SessionStart hook** — described above.
+
+---
+
+## Roadmap management
+
+**File:** `.claude/feature-roadmap.json` (generated in `/replicate` Phase 3
+from PRD MVP scope, or by hand).
+
+**Schema (post v1.5.0):**
+
+```json
+{
+  "version": "1.0",
+  "features": [
+    {
+      "id": "auth-jwt",
+      "number": 1,
+      "branch": "feature/001-auth-jwt",
+      "name": "JWT-based authentication",
+      "priority": "mvp",
+      "status": "next",
+      "complexity": "medium",
+      "estimated_hours": "2-4",
+      "blockers": [],
+      "expected_files": ["packages/backend/src/auth/jwt.ts"],
+      "depends_on": []
+    }
+  ]
+}
+```
+
+**Lifecycle states:**
+- `planned` → not yet prioritized
+- `next` → next in queue (picked by `/next`)
+- `in_progress` → actively being worked
+- `done` → implemented
+- `blocked` → waiting on `depends_on` or manual fix
+
+**`number` and `branch`** are populated by `--feature-branches` flag in
+`/run` or `/go`.
+
+**Auto-commit** via `autocommit-roadmap.cjs` (Stop hook) on changes.
+
+---
+
+## Doctor + Verify — two distinct tools
+
+| Tool | Checks | When |
+|---|---|---|
+| `npx @dzhechkov/p-replicator doctor` | Pre-shipped contract: 10 skills + 11 commands + 4 agents + 5 rules + settings.json + 6 hooks + git on PATH | After init / when something seems broken |
+| `npx @dzhechkov/p-replicator verify` | Pre-shipped + post-/replicate hints (CLAUDE.md, planner.md, security.md, feature-roadmap.json, etc.) | After every `/replicate` to confirm |
+
+**`doctor` exit codes:**
+- `0` — all good
+- `1` — something must-have is missing (run `init --force` to repair)
+
+**`verify` exit codes:**
+- `0` — pre-shipped contract OK (may have warnings about project-specific)
+- `1` — pre-shipped contract violated
+
+---
+
+## Update workflow
+
+```bash
+# Safe upgrade with preserved customizations:
+npx @dzhechkov/p-replicator@latest update
+
+# Or via init --force (also preserves customizations):
+npx @dzhechkov/p-replicator@latest init --force
+
+# Full reset of settings.json to defaults:
+npx @dzhechkov/p-replicator@latest init --force --reset-settings
+```
+
+**What the merge logic does:**
+1. Reads `manifest.shippedDefaults['settings.json']` (what we shipped previously)
+2. Reads current `templates/.claude/settings.json` (new template)
+3. Reads `.claude/settings.json` (user's current)
+4. **Orphan detection:** removes hooks present in old template but missing in new
+5. **Merge:** adds hooks from new template that aren't already in user's current
+6. User-added hooks (never in old template) are **preserved**
+
+**Identity model:** hooks are compared by `command` string. User-modified
+default (changed command) → treated as user-added, preserved.
+
+See algorithm details in [05_architecture.md](./05_architecture.md).
+
+---
+
+## MCP servers
+
+**File:** `.mcp.json` (project-local).
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "..." }
+    }
+  }
+}
+```
+
+Statusline shows MCP server count in the Status line.
+
+`/replicate` Phase 3 auto-generates `.mcp.json` when external integrations
+are detected.
+
+---
+
+## Keysarium integration
+
+If `.keysarium.json` (from sibling `@dzhechkov/keysarium` package) is
+detected:
+
+- `init` shows an integration banner
+- Statusline shows `🧬 Keysarium ✓`
+- `/replicate` Phase 3 doesn't duplicate skills already provided by Keysarium
+
+Keysarium docs are in its own package.
+
+---
+
+## Next
+
+- [04_api_reference.md](./04_api_reference.md) — formal schemas
+- [05_architecture.md](./05_architecture.md) — internal design
+- [06_troubleshooting.md](./06_troubleshooting.md) — common issues

package/README/eng/04_api_reference.md

@@ -0,0 +1,302 @@
+# 04. API Reference
+
+Formal reference: CLI commands, flags, JSON schemas.
+
+## CLI: `npx @dzhechkov/p-replicator`
+
+### Subcommands
+
+| Subcommand | Purpose | Exit code |
+|---|---|---|
+| `init` (default) | Install package in project | `0` ok, `1` if already installed without `--force` |
+| `update` | Upgrade files to new version | `0` ok, `1` if not installed |
+| `remove` | Delete package-tracked files | `0` ok, `1` if not installed |
+| `list` | List installed components | `0` |
+| `doctor` | Health check of pre-shipped contract | `0` ok, `1` if anything broken |
+| `verify` | Pre-shipped + post-/replicate verification | `0` ok, `1` if pre-shipped contract violated |
+
+### Global flags
+
+| Flag | Where it works | Description |
+|---|---|---|
+| `--force` | `init` | Overwrite existing files (with merge logic for settings.json) |
+| `--dry-run` | `init`, `update`, `remove` | Preview without writing to disk |
+| `--reset-settings` | `init --force`, `update` | Full overwrite of settings.json (disables merge) |
+| `--help`, `-h` | any | Show help |
+| `--version`, `-v` | any | Show package version |
+
+### Slash command flags (inside Claude Code)
+
+| Flag | Where | Description |
+|---|---|---|
+| `--feature-branches` | `/run`, `/go` | Each feature on its own branch `feature/{NNN}-{id}` |
+| `--auto-merge` | `/run`, `/go` (with `--feature-branches`) | Auto-merge feature branch into main on success |
+| `--skip-tests` | `/start` | Skip test generation |
+| `--skip-seed` | `/start` | Skip DB seeding |
+| `--dry-run` | `/start`, `/replicate` | Preview without writing |
+
+---
+
+## Manifest schema (`.p-replicator.json`)
+
+```json
+{
+  "version": "1.5.0",
+  "installedAt": "2026-05-07T12:00:00.000Z",
+  "components": ["agents", "commands", "hooks", "rules", "settings", "skills"],
+  "files": [
+    ".claude/agents/doc-validator.md",
+    ".claude/commands/replicate.md",
+    "...sorted list of all installed files..."
+  ],
+  "shippedDefaults": {
+    "settings.json": {
+      "hooks": { "SessionStart": [...], "Stop": [...] },
+      "statusLine": { "type": "command", "command": "..." }
+    }
+  }
+}
+```
+
+| Field | Type | Purpose |
+|---|---|---|
+| `version` | semver | Package version at last install/update |
+| `installedAt` | ISO-8601 | Timestamp of last install |
+| `components` | array of group keys | Pre-shipped groups |
+| `files` | sorted array | All package-tracked files (for `remove`) |
+| `shippedDefaults` | optional map | Template snapshots for orphan detection on upgrade |
+
+**Backward compat:** manifest without `shippedDefaults` (pre-1.4.3) loads
+without error — orphan detection is skipped on first upgrade.
+
+---
+
+## Roadmap schema (`.claude/feature-roadmap.json`)
+
+```json
+{
+  "version": "1.0",
+  "features": [
+    {
+      "id": "auth-jwt",
+      "number": 1,
+      "branch": "feature/001-auth-jwt",
+      "name": "JWT-based authentication",
+      "priority": "mvp",
+      "status": "next",
+      "complexity": "medium",
+      "estimated_hours": "2-4",
+      "blockers": [],
+      "expected_files": ["packages/backend/src/auth/jwt.ts"],
+      "depends_on": []
+    }
+  ]
+}
+```
+
+### Feature fields
+
+| Field | Required | Type | Populated by | Purpose |
+|-------|----------|------|--------------|---------|
+| `id` | yes | kebab-case slug | initial generation | Stable identifier |
+| `number` | optional | int | `--feature-branches` flag | Sequential 1..N for branch naming |
+| `branch` | optional | string | `--feature-branches` after success | `feature/{NNN}-{id}` actual ref |
+| `name` | recommended | string | initial generation | Human-readable title |
+| `priority` | yes | enum | initial generation | `mvp` \| `high` \| `medium` \| `low` |
+| `status` | yes | enum | lifecycle | `planned` \| `next` \| `in_progress` \| `done` \| `blocked` |
+| `complexity` | optional | enum | initial generation | `simple` \| `medium` \| `complex` |
+| `estimated_hours` | optional | string | initial generation | Time hint |
+| `blockers` | optional | string[] | manual | Issue IDs |
+| `expected_files` | optional | string[] | initial generation | Used by `/next update` for completion detection |
+| `depends_on` | optional | string[] | initial generation | Feature IDs that must complete first |
+
+---
+
+## State file schema (`.claude/.p-replicator-state.json`)
+
+```json
+{
+  "currentCommand": "/feature",
+  "currentPhase": {
+    "name": "VALIDATE",
+    "index": 2,
+    "total": 4,
+    "progress": 0.5
+  },
+  "lastCommand": "/replicate",
+  "lastFeature": "auth-jwt",
+  "updatedAt": "2026-05-07T..."
+}
+```
+
+| Field | Type | Purpose |
+|---|---|---|
+| `currentCommand` | `/<name>` | Active command (`null` if idle) |
+| `currentPhase` | object | Live progress in current command |
+| `currentPhase.name` | string | Phase name (e.g., `VALIDATE`) |
+| `currentPhase.index` | int | Current phase 1..total |
+| `currentPhase.total` | int | Total phases |
+| `currentPhase.progress` | float 0..1 | Progress within current phase |
+| `lastCommand` | `/<name>` | Previous command (for status) |
+| `lastFeature` | string | ID of last implemented feature |
+| `updatedAt` | ISO-8601 | Timestamp |
+
+**Stale check:** statusline ignores state older than 30 minutes.
+
+**Update API:**
+
+```bash
+node .claude/hooks/state-update.cjs \
+  --command /feature \
+  --phase VALIDATE \
+  --index 2 \
+  --total 4 \
+  --progress 0.5 \
+  --last-command /replicate \
+  --last-feature auth-jwt
+```
+
+Or with full JSON:
+
+```bash
+node .claude/hooks/state-update.cjs --json '{"currentCommand":"/run", ...}'
+```
+
+---
+
+## settings.json structure
+
+```json
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_comment": "Description",
+  "statusLine": {
+    "type": "command",
+    "command": "node .claude/hooks/statusline.cjs"
+  },
+  "hooks": {
+    "SessionStart": [ /* matchers + hooks */ ],
+    "Stop": [ /* matchers + hooks */ ],
+    "PreToolUse": [ /* user-added */ ],
+    "PostToolUse": [ /* user-added */ ]
+  }
+}
+```
+
+### `statusLine` field
+
+```json
+{
+  "statusLine": {
+    "type": "command",       // only "command" supported
+    "command": "node .claude/hooks/statusline.cjs"
+  }
+}
+```
+
+Script writes multi-line ANSI output to stdout. Remove the field to disable
+statusline (merge preserves the deletion on upgrade).
+
+### `hooks.<EventType>` array
+
+Each entry:
+
+```json
+{
+  "matcher": "*",                    // or regex for tool-name
+  "hooks": [
+    {
+      "type": "command",
+      "command": "node .claude/hooks/X.cjs",
+      "timeout": 10                  // seconds
+    }
+  ]
+}
+```
+
+**Event types in Claude Code:**
+- `SessionStart` — at session start (stdout injected into context)
+- `Stop` — at turn end (side-effects: commit, log)
+- `PreToolUse`, `PostToolUse` — around tool calls
+
+---
+
+## COMPONENTS schema (in `src/utils.js`)
+
+The contract for what's shipped vs generated:
+
+```javascript
+const COMPONENTS = {
+  skills: {
+    src: '.claude/skills',
+    kind: 'pre-shipped',
+    label: 'Skills (10 skill packs)',
+    group: 'core',
+    items: { 'explore': '...', /* ... 10 entries */ },
+  },
+  commands: { kind: 'pre-shipped', items: { /* 11 */ } },
+  agents:   { kind: 'pre-shipped', items: { /* 4 */ } },
+  rules:    { kind: 'pre-shipped', items: { /* 5 */ } },
+  settings: { isFile: true, kind: 'pre-shipped', items: { 'settings.json': '...' } },
+  hooks:    { kind: 'pre-shipped', items: { /* 6 */ } },
+
+  // Project-generated (created by /replicate Phase 3)
+  projectAgents: { kind: 'project-generated', items: { /* full paths */ } },
+  projectRules:  { kind: 'project-generated', items: { /* full paths */ } },
+  projectFiles:  { kind: 'project-generated', items: { /* full paths */ } },
+};
+```
+
+**Identity:**
+- `kind: 'pre-shipped'` — installed by `init`, file paths derived from `src` + item key
+- `kind: 'project-generated'` — created by `/replicate` Phase 3, item keys ARE full paths
+- `isFile: true` — single-file component (settings.json), not a directory
+
+**Helper:** `utils.getItemRelativePath(comp, itemKey)` centralizes path
+derivation:
+- pre-shipped skills: `<src>/<itemKey>/SKILL.md`
+- pre-shipped hooks: `<src>/<itemKey>.cjs`
+- pre-shipped commands/rules/agents: `<src>/<itemKey>.md`
+- pre-shipped settings.json: `comp.src` (full path)
+- project-generated: `itemKey` (already full path)
+
+Used by `verify`, `doctor`, `list` for uniform path resolution.
+
+---
+
+## Hook scripts API
+
+### `session-insights.cjs`
+
+**Trigger:** `SessionStart` hook.
+**Reads:** `.claude/insights/index.md` (`## YYYY-MM-DD` headings)
+**Writes:** stdout (Claude Code injects into session context)
+**Output:** up to 3 recent insights as `## Recent project insights\n\n## ... ## ... ## ...`
+
+### `autocommit-roadmap.cjs` / `autocommit-insights.cjs` / `autocommit-plans.cjs`
+
+**Trigger:** `Stop` hook.
+**Reads:** target paths
+**Side-effect:** `git add` + `git diff --cached --quiet` check + `git commit --only` if changed
+**stdout/stderr:** suppressed
+**Always exits 0** (best-effort)
+
+### `statusline.cjs`
+
+**Trigger:** Claude Code `statusLine` config (every prompt render).
+**Reads:** filesystem heuristics + state-file
+**Writes:** stdout 6-line ANSI output (header + 5 content)
+**Defensive:** every section wrapped in `safeRun()` with fallback
+
+### `state-update.cjs`
+
+**Invoked:** by pipeline commands via Bash tool
+**Args:** `--command`, `--phase`, `--index`, `--total`, `--progress`, `--last-command`, `--last-feature`, `--json`
+**Writes:** `.claude/.p-replicator-state.json`
+**Always exits 0** (best-effort)
+
+---
+
+## Next
+
+- [05_architecture.md](./05_architecture.md) — internal design details