@dzhechkov/p-replicator 1.3.0 → 1.5.3

package/templates/.claude/commands/run.md

@@ -0,0 +1,151 @@
+---
+description: Autonomous build loop — picks next feature from roadmap, dispatches to /go, repeats until exhausted. Modes: `mvp` (default — only features tagged mvp), `all` (everything in `next` or `planned`). Auto-commits after each feature. Supports `--feature-branches` for per-feature git branches (teaching/demo workflow).
+argument-hint: '[mvp | all] [--feature-branches] [--auto-merge]'
+---
+
+# /run $ARGUMENTS
+
+## Purpose
+
+One-command autonomous feature build. Reads `.claude/feature-roadmap.json`,
+loops through features via `/next` → `/go`, marks them done, commits, and
+continues until the scoped list is exhausted.
+
+> **PROCESS COMPLIANCE — BLOCKING RULES:**
+> - MUST delegate to `/next`, `/go`, `/plan`, `/feature` — NEVER spawn raw Agent tools directly
+> - MUST commit after each feature (one feature = one commit cluster)
+> - FORBIDDEN: bypassing /go's complexity routing
+> - FORBIDDEN: batching multiple features in a single commit wave
+
+## Step 0: Parse Scope
+
+| `$ARGUMENTS` | Filter applied to roadmap |
+|--------------|---------------------------|
+| `mvp` (default if empty) | Only features with `priority: "mvp"` and status in `next`/`planned` |
+| `all` | All features with status in `next`/`planned` |
+
+If `.claude/feature-roadmap.json` does not exist → halt with:
+```
+Roadmap not found. Run /replicate first or create .claude/feature-roadmap.json manually.
+```
+
+## Step 1: Bootstrap Check
+
+If `CLAUDE.md` exists but core scaffolding is missing (e.g., no `package.json`,
+no `docker-compose.yml`), call `/start` once before the loop. Skip if
+scaffolding already in place.
+
+## Step 2: Feature Loop
+
+```
+while features_remaining_in_scope:
+    feature_id = /next                       # pick highest-priority next/planned
+    if not feature_id: break
+    /go feature_id                           # complexity router → /plan or /feature
+    verify completion (tests green, code committed)
+    mark roadmap entry: status = "done"
+    git commit -m "docs(roadmap): mark <id> as done"
+    git push origin HEAD
+```
+
+Between iterations, briefly summarize progress: `Completed N of M features in scope`.
+
+## Step 3: Final Summary
+
+When the loop terminates (scope exhausted or user interrupt):
+
+```
+═══════════════════════════════════════════════════════════════
+✅ /run complete — scope: <mvp|all>
+   Completed: <N> features
+   Total commits: <count>
+   Time elapsed: <duration>
+   Next: /docs to generate documentation, /harvest to extract knowledge
+═══════════════════════════════════════════════════════════════
+```
+
+## Error Recovery
+
+If a single feature fails (test red, validation blocked), `/run`:
+1. Marks that feature as `blocked` with reason
+2. Continues to next feature in scope
+3. At the end, lists all blocked features for manual review
+
+`/run` does NOT abort the whole loop on one feature failure — autonomous mode
+is designed for unattended operation.
+
+## Flag: `--feature-branches` (v1.5.0)
+
+Create a separate git branch per feature. Useful for **teaching/demo
+workflows** where each feature must be a discrete unit the instructor can
+checkout independently.
+
+### Branch naming format
+
+```
+feature/{NNN}-{id}
+```
+where `NNN` is a zero-padded 3-digit feature number from the roadmap, and
+`{id}` is the feature's slug. Example: `feature/001-auth-jwt`.
+
+### Per-feature workflow with --feature-branches
+
+```
+For each feature in scope:
+  1. Verify on `main` branch (else fail with hint to switch)
+  2. If working tree is dirty:
+       git stash push -u -m "auto-stash before /run feature-branches"
+  3. Read roadmap entry; if feature has no `number`, assign max(numbers) + 1
+     and persist back to .claude/feature-roadmap.json
+  4. git checkout -b feature/{NNN}-{id}    # branched from main
+  5. /go {feature-id}                       # delegate to standard pipeline
+  6. git push origin feature/{NNN}-{id} --set-upstream
+  7. Mark roadmap entry: status=done, branch="feature/{NNN}-{id}"
+  8. git checkout main                      # ready for next iteration
+  9. If --auto-merge ALSO passed:
+       git merge --no-ff feature/{NNN}-{id} -m "merge: feature/{NNN}-{id}"
+```
+
+### Companion flag: `--auto-merge`
+
+Off by default. When passed alongside `--feature-branches`, each feature
+branch is merged into `main` (with `--no-ff`) immediately after completion.
+Without `--auto-merge`, branches are pushed but **NOT** merged — instructor
+or reviewer is expected to merge via PR or manually.
+
+### Roadmap schema extension (post v1.5.0)
+
+```json
+{
+  "id": "auth-jwt",
+  "number": 1,
+  "branch": "feature/001-auth-jwt",
+  "name": "JWT-based authentication",
+  "priority": "mvp",
+  "status": "done",
+  ...
+}
+```
+
+`number` is auto-assigned on first encounter when `--feature-branches` is
+used. `branch` is populated when the feature completes successfully.
+
+### Use cases
+
+- **Teaching:** instructor checks out `feature/003-payment` to demo a specific
+  feature. All branches are pushed, easy to fetch and explore.
+- **Code review:** each feature has standalone branch for PR-based review.
+- **Experimentation:** abandon a branch cleanly without disturbing main.
+
+### Anti-patterns
+
+- Running `--feature-branches` while on a feature branch (not main) → fails
+- Mixing `--feature-branches` with non-branch features in the same session
+  → mark already-merged features explicitly with `branch: "main"` to avoid retry
+
+## Related
+
+- `/next` — picks next feature (called per iteration)
+- `/go` — complexity router (called per feature; also accepts `--feature-branches`)
+- `/plan`, `/feature` — actual implementation pipelines
+- `.claude/feature-roadmap.json` — source of truth for what to build

package/templates/.claude/commands/start.md

@@ -0,0 +1,88 @@
+---
+description: Bootstrap project from SPARC documentation. Generates monorepo skeleton, packages, Docker configs, database schema, core modules, and basic tests in 4 phases (Foundation → Packages parallel → Integration → Finalize). Reads `docs/` as source of truth.
+argument-hint: '[--skip-tests | --skip-seed | --dry-run]'
+---
+
+# /start $ARGUMENTS
+
+## Purpose
+
+One-command project generation from SPARC documentation → working monorepo
+with `docker compose up`. Reads `docs/` (NOT memory), maximizes parallelism
+via `Task` tool, commits per logical change for safe error recovery.
+
+## Prerequisites
+
+- SPARC documents in `docs/` (output of `/replicate` Phase 1)
+- `CLAUDE.md` at project root
+- Docker + Docker Compose installed
+- Git initialized
+
+## Phases
+
+### Phase 1: Foundation (sequential)
+
+1. **Read all SPARC docs** to build full context:
+   - `docs/Architecture.md` → monorepo structure, Docker Compose, tech stack
+   - `docs/Specification.md` → data model, API endpoints, NFRs
+   - `docs/Pseudocode.md` → core algorithms
+   - `docs/Completion.md` → env config, deployment
+   - `docs/PRD.md` → features (for README)
+   - `docs/Refinement.md` → edge cases, testing strategy
+
+2. **Generate root configs:** `package.json` (monorepo workspaces),
+   `docker-compose.yml`, `.env.example`, `.gitignore`, `tsconfig.base.json`.
+
+3. **Git commit:** `chore: project root configuration`
+
+### Phase 2: Packages (PARALLEL via Task tool ⚡)
+
+For EACH package in Architecture.md, spawn an independent Task referencing
+SOURCE DOCS (not memory):
+
+```
+### Task <X>: packages/<name> ⚡
+Read and use as source:
+- docs/Specification.md → data model → ORM schema
+- docs/Architecture.md → API endpoints → routes
+- docs/Pseudocode.md → algorithms → service layer
+
+Generate: src/<files>, tests/<files>, package.json, README.md
+Commits: one per logical group.
+```
+
+### Phase 3: Integration (sequential)
+
+1. Verify cross-package imports
+2. `docker compose build`
+3. `docker compose up -d`
+4. Database migration (if applicable): `npx prisma migrate dev` (or equivalent)
+5. Health check: `curl localhost:<port>/health`
+6. Run tests
+7. Git commit: `chore: verify docker integration`
+
+### Phase 4: Finalize
+
+1. Generate/update `README.md` with quick start
+2. `git tag v0.1.0-scaffold`
+3. Report summary
+
+## Flags
+
+- `--skip-tests` — don't generate test files (NOT recommended)
+- `--skip-seed` — skip DB seeding
+- `--dry-run` — show plan without executing
+
+## Critical Rules
+
+1. **Docs as source of truth** — every file references specific docs, never memory
+2. **Maximize parallelism** — independent packages run as parallel Tasks
+3. **Atomic commits** — one commit per logical change
+4. **Full integration** — Phase 3 includes build + start + health check
+5. **Project-specific** — adapt all examples to actual tech stack
+
+## Related
+
+- `/replicate` — generates the SPARC docs that `/start` reads
+- `/run mvp` — builds features after scaffold is up
+- `/feature <name>` — implement individual features

package/templates/.claude/hooks/autocommit-insights.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Stop hook — auto-commits .claude/insights/ if anything changed.
+ * Cross-platform: pure Node + execFileSync, no shell.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const TARGET_DIR = path.resolve(process.cwd(), '.claude', 'insights');
+const RELATIVE = path.relative(process.cwd(), TARGET_DIR);
+const SILENT = { stdio: 'ignore' };
+
+function git(args) {
+  return execFileSync('git', args, SILENT);
+}
+
+try {
+  if (!fs.existsSync(TARGET_DIR)) process.exit(0);
+  try { git(['rev-parse', '--git-dir']); } catch { process.exit(0); }
+
+  git(['add', '--', RELATIVE]);
+
+  let hasDiff = false;
+  try {
+    git(['diff', '--cached', '--quiet', '--', RELATIVE]);
+  } catch {
+    hasDiff = true;
+  }
+
+  if (hasDiff) {
+    git(['commit', '--only', '--', RELATIVE, '-m', 'docs(insights): auto-capture']);
+  }
+} catch (_err) {
+  process.exit(0);
+}

package/templates/.claude/hooks/autocommit-plans.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Stop hook — auto-commits docs/plans/ if anything changed.
+ * Cross-platform: pure Node + execFileSync, no shell.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const TARGET_DIR = path.resolve(process.cwd(), 'docs', 'plans');
+const RELATIVE = path.relative(process.cwd(), TARGET_DIR);
+const SILENT = { stdio: 'ignore' };
+
+function git(args) {
+  return execFileSync('git', args, SILENT);
+}
+
+try {
+  if (!fs.existsSync(TARGET_DIR)) process.exit(0);
+  try { git(['rev-parse', '--git-dir']); } catch { process.exit(0); }
+
+  git(['add', '--', RELATIVE]);
+
+  let hasDiff = false;
+  try {
+    git(['diff', '--cached', '--quiet', '--', RELATIVE]);
+  } catch {
+    hasDiff = true;
+  }
+
+  if (hasDiff) {
+    git(['commit', '--only', '--', RELATIVE, '-m', 'docs(plan): auto-save']);
+  }
+} catch (_err) {
+  process.exit(0);
+}

package/templates/.claude/hooks/autocommit-roadmap.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Stop hook — auto-commits .claude/feature-roadmap.json if it changed.
+ * Cross-platform: uses execFileSync('git', [...]) so no shell quoting/redirect issues.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const TARGET = path.resolve(process.cwd(), '.claude', 'feature-roadmap.json');
+const RELATIVE = path.relative(process.cwd(), TARGET);
+const SILENT = { stdio: 'ignore' };
+
+function git(args) {
+  return execFileSync('git', args, SILENT);
+}
+
+try {
+  // Skip if file doesn't exist or we're not in a git repo.
+  if (!fs.existsSync(TARGET)) process.exit(0);
+  try { git(['rev-parse', '--git-dir']); } catch { process.exit(0); }
+
+  // Stage only the target file.
+  git(['add', '--', RELATIVE]);
+
+  // Check whether anything is staged for THIS path.
+  // `git diff --cached --quiet -- <path>` exits 0 = no diff, 1 = diff exists.
+  let hasDiff = false;
+  try {
+    git(['diff', '--cached', '--quiet', '--', RELATIVE]);
+  } catch {
+    hasDiff = true;
+  }
+
+  if (hasDiff) {
+    git(['commit', '--only', '--', RELATIVE, '-m', 'docs(roadmap): auto-update']);
+  }
+} catch (_err) {
+  // Best-effort — never break Claude session on commit failures.
+  process.exit(0);
+}

package/templates/.claude/hooks/session-insights.cjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * SessionStart hook — injects up to 3 most recent insights from
+ * .claude/insights/index.md into Claude's initial session context (via stdout).
+ *
+ * Cross-platform: pure Node, no shell pipes. Silent on missing index.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const INDEX = path.resolve(process.cwd(), '.claude', 'insights', 'index.md');
+
+try {
+  if (!fs.existsSync(INDEX)) process.exit(0);
+  const text = fs.readFileSync(INDEX, 'utf8');
+  // Each insight starts with "## " heading (per insights-capture.md convention).
+  const sections = text.split(/^## /m).filter(Boolean);
+  const recent = sections.slice(-3).map((s) => '## ' + s.trim()).join('\n\n');
+  if (recent.length > 0) {
+    process.stdout.write('## Recent project insights\n\n' + recent + '\n');
+  }
+} catch (_err) {
+  // Hook is advisory — never block the session on errors here.
+  process.exit(0);
+}

package/templates/.claude/hooks/state-update.cjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * state-update.cjs (v1.5.0) — write `.claude/.p-replicator-state.json`.
+ *
+ * Used by pipeline commands (/run, /go, /feature, /replicate) to publish
+ * current command + phase + progress for the statusline to display.
+ *
+ * Usage:
+ *   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 pass JSON in one arg:
+ *   node .claude/hooks/state-update.cjs --json '{"currentCommand":"/run", ...}'
+ *
+ * Idempotent: overwrites the state file each call. Always exits 0 (best-effort).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STATE_FILE = path.resolve(process.cwd(), '.claude', '.p-replicator-state.json');
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      out[key] = next;
+      i++;
+    } else {
+      out[key] = true;
+    }
+  }
+  return out;
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv);
+
+    let state;
+    if (args.json) {
+      try { state = JSON.parse(args.json); }
+      catch { state = {}; }
+    } else {
+      state = {
+        currentCommand: args.command || null,
+        currentPhase: args.phase ? {
+          name: args.phase,
+          index: args.index ? parseInt(args.index, 10) : null,
+          total: args.total ? parseInt(args.total, 10) : null,
+          progress: args.progress ? parseFloat(args.progress) : null,
+        } : null,
+        lastCommand: args['last-command'] || null,
+        lastFeature: args['last-feature'] || null,
+      };
+    }
+
+    state.updatedAt = new Date().toISOString();
+
+    fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  } catch (_err) {
+    // Best-effort. Never fail the calling pipeline on state-write issues.
+  }
+}
+
+main();