@dzhechkov/p-replicator 1.2.0 → 1.5.2

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:**

package/templates/.claude/commands/run.md

@@ -0,0 +1,151 @@
+---
+description: Autonomous build loop — picks next feature from roadmap, dispatches to /go, repeats until exhausted. Modes: `mvp` (default — only features tagged mvp), `all` (everything in `next` or `planned`). Auto-commits after each feature. Supports `--feature-branches` for per-feature git branches (teaching/demo workflow).
+argument-hint: '[mvp | all] [--feature-branches] [--auto-merge]'
+---
+
+# /run $ARGUMENTS
+
+## Purpose
+
+One-command autonomous feature build. Reads `.claude/feature-roadmap.json`,
+loops through features via `/next` → `/go`, marks them done, commits, and
+continues until the scoped list is exhausted.
+
+> **PROCESS COMPLIANCE — BLOCKING RULES:**
+> - MUST delegate to `/next`, `/go`, `/plan`, `/feature` — NEVER spawn raw Agent tools directly
+> - MUST commit after each feature (one feature = one commit cluster)
+> - FORBIDDEN: bypassing /go's complexity routing
+> - FORBIDDEN: batching multiple features in a single commit wave
+
+## Step 0: Parse Scope
+
+| `$ARGUMENTS` | Filter applied to roadmap |
+|--------------|---------------------------|
+| `mvp` (default if empty) | Only features with `priority: "mvp"` and status in `next`/`planned` |
+| `all` | All features with status in `next`/`planned` |
+
+If `.claude/feature-roadmap.json` does not exist → halt with:
+```
+Roadmap not found. Run /replicate first or create .claude/feature-roadmap.json manually.
+```
+
+## Step 1: Bootstrap Check
+
+If `CLAUDE.md` exists but core scaffolding is missing (e.g., no `package.json`,
+no `docker-compose.yml`), call `/start` once before the loop. Skip if
+scaffolding already in place.
+
+## Step 2: Feature Loop
+
+```
+while features_remaining_in_scope:
+    feature_id = /next                       # pick highest-priority next/planned
+    if not feature_id: break
+    /go feature_id                           # complexity router → /plan or /feature
+    verify completion (tests green, code committed)
+    mark roadmap entry: status = "done"
+    git commit -m "docs(roadmap): mark <id> as done"
+    git push origin HEAD
+```
+
+Between iterations, briefly summarize progress: `Completed N of M features in scope`.
+
+## Step 3: Final Summary
+
+When the loop terminates (scope exhausted or user interrupt):
+
+```
+═══════════════════════════════════════════════════════════════
+✅ /run complete — scope: <mvp|all>
+   Completed: <N> features
+   Total commits: <count>
+   Time elapsed: <duration>
+   Next: /docs to generate documentation, /harvest to extract knowledge
+═══════════════════════════════════════════════════════════════
+```
+
+## Error Recovery
+
+If a single feature fails (test red, validation blocked), `/run`:
+1. Marks that feature as `blocked` with reason
+2. Continues to next feature in scope
+3. At the end, lists all blocked features for manual review
+
+`/run` does NOT abort the whole loop on one feature failure — autonomous mode
+is designed for unattended operation.
+
+## Flag: `--feature-branches` (v1.5.0)
+
+Create a separate git branch per feature. Useful for **teaching/demo
+workflows** where each feature must be a discrete unit the instructor can
+checkout independently.
+
+### Branch naming format
+
+```
+feature/{NNN}-{id}
+```
+where `NNN` is a zero-padded 3-digit feature number from the roadmap, and
+`{id}` is the feature's slug. Example: `feature/001-auth-jwt`.
+
+### Per-feature workflow with --feature-branches
+
+```
+For each feature in scope:
+  1. Verify on `main` branch (else fail with hint to switch)
+  2. If working tree is dirty:
+       git stash push -u -m "auto-stash before /run feature-branches"
+  3. Read roadmap entry; if feature has no `number`, assign max(numbers) + 1
+     and persist back to .claude/feature-roadmap.json
+  4. git checkout -b feature/{NNN}-{id}    # branched from main
+  5. /go {feature-id}                       # delegate to standard pipeline
+  6. git push origin feature/{NNN}-{id} --set-upstream
+  7. Mark roadmap entry: status=done, branch="feature/{NNN}-{id}"
+  8. git checkout main                      # ready for next iteration
+  9. If --auto-merge ALSO passed:
+       git merge --no-ff feature/{NNN}-{id} -m "merge: feature/{NNN}-{id}"
+```
+
+### Companion flag: `--auto-merge`
+
+Off by default. When passed alongside `--feature-branches`, each feature
+branch is merged into `main` (with `--no-ff`) immediately after completion.
+Without `--auto-merge`, branches are pushed but **NOT** merged — instructor
+or reviewer is expected to merge via PR or manually.
+
+### Roadmap schema extension (post v1.5.0)
+
+```json
+{
+  "id": "auth-jwt",
+  "number": 1,
+  "branch": "feature/001-auth-jwt",
+  "name": "JWT-based authentication",
+  "priority": "mvp",
+  "status": "done",
+  ...
+}
+```
+
+`number` is auto-assigned on first encounter when `--feature-branches` is
+used. `branch` is populated when the feature completes successfully.
+
+### Use cases
+
+- **Teaching:** instructor checks out `feature/003-payment` to demo a specific
+  feature. All branches are pushed, easy to fetch and explore.
+- **Code review:** each feature has standalone branch for PR-based review.
+- **Experimentation:** abandon a branch cleanly without disturbing main.
+
+### Anti-patterns
+
+- Running `--feature-branches` while on a feature branch (not main) → fails
+- Mixing `--feature-branches` with non-branch features in the same session
+  → mark already-merged features explicitly with `branch: "main"` to avoid retry
+
+## Related
+
+- `/next` — picks next feature (called per iteration)
+- `/go` — complexity router (called per feature; also accepts `--feature-branches`)
+- `/plan`, `/feature` — actual implementation pipelines
+- `.claude/feature-roadmap.json` — source of truth for what to build

package/templates/.claude/commands/start.md

@@ -0,0 +1,88 @@
+---
+description: Bootstrap project from SPARC documentation. Generates monorepo skeleton, packages, Docker configs, database schema, core modules, and basic tests in 4 phases (Foundation → Packages parallel → Integration → Finalize). Reads `docs/` as source of truth.
+argument-hint: '[--skip-tests | --skip-seed | --dry-run]'
+---
+
+# /start $ARGUMENTS
+
+## Purpose
+
+One-command project generation from SPARC documentation → working monorepo
+with `docker compose up`. Reads `docs/` (NOT memory), maximizes parallelism
+via `Task` tool, commits per logical change for safe error recovery.
+
+## Prerequisites
+
+- SPARC documents in `docs/` (output of `/replicate` Phase 1)
+- `CLAUDE.md` at project root
+- Docker + Docker Compose installed
+- Git initialized
+
+## Phases
+
+### Phase 1: Foundation (sequential)
+
+1. **Read all SPARC docs** to build full context:
+   - `docs/Architecture.md` → monorepo structure, Docker Compose, tech stack
+   - `docs/Specification.md` → data model, API endpoints, NFRs
+   - `docs/Pseudocode.md` → core algorithms
+   - `docs/Completion.md` → env config, deployment
+   - `docs/PRD.md` → features (for README)
+   - `docs/Refinement.md` → edge cases, testing strategy
+
+2. **Generate root configs:** `package.json` (monorepo workspaces),
+   `docker-compose.yml`, `.env.example`, `.gitignore`, `tsconfig.base.json`.
+
+3. **Git commit:** `chore: project root configuration`
+
+### Phase 2: Packages (PARALLEL via Task tool ⚡)
+
+For EACH package in Architecture.md, spawn an independent Task referencing
+SOURCE DOCS (not memory):
+
+```
+### Task <X>: packages/<name> ⚡
+Read and use as source:
+- docs/Specification.md → data model → ORM schema
+- docs/Architecture.md → API endpoints → routes
+- docs/Pseudocode.md → algorithms → service layer
+
+Generate: src/<files>, tests/<files>, package.json, README.md
+Commits: one per logical group.
+```
+
+### Phase 3: Integration (sequential)
+
+1. Verify cross-package imports
+2. `docker compose build`
+3. `docker compose up -d`
+4. Database migration (if applicable): `npx prisma migrate dev` (or equivalent)
+5. Health check: `curl localhost:<port>/health`
+6. Run tests
+7. Git commit: `chore: verify docker integration`
+
+### Phase 4: Finalize
+
+1. Generate/update `README.md` with quick start
+2. `git tag v0.1.0-scaffold`
+3. Report summary
+
+## Flags
+
+- `--skip-tests` — don't generate test files (NOT recommended)
+- `--skip-seed` — skip DB seeding
+- `--dry-run` — show plan without executing
+
+## Critical Rules
+
+1. **Docs as source of truth** — every file references specific docs, never memory
+2. **Maximize parallelism** — independent packages run as parallel Tasks
+3. **Atomic commits** — one commit per logical change
+4. **Full integration** — Phase 3 includes build + start + health check
+5. **Project-specific** — adapt all examples to actual tech stack
+
+## Related
+
+- `/replicate` — generates the SPARC docs that `/start` reads
+- `/run mvp` — builds features after scaffold is up
+- `/feature <name>` — implement individual features

package/templates/.claude/hooks/autocommit-insights.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Stop hook — auto-commits .claude/insights/ if anything changed.
+ * Cross-platform: pure Node + execFileSync, no shell.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const TARGET_DIR = path.resolve(process.cwd(), '.claude', 'insights');
+const RELATIVE = path.relative(process.cwd(), TARGET_DIR);
+const SILENT = { stdio: 'ignore' };
+
+function git(args) {
+  return execFileSync('git', args, SILENT);
+}
+
+try {
+  if (!fs.existsSync(TARGET_DIR)) process.exit(0);
+  try { git(['rev-parse', '--git-dir']); } catch { process.exit(0); }
+
+  git(['add', '--', RELATIVE]);
+
+  let hasDiff = false;
+  try {
+    git(['diff', '--cached', '--quiet', '--', RELATIVE]);
+  } catch {
+    hasDiff = true;
+  }
+
+  if (hasDiff) {
+    git(['commit', '--only', '--', RELATIVE, '-m', 'docs(insights): auto-capture']);
+  }
+} catch (_err) {
+  process.exit(0);
+}

package/templates/.claude/hooks/autocommit-plans.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Stop hook — auto-commits docs/plans/ if anything changed.
+ * Cross-platform: pure Node + execFileSync, no shell.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const TARGET_DIR = path.resolve(process.cwd(), 'docs', 'plans');
+const RELATIVE = path.relative(process.cwd(), TARGET_DIR);
+const SILENT = { stdio: 'ignore' };
+
+function git(args) {
+  return execFileSync('git', args, SILENT);
+}
+
+try {
+  if (!fs.existsSync(TARGET_DIR)) process.exit(0);
+  try { git(['rev-parse', '--git-dir']); } catch { process.exit(0); }
+
+  git(['add', '--', RELATIVE]);
+
+  let hasDiff = false;
+  try {
+    git(['diff', '--cached', '--quiet', '--', RELATIVE]);
+  } catch {
+    hasDiff = true;
+  }
+
+  if (hasDiff) {
+    git(['commit', '--only', '--', RELATIVE, '-m', 'docs(plan): auto-save']);
+  }
+} catch (_err) {
+  process.exit(0);
+}

package/templates/.claude/hooks/autocommit-roadmap.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Stop hook — auto-commits .claude/feature-roadmap.json if it changed.
+ * Cross-platform: uses execFileSync('git', [...]) so no shell quoting/redirect issues.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const TARGET = path.resolve(process.cwd(), '.claude', 'feature-roadmap.json');
+const RELATIVE = path.relative(process.cwd(), TARGET);
+const SILENT = { stdio: 'ignore' };
+
+function git(args) {
+  return execFileSync('git', args, SILENT);
+}
+
+try {
+  // Skip if file doesn't exist or we're not in a git repo.
+  if (!fs.existsSync(TARGET)) process.exit(0);
+  try { git(['rev-parse', '--git-dir']); } catch { process.exit(0); }
+
+  // Stage only the target file.
+  git(['add', '--', RELATIVE]);
+
+  // Check whether anything is staged for THIS path.
+  // `git diff --cached --quiet -- <path>` exits 0 = no diff, 1 = diff exists.
+  let hasDiff = false;
+  try {
+    git(['diff', '--cached', '--quiet', '--', RELATIVE]);
+  } catch {
+    hasDiff = true;
+  }
+
+  if (hasDiff) {
+    git(['commit', '--only', '--', RELATIVE, '-m', 'docs(roadmap): auto-update']);
+  }
+} catch (_err) {
+  // Best-effort — never break Claude session on commit failures.
+  process.exit(0);
+}

package/templates/.claude/hooks/session-insights.cjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * SessionStart hook — injects up to 3 most recent insights from
+ * .claude/insights/index.md into Claude's initial session context (via stdout).
+ *
+ * Cross-platform: pure Node, no shell pipes. Silent on missing index.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const INDEX = path.resolve(process.cwd(), '.claude', 'insights', 'index.md');
+
+try {
+  if (!fs.existsSync(INDEX)) process.exit(0);
+  const text = fs.readFileSync(INDEX, 'utf8');
+  // Each insight starts with "## " heading (per insights-capture.md convention).
+  const sections = text.split(/^## /m).filter(Boolean);
+  const recent = sections.slice(-3).map((s) => '## ' + s.trim()).join('\n\n');
+  if (recent.length > 0) {
+    process.stdout.write('## Recent project insights\n\n' + recent + '\n');
+  }
+} catch (_err) {
+  // Hook is advisory — never block the session on errors here.
+  process.exit(0);
+}

package/templates/.claude/hooks/state-update.cjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * state-update.cjs (v1.5.0) — write `.claude/.p-replicator-state.json`.
+ *
+ * Used by pipeline commands (/run, /go, /feature, /replicate) to publish
+ * current command + phase + progress for the statusline to display.
+ *
+ * Usage:
+ *   node .claude/hooks/state-update.cjs \
+ *     --command /feature \
+ *     --phase VALIDATE \
+ *     --index 2 \
+ *     --total 4 \
+ *     --progress 0.5 \
+ *     [--last-command /replicate] \
+ *     [--last-feature auth-jwt]
+ *
+ * Or pass JSON in one arg:
+ *   node .claude/hooks/state-update.cjs --json '{"currentCommand":"/run", ...}'
+ *
+ * Idempotent: overwrites the state file each call. Always exits 0 (best-effort).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STATE_FILE = path.resolve(process.cwd(), '.claude', '.p-replicator-state.json');
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      out[key] = next;
+      i++;
+    } else {
+      out[key] = true;
+    }
+  }
+  return out;
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv);
+
+    let state;
+    if (args.json) {
+      try { state = JSON.parse(args.json); }
+      catch { state = {}; }
+    } else {
+      state = {
+        currentCommand: args.command || null,
+        currentPhase: args.phase ? {
+          name: args.phase,
+          index: args.index ? parseInt(args.index, 10) : null,
+          total: args.total ? parseInt(args.total, 10) : null,
+          progress: args.progress ? parseFloat(args.progress) : null,
+        } : null,
+        lastCommand: args['last-command'] || null,
+        lastFeature: args['last-feature'] || null,
+      };
+    }
+
+    state.updatedAt = new Date().toISOString();
+
+    fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  } catch (_err) {
+    // Best-effort. Never fail the calling pipeline on state-write issues.
+  }
+}
+
+main();