@dzhechkov/p-replicator 1.2.0 → 1.5.2

package/templates/.claude/rules/replicate-pipeline.md

@@ -20,7 +20,7 @@ When executing skills during the pipeline:
 3. When a skill references `/mnt/user-data/uploads/` — read from `docs/` instead
 4. When a skill outputs to `/output/` — write to `docs/` or project root instead
 5. `goap-research` skill name maps to `goap-research-ed25519` in this repo
-6. When a skill has `modules/` directory — read the module file referenced by the phase
+6. **CRITICAL:** When a skill has `modules/` directory — you MUST read the FULL module file for EVERY phase before executing it. SKILL.md is the orchestrator only — it contains summaries, NOT the actual generation logic. NEVER generate artifacts from SKILL.md summaries. In a real project, skipping `modules/04-generate-p1.md` caused 10+ artifacts to be silently omitted.
 7. See `.claude/rules/skill-interface-protocol.md` for full interface specification
 
 ## Modular Skills
@@ -28,6 +28,10 @@ When executing skills during the pipeline:
 Skills with `modules/` directories delegate phases to self-contained module files.
 Each module follows: INPUT → PROCESS → OUTPUT → QUALITY GATE interface.
 
+**MANDATORY:** Before executing any modular skill phase, read the corresponding module file in full.
+Module files contain the actual generation instructions, templates, and quality gates.
+SKILL.md contains only summaries and orchestration logic — it is NOT sufficient for generation.
+
 Currently modularized skills:
 - `cc-toolkit-generator-enhanced` — 9 modules (6 core pipeline + 3 extensions)
 - `knowledge-extractor` — 4 modules (agent review → classify → decontextualize → integrate)
@@ -51,6 +55,47 @@ All generated files go directly into the project. Never create a separate output
 | Dev guide | `DEVELOPMENT_GUIDE.md` |
 | Scaffolds | `docker-compose.yml`, `Dockerfile`, `.gitignore` |
 
+## Alternative entry: starting from existing technical documentation
+
+The pipeline officially supports starting from user-provided technical
+documentation as an alternative to the full Phase 0 (Product Discovery) flow.
+
+### Trigger detection
+
+The orchestrator switches to this entry mode when user input contains any of:
+- A path reference (e.g., "use my docs in `docs/existing/`")
+- An explicit skip request ("skip discovery", "skip Phase 0")
+- A statement of available docs ("I already have technical documentation")
+- The semantic flag `--from-docs <path>` or `--skip-discovery`
+
+### Behavior
+
+When triggered:
+1. Phase 0 is SKIPPED (no reverse-engineering-unicorn invocation)
+2. Phase 1 runs sparc-prd-mini in AUTO mode with pre-filled context from user docs
+3. Phase 1 skips internal Explore/Research/Solve sub-phases (those exist to
+   generate answers that the user already has)
+4. Phase 2 (validation) runs UNCHANGED
+5. Phase 3 (toolkit generation) and Phase 4 (finalize) run UNCHANGED
+
+### Three supported sub-paths
+
+| Path | Use case | Skills invoked |
+|---|---|---|
+| **A** | Full pipeline with existing docs as input | sparc-prd-mini (AUTO) → requirements-validator → cc-toolkit-generator-enhanced |
+| **B** | SPARC docs only, no toolkit/scaffold | sparc-prd-mini (AUTO) only |
+| **C** | Validation-only (docs already SPARC-shaped) | requirements-validator only |
+
+### Test contract preserved
+
+The alternative entry mode preserves:
+- All pre-shipped artifacts (init contract intact)
+- Manifest schema (.p-replicator.json including shippedDefaults)
+- `verify` and `doctor` exit codes
+- All meta-tests (replicate.md ↔ replicate-pipeline.md consistency)
+
+No new flags or state-file fields are required.
+
 ## Architecture Constraints
 
 Always pass these constraints to sparc-prd-mini (Phase 1):
@@ -69,27 +114,59 @@ Commit after each major phase completion:
 - After Phase 3: `feat: Claude Code toolkit for [project-name]`
 - After Phase 4: `chore: initial project setup from SPARC documentation`
 
-## What Gets Generated vs Pre-existing
-
-### Pre-existing (template files — do NOT overwrite)
-- `.claude/skills/*` — all 10 skills (with modules/ subdirectories)
-- `.claude/commands/replicate.md` — this pipeline
-- `.claude/commands/harvest.md` — knowledge extraction pipeline
-- `.claude/agents/replicate-coordinator.md`
-- `.claude/agents/product-discoverer.md`
-- `.claude/agents/doc-validator.md`
-- `.claude/agents/harvest-coordinator.md`
-- `.claude/rules/replicate-pipeline.md` — this file
-- `.claude/rules/skill-interface-protocol.md` — skill composition rules
-
-### Generated by /replicate (create new)
-- `.claude/commands/start.md`, `feature.md`, `plan.md`, `myinsights.md`, `deploy.md`
-- `.claude/agents/planner.md`, `code-reviewer.md`, `architect.md`
-- `.claude/rules/git-workflow.md`, `insights-capture.md`, `feature-lifecycle.md`, `security.md`, `coding-style.md`
-- `.claude/settings.json` — hooks
-- `docs/*` — all documentation
+## What Gets Generated vs Pre-shipped (post v1.4)
+
+### Pre-shipped by `npx @dzhechkov/p-replicator init` (do NOT overwrite)
+
+These files arrive with the package and form the stable workflow toolkit. They
+are project-agnostic and can be enhanced (read by Phase 3) but never recreated.
+
+**Skills (10):** all skills in `.claude/skills/` (`explore`, `sparc-prd-mini`,
+`goap-research-ed25519`, `problem-solver-enhanced`, `requirements-validator`,
+`brutal-honesty-review`, `cc-toolkit-generator-enhanced`,
+`reverse-engineering-unicorn`, `pipeline-forge`, `knowledge-extractor`)
+
+**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:** `.claude/settings.json` (SessionStart + Stop) + cross-platform Node
+scripts in `.claude/hooks/` (`session-insights.cjs`, `autocommit-roadmap.cjs`,
+`autocommit-insights.cjs`, `autocommit-plans.cjs`)
+
+### Generated by /replicate Phase 3 (project-specific — create new)
+
+These exist only AFTER `/replicate` runs because they encode project-specific
+data extracted from SPARC docs.
+
+- `.claude/agents/planner.md` — algorithm templates from Pseudocode.md
+- `.claude/agents/code-reviewer.md` — edge cases from Refinement.md
+- `.claude/agents/architect.md` — system design from Architecture.md
+- `.claude/rules/security.md` — NFRs from Specification.md
+- `.claude/rules/coding-style.md` — tech-stack conventions
+- `.claude/rules/secrets-management.md` — IF external APIs detected
+- `.claude/rules/testing.md` — test strategy from Refinement.md
+- `.claude/skills/project-context/` — domain knowledge
+- `.claude/skills/coding-standards/` — tech-specific patterns
+- `.claude/skills/security-patterns/` — IF external APIs
+- `.claude/feature-roadmap.json` — feature list from PRD MVP scope
+- `.claude/commands/feature-ent.md` — IF DDD docs (idea2prd-manual)
+- `.mcp.json` — IF external integrations
 - `CLAUDE.md`, `README.md`, `DEVELOPMENT_GUIDE.md`
 - `docker-compose.yml`, `Dockerfile`, `.gitignore`
+- `docs/*` — all SPARC documentation
+
+### Post-pipeline verification
+
+After `/replicate` completes, run `npx @dzhechkov/p-replicator verify` to
+confirm both contracts (pre-shipped + post-/replicate). The `verify` command
+detects whether `/replicate` was run (via CLAUDE.md or feature-roadmap.json)
+and reports per-artifact status.
 
 ## Checkpoint Format
 

package/templates/.claude/settings.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://www.schemastore.org/claude-code-settings.json",
+  "_comment": "Default hooks + statusline shipped by @dzhechkov/p-replicator init. Cross-platform Node scripts (no bash dependencies). Auto-commits roadmap/insights/plans on Stop, injects relevant insights on SessionStart. Statusline displays pipeline+roadmap+toolkit dashboard above the prompt. Project-specific hooks (DDD, fitness functions, etc.) are merged in by /replicate Phase 3.",
+  "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
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/.claude/skills/brutal-honesty-review/SKILL.md

@@ -136,6 +136,49 @@ higher quality. They don't."
 
 ---
 
+## Security Review Checklist (Linus Mode — CRITICAL)
+
+When reviewing code that handles authentication, authorization, data storage,
+or external integrations, apply this checklist in addition to standard code quality:
+
+### OWASP Top 10 Quick Checks
+
+| # | Vulnerability | What to Look For | Severity |
+|---|--------------|-------------------|----------|
+| A01 | Broken Access Control | Missing auth middleware, RLS bypass (pool.query vs dbClient), cross-tenant entity access without ownership check | CRITICAL |
+| A02 | Cryptographic Failures | Weak JWT secrets with fallback defaults, hardcoded secrets, missing HMAC on webhooks | CRITICAL |
+| A03 | Injection | SQL via string interpolation (SET LOCAL), template literals in queries, unsanitized user input in commands | CRITICAL |
+| A04 | Insecure Design | Per-request stateful services (circuit breakers never trigger), missing rate limiting | HIGH |
+| A05 | Security Misconfiguration | Same CORS policy across environments, verbose errors in production, missing security headers | HIGH |
+| A07 | Auth Failures | No account lockout, weak password policy, session fixation | HIGH |
+| A08 | Data Integrity | Unsigned webhook payloads, missing CSRF tokens, unvalidated redirects | HIGH |
+| A09 | Logging Failures | No audit trail for auth events, PII in logs, missing failed-attempt logging | MEDIUM |
+
+### Multi-Tenant Security (if applicable)
+
+- [ ] All DB queries use tenant-scoped connection, NOT shared pool
+- [ ] SET LOCAL uses parameterized set_config(), NOT string interpolation
+- [ ] Cross-entity references verify tenant ownership before operation
+- [ ] Tenant isolation tested with cross-tenant attack scenarios
+
+### Secret Management
+
+- [ ] All secrets validated at startup — missing = process.exit(1)
+- [ ] No fallback defaults for security-critical secrets
+- [ ] Secrets never appear in logs, error messages, or stack traces
+- [ ] Environment-specific security posture (dev/staging/prod)
+
+### Webhook Security
+
+- [ ] Every webhook endpoint verifies request signature/HMAC
+- [ ] Unsigned payloads are rejected and logged
+- [ ] Webhook secrets stored in environment variables
+
+**Calibration:** Security violations ALWAYS trigger Level 3 (Brutal).
+Security bugs are not "style issues" — they are negligence.
+
+---
+
 ## Assessment Rubrics
 
 ### Code Quality (Linus Mode)

package/templates/.claude/skills/cc-toolkit-generator-enhanced/SKILL.md

@@ -18,6 +18,14 @@ description: >
   Three modes: AUTO, HYBRID (default), MANUAL.
 ---
 
+> **CRITICAL MODULE LOADING REQUIREMENT:**
+> This skill has 9 modules in `modules/`. SKILL.md is the orchestrator ONLY.
+> You MUST read EVERY module file referenced in the Module Execution Protocol below
+> before executing its phase. Skipping module files causes entire artifact categories
+> to be silently omitted. In one real project, skipping `modules/04-generate-p1.md`
+> caused 10+ P1 artifacts (agents, skills, commands) to be completely missing.
+> NEVER generate artifacts from SKILL.md summaries alone — always read the full module.
+
 # CC-Toolkit-Generator Enhanced
 
 Generate production-ready Claude Code instruments from **SPARC or idea2prd-manual documentation**.

package/templates/.claude/skills/cc-toolkit-generator-enhanced/modules/03-generate-p0.md

@@ -27,6 +27,12 @@ From the Instrument Map this module uses:
 
 ## Process
 
+> **ANTI-COMPRESSION DIRECTIVE:** When generating files from templates in this module,
+> COPY the FULL text of each template. Do NOT summarize, compress, or "interpret" templates.
+> Every section, every placeholder, every comment must be preserved verbatim.
+> AI systems routinely compress 211-line templates to 60 lines — this is a CRITICAL defect.
+> Validate: generated file line count must be >= 80% of template line count.
+
 ### P0 Mandatory Items (always generated)
 
 The following 16 items are generated for every project, regardless of pipeline
@@ -37,6 +43,7 @@ type or user mode.
 #### Item 1: CLAUDE.md
 
 **Template:** `view() references/claude-md-strategy.md`
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 The project's root context file. Generation strategy differs by pipeline:
 
@@ -154,6 +161,39 @@ Generate `.claude/rules/coding-style.md` containing:
 - Code organization patterns
 - IF idea2prd: DDD tactical patterns (aggregate rules, entity identity, VO immutability)
 
+**Known Gotchas section (always include):**
+
+Add a `## Known Gotchas` section to coding-style.md with language/framework-specific
+pitfalls extracted from harvest insights. Include at minimum:
+
+```markdown
+## Known Gotchas
+
+### TypeScript / JavaScript
+- `\w` in regex does NOT match Cyrillic or other non-Latin characters.
+  Use `\p{L}` with `/u` flag or explicit character classes for Unicode text.
+- Direct type casting `req as CustomType` fails with TS2352. Use double-cast
+  via `unknown`: `(req as unknown as CustomType)`. Better: use generic route handlers.
+- Jest `coverageThreshold` (singular) silently fails if spelled `coverageThresholds` (plural).
+  Per-directory thresholds require a `global` key. ts-jest needs `ts-node` as peer dependency.
+- `jest.fn(async () => value)` doesn't satisfy `jest.Mocked<T>` in strict mode.
+  Use `jest.fn().mockResolvedValue(value)` or `jest.fn().mockImplementation(...)`.
+- Opossum `CircuitBreaker.fire()` returns `Promise<unknown>`, requires explicit cast.
+  Both `@types/opossum` and `opossum` packages are needed.
+- Socket.io `Server` has no `.toRoom()` method. Wrap it:
+  `{ toRoom: (room) => io.to(room) }` for hexagonal architecture ports.
+
+### Infrastructure
+- Services with circuit breakers/rate limiters MUST be singletons.
+  Per-request instances bypass protection (breaker never accumulates failures).
+- `SET LOCAL` in PostgreSQL only affects the current transaction on the current connection.
+  Use parameterized `set_config()` instead of string interpolation.
+```
+
+Adapt gotchas to the specific tech stack detected in IPM. Remove irrelevant entries
+(e.g., no TypeScript gotchas for Python projects). Add stack-specific gotchas from
+`view() references/security-patterns-library.md` if applicable.
+
 **Output path:** `.claude/rules/coding-style.md`
 
 ---
@@ -161,6 +201,7 @@ Generate `.claude/rules/coding-style.md` containing:
 #### Item 4: /start command
 
 **Template:** `view() references/templates/start-command.md`
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 Generate `.claude/commands/start.md` -- the full project bootstrap command.
 
@@ -189,6 +230,7 @@ code from memory. Every Phase 2 Task includes explicit doc references.
 #### Item 5: /myinsights command
 
 **Template:** `view() references/templates/insights-system.md` (Section 1)
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 Generate `.claude/commands/myinsights.md` -- the insight capture and management
 command with:
@@ -207,6 +249,7 @@ command with:
 #### Item 6: /feature command
 
 **Template:** `view() references/templates/feature-lifecycle.md` (Section 2)
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 Generate `.claude/commands/feature.md` -- the 4-phase feature lifecycle command:
 
@@ -278,6 +321,7 @@ type(scope): description
 #### Item 8: insights-capture.md rule
 
 **Template:** `view() references/templates/insights-system.md` (Section 2)
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 Generate `.claude/rules/insights-capture.md` with:
 - Error-First Lookup protocol (grep index BEFORE debugging)
@@ -293,6 +337,7 @@ Generate `.claude/rules/insights-capture.md` with:
 #### Item 9: feature-lifecycle.md rule
 
 **Template:** `view() references/templates/feature-lifecycle.md` (Section 3)
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 Generate `.claude/rules/feature-lifecycle.md` with:
 - Protocol definition (4-phase lifecycle)
@@ -310,6 +355,7 @@ Generate `.claude/rules/feature-lifecycle.md` with:
 #### Item 10: settings.json hooks
 
 **Template:** `view() references/templates/insights-system.md` (Section 3 -- Stop hook)
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 Generate `.claude/settings.json` with hook configuration:
 

package/templates/.claude/skills/cc-toolkit-generator-enhanced/modules/04-generate-p1.md

@@ -19,6 +19,12 @@ engine and conditionally included based on project characteristics and document
 
 ## Process
 
+> **ANTI-COMPRESSION DIRECTIVE:** When generating files from templates in this module,
+> COPY the FULL text of each template. Do NOT summarize, compress, or "interpret" templates.
+> Every section, every placeholder, every comment must be preserved verbatim.
+> AI systems routinely compress 211-line templates to 60 lines — this is a CRITICAL defect.
+> Validate: generated file line count must be >= 80% of template line count.
+
 ### Step 1: Filter P1 Candidates
 
 Select all instruments assigned tier P1 from the Instrument Map (score >= 12 after tier boosts).
@@ -208,6 +214,7 @@ Generate .claude/rules/testing.md:
 **Trigger:** `IPM.has_ddd == true`
 
 Read complete template: `view("references/templates/feature-lifecycle-ent.md")`
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 ```
 IF has_ddd:
@@ -254,6 +261,7 @@ IF has_ddd:
 **Trigger:** Always generated for P1 (enhances developer workflow regardless of pipeline).
 
 Read complete template: `view("references/templates/feature-suggestions.md")`
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 ```
 7a. Generate .claude/feature-roadmap.json
@@ -305,6 +313,7 @@ Read complete template: `view("references/templates/feature-suggestions.md")`
 **Trigger:** Always generated for P1 (provides autonomous execution capabilities).
 
 Read complete template: `view("references/templates/automation-commands.md")`
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 ```
 8a. Generate .claude/commands/go.md

package/templates/.claude/skills/cc-toolkit-generator-enhanced/modules/05-generate-p2p3.md

@@ -22,6 +22,12 @@ when DDD documentation is detected.
 
 ## Process
 
+> **ANTI-COMPRESSION DIRECTIVE:** When generating files from templates in this module,
+> COPY the FULL text of each template. Do NOT summarize, compress, or "interpret" templates.
+> Every section, every placeholder, every comment must be preserved verbatim.
+> AI systems routinely compress 211-line templates to 60 lines — this is a CRITICAL defect.
+> Validate: generated file line count must be >= 80% of template line count.
+
 ### Tier Overview
 
 ```
@@ -41,6 +47,7 @@ P3 — External Integrations:
 Source: Pseudocode (SPARC/idea2prd) + Gherkin tests (idea2prd) + Fitness Functions (idea2prd)
 
 Read template: `view("references/templates/ddd-agents.md")` section "tdd-guide.md Agent (Enhanced)"
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 ```
 Generate .claude/agents/tdd-guide.md:
@@ -156,6 +163,7 @@ skip this entire step.
 Source: DDD Tactical (aggregates) + Fitness Functions
 
 Read template: `view("references/templates/ddd-agents.md")` section "ddd-validator.md Agent"
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 ```
 IF has_ddd:
@@ -191,6 +199,7 @@ IF has_ddd:
 Source: DDD Tactical (aggregates, entities, value-objects)
 
 Read template: `view("references/templates/ddd-skills.md")` section "aggregate-patterns/ Skill"
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 ```
 IF has_ddd:
@@ -213,6 +222,7 @@ IF has_ddd:
 Source: DDD Tactical (events)
 
 Read template: `view("references/templates/ddd-skills.md")` section "event-handlers/ Skill"
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 ```
 IF has_ddd:
@@ -284,6 +294,7 @@ IF has_ddd AND has_fitness:
 ### Step 3: Generate P3 Items — MCP Configuration
 
 Read complete template: `view("references/templates/mcp.md")`
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
 
 ```
 Generate .mcp.json in project root:

package/templates/.claude/skills/cc-toolkit-generator-enhanced/modules/06-package-deliver.md

@@ -216,6 +216,52 @@ CHECK 20: P3 MCP (IF external integrations detected)
   [ ] INSTALL.md documents all required env vars from .mcp.json
 ```
 
+### Step 1.5: Automated File-Existence Validation
+
+Before proceeding to placeholder scanning, run an automated file-existence check
+against the expected output manifest. This catches the most common generation failure:
+files that should exist but were silently omitted (often due to skipping module files).
+
+```
+AUTOMATED FILE CHECK PROTOCOL:
+
+Step 1: Build expected file list from Instrument Map tiers:
+  - P0 mandatory: 16 items (always expected)
+  - P0 conditional: check IPM flags before expecting
+  - P1 core: 10 items (if P1 was executed)
+  - P1 conditional: check IPM flags
+  - P2/P3: check flags and execution status
+
+Step 2: For each expected file, run existence check:
+  for file in expected_files:
+    if not exists(file.path):
+      log CRITICAL: "Missing file: {file.path} (expected from {file.phase})"
+      missing_count++
+
+Step 3: For each expected directory, verify SKILL.md exists inside:
+  for skill_dir in expected_skill_directories:
+    if not exists(skill_dir + "/SKILL.md"):
+      log CRITICAL: "Missing SKILL.md in {skill_dir}"
+      missing_count++
+
+Step 4: Verify file sizes (anti-compression check):
+  for file in generated_files:
+    if file.size_bytes < 100:
+      log WARNING: "Suspiciously small file: {file.path} ({file.size_bytes} bytes)"
+      log WARNING: "Possible template compression — verify content completeness"
+
+Step 5: Report
+  if missing_count > 0:
+    CRITICAL FAILURE: {missing_count} expected files are missing.
+    List each missing file with its expected source phase/module.
+    Attempt auto-fix by re-reading the relevant module and regenerating.
+  else:
+    PASS: All {total_count} expected files exist.
+```
+
+This step was added based on a real-project insight where skipping `modules/04-generate-p1.md`
+caused 10+ P1 artifacts to be silently omitted without any error in the final report.
+
 ### Step 2: Verify Placeholder Substitution
 
 Scan ALL generated files for unsubstituted placeholders: