@dzhechkov/p-replicator

v1.5.7

Published

3 days ago

P-Replicator — Claude Code toolkit for AI-assisted product development (Vibe Coding). Full /replicate pipeline, 10 modular skills (194K+ chars), /harvest knowledge extraction, swarm agents, quality gates, security patterns, cross-project learning.

🚀 @dzhechkov/p-replicator

Claude Code toolkit for AI-assisted product development

Transform a product idea — or existing project — into fully documented, validated, toolkit-equipped code

📦 npm · 💻 GitHub · 🐛 Issues · 💬 Telegram

📚 Documentation in your language

| Language | Format | Description | |---|---|---| | 🇷🇺 Русский | Markdown (8 sections) | ~3000 строк deep-dive докуменации | | 🇬🇧 English | Markdown (8 sections) | ~3000 lines deep-dive documentation | | 🌐 Interactive | HTML guide (RU) | Single-page with search, theming, syntax highlighting |

📌 This README is comprehensive and self-contained — covers ~95% of what most users need. For deep dives (architecture internals, full troubleshooting, formal API schemas) see the eng/ folder.

📑 Table of Contents

🌟 Getting Started

🛠️ Reference

⚙️ Operations

🆘 Help & Meta

💡 Quick navigation tip: TOC items use emoji visual anchors instead of plain text — easier to scan than 26 dark-blue links.

📖 What is p-replicator?

@dzhechkov/p-replicator installs a ready-made .claude/ toolkit into any project: 11 slash commands, 10 skills, 4 agents, 5 rules, 6 hook scripts, and a settings.json with pre-configured hooks and a multi-line statusline dashboard.

The flagship /replicate command takes a project through a 5-phase pipeline:

Phase 0 (optional)    Product Discovery     reverse-engineering of similar companies
Phase 1               Planning              11 SPARC documents (PRD, Architecture, Pseudocode, ...)
Phase 2               Validation            5-agent swarm validates against INVEST + SMART
Phase 3               Toolkit Generation    project-specific agents, rules, skills
Phase 4               Finalize              docker-compose.yml, Dockerfile, .gitignore + git commit

Plus /feature for adding new features to a project with the same SPARC-mini validation cycle, /run --feature-branches for autonomous batch builds with per-feature git branches, /harvest for extracting reusable patterns into a knowledge base, and 8 more commands (/start, /plan, /go, /next, /myinsights, /docs, /deploy, /feature-ent).

Two main use cases:

| Use case | Entry command | Time | Result | |---|---|---|---| | Bootstrap a new project from idea or company name | /replicate | 45–90 min | Fully-documented project + scaffold + Docker | | Add features to an existing project | /feature (Mode 2) | 10–30 min per feature | Validated SPARC docs + implementation + review |

Target architecture for generated projects:

Pattern: Distributed Monolith (Monorepo)
Containers: Docker + Docker Compose
Infrastructure: VPS (e.g., AdminVPS, HOSTKEY)
Deploy: Docker Compose direct deploy
AI Integration: MCP servers

🚀 Quick Start

# 1. Install in any project
cd your-project
npx @dzhechkov/p-replicator init

# 2. Open Claude Code
claude

# 3. Run the pipeline
/replicate "Online marketplace for handmade crafts with AI-powered recommendations"

The system walks you through 4–5 phases with interactive checkpoints. At each checkpoint you review the output and confirm before proceeding.

Estimated time: 45–90 minutes for the full pipeline (Phase 0 optional).

After /replicate completes:

/start — bootstrap the scaffold from Architecture.md
/run mvp — autonomous feature build from roadmap
/feature <id> — single-feature lifecycle

📑 Already have technical documentation?

If you already have tech specs, architecture notes, or API docs for the project, you can skip Phase 0 (Product Discovery) and feed your existing docs into Phase 1 as input:

mkdir -p docs/existing
cp your-tech-doc-*.md docs/existing/   # place your existing docs here

claude
/replicate "Use my existing docs in docs/existing/, skip Phase 0"

Three sub-paths:

| Path | When | Result | |---|---|---| | A. Full pipeline | Have tech docs, want full pipeline + toolkit + scaffold | All 11 SPARC docs + validation + toolkit + scaffold | | B. SPARC docs only | Want only the 11 SPARC docs | Invoke sparc-prd-mini skill in AUTO mode | | C. Validation-only | Existing docs already SPARC-shaped | Rename to PRD.md, Architecture.md, ... + invoke requirements-validator |

Modified flow when triggered:

Phase 0 — SKIPPED entirely
Phase 1 — sparc-prd-mini runs in AUTO mode, reads your docs, generates the 11 SPARC slots; missing parts marked [GAP: ...]
Phase 2-4 — unchanged

Full recipe: see User Guide (RU).

🔧 Adding features to an existing project (Mode 2)

If you already have a working project (stack, PRD, CLAUDE.md, Specification defined) and want to add new features with the same SPARC-mini validation cycle that /replicate provides — use /feature (Mode 2):

cd existing-project
npx @dzhechkov/p-replicator init      # idempotent — preserves CLAUDE.md
claude
/feature add-stripe-payments          # 4-phase: PLAN → VALIDATE → IMPLEMENT → REVIEW

/feature runs the same validation pipeline as /replicate Phase 2, scoped to a single feature. Same verdicts: 🟢 READY (≥70) / 🟡 CAVEATS (50–69) / 🔴 NEEDS WORK (<50). Same retry logic. Same brutal-honesty-review post-implementation.

Two officially supported entry modes for /feature:

| Mode | When | Pre-conditions | |---|---|---| | Mode 1: Post-/replicate | Project bootstrapped via /replicate | CLAUDE.md, docs/, scaffold all generated by /replicate | | Mode 2: Existing project | Working project, adding features with verification | init ran on top of existing project; CLAUDE.md already exists |

Three sub-paths for Mode 2:

| Path | When | Skills invoked | |---|---|---| | A. /feature directly | Single feature ≥4 files, new capability | sparc-prd-mini → requirements-validator → parallel implement → brutal-honesty-review | | B. /go auto-router | Mixed complexity | Routes between /plan (≤3 files) and /feature (≥4 files) | | C. Direct skill invocation | Only validation cycle | requirements-validator + brutal-honesty-review skills directly |

Mode 2 setup (one-time):

# 1. Install (idempotent — does NOT touch CLAUDE.md or existing .claude/ files)
npx @dzhechkov/p-replicator init
npx @dzhechkov/p-replicator verify

# 2. Normalize SPARC paths (one-time)
mv docs/your-prd.md   docs/PRD.md
mv docs/your-spec.md  docs/Specification.md
mv docs/your-arch.md  docs/Architecture.md

# 3. (Optional) feature-roadmap for batch mode via /run
cat > .claude/feature-roadmap.json << 'EOF'
{"features": [{"id": "stripe-payments", "title": "Stripe", "priority": "mvp", "status": "planned"}]}
EOF

⚠️ Mode 2 caveats:
DO NOT run /start — it expects a fresh scaffold
/feature-ent unavailable in Mode 2 without DDD/ADR/C4 docs
Auto-commit hooks may conflict with custom git workflows — edit settings.json after init
No --prd-path flag for non-standard paths — one-time rename/symlink required (see KNOWN_LIMITATIONS.md M3)

Full recipe: see User Guide (RU).

📦 Installation

Prerequisites

Node.js ≥ 16.0.0
Claude Code installed (CLI or web)
Git initialized in the project (git init if not already)
Docker + Docker Compose (needed for /start Phase 3, optional for /feature)

Install command

cd your-project
npx @dzhechkov/p-replicator init

This creates:

.claude/skills/ — 10 pre-shipped skills
.claude/commands/ — 11 slash commands (/replicate, /run, /feature, ...)
.claude/agents/ — 4 pipeline agents
.claude/rules/ — 5 governance rules
.claude/hooks/ — 6 cross-platform Node scripts
.claude/settings.json — hooks + statusline configuration
.p-replicator.json — install manifest

📌 Idempotency: init will NOT overwrite existing files without --force. Your CLAUDE.md, custom commands, and modified settings are preserved.

Common install scenarios

| Scenario | Command | |---|---| | Fresh project | npx @dzhechkov/p-replicator init | | Existing project (preserve all custom files) | npx @dzhechkov/p-replicator init (idempotent — same as fresh) | | Upgrade (preserve user customizations) | npx @dzhechkov/p-replicator@latest update | | Repair broken install | npx @dzhechkov/p-replicator init --force | | Full reset (loses custom hooks) | npx @dzhechkov/p-replicator init --force --reset-settings | | Preview without writing | npx @dzhechkov/p-replicator init --dry-run |

📋 What Gets Installed

| Component | Count | Description | |-----------|-------|-------------| | Skills | 10 | 90+ files (~200K chars). Modular architecture: foundation → composite → master orchestrator | | Commands | 11 | /replicate, /harvest, /start, /plan, /feature, /go, /run, /next, /myinsights, /docs, /deploy | | Agents | 4 | replicate-coordinator, product-discoverer, doc-validator, harvest-coordinator | | Rules | 5 | replicate-pipeline, skill-interface-protocol, git-workflow, insights-capture, feature-lifecycle | | Hooks | 6 | session-insights, autocommit-{roadmap,insights,plans}, statusline, state-update (cross-platform Node) | | Settings | 1 | settings.json with statusLine + SessionStart + Stop hooks pre-configured |

After running /replicate, the toolkit also generates project-specific artifacts:

.claude/agents/planner.md, code-reviewer.md, architect.md (project-aware)
.claude/rules/security.md, coding-style.md, testing.md, optionally secrets-management.md
.claude/skills/project-context/, coding-standards/, optionally security-patterns/
.claude/feature-roadmap.json (from PRD MVP scope)
CLAUDE.md enhanced with project-specific content
DEVELOPMENT_GUIDE.md, project README.md
docker-compose.yml, Dockerfile, .gitignore (Phase 4 scaffolds)
docs/* — all SPARC documentation (11 files)

✅ Verify the install

After /replicate, run:

npx @dzhechkov/p-replicator verify

The command checks:

Pre-shipped contract (must-have): 10 skills + 11 commands + 4 agents + 5 rules + settings.json + 6 hooks
Post-/replicate hints (advisory): CLAUDE.md, project-specific agents, feature-roadmap.json, security rules, etc.

Exit codes:

0 — pre-shipped contract intact (warnings about project-specific are normal pre-/replicate)
1 — pre-shipped contract violated → run init --force to repair

Alternative — health check:

npx @dzhechkov/p-replicator doctor

doctor verifies pre-shipped contract + Prerequisites (git on PATH). Stricter than verify for must-have components.

🎯 Pipeline overview — `/replicate` phases

Phase 0 — Product Discovery (optional)

Activated for: new SaaS, startups, products to research. Skipped for: internal tools, experiments, projects with existing tech docs.

Skill: reverse-engineering-unicorn (JTBD analysis + competitors + Blue Ocean canvas)
Output: docs/00_product_discovery.md

Phase 1 — Planning (SPARC docs)

Generates 11 standardized documents in docs/:

| Document | Content | |---|---| | PRD.md | Vision, personas, user stories | | Solution_Strategy.md | Solution approach | | Specification.md | Acceptance criteria, NFRs | | Pseudocode.md | Algorithms, data flow | | Architecture.md | C4 diagrams, tech stack | | Refinement.md | Edge cases, testing strategy | | Completion.md | Deploy, CI/CD, monitoring | | Research_Findings.md | Market and tech research | | Final_Summary.md | Executive summary | | C4_Diagrams.md | Context / container / component | | ADR.md | Architecture Decision Records |

Skill: sparc-prd-mini (internally chains explore + research + solve sub-phases).

Phase 2 — Validation (5-agent swarm)

| Agent | Validates | |---|---| | validator-stories | INVEST criteria for user stories | | validator-acceptance | SMART criteria for acceptance criteria | | validator-architecture | Architecture consistency vs target constraints | | validator-pseudocode | Algorithm cohesion | | validator-coherence | Cross-document consistency |

Verdicts:

🟢 READY (score ≥70) → Phase 3
🟡 CAVEATS (50–69) → Phase 3 with notes (auto-retry once on 🟡 in AUTO mode)
🔴 NEEDS WORK (<50 or blockers) → return to Phase 1, max 3 retries → halt

Output: docs/validation-report.md, docs/test-scenarios.md (BDD).

Phase 3 — Toolkit Generation (project-specific only)

Does NOT generate pre-shipped commands (those are installed via init). Generates only project-specific artifacts:

.claude/agents/{planner,code-reviewer,architect}.md — project-aware
.claude/rules/{security,coding-style,testing}.md — derived from Specification + Refinement
.claude/skills/{project-context,coding-standards}/ — domain knowledge
CLAUDE.md enhanced with project content
.claude/feature-roadmap.json — from PRD MVP scope
DEVELOPMENT_GUIDE.md, README.md
Conditional: .mcp.json (if external integrations detected), .claude/commands/feature-ent.md (if DDD docs detected)

Skill: cc-toolkit-generator-enhanced (9 modules with quality gates).

Phase 4 — Finalize

docker-compose.yml, Dockerfile, .gitignore (scaffold files)
Git commit chore: initial project setup from SPARC documentation
Final summary

🧠 Skills Reference

| Skill | Purpose | |-------|---------| | explore | Socratic task clarification | | sparc-prd-mini | SPARC documentation generator (11 docs) | | goap-research-ed25519 | Verified research with Ed25519 anti-hallucination | | problem-solver-enhanced | First principles + TRIZ (9 modules) | | requirements-validator | INVEST/SMART validation + BDD scenarios | | brutal-honesty-review | Unvarnished technical criticism by severity | | cc-toolkit-generator-enhanced | Modular toolkit generator (9 modules, ~165K chars) + cross-project learning | | reverse-engineering-unicorn | Company reverse engineering + playbook | | pipeline-forge | Meta-skill: build AI pipelines from extracted patterns | | knowledge-extractor | Extract reusable knowledge from projects |

Skill Architecture

Skills use a composable module system with three tiers:

Foundation (explore, problem-solver, goap-research, brutal-honesty-review) — self-contained, no dependencies
Composite (sparc-prd-mini, requirements-validator, knowledge-extractor) — compose foundation skills via view()
Master Orchestrator (cc-toolkit-generator-enhanced) — 9 modular phases with quality gates

The cc-toolkit-generator-enhanced skill is the largest component (~165K chars) split into modules:

| Module | Purpose | |--------|---------| | 01-detect-parse | Document detection → Internal Project Model (IPM) | | 02-analyze-map | Instrument mapping + scoring engine | | 03-generate-p0 | P0 mandatory instruments (CLAUDE.md, /start, etc.) | | 04-generate-p1 | P1 recommended + enterprise lifecycle | | 05-generate-p2p3 | P2 optional + MCP + fitness functions | | 06-package-deliver | Master validation checklist (710 lines) | | 07-harvest-feedback | Post-project learning loop | | 08-skill-composition | Dependency graph + path rewriting | | 09-cross-project-learning | Pattern reuse via maturity model |

`view()` cross-skill loading

Skills use view() for cross-skill loading at runtime:

view() .claude/skills/explore/SKILL.md
view() .claude/skills/explore/references/questioning-techniques.md

Claude Code resolves these references dynamically — when executing a skill, the LLM reads referenced files at the moment of use. This lets skill A delegate to skill B without duplicating content.

Limitation: only Claude Code supports this runtime mechanism. For other platforms (Codex, OpenCode), skill content must be inlined at install time. See MULTIPLATFORM_ROADMAP.md.

⚡ Commands Reference

| Command | Purpose | When to use | |---|---|---| | /replicate | Full pipeline: idea → SPARC docs → toolkit | Start of a new project | | /start | Bootstrap scaffold from SPARC docs | After /replicate, before feature work | | /run | Autonomous feature build loop from roadmap | Regular development | | /go | Router: picks /plan, /feature, or /feature-ent | One specific feature | | /next | Show next feature from roadmap | Sprint navigation | | /plan | Lightweight plan in docs/plans/<id>.md | Small task (≤3 files) | | /feature | Full SPARC-mini cycle (PLAN → VALIDATE → IMPLEMENT → REVIEW) | Large feature (4+ files) | | /myinsights | Capture or recall insights | After every non-trivial debug | | /docs | Bilingual docs generator (RU + EN) | End of project or feature | | /harvest | Extract reusable patterns | After completed project | | /deploy | Deployment workflow (dev/staging/prod) | Deployment |

`/run` — autonomous feature build

/run mvp                                          # only priority=mvp features
/run all                                          # everything in roadmap
/run mvp --feature-branches                       # each feature in its own branch
/run mvp --feature-branches --auto-merge          # also merge into main

One iteration loop:

while features in scope:
    feature_id = /next                       # pick highest-priority
    if no feature: break
    /go feature_id                           # complexity router
    verify (tests green, code committed)
    mark roadmap entry: status=done
    git commit + git push

--feature-branches flag (v1.5.0):

Creates feature/{NNN}-{id} branch per feature (zero-padded 3-digit)
Auto-stashes uncommitted changes with message auto-stash before /run feature-branches
Optional --auto-merge merges branch into main on success
Updates feature-roadmap.json with number + branch fields

`/go` — intelligent router

/go <id> decides between:

/plan — for small tasks (≤3 files, no new architecture)
/feature — for large features (4+ files)
/feature-ent — for cross-bounded-context features with new ADRs (only available if Phase 3 generated feature-ent.md from DDD docs)

`/myinsights` — knowledge capture

Build a project-local knowledge base of "rakes" (development insights) that auto-inject into every session via the SessionStart hook.

/myinsights                                                  # interactive prompt
/myinsights "Prisma migrate dev fails silently if shadow DB unreachable. Workaround: set DATABASE_URL_SHADOW explicitly."
/myinsights recall prisma                                    # search by keyword

Storage: .claude/insights/index.md — markdown log auto-committed by Stop hook.

`/harvest` — knowledge extraction

Extract reusable patterns from a completed project into a knowledge base. Skill: knowledge-extractor (4 modules: agent review → classify → decontextualize → integrate).

💻 CLI Commands

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 (preserves customizations) | 0 ok, 1 if not installed | | remove | Delete package-tracked files | 0 ok, 1 if not installed | | list | List installed components with metadata | 0 | | doctor | Health check of pre-shipped contract + git PATH | 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 |

🎚️ Validation Cycle Details

The same validation pipeline runs in /replicate Phase 2 and /feature Phase 2. Skill: requirements-validator.

Validators (5-agent swarm)

| Agent | Criteria | Scoring | |---|---|---| | validator-stories | INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable | 0–100 per story, average | | validator-acceptance | SMART: Specific, Measurable, Achievable, Relevant, Time-bound | 0–100 per AC, average | | validator-architecture | Consistency vs target constraints (Distributed Monolith / Docker / VPS / MCP) | Pass/fail + score | | validator-pseudocode | Algorithm cohesion + data-flow coherence | 0–100 | | validator-coherence | Cross-document consistency (PRD↔Spec, Spec↔Pseudocode, etc.) | 0–100 |

Verdicts

| Verdict | Threshold | Next | |---|---|---| | 🟢 READY | average ≥ 70, no blockers | Phase 3 (or IMPLEMENT in /feature) | | 🟡 CAVEATS | 50–69, no blockers | Phase 3 with notes (AUTO mode auto-retries once on 🟡) | | 🔴 NEEDS WORK | < 50 OR any blocker | Return to Phase 1 / PLAN, max 3 retries → halt |

After 3 retries with 🔴, the pipeline halts and surfaces to the user. The user can adjust the input or override.

Output

docs/validation-report.md (or docs/features/<id>/validation-report.md for /feature)
docs/test-scenarios.md — BDD scenarios derived from acceptance criteria

Post-implementation review (`brutal-honesty-review`)

After IMPLEMENT phase (Phase 3 of /feature), brutal-honesty-review skill classifies findings by severity:

| Severity | Action | |---|---| | blocker | MUST fix before merge | | high | Fix in this feature unless explicit deferral | | medium | Optional fix; create follow-up issue | | low | Logged, no action required |

Output: docs/features/<id>/review-report.md.

🔄 Feature Lifecycle — `/feature` command

/feature <id> runs a 4-phase lifecycle: PLAN → VALIDATE → IMPLEMENT → REVIEW. Project-context-aware (reads docs/), checkpoint-driven, parallel where independent.

Two entry modes

| Mode | When | Pre-conditions | |---|---|---| | Mode 1: Post-/replicate | Project bootstrapped via /replicate | CLAUDE.md, docs/, scaffold all generated | | Mode 2: Existing project | Working project, adding features with verification | init ran on top of existing project |

The 4-phase pipeline is identical in both modes. Same validation thresholds, same retry logic, same brutal-honesty review.

Phase 1 — PLAN (sparc-prd-mini)

Generates 5 SPARC docs in docs/features/<feature>/:

01_specification.md — requirements + acceptance criteria
02_pseudocode.md — algorithms + data flow
03_architecture.md — component placement + dependencies
04_refinement.md — edge cases + error paths
05_completion.md — testing + deployment notes

Phase 2 — VALIDATE (requirements-validator)

Same swarm-of-5 as /replicate Phase 2. Verdict 🟢/🟡/🔴 with same retry logic.

Phase 3 — IMPLEMENT (parallel agents)

Identify independent work units from Phase 1 Architecture
Spawn parallel Task tool calls, one per unit
Each Task: implement + write tests + commit
Coordinator merges/integrates
Run full test suite

Quality gate: tests pass, lint clean, build succeeds.

Phase 4 — REVIEW (brutal-honesty-review)

Severity-classified findings. Critical (blocker | high) MUST be fixed.

AUTO mode (called from /go or /run)

Phase 1: proceed if all docs exist
Phase 2: proceed if 🟢 or 🟡; auto-retry once on 🔴
Phase 3: proceed if tests + lint + build green
Phase 4: auto-fix high if straightforward; halt on blocker

Final steps

Update .claude/feature-roadmap.json: status in_progress → done
Commit: feat(<feature>): complete lifecycle [phases 1-4]
Push (if --feature-branches mode: also create branch + optional auto-merge)

📊 Statusline Dashboard

6-line ANSI dashboard above Claude Code's prompt with real-time pipeline + roadmap + toolkit + status metrics.

P-Replicator V1.5.x ● 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 |

Defensive design

Every section wrapped in safeRun() with fallback — one parse error doesn't break the whole status bar.

Stale state: state file older than 30 minutes is ignored (Pipeline section shows idle).

Disable statusline: remove the statusLine field from .claude/settings.json. The deletion is preserved on next update thanks to merge logic.

For internals, see admin guide and documentation/07-dashboard-howto.md (in source repo).

🪝 Hooks System

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 into context) | | 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 config) | 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).

State file for live progress

.claude/.p-replicator-state.json — ephemeral state, updated by commands during pipeline execution:

{
  "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:

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.

⚠️ Recommendation: add to .gitignore:

.claude/.p-replicator-state.json
.claude/.last-test.json

🗺️ Roadmap & Insights

Feature roadmap (`.claude/feature-roadmap.json`)

File: generated in /replicate Phase 3 from PRD MVP scope, or by hand for Mode 2.

Schema (post v1.5.0):

{
  "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 → next → in_progress → done (or blocked).

number and branch are populated by --feature-branches flag. Auto-commit via autocommit-roadmap.cjs (Stop hook).

Insights system

Storage: .claude/insights/index.md (markdown log).

Entry format:

## 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: SessionStart hook (session-insights.cjs) reads top 3 recent entries to stdout, Claude Code injects into initial session context.

🏛️ Architecture Highlights

Two-tier model: Pre-shipped vs Project-generated

| Tier | Created by | Lives in | Updated | |---|---|---|---| | Pre-shipped | npx p-replicator init | .claude/{skills,commands,agents,rules,hooks}/ + settings.json | On each package upgrade | | Project-generated | /replicate Phase 3 (LLM execution) | CLAUDE.md, .claude/agents/planner.md, docs/, etc. | Only on regeneration |

💡 Key insight: This is the main fix of v1.4.0 — previously /replicate Phase 3 tried to generate ALL artifacts (including generic commands like /run, /feature), which led to flaky outputs (LLM compression, missed templates). Post-v1.4.0, generic commands are pre-shipped, Phase 3 generates ONLY project-specific artifacts.

SSOT: `utils.COMPONENTS`

Single source of truth for what's shipped and what's generated, in src/utils.js. Any future edit to items automatically updates 5 surfaces (init, update, doctor, verify, list, cli help) — eliminating drift issues that existed pre-v1.3.1.

Settings.json merge logic (v1.4.2 + v1.4.3)

init --force and update use mergeSettingsJson(existing, template) to preserve user customizations:

User-added hook (absent from template) → preserved
User-modified default (changed command) → treated as user-added → preserved
Identical command in template and user → de-duped
New hook in template → added to user's settings
Removed default (was in old template, gone from new) → orphan-detected and removed

Identity model: hooks compared by command string. Override: --reset-settings flag disables merge — full overwrite.

Manifest schema (`.p-replicator.json`)

{
  "version": "1.5.x",
  "installedAt": "2026-05-07T12:00:00.000Z",
  "components": ["agents", "commands", "hooks", "rules", "settings", "skills"],
  "files": ["...sorted list of all installed files..."],
  "shippedDefaults": {
    "settings.json": { "hooks": {...}, "statusLine": {...} }
  }
}

shippedDefaults is the baseline for orphan detection on upgrade (v1.4.3+). Backward-compatible: pre-v1.4.3 manifests load without error, orphan detection skipped on first upgrade.

For complete internals, see README/eng/05_architecture.md — covers cross-platform hooks, sync-templates merge mode, settings merge algorithm, statusline architecture.

⚙️ Configuration

`.claude/settings.json`

Default structure after init:

{
  "$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 — preserved on init --force or update thanks to merge logic.

Disable individual default hooks: delete from settings.json after init. The deletion is preserved on next update (orphan detection only removes hooks previously shipped but absent in new template — your manual deletion is a user customization).

MCP servers (`.mcp.json`)

Project-local MCP server config:

{
  "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. /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

🔄 Update workflow

# 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 (loses custom hooks):
npx @dzhechkov/p-replicator@latest init --force --reset-settings

What the merge logic does

Reads manifest.shippedDefaults['settings.json'] (what we shipped previously)
Reads current templates/.claude/settings.json (new template)
Reads .claude/settings.json (user's current)
Orphan detection: removes hooks present in old template but missing in new
Merge: adds hooks from new template that aren't already in user's current
User-added hooks (never in old template) are preserved

After upgrade, run verify to confirm:

npx @dzhechkov/p-replicator verify

🆘 Troubleshooting

💡 Tip: This section covers the 12 most common issues. For a comprehensive 15+ case troubleshooting reference with detailed diagnostics, see README/eng/06_troubleshooting.md.

`init` refuses: "P-Replicator is already installed"

npx @dzhechkov/p-replicator update                            # safe upgrade
npx @dzhechkov/p-replicator init --force                      # forced re-install
npx @dzhechkov/p-replicator init --force --reset-settings     # full reset

Missing files after `init`

npx @dzhechkov/p-replicator doctor       # see what's missing
npx @dzhechkov/p-replicator init --force # repair

Install went to `~/node_modules` instead of project

Cause: no package.json in your project, npm walks up and finds one in home directory.

npm init -y
npx @dzhechkov/p-replicator init

Statusline doesn't appear

Checks:

Claude Code version supports statusLine config? Update Claude Code.
statusLine field present in .claude/settings.json?
Script runs directly:

node .claude/hooks/statusline.cjs

Should print 6 lines of ANSI output. If it errors:

node .claude/hooks/statusline.cjs 2>&1

Likely cause: corrupt JSON or missing .p-replicator.json.

Hooks aren't auto-committing

npx @dzhechkov/p-replicator doctor

Look for ✓ git on PATH in Prerequisites section. Also verify .git exists:

git rev-parse --git-dir

Debug a specific hook:

node .claude/hooks/autocommit-roadmap.cjs
echo "Exit: $?"
git log -1 --format="%s"

Statusline shows "Settings ⚠️ merged" but I didn't change anything

Cause: some process modified settings.json (formatting, whitespace, ordering). Statusline compares via deep-equals on sorted keys.

npx @dzhechkov/p-replicator init --force --reset-settings

Settings.json lost my custom hooks after update

This was a bug pre-v1.4.2. In v1.4.2+, update and init --force use mergeSettingsJson which preserves user customizations.

If you're on v1.4.1 or earlier:

npx @dzhechkov/p-replicator@latest update

Restore lost hooks from git history:

git log -p --follow -- .claude/settings.json

`/run --feature-branches` immediately fails "not on main"

Cause: you're on a feature branch. Switch to main:

git checkout main
/run mvp --feature-branches

`--feature-branches` lost my unsaved changes

They're stashed:

git stash list
git stash show stash@{0}
git stash pop

p-replicator auto-stashes with message auto-stash before /run feature-branches.

`/replicate` didn't generate expected commands (`/run`, `/feature`, ...)

This is solved in v1.4.0+. All 11 generic commands are now pre-shipped via init. If you're on an old version:

npx @dzhechkov/p-replicator@latest init --force
npx @dzhechkov/p-replicator verify

Insights aren't auto-injected into new sessions

Checks:

.claude/insights/index.md exists with entries?

Hook works:

node .claude/hooks/session-insights.cjs    # should print recent insights

SessionStart hook configured in settings.json?

If all 3 OK but still nothing — Claude Code may cache. Restart claude.

Statusline lags on every command

time node .claude/hooks/statusline.cjs    # how many seconds?

Should be < 100ms. If > 1s, check docs/ size:

du -sh docs/
find docs/ -type f -name "*.md" | wc -l

Workaround: temporarily disable statusline by removing the statusLine field in .claude/settings.json. See KNOWN_LIMITATIONS.md item L6 for future enhancement (STATUSLINE_PROFILE=1 env var).

For full troubleshooting (15+ issues with detailed diagnostics), see README/eng/06_troubleshooting.md.

📈 Migration

| From → To | What you get | Migration cost | |---|---|---| | 1.3.x → 1.5.x | All pre-shipped commands + statusline + feature-branches + merge logic + Mode 2 | init --force (preserves customizations) | | 1.4.0 → 1.4.1 | Cross-platform hooks + sync merge mode | init --force | | 1.4.1 → 1.4.2 | Settings merge (preserve customizations) | init --force is safe (preserves) | | 1.4.2 → 1.4.3 | Orphan detection | First upgrade lacks baseline — re-run init --force to populate | | 1.4.3 → 1.5.0 | Statusline + --feature-branches | update or init --force | | 1.5.0 → 1.5.1 | "Existing tech docs" workflow formalized | docs only — no migration | | 1.5.1 → 1.5.2 | Mode 2 (existing project + /feature) formalized | docs only — no migration |

✅ No breaking changes between any versions. All upgrades are backward-compatible.

After any upgrade — verify to confirm contract:

npx @dzhechkov/p-replicator verify

🧪 Test Infrastructure

Suite: 105 tests, 36 suites, ~25 sec runtime.

| Layer | File | Coverage | |---|---|---| | Unit | tests/unit/utils.test.js (54 tests) | Pure functions: createManifest, mergeSettingsJson, removeOrphanHooks, getItemRelativePath, parseToolkit logic | | E2E | tests/e2e/lifecycle.test.js (48 tests) | Full CLI lifecycle, hooks installation, settings merge edge cases, statusline output, --feature-branches docs | | Snapshot | tests/snapshot/templates.test.js (3 tests) | SHA-256 baseline of all 115 files in templates/ |

Meta-tests verify consistency between documents:

replicate-pipeline.md mentions every pre-shipped command (no orphan in rule)
replicate.md Phase 3 doesn't claim "Generate <pre-shipped>.md" (no spec drift)

Snapshot baseline regenerated via npm run snapshot:baseline after intentional template changes.

npm test                                    # full suite
npm run test:unit                           # unit only
npm run test:e2e                            # e2e only
npm run test:snapshot                       # snapshot only

⚠️ Known Limitations

For currently-open improvement items — see KNOWN_LIMITATIONS.md (8 entries: 3 medium, 5 low priority).

Highlights:

M1 — --feature-branches behavior tested only via documentation-presence (not e2e git workflow)
M2 — No formal --from-docs CLI flag (workflow works via natural-language only)
M3 — /feature requires standard SPARC doc paths (no --prd-path flag)
L5 — .p-replicator-state.json not auto-gitignored
L6 — Statusline could profile per-section if slow

For multiplatform support roadmap (Codex, OpenCode, KiloCode) — see MULTIPLATFORM_ROADMAP.md.

📜 Changelog Highlights

📌 For full version history with migration notes — see CHANGELOG.md (authoritative source).

v1.5.3 — 2026-05-07 (Comprehensive README + visual polish)

📚 Expanded README.md from ~14.6 kB to ~50 kB (consolidating 8 eng/ files for npm registry visibility)
🎨 Visual polish: hero banner, 8 badges, emoji TOC, collapsible sections, callout blocks, <kbd> for CLI commands

v1.5.2 — 2026-05-07 (Mode 2 documentation)

Formalized "Feature workflow in existing project (Mode 2)" across all documentation surfaces. Pure docs/spec patch — no code changes.

v1.5.1 — 2026-05-07 (Existing-docs workflow)

Formalized "Starting from existing technical documentation" workflow for /replicate. New build.js link-rewriter for HTML guide.

v1.5.0 — 2026-05-07 (Statusline + feature-branches)

✨ Statusline dashboard (RuFlo-style 6-line bar) via templates/.claude/hooks/statusline.cjs
✨ --feature-branches flag for /run and /go (each feature on its own branch feature/{NNN}-{id})
🆕 state-update.cjs — argv-driven helper
🆕 --auto-merge companion flag

v1.4.3 — 2026-05-07 (Orphan hook detection)

🐛 mergeSettingsJson now cleans hooks shipped previously but removed in newer template
🆕 manifest.shippedDefaults['settings.json'] baseline
🐛 update.js now also uses merge logic

v1.4.2 — 2026-05-06 (Merge + meta-tests)

🐛 init --force MERGES settings.json (preserves user customizations)
🆕 --reset-settings flag for explicit nuclear-overwrite
🐛 Stronger meta-test for replicate.md drift (multi-axis)
🆕 doctor checks git on PATH

v1.4.1 — 2026-05-06 (Cross-platform + critical fix)

🐛 Cross-platform hooks: replaced bash chains with 4 Node scripts
🐛 verify.js SSOT: kind: 'pre-shipped' | 'project-generated' field
🐛 Meta-tests for replicate.md ↔ replicate-pipeline.md consistency
🐛 Critical regression fixed: sync-templates.js cleanDir silently deleted pre-shipped files

v1.4.0 — 2026-05-06 (Major: 9 pre-shipped commands)

✨ 9 new pre-shipped commands: /start, /plan, /feature, /go, /run, /next, /myinsights, /docs, /deploy
✨ 3 new pre-shipped rules: git-workflow, insights-capture, feature-lifecycle
✨ Settings.json shipped with hooks
✨ verify command — replaces user's manual verification prompt
🐛 5 sources of truth divergence unified via utils.COMPONENTS.items

v1.3.1 — 2026-05-06 (SSOT bugfix)

🐛 cli.js --help showed "1 rule" while EXPECTED_RULES had 2 entries → SSOT fix
🐛 update.js corrupted manifest → getRelativePaths(templateClaude) fix
🐛 update now removes orphan template files

v1.3.0 (baseline)

Initial published version. 10 skills, 2 commands (/replicate, /harvest), 4 agents, 2 rules.

🤝 Contributing

This package is part of the pu-unicorn-replicate monorepo.

Development setup

git clone https://github.com/dzhechko/pu-unicorn-replicate.git
cd pu-unicorn-replicate/packages/p-replicator
npm install
npm test

Pre-publish checklist

npm run snapshot:baseline    # regenerate baseline if templates/ changed
npm test                     # all 105 tests must pass
npm pack --dry-run           # verify tarball contents
npm publish                  # prepublishOnly hook syncs source → templates/

Filing issues

https://github.com/dzhechko/pu-unicorn-replicate/issues

Include:

npx @dzhechkov/p-replicator --version output
npx @dzhechkov/p-replicator verify output
Repro steps + expected vs actual

Patterns persisted in AQE memory

Each significant improvement is persisted as a cross-session pattern (16+ entries from v1.3.1 → v1.5.2). Categories:

cli-package-ssot-component-lists, cli-package-manifest-preservation (v1.3.1)
cli-package-pre-ship-vs-generate-boundary, cli-package-verify-replaces-manual-prompts (v1.4.0)
cli-package-cross-platform-hooks-via-node-scripts, cli-package-kind-discrimination-for-ssot (v1.4.1)
cli-package-settings-json-merge-vs-overwrite, meta-test-multi-axis-drift-detection (v1.4.2)
cli-shipped-defaults-baseline-for-orphan-detection, cli-update-must-mirror-init-merge-logic (v1.4.3)
cli-statusline-multi-line-dashboard, cli-feature-branches-flag-for-teaching-workflows (v1.5.0)
doc-rollout-pattern (v1.5.1, v1.5.2 — 14-surface symmetric rollout)

📃 License

MIT — see LICENSE.

Links

npm: https://www.npmjs.com/package/@dzhechkov/p-replicator
GitHub: https://github.com/dzhechko/pu-unicorn-replicate
Issues: https://github.com/dzhechko/pu-unicorn-replicate/issues
Telegram: https://t.me/llm_notes
Author: dzhechko

Companion documentation

CHANGELOG.md — version history (authoritative)
KNOWN_LIMITATIONS.md — 8 open improvement items
MULTIPLATFORM_ROADMAP.md — Codex/OpenCode/KiloCode support roadmap
README/ru/ — Russian documentation (8 sections)
README/eng/ — English documentation (8 sections, deeper than this README)
README/ru/html/index.html — interactive single-page HTML guide

🚀 Ready to start?

npx @dzhechkov/p-replicator init && claude

Then in Claude Code: /replicate "your idea" (new project) or /feature add-something (existing project).