@hanzlaa/rcode 4.7.0 → 4.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "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/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