@dzhechkov/p-replicator 1.3.0 → 1.5.2

package/templates/.claude/commands/feature.md

@@ -0,0 +1,134 @@
+---
+description: Full SPARC-mini feature lifecycle (PLAN → VALIDATE → IMPLEMENT → REVIEW). Generates per-feature SPARC docs, validates against INVEST/SMART, implements in parallel, reviews with brutal-honesty-review. For features touching 4+ files or introducing new architecture.
+argument-hint: '<feature-name>'
+---
+
+# /feature $ARGUMENTS
+
+## Purpose
+
+Run a 4-phase lifecycle on a single feature: PLAN → VALIDATE → IMPLEMENT →
+REVIEW. Project-context-aware (reads `docs/`), checkpoint-driven, parallel
+where independent.
+
+## Use case: existing project (Mode 2)
+
+`/feature` is the canonical entry point for adding new features both to
+projects bootstrapped via `/replicate` (Mode 1) and to **existing projects**
+that already have stack, PRD, Specification, Architecture, and CLAUDE.md
+defined (Mode 2).
+
+The 4-phase pipeline (PLAN → VALIDATE → IMPLEMENT → REVIEW) is **identical
+in both modes**. The only difference is operational context: in Mode 2 the
+project's CLAUDE.md and existing scaffold are NOT regenerated by `/feature`.
+
+### Prerequisites for Mode 2
+
+- `npx @dzhechkov/p-replicator init` has been run (idempotent — preserves
+  the user's existing CLAUDE.md and `.claude/` files)
+- `npx @dzhechkov/p-replicator verify` reports pre-shipped contract intact
+- Project documentation lives at standard SPARC slot paths:
+  - `docs/PRD.md` (REQUIRED — used as context for Phase 1)
+  - `docs/Specification.md` (RECOMMENDED — used for AC inheritance)
+  - `docs/Architecture.md` (RECOMMENDED — used for component placement)
+  - Pseudocode/Refinement/Completion are OPTIONAL — `/feature` proceeds without them
+- If existing docs are at non-standard paths (e.g., `docs/product/PRD.md`),
+  the user must rename or symlink them ONE-TIME (no `--prd-path` flag yet —
+  see KNOWN_LIMITATIONS.md M3)
+
+### What does NOT happen in Mode 2
+
+- `/start` MUST NOT be invoked — it expects an empty/fresh scaffold
+- Phase 4 (`brutal-honesty-review`) does NOT modify CLAUDE.md unless a finding
+  explicitly requires it
+- `feature-roadmap.json` is NOT auto-generated — the user creates it manually
+  if they want batch automation via `/run mvp`; otherwise ad-hoc `/feature <id>`
+  works without any roadmap
+
+### Three sub-paths for Mode 2
+
+| Path | When | Invocation |
+|---|---|---|
+| **A. /feature directly** | Single feature, ≥ 4 files | `/feature <id>` |
+| **B. /go auto-router** | Mixed complexity | `/go <id>` (routes to /plan or /feature based on heuristics) |
+| **C. Direct skill calls** | Only validation cycle, no full lifecycle | Invoke `requirements-validator` + `brutal-honesty-review` skills directly |
+
+### Verification
+
+After completion in Mode 2, run:
+```bash
+npx @dzhechkov/p-replicator verify
+```
+Pre-shipped contract should remain intact. The existing-project state of
+CLAUDE.md and project files should not have changed except for Phase 3
+implementation diffs.
+
+## Phases
+
+### Phase 1: PLAN (sparc-prd-mini)
+
+Read: `.claude/skills/sparc-prd-mini/SKILL.md`
+
+Generate per-feature SPARC docs in `docs/features/<feature>/`:
+- `01_specification.md` — requirements + acceptance criteria
+- `02_pseudocode.md` — algorithms + data flow
+- `03_architecture.md` — component placement + dependencies
+- `04_refinement.md` — edge cases + error paths
+- `05_completion.md` — testing + deployment notes
+
+**Checkpoint:**
+```
+═══════════════════════════════════════════════════════════════
+✅ PHASE 1: PLAN — docs/features/<feature>/ created
+⏸️ "ок" — next | "превью plan" — show docs
+═══════════════════════════════════════════════════════════════
+```
+
+### Phase 2: VALIDATE (requirements-validator)
+
+Read: `.claude/skills/requirements-validator/SKILL.md`
+
+Run validation against INVEST + SMART + BDD scenario completeness.
+
+| Verdict | Score | Action |
+|---------|-------|--------|
+| 🟢 READY | ≥ 70 average | → Phase 3 |
+| 🟡 CAVEATS | 50-69 with warnings | → Phase 3 with notes |
+| 🔴 NEEDS WORK | < 50 OR blocked items | → Return to Phase 1 (max 3 retries) |
+
+Output: `docs/features/<feature>/validation-report.md`
+
+### Phase 3: IMPLEMENT (parallel agents)
+
+1. Read SPARC docs from Phase 1
+2. Identify independent work units
+3. Spawn parallel `Task` tool calls, one per unit
+4. Each Task: implement + write tests + commit
+5. Coordinator merges/integrates after Tasks complete
+6. Run full test suite
+
+### Phase 4: REVIEW (brutal-honesty-review)
+
+Read: `.claude/skills/brutal-honesty-review/SKILL.md`
+
+Findings classified by severity. Critical (blocker | high) MUST be fixed.
+
+## Final Steps
+
+1. Update `.claude/feature-roadmap.json`: status `in_progress` → `done`
+2. Commit: `feat(<feature>): complete lifecycle [phases 1-4]`
+3. Push
+
+## AUTO mode (when called from /go or /run)
+
+Skip per-phase user confirmations. Auto-decisions:
+- Phase 1: proceed if all docs exist
+- Phase 2: proceed if 🟢 or 🟡; auto-retry once on 🔴
+- Phase 3: proceed if tests + lint + build green
+- Phase 4: auto-fix `high` if straightforward; halt on `blocker`
+
+## Related
+
+- `/plan` — lighter alternative for small tasks
+- `/go` — auto-routes between /plan and /feature
+- `.claude/rules/feature-lifecycle.md` — phase rules

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