@hanzlaa/rcode 4.7.0 → 4.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.7.0",
+  "version": "4.7.2",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/bin/rcode-tools.cjs

@@ -4589,6 +4589,7 @@ This file is loaded by Claude Code, Codex, and compatible AI coding tools at the
 - No "while I'm here" improvements
 - No speculative abstractions
 - No new files unless necessary
+- **No freehand status/handoff docs** (\`HANDOFF.md\`, \`AGENT_X_DONE.md\`, anything at the project root summarizing "what I did"). That record is \`<N>-SUMMARY.md\` under \`.planning/phases/\` — even mid-task or in a parallel multi-agent run, write there, not a new root-level file.
 
 ---
 

package/rcode/commands/do.md

@@ -1,6 +1,15 @@
 ---
 name: rcode-do
-description: "[ROUTER] Interactive picker — describe what you want and rcode picks the command"
+description: >-
+  [ROUTER] Interactive picker — describe what you want and rcode picks
+  the command. Activates whenever the user says "use rcode", "using
+  rcode", "rcode kar do", "rcode say kara do", "let rcode handle
+  this/it", "rcode this", or otherwise names rcode as the tool to use
+  for a task without naming a specific /rcode-* command — especially
+  when the request bundles multiple asks (e.g. "init a phase, build a
+  checklist, make a sprint"). Route through this picker instead of
+  hand-rolling files or Bash workarounds for what rcode already has a
+  command for.
 argument-hint: "[optional question or task description]"
 allowed-tools:
   - Read

package/rcode/references/agent-shared-rules.md

@@ -48,6 +48,12 @@
 
 ---
 
+## File placement discipline
+
+**Completion notes go in the sprint file, never a freehand root-level doc.** When work finishes, the record is `.planning/phases/{phase}/{sprint}-SUMMARY.md` (written by `/rcode-execute`) or a note in the existing `SPRINT.md`/`REVIEW.md` — never a new `SOMETHING_DONE.md`, `HANDOFF.md`, or `AGENT_X_DONE.md` at the project root or anywhere outside `.planning/`/`.rcode/`. If you're in a parallel multi-agent run and were asked for a "handoff doc," that handoff still belongs inside the sprint's own files — a sibling agent reads the next `SPRINT.md`/`CONTEXT.md`, not a scavenger hunt through the repo root for status files with inconsistent names.
+
+**Never invent a new top-level artifact type.** `PROJECT.md`, `ROADMAP.md`, `REQUIREMENTS.md`, `CONTEXT.md`, `RESEARCH.md`, `SPRINT.md`, `SUMMARY.md`, `REVIEW.md` — this is the closed set. If a task genuinely needs a new kind of record, that's a call for the user, not something to freehand mid-task.
+
 ## Framework discipline
 
 **Cite the heuristic by name.** When refusing or recommending, name the rule that drove the call. *"Per the Reversibility test, this is a one-way door — ADR required."* Traceable reasoning beats opinion.

package/rcode/references/executor-playbook.md

@@ -26,7 +26,7 @@ If you commit a file under `.planning/` and `git status` afterwards still shows
 2. **Load sprint** — Parse SPRINT.md frontmatter (phase, sprint, type, autonomous, wave, depends_on). Honor CONTEXT.md if referenced.
 3. **Determine pattern** — Pattern A (no checkpoints → execute all), B (has checkpoints → stop at first), C (continuation → resume).
 4. **Execute stories** — For each story: if `type="auto"`, execute and commit. If `type="checkpoint:*"`, STOP and return checkpoint. Update story status via `rcode-tools.cjs state story move --id NN.S.TT --status done`.
-5. **Create SUMMARY** — After all auto stories complete, write `.planning/phases/XX-name/{phase}-{sprint}-SUMMARY.md`.
+5. **Create SUMMARY** — After all auto stories complete, write `.planning/phases/XX-name/{phase}-{sprint}-SUMMARY.md`. This is the *only* completion artefact. Never write a parallel status/handoff doc (`AGENT_X_DONE.md`, `HANDOFF.md`, a root-level `*_DONE.md`) — if the run involves multiple parallel executors, each still records its own SUMMARY.md under its own sprint; there is no separate hand-off format.
 6. **Update state** — Run state tools to record metrics, mark stories complete, advance sprint.
 7. **Final commit** — Commit SUMMARY.md, STATE.md, ROADMAP.md with docs message.
 

package/rcode/references/planner-playbook.md

@@ -12,6 +12,7 @@ hierarchical ID format, and output routing.
 
 ### Context Fidelity
 - **Locked Decisions** (CONTEXT.md): MUST implement exactly. Reference decision ID (D-01, D-02) in task actions.
+- **Reference, don't restate.** A decision ID is a pointer, not a license to re-paste the rationale. `<action>` explains WHAT to do and cites the ID for WHY (`"per D-02's flattening rule"`) — it does not re-explain the decision's reasoning, alternatives, or findings inline. The full "why" already lives in CONTEXT.md/RESEARCH.md; the executor opens those if they need it. A task whose `<action>` reads like a design doc (multi-paragraph rationale, full alternatives-considered writeups) is a sign the planner copied instead of pointed — cut it down to the instruction + the ID.
 - **Deferred Ideas**: MUST NOT appear in plans.
 - **Agent's Discretion**: Use judgment, document choices.
 

package/rcode/workflows/init.md

@@ -285,6 +285,18 @@ After writing both files, refresh the memory bank fingerprint so staleness check
 node .rcode/bin/rcode-tools.cjs context refresh >/dev/null 2>&1 || true
 ```
 
+## Step 4c — Scaffold CLAUDE.md / AGENTS.md if missing
+
+`generate-claude-md` (the command routing rule + project rules block every agent needs at session start) previously only ran via the `/rcode-new-project` roadmap flow — a project set up with `/rcode-init` alone (the common "add rcode to an existing codebase" path) never got it, so agents had no ambient instruction to check `do.md` before acting ad-hoc. Close that gap here, unconditionally (not just on `fresh`):
+
+```bash
+if [ ! -f CLAUDE.md ]; then
+  node .rcode/bin/rcode-tools.cjs generate-claude-md
+fi
+```
+
+Never pass `--force` here — an existing `CLAUDE.md` is the user's own file (or was already generated by a prior init/new-project run) and must not be overwritten. Silent no-op when `CLAUDE.md` already exists.
+
 ## Step 5 — Suggest the next step
 
 Print a contextual recommendation, **one line of copy-paste per suggestion** (per `.rcode/references/command-redirect-format.md`):
@@ -339,6 +351,7 @@ Silent if state tools fail.
 - [ ] `.rcode/JOURNEY.md` written (unless `--skip-scan` or no code)
 - [ ] `.rcode/context/active.md` populated with project state (not the placeholder stub)
 - [ ] `.rcode/context/project-brief.md` populated with project overview (not the placeholder stub)
+- [ ] `CLAUDE.md` exists (generated if it didn't already)
 - [ ] State detected correctly (fresh / existing-new-rcode / returning)
 - [ ] Contextual next-step suggestion printed as single-line copy-paste
 

package/rcode/workflows/new-project-create-roadmap.md

@@ -161,42 +161,32 @@ Use AskUserQuestion:
 
 **Generate or refresh project instruction file before final commit:**
 
-The rcode-tools CLI does not expose a `generate-claude-md` subcommand. Instead, if `$INSTRUCTION_FILE` does not already exist, write a minimal instruction file pointing at the rcode workflow docs:
-
-```markdown
-# {INSTRUCTION_FILE} — project instructions
-
-This project uses rcode for planning and execution. See `.planning/PROJECT.md` for context and `.planning/ROADMAP.md` for phases.
-
-Common commands:
-- /rcode-progress — check status and next action
-- /rcode-discuss-phase N — gather context before planning phase N
-- /rcode-plan N — create a SPRINT.md for phase N
-- /rcode-execute N — execute a SPRINT.md
-- /rcode-verify-work — conversational UAT
-- /rcode-complete-milestone — archive milestone and reset
-
-Rules:
-- Never run `git push` without explicit user authorization.
-- No Claude/AI attribution in commits.
-- Prefer editing existing files over creating new ones.
+```bash
+node .rcode/bin/rcode-tools.cjs generate-claude-md
 ```
 
-If it already exists, leave it alone (respect user-customized content).
+Writes `CLAUDE.md` and `AGENTS.md` from rcode's own template (commit rules,
+push rules, phase workflow rules, scope discipline, and the command-routing
+rule pointing at `do.md`). Refuses to touch an existing `CLAUDE.md` — if it
+already exists, this is a silent no-op (respects user-customized content).
+`AGENTS.md` is written only when absent, so an install-appended `## rcode
+Agents (installed)` roster section is never clobbered.
 
 **Commit roadmap (guarded):**
 
 ```bash
-git add \
-  .planning/ROADMAP.md \
-  .planning/STATE.md \
-  .planning/REQUIREMENTS.md \
-  "$INSTRUCTION_FILE" 2>/dev/null \
+# git add fails its whole invocation on any missing pathspec, so only pass
+# paths that actually exist (CLAUDE.md/AGENTS.md are conditional — see above).
+ADD_PATHS=(.planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md)
+for f in CLAUDE.md AGENTS.md; do [ -f "$f" ] && ADD_PATHS+=("$f"); done
+
+git add "${ADD_PATHS[@]}" 2>/dev/null \
 && git commit -m "docs: create roadmap ([N] phases)" 2>/dev/null \
-|| echo "ℹ .planning/ gitignored — roadmap written, not committed (instruction file committed separately)"
+|| echo "ℹ .planning/ gitignored — roadmap written, not committed (instruction files committed separately)"
 
-# Fallback: also try committing just the instruction file if .planning was ignored
-git add "$INSTRUCTION_FILE" 2>/dev/null && git commit -m "docs: add project instruction file" 2>/dev/null || true
+# Fallback: also try committing just the instruction files if .planning was ignored
+IFILES=(); for f in CLAUDE.md AGENTS.md; do [ -f "$f" ] && IFILES+=("$f"); done
+[ ${#IFILES[@]} -gt 0 ] && git add "${IFILES[@]}" 2>/dev/null && git commit -m "docs: add project instruction files" 2>/dev/null || true
 
 # Sync all roadmapper-created phases into state.json.
 # rcode-roadmapper writes ROADMAP.md as text — it never calls `phase add` — so

package/rcode/workflows/plan-spawn-planner.md

@@ -79,6 +79,12 @@ Planner prompt:
 **Phase:** {phase_number}
 **Mode:** {standard | gap_closure | reviews}
 
+## Scope
+
+Default: `phase` (one SPRINT.md, up to 8 stories — see Scope-Driven Sizing in your role instructions).
+
+**Self-upgrade to `initiative` mid-decomposition** if, once you've read CONTEXT.md/ROADMAP.md and started breaking down the work, it splits into independent waves or work-streams (e.g. shared-primitive foundation → feature-local migrations → cleanup/tests) and total stories would exceed 8. When that happens, emit multiple SPRINT.md files (`{phase}-1-SPRINT.md`, `{phase}-2-SPRINT.md`, ...) in this same run instead of one oversized plan. Do not wait for rcode-sprint-checker's "scope exceeds context budget" rejection to force a resharding pass — that costs a full extra planner run. Decide the split now, while you're already looking at the file/story list.
+
 <files_to_read>
 - {state_path} (Project State)
 - {roadmap_path} (Roadmap)

package/server/lib/html/client/components/shared.js

@@ -131,7 +131,11 @@ export function Breadcrumb({ items }) {
  * @param {{ cmd: string, desc: string }} props
  */
 export function CmdHint({ cmd, desc }) {
-  function handleClick() {
+  function handleClick(e) {
+    // CmdHint often sits inside a clickable card row (SprintCard's empty
+    // state, etc.) — without this, copying the command also fires the
+    // row's own click (e.g. navigating away mid-copy).
+    if (e && e.stopPropagation) e.stopPropagation();
     navigator.clipboard.writeText(cmd)
       .then(() => showToast('Copied: ' + cmd))
       .catch(() => {
@@ -291,9 +295,7 @@ export function SprintCard({ sprint: s, S }) {
       </div>
       <div style="margin-top:6px;"><${ProgressBar} done=${done} total=${stories.length}/></div>
       ${stories.length === 0 ? html`
-        <div class="empty-action" style="margin-top:var(--space-2);font-size:var(--text-xs);">
-          No tasks — run <code>/rcode-plan ${phaseId}</code> to populate
-        </div>
+        <${CmdHint} cmd=${'/rcode-plan ' + phaseId} desc="Populate this sprint with tasks"/>
       ` : null}
       ${s.started_at ? html`
         <div style="color:var(--text-muted);font-size:var(--text-xs);margin-top:4px;">

package/server/lib/html/client/views/BacklogView.js

@@ -9,7 +9,7 @@
 
 import { html } from '../preact.js';
 import { useStore } from '../store.js';
-import { pressable } from '../components/shared.js';
+import { pressable, CmdHint } from '../components/shared.js';
 import { Icon } from '../icons-client.js';
 
 export function BacklogView() {
@@ -23,7 +23,7 @@ export function BacklogView() {
         ? html`
           <div class="empty">
             No phases waiting in the backlog.
-            <div class="empty-action">Run /rcode-add-phase to queue up new work</div>
+            <${CmdHint} cmd="/rcode-add-phase" desc="Queue up new work"/>
           </div>
         `
         : html`

package/server/lib/html/client/views/KanbanView.js

@@ -9,11 +9,11 @@
 
 import { html, useState, useCallback } from '../preact.js';
 import { useStore, refresh } from '../store.js';
-import { allTasks, currentPhaseName } from '../util.js';
+import { allTasks, currentPhaseName, currentPhaseId } from '../util.js';
 import { stopStory, openOrchPanel, openTermPanel, setTaskStatus } from '../orchestrator.js';
 import { openFileViewer } from '../store.js';
 import { openRunnerPicker } from '../components/RunnerPicker.js';
-import { showToast } from '../components/shared.js';
+import { showToast, CmdHint } from '../components/shared.js';
 
 // ---- Column descriptors ----
 const COLS = [
@@ -262,9 +262,11 @@ export function KanbanView() {
               ${' is active.'}
             </div>
           ` : null}
+          <${CmdHint}
+            cmd=${'/rcode-plan' + (currentPhaseId(currentPhase) ? ' ' + currentPhaseId(currentPhase) : '')}
+            desc="Generate sprint stories"/>
           <div class="empty-action">
-            Run <code>/rcode-plan</code> to generate sprint stories, or browse
-            planning docs in the <a href="#files">Files</a> view.
+            Or browse planning docs in the <a href="#files">Files</a> view.
           </div>
         </div>
       </div>

package/server/lib/html/client/views/MemoryView.js

@@ -14,6 +14,7 @@
 
 import { html, useState, useEffect } from '../preact.js';
 import { FileReader } from '../components/FileReader.js';
+import { CmdHint } from '../components/shared.js';
 
 // ---- Command hints accordion ----
 const MEMORY_HINTS = [
@@ -127,7 +128,7 @@ export function MemoryView() {
         <div class="empty">
           <h3 style="color:var(--rcode-gold);">Not initialised</h3>
           <p>The Memory Bank is rcode's structured project context.</p>
-          <div class="empty-action">Run <code>/rcode-memory-init</code> to bootstrap</div>
+          <${CmdHint} cmd="/rcode-memory-init" desc="Bootstrap the Memory Bank"/>
         </div>
       </div>
     `;

package/server/lib/html/client/views/PhasesView.js

@@ -11,7 +11,7 @@ import { html, useState } from '../preact.js';
 import { useStore } from '../store.js';
 import { pct, humanDate, phaseHints, chip, phaseMilestone } from '../util.js';
 import {
-  Chip, ProgressBar, Breadcrumb, CmdHints, RunningBadge, SprintCard, PhaseCard,
+  Chip, ProgressBar, Breadcrumb, CmdHint, CmdHints, RunningBadge, SprintCard, PhaseCard,
 } from '../components/shared.js';
 import { openTermPanel, runningInPhase } from '../orchestrator.js';
 import { openFileViewer } from '../store.js';
@@ -118,7 +118,7 @@ function PhaseDetail({ phase: p, S }) {
           : html`
               <div class="empty">
                 No sprints in this phase yet.
-                <div class="empty-action">Run /rcode-plan to create sprints</div>
+                <${CmdHint} cmd=${'/rcode-plan ' + p.id} desc="Create sprints for this phase"/>
               </div>
             `}
       </div>
@@ -212,7 +212,7 @@ export function PhasesView({ subId, filters }) {
           : html`
               <div class="empty">
                 No phases yet.
-                <div class="empty-action">Run /rcode-new-project to start</div>
+                <${CmdHint} cmd="/rcode-new-project" desc="Design your first project"/>
               </div>
             `}
       </div>

package/server/lib/html/client/views/SprintsView.js

@@ -10,9 +10,9 @@
 
 import { html, useState } from '../preact.js';
 import { useStore } from '../store.js';
-import { pct, humanDate, allSprints, sprintHints, chip, phaseMilestone } from '../util.js';
+import { pct, humanDate, allSprints, sprintHints, chip, phaseMilestone, currentPhaseId } from '../util.js';
 import {
-  Chip, ProgressBar, Breadcrumb, CmdHints, RunningBadge, SprintCard, TaskCard,
+  Chip, ProgressBar, Breadcrumb, CmdHint, CmdHints, RunningBadge, SprintCard, TaskCard,
 } from '../components/shared.js';
 import { openTermPanel, runningInSprint } from '../orchestrator.js';
 import { openFileViewer } from '../store.js';
@@ -105,7 +105,7 @@ function SprintDetail({ sprint: s, S }) {
           : html`
               <div class="empty">
                 No tasks in this sprint yet.
-                <div class="empty-action">Run /rcode-create-story to add tasks</div>
+                <${CmdHint} cmd=${'/rcode-create-story ' + s.id} desc="Add a task to this sprint"/>
               </div>
             `}
       </div>
@@ -210,7 +210,7 @@ export function SprintsView({ subId, filters }) {
           : html`
               <div class="empty">
                 No sprints yet.
-                <div class="empty-action">Run /rcode-plan to create sprints</div>
+                <${CmdHint} cmd=${'/rcode-plan' + (currentPhaseId(S.currentPhase) ? ' ' + currentPhaseId(S.currentPhase) : '')} desc="Plan sprints for the current phase"/>
               </div>
             `}
       </div>

package/server/lib/html/client/views/TasksView.js

@@ -9,7 +9,7 @@
 import { html, useState, useMemo } from '../preact.js';
 import { useStore } from '../store.js';
 import { allTasks, currentPhaseId } from '../util.js';
-import { CmdHints, TaskCard } from '../components/shared.js';
+import { CmdHint, CmdHints, TaskCard } from '../components/shared.js';
 
 function TaskGrouped({ tasks }) {
   if (!tasks.length) return null;
@@ -137,9 +137,7 @@ export function TasksView() {
           : html`
               <div class="empty">
                 No tasks yet.
-                <div class="empty-action">
-                  Run <code>/rcode-plan${phaseHint}</code> to generate tasks for this project.
-                </div>
+                <${CmdHint} cmd=${'/rcode-plan' + phaseHint} desc="Generate tasks for this project"/>
               </div>
             `}
       </div>