@dzhechkov/p-replicator 1.0.0

package/src/utils.js

@@ -0,0 +1,280 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ===========================================================================
+// Colors — ANSI escape codes (zero dependencies)
+// ===========================================================================
+
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function wrap(code, text) {
+  if (!supportsColor) return text;
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+function green(text)  { return wrap('32', text); }
+function red(text)    { return wrap('31', text); }
+function yellow(text) { return wrap('33', text); }
+function blue(text)   { return wrap('34', text); }
+function cyan(text)   { return wrap('36', text); }
+function bold(text)   { return wrap('1',  text); }
+function dim(text)    { return wrap('2',  text); }
+function gray(text)   { return wrap('90', text); }
+
+// ===========================================================================
+// Logging
+// ===========================================================================
+
+function info(msg)    { console.log(blue('[INFO]') + ' ' + msg); }
+function success(msg) { console.log(green('[OK]') + '   ' + msg); }
+function warn(msg)    { console.log(yellow('[WARN]') + ' ' + msg); }
+function error(msg)   { console.log(red('[ERROR]') + ' ' + msg); }
+
+function step(n, total, msg) {
+  console.log(cyan(`[${n}/${total}]`) + ' ' + msg);
+}
+
+// ===========================================================================
+// File operations — all synchronous, Node.js built-ins only
+// ===========================================================================
+
+/**
+ * Copy a directory recursively from src to dest, creating dirs as needed.
+ */
+function copyDirRecursive(src, dest) {
+  const stat = fs.statSync(src);
+
+  if (stat.isFile()) {
+    ensureDir(path.dirname(dest));
+    fs.copyFileSync(src, dest);
+    return;
+  }
+
+  if (stat.isDirectory()) {
+    ensureDir(dest);
+    const entries = fs.readdirSync(src);
+    for (const entry of entries) {
+      copyDirRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  }
+}
+
+/**
+ * Copy a directory recursively, but only include files matching a filter.
+ */
+function copyDirFiltered(src, dest, filterFn) {
+  const stat = fs.statSync(src);
+
+  if (!stat.isDirectory()) {
+    if (filterFn(path.basename(src))) {
+      ensureDir(path.dirname(dest));
+      fs.copyFileSync(src, dest);
+    }
+    return;
+  }
+
+  ensureDir(dest);
+  const entries = fs.readdirSync(src);
+  for (const entry of entries) {
+    if (!filterFn(entry)) continue;
+    const srcEntry = path.join(src, entry);
+    const destEntry = path.join(dest, entry);
+    const entryStat = fs.statSync(srcEntry);
+
+    if (entryStat.isDirectory()) {
+      copyDirRecursive(srcEntry, destEntry);
+    } else {
+      fs.copyFileSync(srcEntry, destEntry);
+    }
+  }
+}
+
+/**
+ * Returns true if the path exists.
+ */
+function fileExists(filePath) {
+  try {
+    fs.accessSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read and parse a JSON file. Returns null if not found or invalid.
+ */
+function readJSON(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write an object as JSON with 2-space indentation.
+ */
+function writeJSON(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Create a directory (and parents) if it does not exist.
+ */
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+/**
+ * Return an array of all file paths relative to `dir`, traversed recursively.
+ */
+function getRelativePaths(dir) {
+  const results = [];
+
+  function walk(current, rel) {
+    const entries = fs.readdirSync(current);
+    for (const entry of entries) {
+      const full = path.join(current, entry);
+      const relPath = rel ? path.join(rel, entry) : entry;
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        walk(full, relPath);
+      } else {
+        results.push(relPath);
+      }
+    }
+  }
+
+  if (fileExists(dir) && fs.statSync(dir).isDirectory()) {
+    walk(dir, '');
+  }
+
+  return results;
+}
+
+/**
+ * Compare files between srcDir and destDir.
+ * Returns { added, modified, unchanged, missing }.
+ */
+function diffFiles(srcDir, destDir) {
+  const srcFiles = new Set(getRelativePaths(srcDir));
+  const destFiles = new Set(getRelativePaths(destDir));
+
+  const added = [];
+  const modified = [];
+  const unchanged = [];
+  const missing = [];
+
+  for (const rel of srcFiles) {
+    if (!destFiles.has(rel)) {
+      added.push(rel);
+    } else {
+      const srcContent = fs.readFileSync(path.join(srcDir, rel));
+      const destContent = fs.readFileSync(path.join(destDir, rel));
+      if (srcContent.equals(destContent)) {
+        unchanged.push(rel);
+      } else {
+        modified.push(rel);
+      }
+    }
+  }
+
+  for (const rel of destFiles) {
+    if (!srcFiles.has(rel)) {
+      missing.push(rel);
+    }
+  }
+
+  return { added, modified, unchanged, missing };
+}
+
+// ===========================================================================
+// Manifest — .p-replicator.json management
+// ===========================================================================
+
+const MANIFEST_FILE = '.p-replicator.json';
+
+function readManifest(targetDir) {
+  return readJSON(path.join(targetDir, MANIFEST_FILE));
+}
+
+function writeManifest(targetDir, data) {
+  writeJSON(path.join(targetDir, MANIFEST_FILE), data);
+}
+
+function createManifest(version, components, files) {
+  return {
+    version: version,
+    installedAt: new Date().toISOString(),
+    components: components,
+    files: files,
+  };
+}
+
+// ===========================================================================
+// Templates path
+// ===========================================================================
+
+function getTemplatesDir() {
+  return path.join(__dirname, '..', 'templates');
+}
+
+// ===========================================================================
+// Component definitions — PU Unicorn Replicate
+//
+// All components are installed as complete directories (no prefix filtering
+// needed since this is a complete package).
+// ===========================================================================
+
+const COMPONENTS = {
+  skills: {
+    src: '.claude/skills',
+    label: 'Skills (10 skill packs)',
+    group: 'core',
+  },
+  commands: {
+    src: '.claude/commands',
+    label: 'Commands (/replicate, /harvest)',
+    group: 'core',
+  },
+  agents: {
+    src: '.claude/agents',
+    label: 'Agents (4 orchestrators)',
+    group: 'core',
+  },
+  rules: {
+    src: '.claude/rules',
+    label: 'Rules (pipeline constraints)',
+    group: 'core',
+  },
+};
+
+// ===========================================================================
+// Exports
+// ===========================================================================
+
+module.exports = {
+  // Colors
+  green, red, yellow, blue, cyan, bold, dim, gray,
+
+  // Logging
+  info, success, warn, error, step,
+
+  // File operations
+  copyDirRecursive, copyDirFiltered, fileExists, readJSON, writeJSON,
+  ensureDir, getRelativePaths, diffFiles,
+
+  // Manifest
+  MANIFEST_FILE, readManifest, writeManifest, createManifest,
+
+  // Templates
+  getTemplatesDir,
+
+  // Components
+  COMPONENTS,
+};

package/templates/.claude/agents/doc-validator.md

@@ -0,0 +1,92 @@
+# Documentation Validator Agent
+
+Validates SPARC documentation for completeness, testability, and implementation readiness.
+Uses swarm of parallel validation sub-agents.
+
+## When to Use
+
+Activated during `/replicate` Phase 2 after SPARC documentation is generated.
+Also usable standalone to re-validate documentation at any time.
+
+## Skill Reference
+
+Uses `requirements-validator` skill.
+Read from: `.claude/skills/requirements-validator/SKILL.md`
+
+## Swarm Strategy
+
+Launch 5 parallel validation agents using Task tool:
+
+| Agent | Scope | Criteria | Tool |
+|-------|-------|----------|------|
+| `validator-stories` | PRD → User Stories | INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable) | Task |
+| `validator-acceptance` | Stories → AC | SMART (Specific, Measurable, Achievable, Relevant, Time-bound) | Task |
+| `validator-architecture` | Architecture.md | Target constraints compliance, completeness | Task |
+| `validator-pseudocode` | Pseudocode.md | Story coverage, implementability | Task |
+| `validator-coherence` | Cross-document | Consistency, no contradictions | Task |
+
+## Scoring System
+
+- 0-49: BLOCKED (must fix before proceeding)
+- 50-69: WARNING (should improve)
+- 70-100: READY (proceed to toolkit generation)
+
+## Iterative Process (max 3 iterations)
+
+```
+Iteration N:
+  1. ANALYZE — parallel 5 validator agents
+  2. AGGREGATE — Gap Register + scoring
+  3. FIX — resolve gaps in documentation
+  4. RE-VALIDATE — re-check fixes
+
+Exit criteria:
+  - No BLOCKED (score <50)
+  - Average score ≥70
+  - No contradictions between documents
+
+If NOT met and N < 3 → next iteration
+If met OR N = 3 → exit with verdict
+```
+
+## BDD Scenarios Generation
+
+Automatically generate Gherkin scenarios from validated user stories:
+- Happy path (1-2 scenarios per story)
+- Error handling (2-3 scenarios)
+- Edge cases (1-2 scenarios)
+- Security scenarios (if applicable)
+
+Save to: `docs/test-scenarios.md`
+
+## Output
+
+### Validation Report (`docs/validation-report.md`)
+
+```markdown
+# Validation Report
+
+## Summary
+- Iteration: [N] of max 3
+- Average score: XX/100
+- Blocked/Warnings: X/X → Fixed: X/X
+
+## Gap Register
+| ID | Document | Issue | Severity | Status |
+|----|----------|-------|----------|--------|
+
+## Cross-Document Consistency
+| Check | Status | Notes |
+|-------|--------|-------|
+
+## Readiness Verdict
+🟢 READY / 🟡 CAVEATS / 🔴 NEEDS WORK
+```
+
+### Verdicts
+
+| Verdict | Conditions | Action |
+|---------|-----------|--------|
+| 🟢 READY | All scores ≥50, average ≥70, no contradictions | → Phase 3 |
+| 🟡 CAVEATS | Warnings exist, no blocked, limitations described | → Phase 3 with notes |
+| 🔴 NEEDS WORK | Blocked items exist | → Return to Phase 1 |

package/templates/.claude/agents/harvest-coordinator.md

@@ -0,0 +1,91 @@
+# Harvest Coordinator Agent
+
+Orchestrates knowledge extraction from projects using a swarm of parallel
+extraction agents. Coordinates the 4-phase harvest pipeline.
+
+## When to Use
+
+Activated by the `/harvest` command. Also invocable directly when extracting
+knowledge from a completed project or sprint.
+
+## Skill Reference
+
+Uses `knowledge-extractor` skill.
+Read from: `.claude/skills/knowledge-extractor/SKILL.md`
+
+## Responsibilities
+
+1. **Swarm Management** — launch and coordinate 5 parallel extraction agents (Phase 1)
+2. **Classification** — categorize findings into 7 artifact types (Phase 2)
+3. **Quality Enforcement** — ensure decontextualization quality gate passes (Phase 3)
+4. **Integration** — write artifacts and update toolkit index (Phase 4)
+5. **Reporting** — produce harvest report with recommendations
+
+## Swarm Strategy (Phase 1)
+
+Launch 5 parallel agents via Task tool:
+
+| Agent | Scope | Focus |
+|-------|-------|-------|
+| `extractor-patterns` | Architecture & code | Middleware, error handling, data access |
+| `extractor-commands` | Scripts & CLI | Build scripts, dev utilities, commands |
+| `extractor-rules` | Constraints & lessons | TODOs, HACKs, edge cases in tests |
+| `extractor-templates` | Configs & structures | Docker, CI/CD, linter configs |
+| `extractor-snippets` | Code fragments | Utils, helpers, one-liners |
+
+**Each agent receives:**
+- Project root path
+- `TOOLKIT_HARVEST.md` content (if exists)
+- Instructions from its module section in `modules/01-agent-review.md`
+
+**Merge results:** Deduplicate, cross-reference, sort by reusability confidence.
+
+## Quality Gate (Phase 3)
+
+For each artifact, verify before integration:
+
+| Check | Blocking? |
+|-------|-----------|
+| No project-specific names | YES |
+| No hardcoded paths | YES |
+| "When to use" section | YES |
+| "When NOT to use" section | YES |
+| Prerequisites documented | YES |
+| Code compiles standalone | YES (code artifacts) |
+| Maturity level assigned | YES |
+| At least 1 variant | NO |
+
+If `brutal-honesty-review` skill available → apply Bach-mode BS detection.
+
+## Artifact Categories
+
+| Category | Target Location |
+|----------|----------------|
+| Skills | `.claude/skills/[name]/SKILL.md` |
+| Commands | `.claude/commands/[name].md` |
+| Hooks | `.claude/settings.json` |
+| Rules | `.claude/rules/[name].md` |
+| Templates | `templates/[name]/` |
+| Patterns | `docs/patterns/[name].md` |
+| Snippets | `snippets/[lang]/[name].[ext]` |
+
+## Output
+
+### Per Phase
+- Phase 1: Raw Findings List (N candidates)
+- Phase 2: Classified Artifact List (M extract, K skip)
+- Phase 3: Generalized Artifacts (decontextualized, documented)
+- Phase 4: Harvest Report + Updated Toolkit
+
+### Git Commit
+```
+chore: harvest [N] artifacts from [project-name]
+```
+
+## Integration with Other Skills
+
+| Skill | Phase | Purpose |
+|-------|-------|---------|
+| `explore` | Phase 1 | Clarify extraction scope |
+| `brutal-honesty-review` | Phase 3 | BS-detect unworthy artifacts |
+| `pipeline-forge` | Phase 4 | Structure new skills properly |

package/templates/.claude/agents/product-discoverer.md

@@ -0,0 +1,57 @@
+# Product Discoverer Agent
+
+Performs competitive analysis and market research for Phase 0 of the `/replicate` pipeline.
+
+## When to Use
+
+Activated during `/replicate` Phase 0 when the project is a new product, startup, or SaaS.
+Skipped for internal tools and experiments.
+
+## Skill Reference
+
+Uses `reverse-engineering-unicorn` skill in QUICK mode.
+Read from: `.claude/skills/reverse-engineering-unicorn/SKILL.md`
+
+## Selected Modules (QUICK mode)
+
+| Module | When | Output |
+|--------|------|--------|
+| M2: Product & Customers | Always | JTBD, Value Prop, segments |
+| M3: Market & Competition | Always | TAM/SAM, competitors, Blue Ocean Canvas |
+| M4: Business & Finance | If monetization model needed | Unit economics |
+| M5: Growth Engine | If B2C/PLG | Channels, integrations, viral loops |
+
+## Output Format
+
+Product Discovery Brief — structured markdown passed as pre-filled context to Phase 1 (sparc-prd-mini):
+
+```markdown
+## Product Discovery Brief
+
+### Target Segments
+[From JTBD analysis]
+
+### Key Competitors
+| Competitor | Strengths | Weaknesses | Differentiation |
+|------------|-----------|------------|-----------------|
+
+### Blue Ocean Canvas
+[From strategy canvas analysis]
+
+### Monetization Model
+[From unit economics — if applicable]
+
+### Growth Channels
+[From growth engine analysis — if applicable]
+
+### Key Insights for PRD
+[Top 3-5 insights that should inform product planning]
+```
+
+## Anti-Hallucination Rules
+
+- Search first — never answer from memory for facts
+- Source attribution — every fact → URL
+- "НЕ НАЙДЕНО" > fabrication
+- Hypotheses marked with `[H]` tag
+- Confidence score at end

package/templates/.claude/agents/replicate-coordinator.md

@@ -0,0 +1,98 @@
+# Replicate Coordinator Agent
+
+Orchestrates the full `/replicate` pipeline — from product idea to ready-to-code project.
+
+## When to Use
+
+Activated automatically by the `/replicate` command. Do NOT invoke directly.
+
+## Responsibilities
+
+1. **Phase Management** — ensure correct phase sequence (0 → 1 → 2 → 3 → 4)
+2. **Context Passing** — carry forward outputs between phases:
+   - Phase 0 → Phase 1: Product Discovery Brief
+   - Phase 1 → Phase 2: 11 SPARC documents
+   - Phase 2 → Phase 3: Validated docs + test-scenarios
+   - Phase 3 → Phase 4: Complete toolkit
+3. **Skill Coordination** — read and apply skills from `.claude/skills/`
+4. **Quality Gates** — enforce checkpoints between phases
+5. **In-Place Generation** — write all files directly into the project (no zip, no output/)
+
+## Architecture Constraints (always pass to Phase 1)
+
+```yaml
+Architecture Constraints:
+  pattern: "Distributed Monolith (Monorepo)"
+  containers: "Docker + Docker Compose"
+  infrastructure: "VPS (AdminVPS/HOSTKEY)"
+  deploy: "Docker Compose direct deploy (SSH / CI pipeline)"
+  ai_integration: "MCP servers"
+```
+
+## Skill Path Mapping (claude.ai → Claude Code)
+
+When skills reference `/mnt/skills/user/` paths, map them:
+
+| claude.ai path | Claude Code path |
+|----------------|------------------|
+| `/mnt/skills/user/explore/` | `.claude/skills/explore/` |
+| `/mnt/skills/user/goap-research/` | `.claude/skills/goap-research-ed25519/` |
+| `/mnt/skills/user/goap-research-ed25519/` | `.claude/skills/goap-research-ed25519/` |
+| `/mnt/skills/user/problem-solver-enhanced/` | `.claude/skills/problem-solver-enhanced/` |
+| `/mnt/skills/user/sparc-prd-mini/` | `.claude/skills/sparc-prd-mini/` |
+| `/mnt/skills/user/requirements-validator/` | `.claude/skills/requirements-validator/` |
+| `/mnt/skills/user/cc-toolkit-generator-enhanced/` | `.claude/skills/cc-toolkit-generator-enhanced/` |
+| `/mnt/skills/user/reverse-engineering-unicorn/` | `.claude/skills/reverse-engineering-unicorn/` |
+| `/mnt/skills/user/brutal-honesty-review/` | `.claude/skills/brutal-honesty-review/` |
+
+## Output Path Mapping (claude.ai → Claude Code)
+
+| claude.ai path | Claude Code path |
+|----------------|------------------|
+| `/output/[name]-sparc/` | `docs/` |
+| `/mnt/user-data/uploads/` | `docs/` |
+| `[project-name]-cc-toolkit/` | project root (in-place) |
+| `[project-name].zip` | N/A (no packaging) |
+
+## What /replicate Generates
+
+After full pipeline execution, these files are created/modified:
+
+### Generated Commands
+- `.claude/commands/start.md` — project bootstrap
+- `.claude/commands/feature.md` — 4-phase feature lifecycle
+- `.claude/commands/plan.md` — implementation planning
+- `.claude/commands/myinsights.md` — insights capture
+- `.claude/commands/deploy.md` — deployment workflow
+- `.claude/commands/test.md` — test generation (if applicable)
+
+### Generated Agents
+- `.claude/agents/planner.md` — from Pseudocode.md
+- `.claude/agents/code-reviewer.md` — from Refinement.md
+- `.claude/agents/architect.md` — from Architecture.md + Solution_Strategy.md
+
+### Generated Rules
+- `.claude/rules/git-workflow.md` — semantic commit conventions
+- `.claude/rules/insights-capture.md` — insight capture protocol
+- `.claude/rules/feature-lifecycle.md` — feature development protocol
+- `.claude/rules/security.md` — from Specification.md NFRs
+- `.claude/rules/coding-style.md` — from Architecture.md tech stack
+- `.claude/rules/secrets-management.md` — IF external APIs
+
+### Generated/Modified Config
+- `.claude/settings.json` — hooks (insights auto-commit on Stop)
+- `.mcp.json` — IF external integrations
+
+### Generated Documentation
+- `docs/*.md` — 11+ SPARC documents
+- `docs/validation-report.md` — validation results
+- `docs/test-scenarios.md` — BDD/Gherkin scenarios
+- `docs/features/` — empty dir for future features
+
+### Generated Root Files
+- `CLAUDE.md` — enhanced with project-specific content
+- `DEVELOPMENT_GUIDE.md` — step-by-step dev lifecycle
+- `README.md` — enhanced with project info
+- `docker-compose.yml` — from Architecture.md
+- `Dockerfile` — from Architecture.md tech stack
+- `.gitignore` — if not exists