@hanzlaa/rcode 4.7.3 → 4.9.0

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`, `init`, `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)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `init`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `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/CLAUDE.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`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `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`, `rcode`, `review`, `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`, `init`, `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

@@ -282,6 +282,7 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `getting-started` — the `docs/getting-started.md` onboarding guide
 - `config` — team.yaml, config.yaml
 - `github` — CI/CD, issue templates, PR templates
+- `github-sync` — `cli/github-sync.js` and its discovery/parsing logic
 - `cli` — `cli/*.js` and `rcode/bin/rcode-tools.cjs`
 - `state` — `.rcode/state.json` and state-manipulation code paths
 - `refs` — files inside `rcode/references/`
@@ -311,6 +312,8 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `plan` — plan workflow
 - `planner` — planner agent
 - `readme` — README.md
+- `review` — code review reports and review-gate fixes (e.g. `NN-REVIEW.md` resolutions)
+- `rcode` — cross-cutting rcode planning/methodology commits not tied to one narrower scope
 - `sync` — install/state sync flows
 - `sprint` — sprint-level workflow additions and fixes
 - `agent-exp` — agent experience improvements

package/README.md

@@ -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.7.0 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.
+Status: `@hanzlaa/rcode` v4.8.0 on npm. 45 agents · 117 commands · 130 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
 
 ---
 
@@ -154,10 +154,10 @@ The point isn't "I beat LangChain." The point is **you don't need LangChain for
 | Metric | Value | Why it's not a vanity number |
 |---|---|---|
 | **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. |
+| **Automated tests** | **598** across 74 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. |
+| **Specialist agents / commands / workflows / skills** | **45 / 117 / 130 / 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.
@@ -181,6 +181,8 @@ pnpm dlx @hanzlaa/rcode install
 
 `/rcode-init` detects your project state (fresh / existing / returning) and routes to the right first action. For a greenfield project it auto-routes to `/rcode-new-project`.
 
+> **Want a status primer at the start of every session?** Run `/rcode-enable-hooks` to turn on a one-line project status readout (phase, plan progress, blockers) each time Claude Code starts in this project, plus 9 other opt-in guardrails (read-before-edit checks, dangerous-command blocking, auto-formatting). All off by default — a fresh install never surprises you.
+
 ### The full loop
 
 Four commands cover most of a real week of work — decide, plan, build, check in:
@@ -227,9 +229,9 @@ The non-goal: building yet another agent framework. There are enough. rcode stay
 
 ## Honest state of things
 
-- **v4.3.2** is the current release — Memory Bank now ships populated by default, brain-pull is live, and 50+ bug fixes landed from the most recent 3-project dogfeed run.
+- **v4.8.0** is the current release — Memory Bank now ships populated by default, brain-pull is live, and 50+ bug fixes landed from the most recent 3-project dogfeed run.
 - **Open issues**: ~50 — half are feature requests, the rest are backlog bugs ranked by severity.
-- **Test suite**: 497 automated tests across 61 files, 100% pass on every release (run `node --test`). Coverage is structural (compliance + artifact schema + workflow behavioral), not line-coverage.
+- **Test suite**: 598 automated tests across 74 files (run `node --test`). Live pass/fail status is on the CI badge above. Coverage is structural (compliance + artifact schema + workflow behavioral), not line-coverage.
 - **Real users**: I run it on 4 projects daily. A handful of others run it on theirs. If you find a bug, file it — most P1s ship within 48 hours.
 - **Funding**: none. This is solo work. If your company wants commercial support, [email me](mailto:hanzla.dev@gmail.com).
 

package/cli/github-sync.js

@@ -11,10 +11,10 @@
  *   rcode github-sync --execute       # actually create issues
  *
  * Granular targeting (push specific items):
- *   --phase=phase-02          push one phase (all its epics + stories)
- *   --sprint=sprint-01        push stories belonging to one sprint
- *   --epic=epic-1-auth        push one epic and its child stories
- *   --story=story-1-1-login   push one story
+ *   --phase=44                push one phase (all its epics + stories)
+ *   --sprint=44.1             push stories belonging to one sprint
+ *   --epic=EPIC-01            push one epic and its child stories
+ *   --story=44.1.1            push one story (sprint-track task id or epic-track story id, e.g. 1.1)
  *
  * Options:
  *   --repo=owner/name     target a specific repo (otherwise auto-detect)
@@ -45,6 +45,7 @@ const gh = require('./lib/github.cjs');
 const { askText, PromptAbortError } = require('./lib/prompts.cjs');
 const { writeJsonAtomic } = require('./lib/fsutil.cjs');
 const { loadConfig } = require('./lib/config.cjs');
+const { discoverPhases, applyGranularFilters } = require('./lib/github-sync-discover.cjs');
 
 /**
  * Hash a string — used to detect content changes between syncs.
@@ -140,51 +141,6 @@ function parseArgs(args) {
   return opts;
 }
 
-/**
- * Parse YAML-ish frontmatter from the top of a markdown file.
- * Used to extract explicit epic/sprint linking from story files.
- * Returns an object of key/value strings, or {} if no frontmatter block.
- */
-function extractFrontmatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return {};
-  const fm = {};
-  for (const line of match[1].split(/\r?\n/)) {
-    const m = line.match(/^([\w_-]+)\s*:\s*(.*)$/);
-    if (m) fm[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
-  }
-  return fm;
-}
-
-/**
- * Parse .rcode/phases/{phase}/sprints.md if present and return a map of
- * sprint-id → story-ids (based on "- [ ] story-X-Y" list entries under
- * each sprint section). Used by --sprint=ID filtering.
- *
- * Sprint section convention:
- *   ## Sprint 1 — {goal}
- *   - [ ] story-1-1-login
- *   - [ ] story-1-2-signup
- */
-function parseSprintsFile(sprintsContent) {
-  if (!sprintsContent) return {};
-  const sprintMap = {};
-  let currentSprint = null;
-  for (const line of sprintsContent.split(/\r?\n/)) {
-    const header = line.match(/^##\s+Sprint\s+(\S+)/i);
-    if (header) {
-      currentSprint = `sprint-${header[1].replace(/[^\w-]/g, '')}`;
-      sprintMap[currentSprint] = [];
-      continue;
-    }
-    if (currentSprint) {
-      const item = line.match(/^\s*-\s*\[[ xX]\]\s+(\S+)/);
-      if (item) sprintMap[currentSprint].push(item[1]);
-    }
-  }
-  return sprintMap;
-}
-
 // ---------- Discover .rcode/ content ----------
 
 function loadState(cwd) {
@@ -196,148 +152,6 @@ function loadState(cwd) {
   try { return JSON.parse(fs.readFileSync(statePath, 'utf8')); } catch { return null; }
 }
 
-function discoverPhases(cwd) {
-  const phasesDir = path.join(cwd, '.rcode/phases');
-  if (!fs.existsSync(phasesDir)) return [];
-
-  const phases = [];
-  for (const entry of fs.readdirSync(phasesDir, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const phaseDir = path.join(phasesDir, entry.name);
-    const briefPath = path.join(phaseDir, 'brief.md');
-    const sprintsPath = path.join(phaseDir, 'sprints.md');
-    const storiesDir = path.join(phaseDir, 'stories');
-    const tasksDir = path.join(phaseDir, 'tasks');
-
-    const sprintsContent = fs.existsSync(sprintsPath)
-      ? fs.readFileSync(sprintsPath, 'utf8')
-      : null;
-
-    const phase = {
-      id: entry.name,
-      brief: fs.existsSync(briefPath) ? fs.readFileSync(briefPath, 'utf8') : null,
-      sprints: sprintsContent,
-      sprintMap: parseSprintsFile(sprintsContent),
-      stories: [],
-      epics: [],
-    };
-
-    if (fs.existsSync(storiesDir)) {
-      for (const file of fs.readdirSync(storiesDir)) {
-        if (!file.endsWith('.md')) continue;
-        const content = fs.readFileSync(path.join(storiesDir, file), 'utf8');
-        const fm = extractFrontmatter(content);
-        const id = file.replace('.md', '');
-        // Figure out which epic this story belongs to: prefer explicit
-        // frontmatter, fall back to "story-X-..." → "epic-X-..." naming
-        // convention so existing projects without frontmatter still link.
-        let parentEpic = fm.epic || null;
-        if (!parentEpic) {
-          const m = id.match(/^story-(\d+)/);
-          if (m) parentEpic = `epic-${m[1]}`;
-        }
-        // Figure out which sprint this story belongs to: explicit
-        // frontmatter wins, else look it up in the sprint map.
-        let sprintId = fm.sprint || null;
-        if (!sprintId) {
-          for (const [sid, storyList] of Object.entries(phase.sprintMap)) {
-            if (storyList.some((s) => s === id || id.startsWith(s))) {
-              sprintId = sid;
-              break;
-            }
-          }
-        }
-        phase.stories.push({
-          id,
-          file,
-          content,
-          title: extractTitle(content) || id,
-          parentEpic,
-          sprintId,
-          frontmatter: fm,
-        });
-      }
-    }
-
-    if (fs.existsSync(tasksDir)) {
-      for (const file of fs.readdirSync(tasksDir)) {
-        if (!file.endsWith('.md')) continue;
-        const content = fs.readFileSync(path.join(tasksDir, file), 'utf8');
-        const fm = extractFrontmatter(content);
-        phase.epics.push({
-          id: file.replace('.md', ''),
-          file,
-          content,
-          title: extractTitle(content) || file.replace('.md', ''),
-          frontmatter: fm,
-        });
-      }
-    }
-
-    phases.push(phase);
-  }
-
-  return phases;
-}
-
-/**
- * Apply granular --sprint/--epic/--story filters to the discovered phases.
- * Mutates a shallow copy — original discovery result is not touched.
- * Returns a new phases array where only the requested items remain.
- */
-function applyGranularFilters(phases, opts) {
-  // No filters → return as-is
-  if (!opts.sprint && !opts.epic && !opts.story) return phases;
-
-  const filtered = phases.map((p) => ({
-    ...p,
-    epics: [...p.epics],
-    stories: [...p.stories],
-  }));
-
-  if (opts.sprint) {
-    for (const p of filtered) {
-      // Keep only stories whose sprintId matches
-      p.stories = p.stories.filter((s) => s.sprintId === opts.sprint);
-      // Keep only epics that have at least one remaining story or whose id
-      // the user might also be interested in (conservative: keep all epics
-      // in this phase so child stories have a visible parent reference)
-      // Actually: if filtering by sprint, user wants the sprint's work —
-      // stories only. Drop epics unless they're referenced by a remaining
-      // story.
-      const liveEpicIds = new Set(p.stories.map((s) => s.parentEpic).filter(Boolean));
-      p.epics = p.epics.filter((e) => liveEpicIds.has(e.id));
-    }
-  }
-
-  if (opts.epic) {
-    for (const p of filtered) {
-      p.epics = p.epics.filter((e) => e.id === opts.epic);
-      // Keep stories whose parentEpic matches
-      p.stories = p.stories.filter((s) => s.parentEpic === opts.epic);
-    }
-  }
-
-  if (opts.story) {
-    for (const p of filtered) {
-      p.stories = p.stories.filter((s) => s.id === opts.story);
-      // Keep any epic a surviving story points at (so link target exists)
-      const parents = new Set(p.stories.map((s) => s.parentEpic).filter(Boolean));
-      p.epics = p.epics.filter((e) => parents.has(e.id));
-    }
-  }
-
-  // Drop phases that ended up completely empty after filtering
-  return filtered.filter(
-    (p) => p.epics.length > 0 || p.stories.length > 0,
-  );
-}
-
-function extractTitle(markdown) {
-  const match = markdown.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : null;
-}
-
 // ---------- Load/save sync map (for idempotency) ----------
 
 function loadSyncMap(cwd) {
@@ -460,7 +274,9 @@ async function main(args) {
   // ------ Discover phases ------
   let phases = discoverPhases(cwd);
   if (opts.phase) {
-    phases = phases.filter((p) => p.id === opts.phase);
+    // Match either the full directory id or the bare numeric prefix so
+    // --phase=44 and --phase=44-github-sync-... both work.
+    phases = phases.filter((p) => p.id === opts.phase || p.numericId === opts.phase);
     if (phases.length === 0) {
       console.error(`❌ Phase '${opts.phase}' not found.`);
       process.exit(1);
@@ -481,8 +297,8 @@ async function main(args) {
       console.error(`   Check the filter value or run without filters to see available ids.`);
       process.exit(1);
     }
-    console.log(`ℹ  No phases found in .rcode/phases/ — nothing to sync.`);
-    console.log(`   Run 'rcode init' or create a phase to get started.`);
+    console.log(`ℹ  No phases found in .planning/phases/ or epics in .planning/epics/ — nothing to sync.`);
+    console.log(`   Run /rcode-plan or /rcode-create-epics-and-stories to get started.`);
     process.exit(0);
   }
 
@@ -551,7 +367,7 @@ async function main(args) {
       { name: 'QA', color: 'd73a4a', description: 'Quality assurance' },
       { name: 'Docs', color: 'c5def5', description: 'Documentation' },
     ] : [],
-    milestones: phases.filter((p) => !syncMap.phases[p.id]),
+    milestones: phases.filter((p) => !p.noMilestone && !syncMap.phases[p.id]),
     epics: phases.flatMap((p) =>
       p.epics.filter((e) => !syncMap.epics[e.id]).map((e) => ({ ...e, phase: p.id })),
     ),
@@ -702,7 +518,7 @@ async function main(args) {
         `## 📊 Meta`,
         ``,
         `- **Phase:** \`${epic.phase}\``,
-        `- **Source:** \`.rcode/phases/${epic.phase}/tasks/${epic.file}\``,
+        `- **Source:** \`${epic.sourcePath}\``,
         `- **Synced by:** rcode github-sync`,
         ``,
         `## 📝 Child Stories`,
@@ -785,7 +601,7 @@ async function main(args) {
         parentRefLine,
         sprintRefLine,
         `- **Phase:** \`${story.phase}\``,
-        `- **Source:** \`.rcode/phases/${story.phase}/stories/${story.file}\``,
+        `- **Source:** \`${story.sourcePath}\``,
         `- **Synced by:** rcode github-sync`,
         ``,
         `> **Linking:** Reference this story in commits with \`refs #${'{issue}'}\``,
@@ -892,7 +708,7 @@ async function main(args) {
       const body = [
         `## 🎯 Epic Vision`,
         ``,
-        `_Strategic goal this Epic contributes to. Fill in from \`.rcode/phases/${epic.phase}/tasks/${epic.file}\`._`,
+        `_Strategic goal this Epic contributes to. Fill in from \`${epic.sourcePath}\`._`,
         ``,
         `## 📋 Source Content`,
         ``,
@@ -903,7 +719,7 @@ async function main(args) {
         `## 📊 Meta`,
         ``,
         `- **Phase:** \`${epic.phase}\``,
-        `- **Source:** \`.rcode/phases/${epic.phase}/tasks/${epic.file}\``,
+        `- **Source:** \`${epic.sourcePath}\``,
         `- **Last synced:** ${new Date().toISOString()}`,
       ].join('\n');
 
@@ -937,7 +753,7 @@ async function main(args) {
       const body = [
         `## 🎯 Problem Statement`,
         ``,
-        `_From \`.rcode/phases/${story.phase}/stories/${story.file}\`._`,
+        `_From \`${story.sourcePath}\`._`,
         ``,
         `## 📋 Source Content`,
         ``,
@@ -948,7 +764,7 @@ async function main(args) {
         `## 📊 Meta`,
         ``,
         `- **Phase:** \`${story.phase}\``,
-        `- **Source:** \`.rcode/phases/${story.phase}/stories/${story.file}\``,
+        `- **Source:** \`${story.sourcePath}\``,
         `- **Last synced:** ${new Date().toISOString()}`,
       ].join('\n');
 

package/cli/install.js

@@ -2502,21 +2502,32 @@ async function installInner(opts) {
         fs.existsSync(path.join(projectClaudeCommands, 'rcode'))
       );
       if (globalHasrcode && !projectHasrcode) {
-        // Global commands exist, project has none yet — filter them out of the plan
-        // so we don't create duplicates. Project gets .rcode/ state only.
+        // Global commands exist, project has none yet — filter commands out of the
+        // plan so we don't create duplicates. Project gets .rcode/ state only.
+        //
+        // Issue #1022: agents are NOT deferrable to global the way commands/skills
+        // are — they are first-class, project-local files by design (see the
+        // createInstallBackup comment above: "closes #381 — without this,
+        // customized .claude/agents/rcode-*.md ... were silently lost"). Lumping
+        // `.claude/agents/` into this commands-dedup filter meant a project with
+        // global rcode commands installed but no project-level commands yet would
+        // never get its .claude/agents/*.md files written at all, leaving only
+        // whatever pre-existing subdirectories (e.g. rules/) survived untouched.
         const before = plan.length;
         const filtered = plan.filter(e => {
           const rel = e.rel.split(path.sep).join('/');
-          return !rel.startsWith('.claude/commands/') && !rel.startsWith('.claude/agents/');
+          return !rel.startsWith('.claude/commands/');
         });
         if (filtered.length < before) {
           plan.length = 0;
           filtered.forEach(e => plan.push(e));
-          console.log('  ' + dim('Global rcode commands detected in ~/.claude/ — skipping project-level agent/command install to avoid duplicates.'));
+          console.log('  ' + dim('Global rcode commands detected in ~/.claude/ — skipping project-level command install to avoid duplicates.'));
           console.log('  ' + dim('Use --force-overwrite to install locally anyway.'));
         }
       } else if (globalHasrcode && projectHasrcode) {
         // Both exist — project commands are duplicates. Remove project-level ones.
+        // Agents are left untouched (#1022) — they are project-local by design,
+        // never deduped against the global commands install.
         try {
           // Remove root-level rcode-*.md files
           const projectCommandFiles = fs.readdirSync(projectClaudeCommands)
@@ -2530,19 +2541,11 @@ async function installInner(opts) {
           if (fs.existsSync(rcodeSubdir)) {
             safeRmSync(rcodeSubdir, opts.target);
           }
-          const projectAgentsDir = path.join(opts.target, '.claude', 'agents');
-          if (fs.existsSync(projectAgentsDir)) {
-            const agentFiles = fs.readdirSync(projectAgentsDir)
-              .filter(f => f.startsWith('rcode-') && f.endsWith('.md'));
-            for (const f of agentFiles) {
-              fs.unlinkSync(path.join(projectAgentsDir, f));
-            }
-          }
           console.log('  ' + dim('Removed duplicate project-level rcode commands (global ones in ~/.claude/ take precedence).'));
         } catch { /* non-fatal */ }
         const filtered = plan.filter(e => {
           const rel = e.rel.split(path.sep).join('/');
-          return !rel.startsWith('.claude/commands/') && !rel.startsWith('.claude/agents/');
+          return !rel.startsWith('.claude/commands/');
         });
         plan.length = 0;
         filtered.forEach(e => plan.push(e));

package/cli/lib/config.cjs

@@ -49,7 +49,7 @@ const HARDCODED_DEFAULTS = {
 
   // Paths
   output_folder: '.rcode',
-  planning_artifacts: '.rcode/phases',
+  planning_artifacts: '.planning/phases',
   project_knowledge: '.rcode/context',
 
   // Model profile — matches model-profiles.json names