@hanzlaa/rcode 4.4.1 → 4.4.3

package/AGENTS.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CONTRIBUTING.md

@@ -353,6 +353,12 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `scaffold` — scaffold-project workflow changes
 - `campaign` — fix-campaign orchestration tracking files
 - `ship` — ship workflow changes
+- `do-router` — `/rcode-do` intent-router table and dispatch logic
+- `milestone-health` — milestone-health scoring in rcode-tools
+- `modules` — installable capability bundles under `rcode/skills/<module>/`
+- `project-types` — project-type templates and detection
+- `roadmapper` — roadmap generation agent/workflow
+- `token` — token-budget and cost-tracking logic
 - `<phase-id>` — numeric phase scope when committing inside a phase (e.g. `docs(15)`, `feat(8.3)`)
 - `<sprint-id>` — numeric sprint scope inside a phase (e.g. `feat(15.1)`)
 

package/README.md

@@ -6,7 +6,7 @@
 
 ### An engineering org in a folder — and you can watch it work.
 
-*A roster of specialist agents, phase-driven delivery, and a persistent Memory Bank — running as plain files your IDE reads. **45 agents · 116 commands · 1 runtime dependency** — test count and CI status tracked by the badge above.*
+*A roster of specialist agents, phase-driven delivery, and a persistent Memory Bank — running as plain files your IDE reads. **45 agents · 117 commands · 1 runtime dependency** — test count and CI status tracked by the badge above.*
 
 <p align="center"><img src="brand/dashboard-team.png" alt="rcode agent roster grouped by function — Leadership (Sadiq / strategy, Waleed / CTO, Ahmed / delivery, Nasser / eng manager), Engineering (Omar, Haitham / frontend, Yousef / backend, Zayd / ML, Khalid / DevOps), Product (Hussain / PM, Mariam / marketing), each card showing its role and tools" width="860"></p>
 
@@ -23,7 +23,7 @@ pnpm dlx @hanzlaa/rcode install
 [![CI](https://github.com/hanzlahabib/rcode/actions/workflows/test.yml/badge.svg)](https://github.com/hanzlahabib/rcode/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Status: `@hanzlaa/rcode` v4.4.1 on npm. 45 agents · 116 commands · 129 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
+Status: `@hanzlaa/rcode` v4.4.3 on npm. 45 agents · 117 commands · 129 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
 
 ---
 
@@ -54,7 +54,7 @@ Three layers, specialised for software delivery:
 | Layer | What lives here | Example |
 |-------|-----------------|---------|
 | **Memory** | `.rcode/memory/` — git-tracked markdown, lossless distillates | "We chose Postgres over Mongo because of JSON-B + RLS — see ADR-007" |
-| **Skills** | `rcode/skills/` — 88 phrase-activated playbooks | `rcode-sprint-checker` validates file/symbol refs before execute |
+| **Skills** | `rcode/skills/` — 96 phrase-activated playbooks | `rcode-sprint-checker` validates file/symbol refs before execute |
 | **Workflows** | `rcode/workflows/` — orchestrated multi-step paths | `/rcode-plan` runs research → planner → checker → confirm |
 
 Single agent navigates the structure. No LangChain, no AutoGen, no orchestrator process. Just folders the model can read.
@@ -127,18 +127,18 @@ The point isn't "I beat LangChain." The point is **you don't need LangChain for
 > node benchmarks/facts.cjs
 > ```
 
-<p align="center"><img src="brand/hero-receipt.png" alt="benchmarks/facts.cjs output — 497 tests, 0 failing · 45 agents · 116 commands · 1 runtime dependency, computed from files on disk" width="720"></p>
-
 | Metric | Value | Why it's not a vanity number |
 |---|---|---|
-| **Portable methodology corpus** | **94,481 lines** of markdown | A 10-person eng org's playbooks (agents + commands + workflows + skills + references) — as files you own and grep, not a SaaS you rent. |
-| **Automated tests** | **497**, 100% passing across 61 files | The methodology is *guarded*, not vibes. CI runs them on every push; `node --test` reproduces locally in seconds. |
-| **Tested CLI engine** | **9,005 lines** (`rcode-tools.cjs` + `lib/`) | The deterministic brain — routing, state, planning math — is real code under test, not prompt soup. |
-| **Runtime dependencies** | **1** (`ws`, for the dashboard socket) | The view-only dashboard is pure Node stdlib. Almost nothing to audit, nothing to CVE-scan, nothing to break on `npm install`. |
-| **Specialist agents / commands / workflows / skills** | **45 / 116 / 129 / 88** | An entire engineering org, phrase-activated, that travels with you across Claude Code, Cursor, Codex, VS Code, Antigravity, Windsurf. |
-| **Core-op latency** | **~33 ms**, **0 LLM tokens** (best-of-7) | Intent routing, state reads, and milestone-health are deterministic *local* compute — a few ms over Node's own cold-start floor. The orchestration layer doesn't burn API tokens on bookkeeping the way pure-LLM agent frameworks do. |
-
-**The headline:** an entire software-delivery methodology — 94k lines of it — guarded by 497 tests, riding on a single runtime dependency, with an orchestration brain that costs **zero tokens** to think. Not a viral prompt. A system you can verify line by line.
+| **Portable methodology corpus** | **~105,000 lines** of markdown | A 10-person eng org's playbooks (agents + commands + workflows + skills + references) — as files you own and grep, not a SaaS you rent. |
+| **Automated tests** | **495** across 62 files | The methodology is *guarded*, not vibes. Live pass/fail status is on the CI badge above; `node --test` (or `node benchmarks/facts.cjs`) reproduces locally in seconds. |
+| **Tested CLI engine** | **~9,700 lines** (`rcode-tools.cjs` + `lib/`) | The deterministic brain — routing, state, planning math — is real code under test, not prompt soup. |
+| **Runtime dependencies** | **1** (`ws`, for the dashboard socket) | The dashboard is otherwise pure Node stdlib. Almost nothing to audit, nothing to CVE-scan, nothing to break on `npm install`. |
+| **Specialist agents / commands / workflows / skills** | **45 / 117 / 129 / 96** | An entire engineering org, phrase-activated, that travels with you across Claude Code, Cursor, Codex, VS Code, Antigravity, Windsurf. |
+| **Core-op latency** | **~60 ms**, **0 LLM tokens** (best-of-7) | Intent routing, state reads, and milestone-health are deterministic *local* compute — a few ms over Node's own cold-start floor. The orchestration layer doesn't burn API tokens on bookkeeping the way pure-LLM agent frameworks do. |
+
+> Counts above are produced by `node benchmarks/facts.cjs` and may drift slightly between releases — run it for the exact current figures.
+
+**The headline:** an entire software-delivery methodology — ~105k lines of it — guarded by a real test suite, riding on a single runtime dependency, with an orchestration brain that costs **zero tokens** to think. Not a viral prompt. A system you can verify line by line.
 
 ---
 

package/cli/install.js

@@ -205,6 +205,9 @@ function parseArgs(argv) {
     silent: false,
     // noPrompt — skip all interactive prompts (used by postinstall auto-run)
     noPrompt: false,
+    // localOnly (#938) — force a self-contained project install: write all
+    // skills locally instead of deferring to global ~/.claude/skills.
+    localOnly: false,
     // dry-run / list-files — preview paths that would be written, then exit
     dryRun: false,
     listFiles: false,
@@ -240,6 +243,7 @@ function parseArgs(argv) {
     else if (arg === '--no-git-hooks') opts.gitHooks = false;         // #199
     else if (arg === '--git-hooks') opts.gitHooks = true;             // #199
     else if (arg === '--global') opts.global = true;
+    else if (arg === '--local-only') opts.localOnly = true; // #938 — force self-contained install (don't defer to global skills)
     else if (arg === '--silent') opts.silent = true;
     else if (arg === '--no-prompt') opts.noPrompt = true;
     else if (arg === '--dry-run') opts.dryRun = true;
@@ -825,15 +829,20 @@ function seedStarterPlanning(target, projectName) {
 
     const state = {
       version: '1',
-      project: resolvedProject,
+      // #940 — match the canonical schema (cli/lib/schemas.cjs stateSchema):
+      // schema_version is required, milestones is a plural array. Without these
+      // a freshly-installed state.json failed `rcode-tools validate` until the
+      // first migrateState() read. Write conformant state up front.
+      schema_version: 2,
+      project: resolvedProject || path.basename(target),
       ...(isStubProject ? { _seeded_stub: true } : {}),
       created: now,
       updated: now,
       current_phase: resolvedPhase,
       current_plan: 0,
       current_sprint: null,
-      milestone: null,
       phases: [],
+      milestones: [],
       executions: [],
       decisions: [],
       blockers: [],
@@ -2469,7 +2478,9 @@ async function installInner(opts) {
   // of identical files — Claude Code shows both as duplicate slash commands.
   const globalClaudeCommands = path.join(homedir(), '.claude', 'commands');
   const projectClaudeCommands = path.join(opts.target, '.claude', 'commands');
-  const isProjectInstall = opts.target !== homedir();
+  // #938 — --local-only forces a self-contained install: treat it as NOT a
+  // global-deferring project install so all skills/commands are written locally.
+  const isProjectInstall = opts.target !== homedir() && !opts.localOnly;
   // Run dedup even when force:true — only forceOverwrite skips it.
   if (isProjectInstall && !opts.forceOverwrite) {
     try {
@@ -2672,6 +2683,12 @@ async function installInner(opts) {
   let skillsInstalled = skillsResult.count;
   if (skillsResult.skippedGlobal > 0) {
     console.log('  ' + dim(`Skipped ${skillsResult.skippedGlobal} project-level rcode skills (global ones in ~/.claude/skills/ take precedence) — closes #679.`));
+    // #938 — make the global dependency explicit. When local skills are skipped
+    // the project relies on whatever rcode version is installed globally; a
+    // collaborator without a global install (or on a different version) gets
+    // different behavior. Tell the user how to force a self-contained install.
+    console.log('  ' + dim('  ↳ This project now depends on your GLOBAL rcode install for those skills.'));
+    console.log('  ' + dim('    For a self-contained project (e.g. for collaborators/CI), reinstall with --local-only.'));
   }
 
   // Generate install-time skill stubs that mirror sidebar-worthy slash commands.

package/cli/postinstall.js

@@ -57,10 +57,22 @@ function isGlobalInstall(env, dirname, cwd) {
 
 // Skip in CI or test environments. Tests that import this module bypass
 // the top-level effect by checking require.main !== module.
+//
+// #924 — opt-out for users who install the package globally but do NOT want
+// their ~/.claude mutated (e.g. inspecting the package, or managing the global
+// install themselves). Setting RCODE_NO_POSTINSTALL=1 (or the npm-config
+// equivalent `npm install -g @hanzlaa/rcode --rcode-no-postinstall`) skips the
+// auto-install entirely; the user can run `rcode install --global` later. Note:
+// `npm install --ignore-scripts` already prevents this script from running at all.
 if (require.main === module) {
   if (process.env.CI || process.env.NODE_ENV === 'test') {
     process.exit(0);
   }
+  if (process.env.RCODE_NO_POSTINSTALL === '1' || process.env.npm_config_rcode_no_postinstall) {
+    process.stderr.write('\nrcode: skipping global auto-install (RCODE_NO_POSTINSTALL set).\n');
+    process.stderr.write("       Run 'rcode install --global' when you want /rcode-* commands.\n\n");
+    process.exit(0);
+  }
   runPostInstall();
 }