@dzhechkov/p-replicator 1.3.0 → 1.5.3

package/templates/.claude/commands/go.md

@@ -0,0 +1,115 @@
+---
+description: Intelligent feature implementation router. Scores complexity and dispatches to /plan (simple), /feature (standard), or /feature-ent (complex + enterprise, only if available). Executes autonomously without per-phase confirmations. Supports `--feature-branches` for per-feature git branch workflow (teaching/demo).
+argument-hint: '[feature-name | feature-id | description] [--feature-branches] [--auto-merge]'
+---
+
+# /go $ARGUMENTS
+
+## Purpose
+
+One-command feature implementation that picks the right pipeline by scoring
+complexity, then runs it without interactive checkpoints.
+
+## Step 1: Determine Target Feature
+
+```
+IF $ARGUMENTS provided:
+  Parse as feature-name | roadmap-id | free-form description
+  Look up in .claude/feature-roadmap.json if it matches an id
+ELSE:
+  Run /next logic — pick highest-priority `next`/`planned` feature
+  Confirm selection before proceeding
+```
+
+## Step 2: Detect Available Pipelines
+
+```
+✅ /plan        — always available
+✅ /feature     — always available
+⚠️ /feature-ent — ONLY if .claude/commands/feature-ent.md exists
+                  (generated by idea2prd-manual pipeline with DDD docs)
+
+CHECK: feature_ent_available = fileExists(".claude/commands/feature-ent.md")
+```
+
+## Step 3: Score Complexity
+
+| Signal | Score |
+|--------|-------|
+| Touches ≤ 3 files | -2 |
+| Touches 4-10 files | 0 |
+| Touches > 10 files | +3 |
+| External API integration | +2 |
+| New database entities | +2 |
+| Cross-bounded-context dependencies | +3 |
+| Hotfix or minor improvement | -3 |
+| DDD docs in `docs/ddd/` exist | +1 |
+| Gherkin scenarios for this feature | +1 |
+| Estimated < 30 min | -2 |
+| Estimated > 2 hours | +3 |
+
+## Step 4: Decision Matrix
+
+| Total Score | Pipeline | Rationale |
+|-------------|----------|-----------|
+| ≤ -2 | `/plan` | Simple, lightweight plan suffices |
+| -1 to +4 | `/feature` | Standard SPARC-mini lifecycle |
+| ≥ +5 AND `feature_ent_available` | `/feature-ent` | Complex enterprise with DDD/ADR/C4 |
+| ≥ +5 AND NOT `feature_ent_available` | `/feature` (fallback) | Use `/feature` with extra architecture care |
+
+## Step 5: Execute
+
+### `/plan` selected
+1. `/plan <feature-name>` → creates `docs/plans/<feature>.md`
+2. Implement plan immediately (parallel Tasks where independent)
+3. Run tests, commit + push
+
+### `/feature` selected
+1. `/feature <feature-name>` in AUTO mode (no inter-phase confirmations)
+2. Spawn parallel Tasks where work is independent
+3. Commit after each phase, push at end
+
+### `/feature-ent` selected (if available)
+Same as `/feature` but with idea2prd-manual + DDD coherence + ADR consistency
++ 7-agent validation + 6-agent review.
+
+## Step 6: Post-Implementation
+
+1. Update roadmap: feature `status: done`, `files: [actually-touched]`
+2. Commit: `docs(roadmap): mark <feature> as done`
+3. Push, report
+
+## Flag: `--feature-branches` (v1.5.0)
+
+Wrap the chosen pipeline (`/plan` or `/feature`) in a per-feature git branch.
+
+### Workflow when `--feature-branches` is passed
+
+```
+1. Verify on `main` (else fail with hint)
+2. If working tree dirty:
+     git stash push -u -m "auto-stash before /go feature-branches"
+3. Read roadmap entry for target feature; assign `number` if absent
+4. git checkout -b feature/{NNN}-{id}     # NNN = zero-padded 3-digit
+5. Run selected pipeline (/plan | /feature | /feature-ent) inside this branch
+6. git push origin feature/{NNN}-{id} --set-upstream
+7. Update roadmap: status=done, branch="feature/{NNN}-{id}"
+8. git checkout main
+9. If --auto-merge: git merge --no-ff feature/{NNN}-{id}
+```
+
+Branch format: `feature/{NNN}-{id}` (e.g., `feature/001-auth-jwt`).
+
+### Companion flag: `--auto-merge`
+
+Off by default. When passed: feature branch is merged into `main` after
+completion via `git merge --no-ff`. Without it: branch is pushed but stays
+unmerged for instructor/reviewer to handle.
+
+See `/run.md` for full per-feature-branch workflow rationale and use cases.
+
+## Related
+
+- `/next` — picks the feature when `$ARGUMENTS` empty
+- `/plan`, `/feature` — implementation pipelines
+- `/run` — autonomous loop that calls `/go` per feature (also accepts `--feature-branches`)

package/templates/.claude/commands/myinsights.md

@@ -0,0 +1,72 @@
+---
+description: Capture and recall development insights. Append a new insight to `.claude/insights/index.md` with structured fields (problem, solution, tags). Auto-injected into context on SessionStart for relevant tasks.
+argument-hint: '[recall <query> | <free-form insight>]'
+---
+
+# /myinsights $ARGUMENTS
+
+## Purpose
+
+Build a project-local knowledge base of "грабли" (rakes) — errors, workarounds,
+discoveries — so they don't have to be re-learned. Insights are auto-loaded
+into Claude Code context on each session start (via `SessionStart` hook in
+`.claude/settings.json`) when their tags match the current task.
+
+## Modes
+
+### Capture (default)
+
+Run `/myinsights` with a free-form description, or no arguments to be prompted.
+
+Process:
+1. Ask 3 short questions (or extract from `$ARGUMENTS`):
+   - **Problem** — what went wrong / surprised you
+   - **Solution** — what fixed it
+   - **Tags** — keywords for future recall
+2. Append entry to `.claude/insights/index.md`:
+
+```markdown
+## <ISO date> — <short title>
+
+**Tags:** <comma-separated>
+
+**Problem:**
+<1-3 sentences>
+
+**Solution:**
+<1-5 sentences with code if relevant>
+
+**References:** <file:line | commit hash>
+
+---
+```
+
+3. Auto-commit (Stop hook handles this if `.claude/settings.json` is in place).
+
+### Recall
+
+`/myinsights recall <query>`:
+
+1. Read `.claude/insights/index.md`
+2. Filter entries whose tags or text match `<query>` (case-insensitive)
+3. Print top 5 matches with relevance score
+
+## Storage
+
+`.claude/insights/index.md` — chronological log, Markdown format. One file per
+project to keep recall trivial.
+
+## Auto-injection on SessionStart
+
+The default `.claude/settings.json` configures `node .claude/hooks/session-insights.cjs`
+which: (1) reads recent insights, (2) prints them to stdout, (3) Claude Code
+captures stdout and injects into the initial context.
+
+This is what makes insights compounding: every session benefits from past
+mistakes without manual recall.
+
+## Related
+
+- `.claude/rules/insights-capture.md` — when/how to capture
+- `.claude/hooks/session-insights.cjs` — session injection
+- `/harvest` — extracts reusable patterns from insights at project end

package/templates/.claude/commands/next.md

@@ -0,0 +1,110 @@
+---
+description: Determine the next feature to work on. Reads `.claude/feature-roadmap.json`, applies priority + status filters, and returns the top entry. Subcommands: default (show top 3), `update` (scan codebase + suggest status changes), `<feature-id>` (mark a specific feature done and cascade unblock).
+argument-hint: '[update | <feature-id>]'
+---
+
+# /next $ARGUMENTS
+
+## Purpose
+
+Single source of "what to work on next" backed by `.claude/feature-roadmap.json`.
+Used by `/run` for autonomous loops and by humans to navigate sprint state.
+
+## Modes
+
+### Default (no arguments)
+
+1. Read `.claude/feature-roadmap.json`
+2. Filter entries to `status ∈ {next, planned}`
+3. Sort by priority (`mvp` > `high` > `medium` > `low`), then by `id`
+4. Output top 3 entries with: id, name, priority, complexity hint, blockers
+
+```
+═══════════════════════════════════════════════════════════════
+Next 3 features:
+1. [mvp] auth-jwt           — User login with JWT tokens (medium, 2-4h)
+2. [mvp] user-profile       — Profile CRUD endpoints (simple, 1-2h)
+3. [high] payment-webhook   — Stripe webhook handler (complex, 4-6h)
+
+In progress: <id> [<name>]
+Done: <N> / <total>
+Blocked: <count> (run /next blocked to see)
+═══════════════════════════════════════════════════════════════
+```
+
+### `/next update`
+
+1. Scan codebase for evidence of feature completion (e.g., file paths in
+   roadmap entry's `expected_files` exist + tests pass)
+2. Suggest status updates for each detected feature:
+   - `planned` → `next` if dependencies met
+   - `in_progress` → `done` if implementation + tests present
+   - `next` → `blocked` if dependency entry is `blocked`
+3. Print proposed diff, ask for confirmation
+4. Apply, commit `docs(roadmap): update statuses`
+
+### `/next <feature-id>`
+
+1. Mark that feature `done` in roadmap
+2. Cascade: any feature that listed `<feature-id>` as a blocker is unblocked
+   (status `blocked` → `next`)
+3. Update `last_completed` field
+4. Commit roadmap, return next item to work on
+
+## Roadmap Schema
+
+`.claude/feature-roadmap.json`:
+
+```json
+{
+  "version": "1.0",
+  "features": [
+    {
+      "id": "auth-jwt",
+      "number": 1,
+      "branch": "feature/001-auth-jwt",
+      "name": "JWT-based authentication",
+      "priority": "mvp",
+      "status": "next",
+      "complexity": "medium",
+      "estimated_hours": "2-4",
+      "blockers": [],
+      "expected_files": [
+        "packages/backend/src/auth/jwt.ts",
+        "packages/backend/src/auth/middleware.ts"
+      ],
+      "depends_on": []
+    }
+  ]
+}
+```
+
+### Schema fields (post v1.5.0)
+
+| Field | Required | Populated by | Purpose |
+|-------|----------|--------------|---------|
+| `id` | yes | initial roadmap generation | Stable kebab-case slug |
+| `number` | optional | `--feature-branches` flag in `/run` or `/go` | Sequential 1, 2, 3 ... assigned on first encounter; used to compose branch name |
+| `branch` | optional | `--feature-branches` flag after feature completes | `feature/{NNN}-{id}` actually pushed |
+| `name` | recommended | initial generation | Human-readable title |
+| `priority` | yes | initial generation | `mvp` \| `high` \| `medium` \| `low` |
+| `status` | yes | lifecycle | `planned` \| `next` \| `in_progress` \| `done` \| `blocked` |
+| `complexity` | optional | initial generation | `simple` \| `medium` \| `complex` |
+| `estimated_hours` | optional | initial generation | Time hint |
+| `blockers` | optional | manual | List of blocking issue IDs |
+| `expected_files` | optional | initial generation | Used by `/next update` to detect completion |
+| `depends_on` | optional | initial generation | Other feature IDs that must complete first |
+
+## Auto-Generation
+
+If `.claude/feature-roadmap.json` does not exist when `/next` is called:
+1. Read `docs/PRD.md` and extract user stories
+2. Generate initial roadmap with all stories as `planned`
+3. Set MVP scope from PRD's "MVP" section
+4. Commit `docs(roadmap): initial roadmap from PRD`
+
+## Related
+
+- `/run mvp` — automated loop over MVP-scoped roadmap entries
+- `/go <id>` — work on a specific feature (called by /run)
+- `docs/PRD.md` — source for initial roadmap generation

package/templates/.claude/commands/plan.md

@@ -0,0 +1,88 @@
+---
+description: Lightweight implementation planning. Creates a single plan file in `docs/plans/<feature>.md` with sections (Goal, Tasks, Files, Dependencies, Risks). Faster alternative to `/feature` for tasks touching ≤ 3 files.
+argument-hint: '<feature-name | task-description>'
+---
+
+# /plan $ARGUMENTS
+
+## Purpose
+
+Generate a focused implementation plan for a small task without running the
+full SPARC-mini lifecycle. Plans live in `docs/plans/` and are auto-committed.
+
+## When to use /plan vs /feature
+
+| Use `/plan` | Use `/feature` |
+|-------------|----------------|
+| ≤ 3 files | ≥ 4 files |
+| < 30 min implementation | > 1 hour |
+| No new architecture | New layer/pattern |
+| Bug fix or small improvement | New capability |
+
+If unsure, run `/go <name>` — it scores complexity and routes correctly.
+
+## Process
+
+### 1. Clarify (if ambiguous)
+
+Read `$ARGUMENTS`. If task is too vague, ask 1-3 targeted questions before
+proceeding.
+
+### 2. Read Context
+
+- `docs/Architecture.md` — relevant subsystems
+- `docs/Specification.md` — requirements that touch this task
+- Source files matching the task scope (use Grep to locate)
+
+### 3. Write Plan
+
+Create `docs/plans/<slug>.md` with:
+
+```markdown
+# Plan: <feature-name>
+
+**Status:** draft
+**Created:** <ISO timestamp>
+**Estimated:** <time>
+
+## Goal
+<1-2 sentence outcome statement>
+
+## Tasks
+- [ ] Task 1 — concrete, verifiable
+- [ ] Task 2
+
+## Files Touched
+| File | Change | Reason |
+|------|--------|--------|
+
+## Dependencies
+- Blocks: <feature-id>
+- Blocked by: <feature-id>
+
+## Risks
+- <risk> — <mitigation>
+
+## Verification
+How to confirm done.
+```
+
+### 4. Auto-Commit
+
+If `Stop` hook is configured (default in v1.4+), the plan auto-commits when
+the response ends. Otherwise: `git add docs/plans/<slug>.md && git commit
+-m "docs(plan): <feature-name>"`.
+
+### 5. Report
+
+```
+✅ Plan saved: docs/plans/<slug>.md
+   Tasks: <N>, Files: <count>
+   Next: implement directly, or run /go <slug> for autonomous execution
+```
+
+## Related
+
+- `/feature` — full SPARC-mini lifecycle (heavier)
+- `/go` — auto-pick between /plan and /feature
+- `docs/plans/` — directory of all plans

package/templates/.claude/commands/replicate.md

@@ -56,6 +56,88 @@ INPUT → [PRODUCT DISCOVERY] → PLANNING → VALIDATION → TOOLKIT → FINALI
 **Note:** sparc-prd-mini v2 already includes Explore, Research, and Solve phases
 internally via skill references. The coordinator does NOT duplicate these phases.
 
+## Alternative entry: starting from existing technical documentation
+
+If the user already has technical documentation for the project (tech spec,
+architecture docs, API spec, design docs, etc.), the pipeline supports
+**skipping Phase 0 entirely** and feeding the user's existing docs into
+Phase 1 as pre-filled context.
+
+### Trigger detection (any of these in user input)
+
+Switch to this alternative flow when the user input contains:
+- A path reference: "use my docs in `docs/existing/`", "my tech specs are in `<path>`"
+- An explicit skip request: "skip discovery", "skip Phase 0"
+- A statement of available docs: "I already have technical documentation"
+- The semantic flag: `/replicate --from-docs <path>` (or `--skip-discovery`)
+
+### Recommended setup
+
+The user should place their existing docs in a project-local subfolder
+(conventionally `docs/existing/` or `docs/source/`) so they're discoverable
+but distinct from generated SPARC outputs.
+
+### Modified pipeline flow when triggered
+
+- **Phase 0** (Product Discovery): SKIPPED entirely (no reverse-engineering-unicorn invocation)
+- **Phase 1** (sparc-prd-mini): MODIFIED
+  - Run in **AUTO mode** — do NOT ask interactive clarification questions
+  - SKIP internal sub-phases Explore / Research / Solve (their job is to
+    generate the answers that already exist in user docs)
+  - READ all files in user-provided path as pre-filled context
+  - Generate the 11 standardized SPARC documents in `docs/`, mapping content
+    from existing docs to appropriate slots (PRD, Solution_Strategy,
+    Specification, Pseudocode, Architecture, Refinement, Completion,
+    Research_Findings, Final_Summary, C4_Diagrams, ADR)
+  - For SPARC slots without source content in existing docs, mark with a
+    `[GAP: needs <description>]` placeholder rather than asking the user
+- **Phase 2** (validation): runs UNCHANGED (validates the generated SPARC docs)
+- **Phase 3** (toolkit generation): runs UNCHANGED
+- **Phase 4** (finalize): runs UNCHANGED
+
+### Three sub-paths the user may prefer
+
+| Sub-path | When | Skills invoked |
+|---|---|---|
+| **A. Full /replicate with override directives** | Have tech docs, want full pipeline + toolkit + scaffold | sparc-prd-mini (AUTO) → requirements-validator → cc-toolkit-generator-enhanced |
+| **B. Invoke sparc-prd-mini skill directly** | Want only the 11 SPARC docs, no toolkit/scaffold | sparc-prd-mini (AUTO) only |
+| **C. Rename existing docs to SPARC slot names + invoke validator only** | Existing docs already SPARC-shaped | requirements-validator only |
+
+### Caveats (always surface to the user)
+
+- Existing docs may not cover all 11 SPARC slots — expect `[GAP: ...]` markers
+- Validation may flag user stories as "not negotiable/testable" if existing
+  docs aren't INVEST/SMART-shaped — this is a real signal, not a bug
+- Architectural constraints (pattern, containers, infra, deploy, AI integration)
+  must be passed explicitly if not present in existing docs (use the constraints
+  block from "Phase 1: PLANNING" below)
+
+### Verification after completion
+
+```bash
+npx @dzhechkov/p-replicator verify
+```
+Should report pre-shipped contract OK + post-/replicate hints showing the
+generated SPARC docs and (if Phase 3+4 ran) the project-specific artifacts.
+
+### See also: existing-project feature workflow (Mode 2)
+
+If the user already has a working project (stack, PRD, CLAUDE.md, etc. all
+defined) and just wants to **add new features** with the same SPARC-mini
+validation cycle — they should use `/feature` (NOT `/replicate`):
+
+```bash
+cd existing-project
+npx @dzhechkov/p-replicator init      # idempotent — preserves CLAUDE.md
+claude
+/feature add-stripe-payments          # 4-phase: PLAN → VALIDATE → IMPLEMENT → REVIEW
+```
+
+See `.claude/commands/feature.md` ("Use case: existing project") and
+`.claude/rules/feature-lifecycle.md` ("Entry modes" → "Mode 2") for the full
+spec. This Mode 2 workflow is parallel to /replicate's "Alternative entry"
+above, but applies to ad-hoc feature additions rather than full project bootstrap.
+
 ## Execution
 
 ### Start
@@ -71,6 +153,7 @@ internally via skill references. The coordinator does NOT duplicate these phases
 - New product / startup / SaaS → **activate**
 - Competitors to analyze → **activate**
 - Internal tool / experiment → **skip**
+- **Existing technical documentation provided** → **skip** (see "Alternative entry" below)
 
 Read the skill: `.claude/skills/reverse-engineering-unicorn/SKILL.md`
 
@@ -216,13 +299,16 @@ Read the skill: `.claude/skills/cc-toolkit-generator-enhanced/SKILL.md`
 
 **Goal:** Generate project-specific Claude Code instruments IN-PLACE.
 
-**IMPORTANT (Claude Code adaptation):**
+**IMPORTANT (Claude Code adaptation, post v1.4):**
 - Scan `docs/` directory for SPARC documents (NOT `/mnt/user-data/uploads/`)
 - Generate files IN-PLACE into the project (NOT into output directory)
-- Lifecycle skills already exist in `.claude/skills/` — do NOT copy
-- Generic commands (`/feature`, `/myinsights`) already exist — do NOT overwrite
-- Generic rules (`feature-lifecycle`, `insights-capture`, `git-workflow`) already exist — do NOT overwrite
-- `settings.json` already exists with hooks — do NOT overwrite
+- **Pre-shipped by `npx p-replicator init` — do NOT overwrite or regenerate:**
+  - All 10 skills in `.claude/skills/`
+  - All 11 commands: `/replicate`, `/harvest`, `/start`, `/plan`, `/feature`, `/go`, `/run`, `/next`, `/myinsights`, `/docs`, `/deploy`
+  - All 5 rules: `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle`
+  - All 4 pipeline agents: `replicate-coordinator`, `product-discoverer`, `doc-validator`, `harvest-coordinator`
+  - `.claude/settings.json` + cross-platform Node hook scripts in `.claude/hooks/`
+- Phase 3 generates ONLY project-specific artifacts derived from SPARC docs (see below).
 
 **Generate these project-specific files:**
 
@@ -231,39 +317,39 @@ Read the skill: `.claude/skills/cc-toolkit-generator-enhanced/SKILL.md`
 - Architecture from Architecture.md
 - Tech stack decisions
 - Parallel execution strategy
-- Swarm agents section
-- Available agents/skills/commands list
+- Available agents/skills/commands list (reference pre-shipped + project-generated)
 - Development insights section
 - Feature lifecycle section
 
-**2. Commands (`.claude/commands/`):**
-- `start.md` — project bootstrap (uses /start template from cc-toolkit skill)
-- `plan.md` — implementation planning
-- `test.md` — test generation/execution
-- `deploy.md` — deployment workflow
-
-**3. Agents (`.claude/agents/`):**
+**2. Project-specific Agents (`.claude/agents/`):**
 - `planner.md` — feature planning with algorithm templates from Pseudocode.md
 - `code-reviewer.md` — quality review with edge cases from Refinement.md
 - `architect.md` — system design from Architecture.md + Solution_Strategy.md
 - Additional agents based on project characteristics
 
-**4. Project-specific Rules (`.claude/rules/`):**
+**3. Project-specific Rules (`.claude/rules/`):**
 - `security.md` — from Specification.md NFRs
 - `coding-style.md` — from Architecture.md tech stack
 - `secrets-management.md` — IF external APIs detected
 - `testing.md` — from Refinement.md test strategy
 
-**5. Project-specific Skills (`.claude/skills/`):**
+**4. Project-specific Skills (`.claude/skills/`):**
 - `project-context/` — domain knowledge from Research_Findings.md
 - `coding-standards/` — tech-specific patterns from Architecture.md
 - `security-patterns/` — IF external APIs (encrypted storage pattern)
 
-**6. Additional files:**
+**5. Project state:**
+- `.claude/feature-roadmap.json` — generated from PRD.md MVP scope
 - `.mcp.json` — IF external integrations
 - `DEVELOPMENT_GUIDE.md` — step-by-step development lifecycle
 - `README.md` — enhanced with project info
 
+**6. Conditional command (only if DDD docs present):**
+- `.claude/commands/feature-ent.md` — enterprise feature lifecycle with DDD/ADR/C4
+
+**Verify after Phase 3:**
+- Run `npx @dzhechkov/p-replicator verify` to confirm both pre-shipped contract AND post-/replicate artifacts are in place.
+
 Git commit: `feat: Claude Code toolkit for [project-name]`
 
 **Checkpoint:**