@dzhechkov/p-replicator 1.5.2 β†’ 1.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +1147 -193
  2. package/package.json +1 -1
  3. package/templates/.claude/settings.json +1 -1
package/README.md CHANGED
@@ -1,37 +1,153 @@
1
- # @dzhechkov/p-replicator
1
+ <div align="center">
2
2
 
3
- **P-Replicator** β€” Claude Code toolkit for AI-assisted product development (Vibe Coding).
3
+ # πŸš€ @dzhechkov/p-replicator
4
4
 
5
- Transform a product idea into a fully documented, validated, toolkit-equipped project ready for development.
5
+ ### **Claude Code toolkit for AI-assisted product development**
6
+ ##### *Transform a product idea β€” or existing project β€” into fully documented, validated, toolkit-equipped code*
6
7
 
7
- ## Documentation
8
+ <br>
8
9
 
9
- - πŸ‡·πŸ‡Ί [ДокумСнтация Π½Π° русском](./README/ru/README.md)
10
- - πŸ‡¬πŸ‡§ [English documentation](./README/eng/README.md)
10
+ [![npm version](https://img.shields.io/npm/v/@dzhechkov/p-replicator?color=cb3837&label=npm&style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@dzhechkov/p-replicator)
11
+ [![License](https://img.shields.io/badge/License-MIT-22c55e.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
12
+ [![Node](https://img.shields.io/badge/node-%E2%89%A516-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
11
13
 
12
- Each language pack includes 7 sections: Quick start, User guide, Admin guide,
13
- API reference, Architecture, Troubleshooting, Changelog.
14
+ [![Tests](https://img.shields.io/badge/tests-105%2F105-22c55e?style=flat-square)](#test-infrastructure)
15
+ [![Skills](https://img.shields.io/badge/skills-10-8b5cf6?style=flat-square)](#skills-reference)
16
+ [![Commands](https://img.shields.io/badge/slash%20commands-11-f59e0b?style=flat-square)](#commands-reference)
17
+ [![Hooks](https://img.shields.io/badge/hooks-6-3b82f6?style=flat-square)](#hooks-system)
18
+ [![SPARC Pipeline](https://img.shields.io/badge/SPARC-5%20phases-ec4899?style=flat-square)](#pipeline-overview--replicate-phases)
14
19
 
15
- ## Quick Start
20
+ <br>
21
+
22
+ **[πŸ“¦ 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)**
23
+
24
+ </div>
25
+
26
+ ---
27
+
28
+ ## πŸ“š Documentation in your language
29
+
30
+ | Language | Format | Description |
31
+ |---|---|---|
32
+ | πŸ‡·πŸ‡Ί Русский | [Markdown (8 sections)](./README/ru/README.md) | ~3000 строк deep-dive Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Π°Ρ†ΠΈΠΈ |
33
+ | πŸ‡¬πŸ‡§ English | [Markdown (8 sections)](./README/eng/README.md) | ~3000 lines deep-dive documentation |
34
+ | 🌐 Interactive | [HTML guide (RU)](./README/ru/html/index.html) | Single-page with search, theming, syntax highlighting |
35
+
36
+ > πŸ“Œ **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.
37
+
38
+ ---
39
+
40
+ ## πŸ“‘ Table of Contents
41
+
42
+ <table>
43
+ <tr>
44
+ <td width="50%" valign="top">
45
+
46
+ **🌟 Getting Started**
47
+ - [πŸ“– What is p-replicator?](#-what-is-p-replicator)
48
+ - [πŸš€ Quick Start](#-quick-start)
49
+ - [πŸ“‘ Already have technical docs?](#-already-have-technical-documentation)
50
+ - [πŸ”§ Adding features (Mode 2)](#-adding-features-to-an-existing-project-mode-2)
51
+ - [πŸ“¦ Installation](#-installation)
52
+ - [πŸ“‹ What Gets Installed](#-what-gets-installed)
53
+ - [βœ… Verify the install](#-verify-the-install)
54
+
55
+ **πŸ› οΈ Reference**
56
+ - [🎯 Pipeline overview](#-pipeline-overview--replicate-phases)
57
+ - [🧠 Skills Reference](#-skills-reference)
58
+ - [⚑ Commands Reference](#-commands-reference)
59
+ - [πŸ’» CLI Commands](#-cli-commands)
60
+ - [🎚️ Validation Cycle](#-validation-cycle-details)
61
+ - [πŸ”„ Feature Lifecycle](#-feature-lifecycle--feature-command)
62
+
63
+ </td>
64
+ <td width="50%" valign="top">
65
+
66
+ **βš™οΈ Operations**
67
+ - [πŸ“Š Statusline Dashboard](#-statusline-dashboard)
68
+ - [πŸͺ Hooks System](#-hooks-system)
69
+ - [πŸ—ΊοΈ Roadmap & Insights](#%EF%B8%8F-roadmap--insights)
70
+ - [πŸ›οΈ Architecture Highlights](#%EF%B8%8F-architecture-highlights)
71
+ - [βš™οΈ Configuration](#%EF%B8%8F-configuration)
72
+ - [πŸ”„ Update workflow](#-update-workflow)
73
+
74
+ **πŸ†˜ Help & Meta**
75
+ - [πŸ†˜ Troubleshooting](#-troubleshooting)
76
+ - [πŸ“ˆ Migration](#-migration)
77
+ - [πŸ§ͺ Test Infrastructure](#-test-infrastructure)
78
+ - [⚠️ Known Limitations](#%EF%B8%8F-known-limitations)
79
+ - [πŸ“œ Changelog Highlights](#-changelog-highlights)
80
+ - [🀝 Contributing](#-contributing)
81
+ - [πŸ“ƒ License](#-license)
82
+
83
+ </td>
84
+ </tr>
85
+ </table>
86
+
87
+ > πŸ’‘ **Quick navigation tip:** TOC items use emoji visual anchors instead of plain text β€” easier to scan than 26 dark-blue links.
88
+
89
+ <div align="center">━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</div>
90
+
91
+ ## πŸ“– What is p-replicator?
92
+
93
+ `@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.
94
+
95
+ The flagship `/replicate` command takes a project through a **5-phase pipeline**:
96
+
97
+ ```
98
+ Phase 0 (optional) Product Discovery reverse-engineering of similar companies
99
+ Phase 1 Planning 11 SPARC documents (PRD, Architecture, Pseudocode, ...)
100
+ Phase 2 Validation 5-agent swarm validates against INVEST + SMART
101
+ Phase 3 Toolkit Generation project-specific agents, rules, skills
102
+ Phase 4 Finalize docker-compose.yml, Dockerfile, .gitignore + git commit
103
+ ```
104
+
105
+ 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`).
106
+
107
+ **Two main use cases:**
108
+
109
+ | Use case | Entry command | Time | Result |
110
+ |---|---|---|---|
111
+ | **Bootstrap a new project** from idea or company name | `/replicate` | 45–90 min | Fully-documented project + scaffold + Docker |
112
+ | **Add features** to an existing project | `/feature` (Mode 2) | 10–30 min per feature | Validated SPARC docs + implementation + review |
113
+
114
+ **Target architecture for generated projects:**
115
+ - **Pattern:** Distributed Monolith (Monorepo)
116
+ - **Containers:** Docker + Docker Compose
117
+ - **Infrastructure:** VPS (e.g., AdminVPS, HOSTKEY)
118
+ - **Deploy:** Docker Compose direct deploy
119
+ - **AI Integration:** MCP servers
120
+
121
+ ---
122
+
123
+ ## πŸš€ Quick Start
16
124
 
17
125
  ```bash
18
- # Install into any project
126
+ # 1. Install in any project
127
+ cd your-project
19
128
  npx @dzhechkov/p-replicator init
20
129
 
21
- # Open Claude Code
130
+ # 2. Open Claude Code
22
131
  claude
23
132
 
24
- # Run the pipeline
133
+ # 3. Run the pipeline
25
134
  /replicate "Online marketplace for handmade crafts with AI-powered recommendations"
26
135
  ```
27
136
 
28
- 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.
137
+ The system walks you through 4–5 phases with interactive checkpoints. At each checkpoint you review the output and confirm before proceeding.
138
+
139
+ **Estimated time:** 45–90 minutes for the full pipeline (Phase 0 optional).
29
140
 
30
- ### Already have technical documentation?
141
+ After `/replicate` completes:
142
+ - `/start` β€” bootstrap the scaffold from `Architecture.md`
143
+ - `/run mvp` β€” autonomous feature build from roadmap
144
+ - `/feature <id>` β€” single-feature lifecycle
31
145
 
32
- If you already have tech specs, architecture notes, or API docs for the project,
33
- you can skip Phase 0 (Product Discovery) and feed your existing docs into Phase 1
34
- as input:
146
+ ---
147
+
148
+ ## πŸ“‘ Already have technical documentation?
149
+
150
+ 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:
35
151
 
36
152
  ```bash
37
153
  mkdir -p docs/existing
@@ -41,19 +157,26 @@ claude
41
157
  /replicate "Use my existing docs in docs/existing/, skip Phase 0"
42
158
  ```
43
159
 
44
- Three sub-paths are supported:
45
- - **A. Full pipeline** β€” `/replicate` reads your docs, generates the 11 SPARC docs + validation + toolkit + scaffold
46
- - **B. SPARC docs only** β€” invoke the `sparc-prd-mini` skill directly, no toolkit/scaffold
47
- - **C. Validation-only** β€” rename existing docs to SPARC slot names + invoke the `requirements-validator` skill
160
+ **Three sub-paths:**
161
+
162
+ | Path | When | Result |
163
+ |---|---|---|
164
+ | **A. Full pipeline** | Have tech docs, want full pipeline + toolkit + scaffold | All 11 SPARC docs + validation + toolkit + scaffold |
165
+ | **B. SPARC docs only** | Want only the 11 SPARC docs | Invoke `sparc-prd-mini` skill in AUTO mode |
166
+ | **C. Validation-only** | Existing docs already SPARC-shaped | Rename to `PRD.md`, `Architecture.md`, ... + invoke `requirements-validator` |
167
+
168
+ **Modified flow when triggered:**
169
+ - **Phase 0** β€” SKIPPED entirely
170
+ - **Phase 1** β€” `sparc-prd-mini` runs in **AUTO mode**, reads your docs, generates the 11 SPARC slots; missing parts marked `[GAP: ...]`
171
+ - **Phase 2-4** β€” unchanged
172
+
173
+ Full recipe: see [User Guide](./README/eng/02_user_guide.md#starting-from-existing-tech-docs) ([RU](./README/ru/02_user_guide.md#Π°Π»ΡŒΡ‚Π΅Ρ€Π½Π°Ρ‚ΠΈΠ²Π½Ρ‹ΠΉ-Π²Ρ…ΠΎΠ΄-Ρƒ-вас-ΡƒΠΆΠ΅-Π΅ΡΡ‚ΡŒ-тСхдокумСнтация)).
48
174
 
49
- Full recipe with caveats: see [User Guide](./README/eng/02_user_guide.md#starting-from-existing-tech-docs)
50
- ([RU](./README/ru/02_user_guide.md#Π°Π»ΡŒΡ‚Π΅Ρ€Π½Π°Ρ‚ΠΈΠ²Π½Ρ‹ΠΉ-Π²Ρ…ΠΎΠ΄-Ρƒ-вас-ΡƒΠΆΠ΅-Π΅ΡΡ‚ΡŒ-тСхдокумСнтация)).
175
+ ---
51
176
 
52
- ### Adding features to an existing project?
177
+ ## πŸ”§ Adding features to an existing project (Mode 2)
53
178
 
54
- If you already have a working project (stack, PRD, CLAUDE.md, Specification
55
- defined) and want to **add new features** with the same SPARC-mini validation
56
- cycle that `/replicate` provides β€” use `/feature` (Mode 2):
179
+ 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):
57
180
 
58
181
  ```bash
59
182
  cd existing-project
@@ -62,30 +185,212 @@ claude
62
185
  /feature add-stripe-payments # 4-phase: PLAN β†’ VALIDATE β†’ IMPLEMENT β†’ REVIEW
63
186
  ```
64
187
 
65
- `/feature` runs the same validation pipeline as `/replicate` Phase 2, scoped
66
- to a single feature. Same verdicts: 🟒 READY (β‰₯70) / 🟑 CAVEATS (50-69) /
67
- πŸ”΄ NEEDS WORK (<50). Same retry logic. Same `brutal-honesty-review` post-implementation.
188
+ `/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.
68
189
 
69
- Three sub-paths:
70
- - **A. /feature directly** β€” single feature, full 4-phase lifecycle
71
- - **B. /go auto-router** β€” picks /plan vs /feature based on complexity
72
- - **C. Direct skill invocation** β€” only the validation cycle, no full lifecycle
190
+ **Two officially supported entry modes for `/feature`:**
73
191
 
74
- Full recipe: see [User Guide](./README/eng/02_user_guide.md#feature-workflow-in-an-existing-project-mode-2)
75
- ([RU](./README/ru/02_user_guide.md#feature-workflow-Π²-ΡΡƒΡ‰Π΅ΡΡ‚Π²ΡƒΡŽΡ‰Π΅ΠΌ-ΠΏΡ€ΠΎΠ΅ΠΊΡ‚Π΅-mode-2)).
192
+ | Mode | When | Pre-conditions |
193
+ |---|---|---|
194
+ | **Mode 1: Post-/replicate** | Project bootstrapped via `/replicate` | CLAUDE.md, docs/, scaffold all generated by /replicate |
195
+ | **Mode 2: Existing project** | Working project, adding features with verification | `init` ran on top of existing project; CLAUDE.md already exists |
76
196
 
77
- ## What Gets Installed
197
+ **Three sub-paths for Mode 2:**
198
+
199
+ | Path | When | Skills invoked |
200
+ |---|---|---|
201
+ | **A. /feature directly** | Single feature β‰₯4 files, new capability | sparc-prd-mini β†’ requirements-validator β†’ parallel implement β†’ brutal-honesty-review |
202
+ | **B. /go auto-router** | Mixed complexity | Routes between /plan (≀3 files) and /feature (β‰₯4 files) |
203
+ | **C. Direct skill invocation** | Only validation cycle | requirements-validator + brutal-honesty-review skills directly |
204
+
205
+ **Mode 2 setup (one-time):**
206
+
207
+ ```bash
208
+ # 1. Install (idempotent β€” does NOT touch CLAUDE.md or existing .claude/ files)
209
+ npx @dzhechkov/p-replicator init
210
+ npx @dzhechkov/p-replicator verify
211
+
212
+ # 2. Normalize SPARC paths (one-time)
213
+ mv docs/your-prd.md docs/PRD.md
214
+ mv docs/your-spec.md docs/Specification.md
215
+ mv docs/your-arch.md docs/Architecture.md
216
+
217
+ # 3. (Optional) feature-roadmap for batch mode via /run
218
+ cat > .claude/feature-roadmap.json << 'EOF'
219
+ {"features": [{"id": "stripe-payments", "title": "Stripe", "priority": "mvp", "status": "planned"}]}
220
+ EOF
221
+ ```
222
+
223
+ > ⚠️ **Mode 2 caveats:**
224
+ > - DO NOT run `/start` β€” it expects a fresh scaffold
225
+ > - `/feature-ent` unavailable in Mode 2 without DDD/ADR/C4 docs
226
+ > - Auto-commit hooks may conflict with custom git workflows β€” edit `settings.json` after `init`
227
+ > - No `--prd-path` flag for non-standard paths β€” one-time rename/symlink required (see [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md) M3)
228
+
229
+ Full recipe: see [User Guide](./README/eng/02_user_guide.md#feature-workflow-in-an-existing-project-mode-2) ([RU](./README/ru/02_user_guide.md#feature-workflow-Π²-ΡΡƒΡ‰Π΅ΡΡ‚Π²ΡƒΡŽΡ‰Π΅ΠΌ-ΠΏΡ€ΠΎΠ΅ΠΊΡ‚Π΅-mode-2)).
230
+
231
+ ---
232
+
233
+ ## πŸ“¦ Installation
234
+
235
+ ### Prerequisites
236
+
237
+ - **Node.js** β‰₯ 16.0.0
238
+ - **Claude Code** installed (CLI or web)
239
+ - **Git** initialized in the project (`git init` if not already)
240
+ - **Docker + Docker Compose** (needed for `/start` Phase 3, optional for `/feature`)
241
+
242
+ ### Install command
243
+
244
+ ```bash
245
+ cd your-project
246
+ npx @dzhechkov/p-replicator init
247
+ ```
248
+
249
+ This creates:
250
+
251
+ - `.claude/skills/` β€” 10 pre-shipped skills
252
+ - `.claude/commands/` β€” 11 slash commands (`/replicate`, `/run`, `/feature`, ...)
253
+ - `.claude/agents/` β€” 4 pipeline agents
254
+ - `.claude/rules/` β€” 5 governance rules
255
+ - `.claude/hooks/` β€” 6 cross-platform Node scripts
256
+ - `.claude/settings.json` β€” hooks + statusline configuration
257
+ - `.p-replicator.json` β€” install manifest
258
+
259
+ > πŸ“Œ **Idempotency:** `init` will NOT overwrite existing files without `--force`. Your `CLAUDE.md`, custom commands, and modified settings are preserved.
260
+
261
+ ### Common install scenarios
262
+
263
+ | Scenario | Command |
264
+ |---|---|
265
+ | Fresh project | `npx @dzhechkov/p-replicator init` |
266
+ | Existing project (preserve all custom files) | `npx @dzhechkov/p-replicator init` (idempotent β€” same as fresh) |
267
+ | Upgrade (preserve user customizations) | `npx @dzhechkov/p-replicator@latest update` |
268
+ | Repair broken install | `npx @dzhechkov/p-replicator init --force` |
269
+ | Full reset (loses custom hooks) | `npx @dzhechkov/p-replicator init --force --reset-settings` |
270
+ | Preview without writing | `npx @dzhechkov/p-replicator init --dry-run` |
271
+
272
+ ---
273
+
274
+ ## πŸ“‹ What Gets Installed
78
275
 
79
276
  | Component | Count | Description |
80
277
  |-----------|-------|-------------|
81
278
  | **Skills** | 10 | 90+ files (~200K chars). Modular architecture: foundation β†’ composite β†’ master orchestrator |
82
- | **Commands** | 2 | `/replicate` (full pipeline), `/harvest` (knowledge extraction) |
83
- | **Agents** | 4 | replicate-coordinator, product-discoverer, doc-validator, harvest-coordinator |
84
- | **Rules** | 2 | replicate-pipeline (phase constraints), skill-interface-protocol (composition standard) |
279
+ | **Commands** | 11 | `/replicate`, `/harvest`, `/start`, `/plan`, `/feature`, `/go`, `/run`, `/next`, `/myinsights`, `/docs`, `/deploy` |
280
+ | **Agents** | 4 | `replicate-coordinator`, `product-discoverer`, `doc-validator`, `harvest-coordinator` |
281
+ | **Rules** | 5 | `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle` |
282
+ | **Hooks** | 6 | `session-insights`, `autocommit-{roadmap,insights,plans}`, `statusline`, `state-update` (cross-platform Node) |
283
+ | **Settings** | 1 | `settings.json` with statusLine + SessionStart + Stop hooks pre-configured |
284
+
285
+ After running `/replicate`, the toolkit also generates **project-specific** artifacts:
286
+
287
+ - `.claude/agents/planner.md`, `code-reviewer.md`, `architect.md` (project-aware)
288
+ - `.claude/rules/security.md`, `coding-style.md`, `testing.md`, optionally `secrets-management.md`
289
+ - `.claude/skills/project-context/`, `coding-standards/`, optionally `security-patterns/`
290
+ - `.claude/feature-roadmap.json` (from PRD MVP scope)
291
+ - `CLAUDE.md` enhanced with project-specific content
292
+ - `DEVELOPMENT_GUIDE.md`, project `README.md`
293
+ - `docker-compose.yml`, `Dockerfile`, `.gitignore` (Phase 4 scaffolds)
294
+ - `docs/*` β€” all SPARC documentation (11 files)
295
+
296
+ ---
297
+
298
+ ## βœ… Verify the install
299
+
300
+ After `/replicate`, run:
301
+
302
+ ```bash
303
+ npx @dzhechkov/p-replicator verify
304
+ ```
305
+
306
+ The command checks:
307
+
308
+ - **Pre-shipped contract** (must-have): 10 skills + 11 commands + 4 agents + 5 rules + settings.json + 6 hooks
309
+ - **Post-/replicate hints** (advisory): CLAUDE.md, project-specific agents, feature-roadmap.json, security rules, etc.
310
+
311
+ **Exit codes:**
312
+ - `0` β€” pre-shipped contract intact (warnings about project-specific are normal pre-/replicate)
313
+ - `1` β€” pre-shipped contract violated β†’ run `init --force` to repair
314
+
315
+ **Alternative β€” health check:**
316
+
317
+ ```bash
318
+ npx @dzhechkov/p-replicator doctor
319
+ ```
320
+
321
+ `doctor` verifies pre-shipped contract + Prerequisites (`git on PATH`). Stricter than `verify` for must-have components.
322
+
323
+ ---
324
+
325
+ ## 🎯 Pipeline overview β€” `/replicate` phases
85
326
 
86
- After running `/replicate`, the toolkit generates additional commands, agents, rules, and skills specific to your project (see [Post-Pipeline Commands](#post-pipeline-commands)).
327
+ ### Phase 0 β€” Product Discovery (optional)
87
328
 
88
- ## Skills Reference
329
+ **Activated for:** new SaaS, startups, products to research. **Skipped for:** internal tools, experiments, projects with existing tech docs.
330
+
331
+ - Skill: `reverse-engineering-unicorn` (JTBD analysis + competitors + Blue Ocean canvas)
332
+ - Output: `docs/00_product_discovery.md`
333
+
334
+ ### Phase 1 β€” Planning (SPARC docs)
335
+
336
+ Generates 11 standardized documents in `docs/`:
337
+
338
+ | Document | Content |
339
+ |---|---|
340
+ | `PRD.md` | Vision, personas, user stories |
341
+ | `Solution_Strategy.md` | Solution approach |
342
+ | `Specification.md` | Acceptance criteria, NFRs |
343
+ | `Pseudocode.md` | Algorithms, data flow |
344
+ | `Architecture.md` | C4 diagrams, tech stack |
345
+ | `Refinement.md` | Edge cases, testing strategy |
346
+ | `Completion.md` | Deploy, CI/CD, monitoring |
347
+ | `Research_Findings.md` | Market and tech research |
348
+ | `Final_Summary.md` | Executive summary |
349
+ | `C4_Diagrams.md` | Context / container / component |
350
+ | `ADR.md` | Architecture Decision Records |
351
+
352
+ Skill: `sparc-prd-mini` (internally chains explore + research + solve sub-phases).
353
+
354
+ ### Phase 2 β€” Validation (5-agent swarm)
355
+
356
+ | Agent | Validates |
357
+ |---|---|
358
+ | `validator-stories` | INVEST criteria for user stories |
359
+ | `validator-acceptance` | SMART criteria for acceptance criteria |
360
+ | `validator-architecture` | Architecture consistency vs target constraints |
361
+ | `validator-pseudocode` | Algorithm cohesion |
362
+ | `validator-coherence` | Cross-document consistency |
363
+
364
+ **Verdicts:**
365
+ - 🟒 **READY** (score β‰₯70) β†’ Phase 3
366
+ - 🟑 **CAVEATS** (50–69) β†’ Phase 3 with notes (auto-retry once on 🟑 in AUTO mode)
367
+ - πŸ”΄ **NEEDS WORK** (<50 or blockers) β†’ return to Phase 1, max 3 retries β†’ halt
368
+
369
+ Output: `docs/validation-report.md`, `docs/test-scenarios.md` (BDD).
370
+
371
+ ### Phase 3 β€” Toolkit Generation (project-specific only)
372
+
373
+ **Does NOT generate pre-shipped commands** (those are installed via `init`). Generates only project-specific artifacts:
374
+
375
+ - `.claude/agents/{planner,code-reviewer,architect}.md` β€” project-aware
376
+ - `.claude/rules/{security,coding-style,testing}.md` β€” derived from Specification + Refinement
377
+ - `.claude/skills/{project-context,coding-standards}/` β€” domain knowledge
378
+ - `CLAUDE.md` enhanced with project content
379
+ - `.claude/feature-roadmap.json` β€” from PRD MVP scope
380
+ - `DEVELOPMENT_GUIDE.md`, `README.md`
381
+ - Conditional: `.mcp.json` (if external integrations detected), `.claude/commands/feature-ent.md` (if DDD docs detected)
382
+
383
+ Skill: `cc-toolkit-generator-enhanced` (9 modules with quality gates).
384
+
385
+ ### Phase 4 β€” Finalize
386
+
387
+ - `docker-compose.yml`, `Dockerfile`, `.gitignore` (scaffold files)
388
+ - Git commit `chore: initial project setup from SPARC documentation`
389
+ - Final summary
390
+
391
+ ---
392
+
393
+ ## 🧠 Skills Reference
89
394
 
90
395
  | Skill | Purpose |
91
396
  |-------|---------|
@@ -94,13 +399,13 @@ After running `/replicate`, the toolkit generates additional commands, agents, r
94
399
  | `goap-research-ed25519` | Verified research with Ed25519 anti-hallucination |
95
400
  | `problem-solver-enhanced` | First principles + TRIZ (9 modules) |
96
401
  | `requirements-validator` | INVEST/SMART validation + BDD scenarios |
97
- | `brutal-honesty-review` | Unvarnished technical criticism |
402
+ | `brutal-honesty-review` | Unvarnished technical criticism by severity |
98
403
  | `cc-toolkit-generator-enhanced` | Modular toolkit generator (9 modules, ~165K chars) + cross-project learning |
99
404
  | `reverse-engineering-unicorn` | Company reverse engineering + playbook |
100
- | `pipeline-forge` | Meta-skill: build AI pipelines from patterns |
405
+ | `pipeline-forge` | Meta-skill: build AI pipelines from extracted patterns |
101
406
  | `knowledge-extractor` | Extract reusable knowledge from projects |
102
407
 
103
- ## Skill Architecture
408
+ ### Skill Architecture
104
409
 
105
410
  Skills use a **composable module system** with three tiers:
106
411
 
@@ -122,270 +427,919 @@ The `cc-toolkit-generator-enhanced` skill is the largest component (~165K chars)
122
427
  | 08-skill-composition | Dependency graph + path rewriting |
123
428
  | 09-cross-project-learning | Pattern reuse via maturity model |
124
429
 
125
- ## CLI Commands
430
+ ### `view()` cross-skill loading
431
+
432
+ Skills use `view()` for cross-skill loading at runtime:
433
+
434
+ ```markdown
435
+ view() .claude/skills/explore/SKILL.md
436
+ view() .claude/skills/explore/references/questioning-techniques.md
437
+ ```
438
+
439
+ 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.
440
+
441
+ **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`](./MULTIPLATFORM_ROADMAP.md).
442
+
443
+ ---
444
+
445
+ ## ⚑ Commands Reference
446
+
447
+ | Command | Purpose | When to use |
448
+ |---|---|---|
449
+ | `/replicate` | Full pipeline: idea β†’ SPARC docs β†’ toolkit | Start of a new project |
450
+ | `/start` | Bootstrap scaffold from SPARC docs | After `/replicate`, before feature work |
451
+ | `/run` | Autonomous feature build loop from roadmap | Regular development |
452
+ | `/go` | Router: picks `/plan`, `/feature`, or `/feature-ent` | One specific feature |
453
+ | `/next` | Show next feature from roadmap | Sprint navigation |
454
+ | `/plan` | Lightweight plan in `docs/plans/<id>.md` | Small task (≀3 files) |
455
+ | `/feature` | Full SPARC-mini cycle (PLAN β†’ VALIDATE β†’ IMPLEMENT β†’ REVIEW) | Large feature (4+ files) |
456
+ | `/myinsights` | Capture or recall insights | After every non-trivial debug |
457
+ | `/docs` | Bilingual docs generator (RU + EN) | End of project or feature |
458
+ | `/harvest` | Extract reusable patterns | After completed project |
459
+ | `/deploy` | Deployment workflow (dev/staging/prod) | Deployment |
460
+
461
+ ### `/run` β€” autonomous feature build
126
462
 
127
463
  ```bash
128
- npx @dzhechkov/p-replicator init # Install (default)
129
- npx @dzhechkov/p-replicator update # Update to latest version
130
- npx @dzhechkov/p-replicator remove # Remove from project
131
- npx @dzhechkov/p-replicator list # List installed components
132
- npx @dzhechkov/p-replicator doctor # Health check
464
+ /run mvp # only priority=mvp features
465
+ /run all # everything in roadmap
466
+ /run mvp --feature-branches # each feature in its own branch
467
+ /run mvp --feature-branches --auto-merge # also merge into main
133
468
  ```
134
469
 
135
- ### Options
470
+ **One iteration loop:**
136
471
 
137
472
  ```
138
- --force Overwrite existing files without prompting
139
- --dry-run Show what would be done without making changes
140
- --help Show help message
141
- --version Show version number
473
+ while features in scope:
474
+ feature_id = /next # pick highest-priority
475
+ if no feature: break
476
+ /go feature_id # complexity router
477
+ verify (tests green, code committed)
478
+ mark roadmap entry: status=done
479
+ git commit + git push
142
480
  ```
143
481
 
144
- ## The /replicate Pipeline
482
+ **`--feature-branches` flag** (v1.5.0):
483
+ - Creates `feature/{NNN}-{id}` branch per feature (zero-padded 3-digit)
484
+ - Auto-stashes uncommitted changes with message `auto-stash before /run feature-branches`
485
+ - Optional `--auto-merge` merges branch into main on success
486
+ - Updates `feature-roadmap.json` with `number` + `branch` fields
145
487
 
146
- After installation, run `/replicate "idea"` in Claude Code to execute:
488
+ ### `/go` β€” intelligent router
147
489
 
148
- ```
149
- Phase 0 (optional) β†’ Phase 1 β†’ Phase 2 β†’ Phase 3 β†’ Phase 4
150
- Product Discovery Planning Validation Toolkit Finalize
490
+ `/go <id>` decides between:
491
+ - `/plan` β€” for small tasks (≀3 files, no new architecture)
492
+ - `/feature` β€” for large features (4+ files)
493
+ - `/feature-ent` β€” for cross-bounded-context features with new ADRs (only available if Phase 3 generated `feature-ent.md` from DDD docs)
494
+
495
+ ### `/myinsights` β€” knowledge capture
496
+
497
+ Build a project-local knowledge base of "rakes" (development insights) that auto-inject into every session via the SessionStart hook.
498
+
499
+ ```bash
500
+ /myinsights # interactive prompt
501
+ /myinsights "Prisma migrate dev fails silently if shadow DB unreachable. Workaround: set DATABASE_URL_SHADOW explicitly."
502
+ /myinsights recall prisma # search by keyword
151
503
  ```
152
504
 
153
- ### Phase 0: Product Discovery (Optional)
505
+ Storage: `.claude/insights/index.md` β€” markdown log auto-committed by Stop hook.
154
506
 
155
- Activates automatically for SaaS, startups, and new products. Skipped for internal tools and utilities.
507
+ ### `/harvest` β€” knowledge extraction
156
508
 
157
- - Reverse engineers similar companies and products
158
- - Identifies target customer segments (Jobs-To-Be-Done)
159
- - Analyzes competitive landscape (Blue Ocean Canvas)
160
- - Maps unit economics and monetization
161
- - Produces a Product Discovery Brief used by Phase 1
509
+ Extract reusable patterns from a completed project into a knowledge base. Skill: `knowledge-extractor` (4 modules: agent review β†’ classify β†’ decontextualize β†’ integrate).
162
510
 
163
- ### Phase 1: Planning
511
+ ---
164
512
 
165
- Generates 11 SPARC documents in `docs/`:
513
+ ## πŸ’» CLI Commands
166
514
 
167
- | Document | Content |
168
- |----------|---------|
169
- | `PRD.md` | Product Requirements β€” vision, personas, user stories |
170
- | `Solution_Strategy.md` | Problem analysis and solution approach |
171
- | `Specification.md` | Detailed requirements with acceptance criteria |
172
- | `Pseudocode.md` | Algorithms and data flow |
173
- | `Architecture.md` | System design and component diagrams |
174
- | `Refinement.md` | Edge cases, testing strategy |
175
- | `Completion.md` | Deployment, CI/CD, monitoring |
176
- | `Research_Findings.md` | Market and technology research |
177
- | `Final_Summary.md` | Executive summary |
178
- | `C4_Diagrams.md` | System context, container, and component diagrams |
179
- | `ADR.md` | Architecture Decision Records |
515
+ ### Subcommands
180
516
 
181
- ### Phase 2: Validation
517
+ | Subcommand | Purpose | Exit code |
518
+ |---|---|---|
519
+ | `init` (default) | Install package in project | `0` ok, `1` if already installed without `--force` |
520
+ | `update` | Upgrade files to new version (preserves customizations) | `0` ok, `1` if not installed |
521
+ | `remove` | Delete package-tracked files | `0` ok, `1` if not installed |
522
+ | `list` | List installed components with metadata | `0` |
523
+ | `doctor` | Health check of pre-shipped contract + git PATH | `0` ok, `1` if anything broken |
524
+ | `verify` | Pre-shipped + post-/replicate verification | `0` ok, `1` if pre-shipped contract violated |
182
525
 
183
- Validates documentation quality using 5 parallel agents (swarm):
526
+ ### Global flags
184
527
 
185
- | Agent | Validates |
186
- |-------|----------|
187
- | Stories Validator | User stories against INVEST criteria |
188
- | AC Validator | Acceptance criteria against SMART criteria |
189
- | Architecture Validator | Architecture consistency and completeness |
190
- | Pseudocode Validator | Algorithm correctness and edge cases |
191
- | Coherence Validator | Cross-document consistency |
528
+ | Flag | Where it works | Description |
529
+ |---|---|---|
530
+ | `--force` | `init` | Overwrite existing files (with merge logic for settings.json) |
531
+ | `--dry-run` | `init`, `update`, `remove` | Preview without writing to disk |
532
+ | `--reset-settings` | `init --force`, `update` | Full overwrite of settings.json (disables merge) |
533
+ | `--help`, `-h` | any | Show help |
534
+ | `--version`, `-v` | any | Show package version |
535
+
536
+ ### Slash command flags (inside Claude Code)
537
+
538
+ | Flag | Where | Description |
539
+ |---|---|---|
540
+ | `--feature-branches` | `/run`, `/go` | Each feature on its own branch `feature/{NNN}-{id}` |
541
+ | `--auto-merge` | `/run`, `/go` (with `--feature-branches`) | Auto-merge feature branch into main on success |
542
+ | `--skip-tests` | `/start` | Skip test generation |
543
+ | `--skip-seed` | `/start` | Skip DB seeding |
544
+ | `--dry-run` | `/start`, `/replicate` | Preview without writing |
545
+
546
+ ---
547
+
548
+ ## 🎚️ Validation Cycle Details
549
+
550
+ The same validation pipeline runs in **`/replicate` Phase 2** and **`/feature` Phase 2**. Skill: `requirements-validator`.
551
+
552
+ ### Validators (5-agent swarm)
553
+
554
+ | Agent | Criteria | Scoring |
555
+ |---|---|---|
556
+ | `validator-stories` | INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable | 0–100 per story, average |
557
+ | `validator-acceptance` | SMART: Specific, Measurable, Achievable, Relevant, Time-bound | 0–100 per AC, average |
558
+ | `validator-architecture` | Consistency vs target constraints (Distributed Monolith / Docker / VPS / MCP) | Pass/fail + score |
559
+ | `validator-pseudocode` | Algorithm cohesion + data-flow coherence | 0–100 |
560
+ | `validator-coherence` | Cross-document consistency (PRD↔Spec, Spec↔Pseudocode, etc.) | 0–100 |
561
+
562
+ ### Verdicts
563
+
564
+ | Verdict | Threshold | Next |
565
+ |---|---|---|
566
+ | 🟒 **READY** | average β‰₯ 70, no blockers | Phase 3 (or IMPLEMENT in /feature) |
567
+ | 🟑 **CAVEATS** | 50–69, no blockers | Phase 3 with notes (AUTO mode auto-retries once on 🟑) |
568
+ | πŸ”΄ **NEEDS WORK** | < 50 OR any blocker | Return to Phase 1 / PLAN, max 3 retries β†’ halt |
569
+
570
+ After 3 retries with πŸ”΄, the pipeline halts and surfaces to the user. The user can adjust the input or override.
571
+
572
+ ### Output
573
+
574
+ - `docs/validation-report.md` (or `docs/features/<id>/validation-report.md` for /feature)
575
+ - `docs/test-scenarios.md` β€” BDD scenarios derived from acceptance criteria
576
+
577
+ ### Post-implementation review (`brutal-honesty-review`)
578
+
579
+ After `IMPLEMENT` phase (Phase 3 of /feature), `brutal-honesty-review` skill classifies findings by severity:
580
+
581
+ | Severity | Action |
582
+ |---|---|
583
+ | `blocker` | MUST fix before merge |
584
+ | `high` | Fix in this feature unless explicit deferral |
585
+ | `medium` | Optional fix; create follow-up issue |
586
+ | `low` | Logged, no action required |
587
+
588
+ Output: `docs/features/<id>/review-report.md`.
589
+
590
+ ---
591
+
592
+ ## πŸ”„ Feature Lifecycle β€” `/feature` command
593
+
594
+ `/feature <id>` runs a 4-phase lifecycle: **PLAN β†’ VALIDATE β†’ IMPLEMENT β†’ REVIEW**. Project-context-aware (reads `docs/`), checkpoint-driven, parallel where independent.
192
595
 
193
- **Scoring:** Score >= 70 passes (READY), 50-69 passes with caveats, <50 requires fixes (auto-retries up to 3 times).
596
+ ### Two entry modes
194
597
 
195
- **Output:** `docs/validation-report.md` and `docs/test-scenarios.md` (BDD/Gherkin).
598
+ | Mode | When | Pre-conditions |
599
+ |---|---|---|
600
+ | **Mode 1: Post-/replicate** | Project bootstrapped via `/replicate` | CLAUDE.md, docs/, scaffold all generated |
601
+ | **Mode 2: Existing project** | Working project, adding features with verification | `init` ran on top of existing project |
196
602
 
197
- ### Phase 3: Toolkit Generation
603
+ The 4-phase pipeline is **identical in both modes**. Same validation thresholds, same retry logic, same brutal-honesty review.
198
604
 
199
- Creates Claude Code instruments for your project:
605
+ ### Phase 1 β€” PLAN (sparc-prd-mini)
200
606
 
201
- | Category | Generated |
202
- |----------|-----------|
203
- | **Commands** | `/start`, `/feature`, `/plan`, `/next`, `/deploy`, `/myinsights`, `/go`, `/run`, `/docs` |
204
- | **Agents** | `planner`, `code-reviewer`, `architect` |
205
- | **Rules** | `git-workflow`, `feature-lifecycle`, `security`, `coding-style`, `insights-capture` |
206
- | **Skills** | `project-context`, `coding-standards`, `testing-patterns`, `feature-navigator` |
207
- | **Hooks** | `SessionStart` (feature context), `Stop` (auto-commit) |
208
- | **Project files** | `CLAUDE.md`, `DEVELOPMENT_GUIDE.md`, `README.md` |
607
+ Generates 5 SPARC docs in `docs/features/<feature>/`:
608
+ - `01_specification.md` β€” requirements + acceptance criteria
609
+ - `02_pseudocode.md` β€” algorithms + data flow
610
+ - `03_architecture.md` β€” component placement + dependencies
611
+ - `04_refinement.md` β€” edge cases + error paths
612
+ - `05_completion.md` β€” testing + deployment notes
209
613
 
210
- Conditional generation (automatically detected):
211
- - DDD patterns found β†’ `/feature-ent`, enterprise lifecycle
212
- - External APIs detected β†’ security rules, secrets management
213
- - Fitness functions defined β†’ fitness validation rules
614
+ ### Phase 2 β€” VALIDATE (requirements-validator)
214
615
 
215
- ### Phase 4: Finalization
616
+ Same swarm-of-5 as `/replicate` Phase 2. Verdict 🟒/🟑/πŸ”΄ with same retry logic.
216
617
 
217
- Creates infrastructure scaffolding (`docker-compose.yml`, `Dockerfile`, `.gitignore`) and commits everything with structured git history.
618
+ ### Phase 3 β€” IMPLEMENT (parallel agents)
218
619
 
219
- ### Checkpoint Interaction
620
+ 1. Identify independent work units from Phase 1 Architecture
621
+ 2. Spawn parallel `Task` tool calls, one per unit
622
+ 3. Each Task: implement + write tests + commit
623
+ 4. Coordinator merges/integrates
624
+ 5. Run full test suite
220
625
 
221
- After each phase, you see a checkpoint prompt and can respond:
626
+ **Quality gate:** tests pass, lint clean, build succeeds.
222
627
 
223
- | Command | Action |
224
- |---------|--------|
225
- | `ok` | Proceed to next phase |
226
- | `add [detail]` | Add information to current phase output |
227
- | `fix [issue]` | Fix something in current output |
228
- | `redo` | Redo the current phase |
229
- | `skip` | Skip the current phase (not recommended for Phase 2) |
628
+ ### Phase 4 β€” REVIEW (brutal-honesty-review)
230
629
 
231
- ## Post-Pipeline Commands
630
+ Severity-classified findings. Critical (`blocker` | `high`) MUST be fixed.
232
631
 
233
- After `/replicate` completes, the following commands become available:
632
+ ### AUTO mode (called from /go or /run)
234
633
 
235
- ### /start β€” Bootstrap the Project
634
+ - Phase 1: proceed if all docs exist
635
+ - Phase 2: proceed if 🟒 or 🟑; auto-retry once on πŸ”΄
636
+ - Phase 3: proceed if tests + lint + build green
637
+ - Phase 4: auto-fix `high` if straightforward; halt on `blocker`
236
638
 
237
- Reads SPARC documentation and creates the initial project structure: source code directories, database schemas, API stubs, and configuration files.
639
+ ### Final steps
238
640
 
239
- ### /feature β€” Full Feature Lifecycle
641
+ 1. Update `.claude/feature-roadmap.json`: status `in_progress` β†’ `done`
642
+ 2. Commit: `feat(<feature>): complete lifecycle [phases 1-4]`
643
+ 3. Push (if `--feature-branches` mode: also create branch + optional auto-merge)
644
+
645
+ ---
646
+
647
+ ## πŸ“Š Statusline Dashboard
648
+
649
+ **6-line ANSI dashboard** above Claude Code's prompt with real-time pipeline + roadmap + toolkit + status metrics.
240
650
 
241
651
  ```
242
- /feature user-authentication
652
+ P-Replicator V1.5.x ● user β”‚ Sonnet 4.7
653
+ πŸš€ Pipeline /<cmd> β–“β–“β–“β–‘β–‘β–‘β–‘ 50% β”‚ Phase: VALIDATE (2/4) β”‚ Last: /replicate
654
+ 🎯 Roadmap [●●●○○○○○] mvp 3/8 β”‚ Done 5/12 β”‚ β–Ά auth-jwt β”‚ Domain: banking
655
+ πŸ“Š SPARC ●11/11 β”‚ 🟒 78/100 β”‚ Plans ●3 β”‚ ADRs ●2 β”‚ Harvest 2026-05-05
656
+ πŸ› οΈ Toolkit Skills ●10/10 β”‚ Cmds ●11/11 β”‚ Agents ●4+3 β”‚ Rules ●5+2 β”‚ Hooks ●6/6
657
+ πŸ’‘ Insights ●12 (2026-05-06) β”‚ Tests 85/85 βœ“ β”‚ MCP ●1/1 β”‚ Settings βœ“ β”‚ 🧬 Keysarium βœ“
243
658
  ```
244
659
 
245
- 4-phase lifecycle: **PLAN** (SPARC docs) β†’ **VALIDATE** (swarm, score >= 70) β†’ **IMPLEMENT** (parallel agents) β†’ **REVIEW** (code review swarm).
660
+ ### Sources (heuristic + state-file)
661
+
662
+ | Metric | Source |
663
+ |---|---|
664
+ | Pipeline command + phase + progress | `.claude/.p-replicator-state.json` |
665
+ | Roadmap progress | `.claude/feature-roadmap.json` |
666
+ | SPARC count | `docs/{PRD,Architecture,...}.md` |
667
+ | Validation score | regex extract from `docs/validation-report.md` |
668
+ | Plans count | `docs/plans/*.md` |
669
+ | ADRs count | `docs/ADR.md` H2/H3 headings, or `docs/adr/*.md`, or `docs/ddd/adr/*.md` |
670
+ | Insights count + last date | `## YYYY-MM-DD` in `.claude/insights/index.md` |
671
+ | Toolkit counts | filesystem walks of `.claude/{skills,commands,agents,rules,hooks}/` |
672
+ | Settings status | deep-equals current vs `manifest.shippedDefaults` |
673
+ | MCP servers | `.mcp.json` |
674
+ | Domain | keyword grep in `CLAUDE.md` |
675
+ | Last harvest | `TOOLKIT_HARVEST.md` mtime |
676
+ | Last test | optional `.claude/.last-test.json` cache |
677
+
678
+ ### Defensive design
679
+
680
+ Every section wrapped in `safeRun()` with fallback β€” one parse error doesn't break the whole status bar.
681
+
682
+ **Stale state:** state file older than 30 minutes is ignored (Pipeline section shows `idle`).
683
+
684
+ **Disable statusline:** remove the `statusLine` field from `.claude/settings.json`. The deletion is preserved on next `update` thanks to merge logic.
685
+
686
+ For internals, see [admin guide](./README/eng/03_admin_guide.md#statusline--dashboard) and [`documentation/07-dashboard-howto.md`](../../documentation/07-dashboard-howto.md) (in source repo).
687
+
688
+ ---
246
689
 
247
- ### /plan β€” Lightweight Planning
690
+ ## πŸͺ Hooks System
248
691
 
692
+ `p-replicator` ships **6 cross-platform Node scripts** in `.claude/hooks/`:
693
+
694
+ | Hook | Event | Purpose |
695
+ |---|---|---|
696
+ | `session-insights.cjs` | SessionStart | Inject 3 recent insights from `.claude/insights/index.md` to stdout (Claude Code captures into context) |
697
+ | `autocommit-roadmap.cjs` | Stop | Auto-commit `.claude/feature-roadmap.json` if changed |
698
+ | `autocommit-insights.cjs` | Stop | Auto-commit `.claude/insights/` if changed |
699
+ | `autocommit-plans.cjs` | Stop | Auto-commit `docs/plans/` if changed |
700
+ | `statusline.cjs` | (statusLine config) | Multi-line dashboard above the prompt |
701
+ | `state-update.cjs` | (utility) | Argv-driven helper for writing `.claude/.p-replicator-state.json` |
702
+
703
+ ### Cross-platform discipline
704
+
705
+ All 4 autocommit scripts use `execFileSync('git', [...])` (no shell pipes, no `2>/dev/null`/`|| true`). Works identically on Windows-cmd, bash, PowerShell.
706
+
707
+ **Each script is defensive:** wrapped in try/catch, always exits 0 (best-effort, never blocks the session).
708
+
709
+ ### State file for live progress
710
+
711
+ `.claude/.p-replicator-state.json` β€” ephemeral state, updated by commands during pipeline execution:
712
+
713
+ ```json
714
+ {
715
+ "currentCommand": "/feature",
716
+ "currentPhase": { "name": "VALIDATE", "index": 2, "total": 4, "progress": 0.5 },
717
+ "lastCommand": "/replicate",
718
+ "lastFeature": "auth-jwt",
719
+ "updatedAt": "2026-05-07T..."
720
+ }
249
721
  ```
250
- /plan add-payment-gateway
722
+
723
+ Updated via `state-update.cjs`:
724
+
725
+ ```bash
726
+ node .claude/hooks/state-update.cjs \
727
+ --command /feature \
728
+ --phase VALIDATE \
729
+ --index 2 \
730
+ --total 4 \
731
+ --progress 0.5
251
732
  ```
252
733
 
253
- Creates a single plan file in `docs/plans/`. Good for smaller tasks (2-5 min vs. 15-30 min for `/feature`).
734
+ Pipeline commands optionally call this script (via Bash tool) so statusline shows real progress.
254
735
 
255
- ### /go β€” Smart Pipeline Selector
736
+ **⚠️ Recommendation:** add to `.gitignore`:
256
737
 
257
738
  ```
258
- /go user-authentication
739
+ .claude/.p-replicator-state.json
740
+ .claude/.last-test.json
741
+ ```
742
+
743
+ ---
744
+
745
+ ## πŸ—ΊοΈ Roadmap & Insights
746
+
747
+ ### Feature roadmap (`.claude/feature-roadmap.json`)
748
+
749
+ **File:** generated in `/replicate` Phase 3 from PRD MVP scope, or by hand for Mode 2.
750
+
751
+ **Schema (post v1.5.0):**
752
+
753
+ ```json
754
+ {
755
+ "version": "1.0",
756
+ "features": [
757
+ {
758
+ "id": "auth-jwt",
759
+ "number": 1,
760
+ "branch": "feature/001-auth-jwt",
761
+ "name": "JWT-based authentication",
762
+ "priority": "mvp",
763
+ "status": "next",
764
+ "complexity": "medium",
765
+ "estimated_hours": "2-4",
766
+ "blockers": [],
767
+ "expected_files": ["packages/backend/src/auth/jwt.ts"],
768
+ "depends_on": []
769
+ }
770
+ ]
771
+ }
772
+ ```
773
+
774
+ **Lifecycle states:** `planned` β†’ `next` β†’ `in_progress` β†’ `done` (or `blocked`).
775
+
776
+ **`number` and `branch`** are populated by `--feature-branches` flag. Auto-commit via `autocommit-roadmap.cjs` (Stop hook).
777
+
778
+ ### Insights system
779
+
780
+ **Storage:** `.claude/insights/index.md` (markdown log).
781
+
782
+ **Entry format:**
783
+
784
+ ```markdown
785
+ ## YYYY-MM-DD β€” short title
786
+
787
+ **Tags:** tag1, tag2, tag3
788
+
789
+ **Problem:**
790
+ What happened (1-3 sentences).
791
+
792
+ **Solution:**
793
+ What fixed it (1-5 sentences with code if relevant).
794
+
795
+ **References:** file:line or commit hash or external link
796
+
797
+ ---
259
798
  ```
260
799
 
261
- Automatically analyzes task complexity and selects `/plan`, `/feature`, or `/feature-ent`.
800
+ **Lifecycle:**
801
+ - ≀ 50 entries β†’ single `index.md`
802
+ - > 50 β†’ split into archive `<YYYY-MM>.md` with `index.md` as TOC
803
+ - Never delete β€” only supersede via `**Status:** superseded by <link>`
804
+
805
+ **Tag conventions:**
806
+ - βœ… `prisma-migration`, `postgres-timezone`, `docker-compose-network`
807
+ - ❌ `bug`, `fix`, `important` (too generic β€” recall fails)
808
+
809
+ **Auto-injection:** `SessionStart` hook (`session-insights.cjs`) reads top 3 recent entries to stdout, Claude Code injects into initial session context.
810
+
811
+ ---
812
+
813
+ ## πŸ›οΈ Architecture Highlights
814
+
815
+ ### Two-tier model: Pre-shipped vs Project-generated
262
816
 
263
- ### /run β€” Autonomous Build Loop
817
+ | Tier | Created by | Lives in | Updated |
818
+ |---|---|---|---|
819
+ | **Pre-shipped** | `npx p-replicator init` | `.claude/{skills,commands,agents,rules,hooks}/` + `settings.json` | On each package upgrade |
820
+ | **Project-generated** | `/replicate` Phase 3 (LLM execution) | `CLAUDE.md`, `.claude/agents/planner.md`, `docs/`, etc. | Only on regeneration |
264
821
 
822
+ > πŸ’‘ **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.
823
+
824
+ ### SSOT: `utils.COMPONENTS`
825
+
826
+ 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.
827
+
828
+ ### Settings.json merge logic (v1.4.2 + v1.4.3)
829
+
830
+ `init --force` and `update` use `mergeSettingsJson(existing, template)` to preserve user customizations:
831
+
832
+ - **User-added hook** (absent from template) β†’ preserved
833
+ - **User-modified default** (changed command) β†’ treated as user-added β†’ preserved
834
+ - **Identical command** in template and user β†’ de-duped
835
+ - **New hook in template** β†’ added to user's settings
836
+ - **Removed default** (was in old template, gone from new) β†’ orphan-detected and removed
837
+
838
+ **Identity model:** hooks compared by `command` string. **Override:** `--reset-settings` flag disables merge β€” full overwrite.
839
+
840
+ ### Manifest schema (`.p-replicator.json`)
841
+
842
+ ```json
843
+ {
844
+ "version": "1.5.x",
845
+ "installedAt": "2026-05-07T12:00:00.000Z",
846
+ "components": ["agents", "commands", "hooks", "rules", "settings", "skills"],
847
+ "files": ["...sorted list of all installed files..."],
848
+ "shippedDefaults": {
849
+ "settings.json": { "hooks": {...}, "statusLine": {...} }
850
+ }
851
+ }
265
852
  ```
266
- /run # Build next features (MVP scope)
267
- /run all # Build all planned features
853
+
854
+ `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.
855
+
856
+ For complete internals, see [`README/eng/05_architecture.md`](./README/eng/05_architecture.md) β€” covers cross-platform hooks, sync-templates merge mode, settings merge algorithm, statusline architecture.
857
+
858
+ ---
859
+
860
+ ## βš™οΈ Configuration
861
+
862
+ ### `.claude/settings.json`
863
+
864
+ Default structure after `init`:
865
+
866
+ ```json
867
+ {
868
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
869
+ "_comment": "Default hooks + statusline shipped by @dzhechkov/p-replicator init.",
870
+ "statusLine": {
871
+ "type": "command",
872
+ "command": "node .claude/hooks/statusline.cjs"
873
+ },
874
+ "hooks": {
875
+ "SessionStart": [
876
+ {
877
+ "matcher": "*",
878
+ "hooks": [
879
+ { "type": "command", "command": "node .claude/hooks/session-insights.cjs", "timeout": 5 }
880
+ ]
881
+ }
882
+ ],
883
+ "Stop": [
884
+ {
885
+ "matcher": "*",
886
+ "hooks": [
887
+ { "type": "command", "command": "node .claude/hooks/autocommit-roadmap.cjs", "timeout": 10 },
888
+ { "type": "command", "command": "node .claude/hooks/autocommit-insights.cjs", "timeout": 10 },
889
+ { "type": "command", "command": "node .claude/hooks/autocommit-plans.cjs", "timeout": 10 }
890
+ ]
891
+ }
892
+ ]
893
+ }
894
+ }
268
895
  ```
269
896
 
270
- Continuously implements features from the roadmap until complete.
897
+ **Customization:** add new hooks or event types β€” preserved on `init --force` or `update` thanks to merge logic.
271
898
 
272
- ### /next β€” What to Do Next
899
+ **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).
273
900
 
274
- Shows current sprint progress, features in progress, suggested next tasks, blockers and dependencies.
901
+ ### MCP servers (`.mcp.json`)
275
902
 
276
- ### /deploy β€” Deployment
903
+ Project-local MCP server config:
277
904
 
905
+ ```json
906
+ {
907
+ "mcpServers": {
908
+ "filesystem": {
909
+ "command": "npx",
910
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
911
+ },
912
+ "github": {
913
+ "command": "npx",
914
+ "args": ["-y", "@modelcontextprotocol/server-github"],
915
+ "env": { "GITHUB_TOKEN": "..." }
916
+ }
917
+ }
918
+ }
278
919
  ```
279
- /deploy staging
280
- /deploy production
920
+
921
+ Statusline shows MCP server count. `/replicate` Phase 3 auto-generates `.mcp.json` when external integrations are detected.
922
+
923
+ ### Keysarium integration
924
+
925
+ If `.keysarium.json` (from sibling `@dzhechkov/keysarium` package) is detected:
926
+
927
+ - `init` shows an integration banner
928
+ - Statusline shows `🧬 Keysarium βœ“`
929
+ - `/replicate` Phase 3 doesn't duplicate skills already provided by Keysarium
930
+
931
+ ---
932
+
933
+ ## πŸ”„ Update workflow
934
+
935
+ ```bash
936
+ # Safe upgrade with preserved customizations:
937
+ npx @dzhechkov/p-replicator@latest update
938
+
939
+ # Or via init --force (also preserves customizations):
940
+ npx @dzhechkov/p-replicator@latest init --force
941
+
942
+ # Full reset of settings.json to defaults (loses custom hooks):
943
+ npx @dzhechkov/p-replicator@latest init --force --reset-settings
281
944
  ```
282
945
 
283
- Guides the deployment process to the specified environment.
946
+ ### What the merge logic does
284
947
 
285
- ### /myinsights β€” Development Insights
948
+ 1. Reads `manifest.shippedDefaults['settings.json']` (what we shipped previously)
949
+ 2. Reads current `templates/.claude/settings.json` (new template)
950
+ 3. Reads `.claude/settings.json` (user's current)
951
+ 4. **Orphan detection:** removes hooks present in old template but missing in new
952
+ 5. **Merge:** adds hooks from new template that aren't already in user's current
953
+ 6. User-added hooks (never in old template) are **preserved**
286
954
 
287
- Captures errors, workarounds, and discoveries into the knowledge base. Error-first lookup: when you hit an error, the system checks if a solution already exists.
955
+ After upgrade, run `verify` to confirm:
288
956
 
289
- ### /docs β€” Generate Documentation
957
+ ```bash
958
+ npx @dzhechkov/p-replicator verify
959
+ ```
960
+
961
+ ---
962
+
963
+ ## πŸ†˜ Troubleshooting
964
+
965
+ > πŸ’‘ **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`](./README/eng/06_troubleshooting.md).
966
+
967
+ <details>
968
+ <summary><b>πŸ‘‰ Click to expand 12 common issues + fixes</b></summary>
290
969
 
970
+ <br>
971
+
972
+ ### `init` refuses: "P-Replicator is already installed"
973
+
974
+ ```bash
975
+ npx @dzhechkov/p-replicator update # safe upgrade
976
+ npx @dzhechkov/p-replicator init --force # forced re-install
977
+ npx @dzhechkov/p-replicator init --force --reset-settings # full reset
291
978
  ```
292
- /docs # Both Russian and English
293
- /docs eng # English only
294
- /docs update # Update existing docs
979
+
980
+ ### Missing files after `init`
981
+
982
+ ```bash
983
+ npx @dzhechkov/p-replicator doctor # see what's missing
984
+ npx @dzhechkov/p-replicator init --force # repair
295
985
  ```
296
986
 
297
- Generates bilingual documentation in `README/` directory.
987
+ ### Install went to `~/node_modules` instead of project
988
+
989
+ Cause: no `package.json` in your project, npm walks up and finds one in home directory.
990
+
991
+ ```bash
992
+ npm init -y
993
+ npx @dzhechkov/p-replicator init
994
+ ```
298
995
 
299
- ## Feature Development Workflows
996
+ ### Statusline doesn't appear
300
997
 
301
- ### Simple Task
998
+ Checks:
999
+ 1. Claude Code version supports `statusLine` config? Update Claude Code.
1000
+ 2. `statusLine` field present in `.claude/settings.json`?
1001
+ 3. Script runs directly:
302
1002
 
1003
+ ```bash
1004
+ node .claude/hooks/statusline.cjs
303
1005
  ```
304
- /plan task-name β†’ Creates plan in docs/plans/
305
- implement manually β†’ Write code following the plan
306
- /myinsights β†’ Capture any learnings
1006
+
1007
+ Should print 6 lines of ANSI output. If it errors:
1008
+
1009
+ ```bash
1010
+ node .claude/hooks/statusline.cjs 2>&1
307
1011
  ```
308
1012
 
309
- ### Standard Feature
1013
+ Likely cause: corrupt JSON or missing `.p-replicator.json`.
310
1014
 
1015
+ ### Hooks aren't auto-committing
1016
+
1017
+ ```bash
1018
+ npx @dzhechkov/p-replicator doctor
311
1019
  ```
312
- /feature feature-name β†’ Runs 4-phase lifecycle
313
- /next β†’ Check what's next
1020
+
1021
+ Look for `βœ“ git on PATH` in Prerequisites section. Also verify `.git` exists:
1022
+
1023
+ ```bash
1024
+ git rev-parse --git-dir
314
1025
  ```
315
1026
 
316
- ### Smart Mode
1027
+ Debug a specific hook:
317
1028
 
1029
+ ```bash
1030
+ node .claude/hooks/autocommit-roadmap.cjs
1031
+ echo "Exit: $?"
1032
+ git log -1 --format="%s"
318
1033
  ```
319
- /go feature-name β†’ Auto-selects /plan or /feature or /feature-ent
1034
+
1035
+ ### Statusline shows "Settings ⚠️ merged" but I didn't change anything
1036
+
1037
+ Cause: some process modified `settings.json` (formatting, whitespace, ordering). Statusline compares via deep-equals on sorted keys.
1038
+
1039
+ ```bash
1040
+ npx @dzhechkov/p-replicator init --force --reset-settings
320
1041
  ```
321
1042
 
322
- ### Autonomous Build
1043
+ ### Settings.json lost my custom hooks after update
323
1044
 
1045
+ This was a bug pre-v1.4.2. In v1.4.2+, `update` and `init --force` use `mergeSettingsJson` which preserves user customizations.
1046
+
1047
+ If you're on v1.4.1 or earlier:
1048
+
1049
+ ```bash
1050
+ npx @dzhechkov/p-replicator@latest update
324
1051
  ```
325
- /run β†’ Builds all "next" features from roadmap
1052
+
1053
+ Restore lost hooks from git history:
1054
+
1055
+ ```bash
1056
+ git log -p --follow -- .claude/settings.json
326
1057
  ```
327
1058
 
328
- ### Feature Roadmap
1059
+ ### `/run --feature-branches` immediately fails "not on main"
1060
+
1061
+ Cause: you're on a feature branch. Switch to main:
329
1062
 
330
- The system maintains `.claude/feature-roadmap.json` with statuses: `done`, `in_progress`, `next`, `planned`, `blocked`. Use `/next` to navigate.
1063
+ ```bash
1064
+ git checkout main
1065
+ /run mvp --feature-branches
1066
+ ```
331
1067
 
332
- ## The /harvest Pipeline
1068
+ ### `--feature-branches` lost my unsaved changes
333
1069
 
334
- Extract reusable knowledge from completed projects:
1070
+ They're stashed:
335
1071
 
1072
+ ```bash
1073
+ git stash list
1074
+ git stash show stash@{0}
1075
+ git stash pop
336
1076
  ```
337
- /harvest quick # Fast extraction, no checkpoints (~15 min)
338
- /harvest full # Comprehensive 4-phase pipeline with checkpoints (~45 min)
339
- /harvest marker # Mark artifact for later extraction (~30 sec)
1077
+
1078
+ `p-replicator` auto-stashes with message `auto-stash before /run feature-branches`.
1079
+
1080
+ ### `/replicate` didn't generate expected commands (`/run`, `/feature`, ...)
1081
+
1082
+ This is solved in v1.4.0+. All 11 generic commands are now pre-shipped via `init`. If you're on an old version:
1083
+
1084
+ ```bash
1085
+ npx @dzhechkov/p-replicator@latest init --force
1086
+ npx @dzhechkov/p-replicator verify
340
1087
  ```
341
1088
 
342
- ### How /harvest full Works
1089
+ ### Insights aren't auto-injected into new sessions
1090
+
1091
+ Checks:
1092
+ 1. `.claude/insights/index.md` exists with entries?
1093
+ 2. Hook works:
1094
+ ```bash
1095
+ node .claude/hooks/session-insights.cjs # should print recent insights
1096
+ ```
1097
+ 3. SessionStart hook configured in `settings.json`?
1098
+
1099
+ If all 3 OK but still nothing β€” Claude Code may cache. Restart `claude`.
343
1100
 
1101
+ ### Statusline lags on every command
1102
+
1103
+ ```bash
1104
+ time node .claude/hooks/statusline.cjs # how many seconds?
344
1105
  ```
345
- Phase 1: AGENT REVIEW β†’ 5 parallel scanners
346
- Phase 2: CLASSIFY β†’ Categorize into skills/commands/rules/etc.
347
- Phase 3: DECONTEXTUALIZE β†’ Remove project-specific names, generalize
348
- Phase 4: INTEGRATE β†’ Write to toolkit, update index
1106
+
1107
+ Should be < 100ms. If > 1s, check `docs/` size:
1108
+
1109
+ ```bash
1110
+ du -sh docs/
1111
+ find docs/ -type f -name "*.md" | wc -l
349
1112
  ```
350
1113
 
351
- ### Harvest Audit
1114
+ Workaround: temporarily disable statusline by removing the `statusLine` field in `.claude/settings.json`. See [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md) item L6 for future enhancement (`STATUSLINE_PROFILE=1` env var).
1115
+
1116
+ For full troubleshooting (15+ issues with detailed diagnostics), see [`README/eng/06_troubleshooting.md`](./README/eng/06_troubleshooting.md).
1117
+
1118
+ </details>
1119
+
1120
+ ---
1121
+
1122
+ ## πŸ“ˆ Migration
1123
+
1124
+ <details>
1125
+ <summary><b>πŸ‘‰ Click to expand per-version migration matrix</b></summary>
1126
+
1127
+ <br>
1128
+
1129
+ | From β†’ To | What you get | Migration cost |
1130
+ |---|---|---|
1131
+ | 1.3.x β†’ 1.5.x | All pre-shipped commands + statusline + feature-branches + merge logic + Mode 2 | `init --force` (preserves customizations) |
1132
+ | 1.4.0 β†’ 1.4.1 | Cross-platform hooks + sync merge mode | `init --force` |
1133
+ | 1.4.1 β†’ 1.4.2 | Settings merge (preserve customizations) | `init --force` is safe (preserves) |
1134
+ | 1.4.2 β†’ 1.4.3 | Orphan detection | First upgrade lacks baseline β€” re-run `init --force` to populate |
1135
+ | 1.4.3 β†’ 1.5.0 | Statusline + `--feature-branches` | `update` or `init --force` |
1136
+ | 1.5.0 β†’ 1.5.1 | "Existing tech docs" workflow formalized | docs only β€” no migration |
1137
+ | 1.5.1 β†’ 1.5.2 | Mode 2 (existing project + /feature) formalized | docs only β€” no migration |
352
1138
 
1139
+ > βœ… **No breaking changes** between any versions. All upgrades are backward-compatible.
1140
+
1141
+ After any upgrade β€” `verify` to confirm contract:
1142
+
1143
+ ```bash
1144
+ npx @dzhechkov/p-replicator verify
353
1145
  ```
354
- /harvest audit
1146
+
1147
+ </details>
1148
+
1149
+ ---
1150
+
1151
+ ## πŸ§ͺ Test Infrastructure
1152
+
1153
+ <details>
1154
+ <summary><b>πŸ‘‰ Click to expand test layer breakdown + meta-tests</b></summary>
1155
+
1156
+ <br>
1157
+
1158
+ **Suite:** 105 tests, 36 suites, ~25 sec runtime.
1159
+
1160
+ | Layer | File | Coverage |
1161
+ |---|---|---|
1162
+ | **Unit** | `tests/unit/utils.test.js` (54 tests) | Pure functions: createManifest, mergeSettingsJson, removeOrphanHooks, getItemRelativePath, parseToolkit logic |
1163
+ | **E2E** | `tests/e2e/lifecycle.test.js` (48 tests) | Full CLI lifecycle, hooks installation, settings merge edge cases, statusline output, --feature-branches docs |
1164
+ | **Snapshot** | `tests/snapshot/templates.test.js` (3 tests) | SHA-256 baseline of all 115 files in `templates/` |
1165
+
1166
+ **Meta-tests** verify consistency between documents:
1167
+ - `replicate-pipeline.md` mentions every pre-shipped command (no orphan in rule)
1168
+ - `replicate.md` Phase 3 doesn't claim "Generate `<pre-shipped>.md`" (no spec drift)
1169
+
1170
+ **Snapshot baseline** regenerated via `npm run snapshot:baseline` after intentional template changes.
1171
+
1172
+ ```bash
1173
+ npm test # full suite
1174
+ npm run test:unit # unit only
1175
+ npm run test:e2e # e2e only
1176
+ npm run test:snapshot # snapshot only
355
1177
  ```
356
1178
 
357
- Reviews toolkit maturity distribution, recommendations for promotion, and gaps in coverage.
1179
+ </details>
1180
+
1181
+ ---
1182
+
1183
+ ## ⚠️ Known Limitations
1184
+
1185
+ For currently-open improvement items β€” see [`KNOWN_LIMITATIONS.md`](./KNOWN_LIMITATIONS.md) (8 entries: 3 medium, 5 low priority).
1186
+
1187
+ **Highlights:**
1188
+ - **M1** β€” `--feature-branches` behavior tested only via documentation-presence (not e2e git workflow)
1189
+ - **M2** β€” No formal `--from-docs` CLI flag (workflow works via natural-language only)
1190
+ - **M3** β€” `/feature` requires standard SPARC doc paths (no `--prd-path` flag)
1191
+ - **L5** β€” `.p-replicator-state.json` not auto-gitignored
1192
+ - **L6** β€” Statusline could profile per-section if slow
1193
+
1194
+ For multiplatform support roadmap (Codex, OpenCode, KiloCode) β€” see [`MULTIPLATFORM_ROADMAP.md`](./MULTIPLATFORM_ROADMAP.md).
1195
+
1196
+ ---
358
1197
 
359
- ## Tips & Best Practices
1198
+ ## πŸ“œ Changelog Highlights
360
1199
 
361
- 1. **Write descriptive product ideas** β€” the more detail you provide to `/replicate`, the better the documentation quality.
1200
+ > πŸ“Œ For full version history with migration notes β€” see [`CHANGELOG.md`](./CHANGELOG.md) (authoritative source).
362
1201
 
363
- 2. **Use checkpoints actively** β€” review output at each phase, don't just skip through. Check that user stories match your vision and architecture aligns with constraints.
1202
+ <details>
1203
+ <summary><b>πŸ‘‰ Click to expand 9 versions: v1.3.0 β†’ v1.5.3</b></summary>
364
1204
 
365
- 3. **Start with /plan for small tasks** β€” not every task needs `/feature`. For tasks touching <= 3 files, `/plan` is faster and sufficient.
1205
+ <br>
366
1206
 
367
- 4. **Use /go for automatic selection** β€” let the system decide between `/plan`, `/feature`, and `/feature-ent` based on complexity.
1207
+ ### v1.5.3 β€” 2026-05-07 (Comprehensive README + visual polish)
368
1208
 
369
- 5. **Harvest knowledge regularly** β€” use `/harvest marker` during development, run `/harvest quick` at the end of each sprint.
1209
+ - πŸ“š **Expanded `README.md`** from ~14.6 kB to ~50 kB (consolidating 8 eng/ files for npm registry visibility)
1210
+ - 🎨 Visual polish: hero banner, 8 badges, emoji TOC, collapsible sections, callout blocks, `<kbd>` for CLI commands
370
1211
 
371
- 6. **Use /next for focus** β€” start each session with `/next` to understand current state, blockers, and priorities.
1212
+ ### v1.5.2 β€” 2026-05-07 (Mode 2 documentation)
372
1213
 
373
- 7. **Check insights before debugging** β€” the `SessionStart` hook automatically injects relevant insights from previous sessions.
1214
+ Formalized **"Feature workflow in existing project (Mode 2)"** across all documentation surfaces. Pure docs/spec patch β€” no code changes.
374
1215
 
375
- 8. **Review generated CLAUDE.md** β€” it's Claude Code's primary context. Ensure architecture, commands, and coding standards are accurate.
1216
+ ### v1.5.1 β€” 2026-05-07 (Existing-docs workflow)
376
1217
 
377
- 9. **Iterate on validation** β€” if Phase 2 returns CAVEATS, fix documentation before proceeding. Toolkit quality depends on documentation quality.
1218
+ Formalized **"Starting from existing technical documentation"** workflow for `/replicate`. New build.js link-rewriter for HTML guide.
378
1219
 
379
- ## Integration with @dzhechkov/keysarium
1220
+ ### v1.5.0 β€” 2026-05-07 (Statusline + feature-branches)
380
1221
 
381
- Works alongside Keysarium. If `@dzhechkov/keysarium` is detected during `init`, PU skills integrate with the existing Keysarium setup, sharing `.claude/commands`, `.claude/rules`, and `.claude/agents` directories.
1222
+ - ✨ **Statusline dashboard** (RuFlo-style 6-line bar) via `templates/.claude/hooks/statusline.cjs`
1223
+ - ✨ **`--feature-branches` flag** for `/run` and `/go` (each feature on its own branch `feature/{NNN}-{id}`)
1224
+ - πŸ†• `state-update.cjs` β€” argv-driven helper
1225
+ - πŸ†• `--auto-merge` companion flag
1226
+
1227
+ ### v1.4.3 β€” 2026-05-07 (Orphan hook detection)
1228
+
1229
+ - πŸ› `mergeSettingsJson` now cleans hooks shipped previously but removed in newer template
1230
+ - πŸ†• `manifest.shippedDefaults['settings.json']` baseline
1231
+ - πŸ› `update.js` now also uses merge logic
1232
+
1233
+ ### v1.4.2 β€” 2026-05-06 (Merge + meta-tests)
1234
+
1235
+ - πŸ› `init --force` MERGES settings.json (preserves user customizations)
1236
+ - πŸ†• `--reset-settings` flag for explicit nuclear-overwrite
1237
+ - πŸ› Stronger meta-test for `replicate.md` drift (multi-axis)
1238
+ - πŸ†• `doctor` checks `git on PATH`
1239
+
1240
+ ### v1.4.1 β€” 2026-05-06 (Cross-platform + critical fix)
1241
+
1242
+ - πŸ› Cross-platform hooks: replaced bash chains with 4 Node scripts
1243
+ - πŸ› `verify.js` SSOT: `kind: 'pre-shipped' | 'project-generated'` field
1244
+ - πŸ› Meta-tests for `replicate.md` ↔ `replicate-pipeline.md` consistency
1245
+ - πŸ› **Critical regression fixed:** `sync-templates.js` cleanDir silently deleted pre-shipped files
1246
+
1247
+ ### v1.4.0 β€” 2026-05-06 (Major: 9 pre-shipped commands)
1248
+
1249
+ - ✨ **9 new pre-shipped commands:** `/start`, `/plan`, `/feature`, `/go`, `/run`, `/next`, `/myinsights`, `/docs`, `/deploy`
1250
+ - ✨ **3 new pre-shipped rules:** `git-workflow`, `insights-capture`, `feature-lifecycle`
1251
+ - ✨ Settings.json shipped with hooks
1252
+ - ✨ `verify` command β€” replaces user's manual verification prompt
1253
+ - πŸ› 5 sources of truth divergence unified via `utils.COMPONENTS.items`
1254
+
1255
+ ### v1.3.1 β€” 2026-05-06 (SSOT bugfix)
1256
+
1257
+ - πŸ› `cli.js` --help showed "1 rule" while `EXPECTED_RULES` had 2 entries β†’ SSOT fix
1258
+ - πŸ› `update.js` corrupted manifest β†’ `getRelativePaths(templateClaude)` fix
1259
+ - πŸ› `update` now removes orphan template files
1260
+
1261
+ ### v1.3.0 (baseline)
1262
+
1263
+ Initial published version. 10 skills, 2 commands (`/replicate`, `/harvest`), 4 agents, 2 rules.
1264
+
1265
+ </details>
1266
+
1267
+ ---
1268
+
1269
+ ## 🀝 Contributing
1270
+
1271
+ This package is part of the [`pu-unicorn-replicate`](https://github.com/dzhechko/pu-unicorn-replicate) monorepo.
1272
+
1273
+ ### Development setup
382
1274
 
383
1275
  ```bash
384
- npx @dzhechkov/keysarium init # Install Keysarium
385
- npx @dzhechkov/p-replicator init # Add PU Unicorn skills
386
- # Both work together seamlessly
1276
+ git clone https://github.com/dzhechko/pu-unicorn-replicate.git
1277
+ cd pu-unicorn-replicate/packages/p-replicator
1278
+ npm install
1279
+ npm test
387
1280
  ```
388
1281
 
389
- ## License
1282
+ ### Pre-publish checklist
1283
+
1284
+ ```bash
1285
+ npm run snapshot:baseline # regenerate baseline if templates/ changed
1286
+ npm test # all 105 tests must pass
1287
+ npm pack --dry-run # verify tarball contents
1288
+ npm publish # prepublishOnly hook syncs source β†’ templates/
1289
+ ```
1290
+
1291
+ ### Filing issues
1292
+
1293
+ https://github.com/dzhechko/pu-unicorn-replicate/issues
1294
+
1295
+ Include:
1296
+ - `npx @dzhechkov/p-replicator --version` output
1297
+ - `npx @dzhechkov/p-replicator verify` output
1298
+ - Repro steps + expected vs actual
1299
+
1300
+ ### Patterns persisted in AQE memory
1301
+
1302
+ Each significant improvement is persisted as a cross-session pattern (16+ entries from v1.3.1 β†’ v1.5.2). Categories:
1303
+
1304
+ - `cli-package-ssot-component-lists`, `cli-package-manifest-preservation` (v1.3.1)
1305
+ - `cli-package-pre-ship-vs-generate-boundary`, `cli-package-verify-replaces-manual-prompts` (v1.4.0)
1306
+ - `cli-package-cross-platform-hooks-via-node-scripts`, `cli-package-kind-discrimination-for-ssot` (v1.4.1)
1307
+ - `cli-package-settings-json-merge-vs-overwrite`, `meta-test-multi-axis-drift-detection` (v1.4.2)
1308
+ - `cli-shipped-defaults-baseline-for-orphan-detection`, `cli-update-must-mirror-init-merge-logic` (v1.4.3)
1309
+ - `cli-statusline-multi-line-dashboard`, `cli-feature-branches-flag-for-teaching-workflows` (v1.5.0)
1310
+ - `doc-rollout-pattern` (v1.5.1, v1.5.2 β€” 14-surface symmetric rollout)
1311
+
1312
+ ---
1313
+
1314
+ ## πŸ“ƒ License
1315
+
1316
+ MIT β€” see [LICENSE](./LICENSE).
1317
+
1318
+ ---
1319
+
1320
+ ## Links
1321
+
1322
+ - **npm:** https://www.npmjs.com/package/@dzhechkov/p-replicator
1323
+ - **GitHub:** https://github.com/dzhechko/pu-unicorn-replicate
1324
+ - **Issues:** https://github.com/dzhechko/pu-unicorn-replicate/issues
1325
+ - **Telegram:** https://t.me/llm_notes
1326
+ - **Author:** dzhechko
1327
+
1328
+ ### Companion documentation
1329
+
1330
+ - [`CHANGELOG.md`](./CHANGELOG.md) β€” version history (authoritative)
1331
+ - [`KNOWN_LIMITATIONS.md`](./KNOWN_LIMITATIONS.md) β€” 8 open improvement items
1332
+ - [`MULTIPLATFORM_ROADMAP.md`](./MULTIPLATFORM_ROADMAP.md) β€” Codex/OpenCode/KiloCode support roadmap
1333
+ - [`README/ru/`](./README/ru/) β€” Russian documentation (8 sections)
1334
+ - [`README/eng/`](./README/eng/) β€” English documentation (8 sections, deeper than this README)
1335
+ - [`README/ru/html/index.html`](./README/ru/html/index.html) β€” interactive single-page HTML guide
1336
+
1337
+ ---
1338
+
1339
+ **πŸš€ Ready to start?**
1340
+
1341
+ ```bash
1342
+ npx @dzhechkov/p-replicator init && claude
1343
+ ```
390
1344
 
391
- MIT
1345
+ Then in Claude Code: `/replicate "your idea"` (new project) or `/feature add-something` (existing project).