@hanzlaa/rcode 4.1.0 → 4.1.2

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/SKILL.md

@@ -2,10 +2,12 @@
 name: rcode-scaffold-project
 internal: true
 description: >
-  Scaffold a new project for rcode users using the official rcode template repo.
+  Scaffold a new project for rcode users using the official rcode template repo,
+  or initialize rcode in an existing project (brownfield / --here mode).
   Activates when the user says "scaffold project", "create project", "new project",
   "initialize project", "setup new project", "scaffold from template", "create from template",
-  "rcode new project", or "start a new rcode project". Do NOT use for generating
+  "rcode new project", "start a new rcode project", "scaffold here", "use here",
+  "scaffold in this project", or "initialize rcode here". Do NOT use for generating
   project context files (use rcode-generate-project-context) or cloning websites
   (use rcode-clone-website).
 triggers:
@@ -18,6 +20,12 @@ triggers:
   - "create from template"
   - "rcode new project"
   - "start a new rcode project"
+  - "scaffold here"
+  - "scaffold --here"
+  - "use current directory"
+  - "scaffold in this project"
+  - "initialize rcode here"
+  - "add rcode to existing project"
 user-invocable: true
 ---
 @.rcode/references/karpathy-guidelines.md
@@ -30,14 +38,21 @@ user-invocable: true
 
 ## Overview
 
-This skill bootstraps a new rcode project by cloning the official rcode template
-repository (`https://github.com/rcode-om/template`) into a target directory.
+This skill operates in two modes:
 
-It always clones fresh from GitHub — nothing is stored locally — so if the template
-is updated, the next scaffold automatically picks up the latest version.
+**Greenfield mode (default):** Bootstraps a new rcode project by cloning the
+official rcode template (`https://github.com/rcode-om/template`) into a target
+directory. Always clones fresh from GitHub.
+
+**Brownfield mode (`--here`):** Initializes rcode in an *existing* project
+without cloning the template. Use this when your codebase already exists and
+you just want to add rcode structure to it. Invoke as:
+`/rcode-scaffold-project --here` or just say "scaffold here" / "add rcode to
+this existing project".
 
 The workflow enforces safety: it never overwrites an existing non-empty directory
-without explicit user consent.
+without explicit user consent (greenfield), and never modifies existing project
+files in brownfield mode.
 
 ## On Activation
 
@@ -53,9 +68,10 @@ Then proceed to `./steps/step-01-target.md`.
 
 | # | Stage | Purpose | File |
 |---|-------|---------|------|
-| 1 | Target Directory | Get + validate destination path | `steps/step-01-target.md` |
-| 2 | Safety Check | Verify folder is empty or get new path | `steps/step-02-safety.md` |
-| 3 | Clone | Clone template repo fresh from GitHub | `steps/step-03-clone.md` |
+| 1 | Target Directory | Get + validate destination path; detect `--here` flag | `steps/step-01-target.md` |
+| 2 | Safety Check | Verify folder is empty or get new path (greenfield); brownfield consent (brownfield) | `steps/step-02-safety.md` |
+| 3a | Clone | Clone template repo fresh from GitHub *(greenfield only)* | `steps/step-03-clone.md` |
+| 3b | Brownfield Init | Overlay rcode structure into existing project *(brownfield only)* | `steps/step-03-brownfield.md` |
 | 4 | Post-Setup | Rename, init git, suggest next steps | `steps/step-04-post-setup.md` |
 
 ## Design Decisions
@@ -63,6 +79,7 @@ Then proceed to `./steps/step-01-target.md`.
 - **Always clone fresh** — never cache template locally. Template updates are free.
 - **No local template copy** — single source of truth is `https://github.com/rcode-om/template`.
 - **Safety first** — never touch a non-empty directory without user approval.
+- **Brownfield never overwrites** — in `--here` mode, existing files are never modified.
 - **Minimal assumptions** — ask before acting on any ambiguity.
 
 ## Output Format
@@ -86,6 +103,16 @@ Then proceed to `./steps/step-01-target.md`.
 **Input:** "scaffold project"
 **Expected:** Ask for project name before proceeding.
 
+### Happy Path — Brownfield (--here)
+**Input:** "/rcode-scaffold-project --here" or "add rcode to this existing project"
+**Expected:** Detect brownfield mode, use current directory, ask for consent, overlay
+`.rcode/` structure only, never touch existing files, summarize what was added.
+
+### Edge Case — Brownfield, .rcode already exists
+**Input:** `--here` flag but `.rcode/` already present in current dir
+**Expected:** "rcode is already initialized here. Run `/rcode-init` to reconfigure."
+
 ### Negative Test
-**Input:** "scaffold my existing repo" (existing non-empty dir provided)
-**Expected:** Safety check triggers. Never overwrites. Offers alternatives.
+**Input:** "scaffold my existing repo" (existing non-empty dir provided, no --here flag)
+**Expected:** Safety check triggers. Never overwrites. Offers alternatives including
+"Use `--here` mode to add rcode to this existing project instead".

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-01-target.md

@@ -1,14 +1,29 @@
 # Step 1: Target Directory
 
 ## Goal
-Determine the target directory for the new project.
+Determine the target directory and mode (greenfield or brownfield).
 
-## Rules
-- If the user already provided a project name or path when invoking the skill, use it.
+## Brownfield Detection (`--here` flag)
+
+Check whether the user invoked with `--here`, said "scaffold here", "add rcode to
+this project", "initialize rcode here", or any equivalent phrasing.
+
+If **brownfield mode** is detected:
+- Set `{brownfield_mode}` = `true`
+- Set `{target_path}` = current working directory (`pwd`)
+- Set `{project_name}` = basename of current directory
+- Inform the user:
+  > "Brownfield mode — I'll add rcode to the current directory `{target_path}` without touching any existing files."
+- Skip the name prompt and proceed directly to `step-02-safety.md`.
+
+## Greenfield Mode (default)
+
+- If the user already provided a project name or path, use it.
 - If not, ask: **"What should the project be called? I'll create a folder with that name in the current directory."**
 - Accept either a bare name (`my-app`) or a full path (`/home/user/projects/my-app`).
 - If bare name: resolve to `{cwd}/{name}` where `{cwd}` is the directory the user is currently in.
 - Store resolved path as `{target_path}` and project name as `{project_name}`.
+- Set `{brownfield_mode}` = `false`.
 - **Security:** Reject paths containing `..` traversal sequences before proceeding:
   ```bash
   case "{target_path}" in

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-02-safety.md

@@ -3,7 +3,29 @@
 ## Goal
 Ensure the target directory is safe to scaffold into.
 
-## Check: Does the directory exist?
+---
+
+## Brownfield Mode (`{brownfield_mode}` = true)
+
+### Case D — `.rcode/` already exists
+- Check if `{target_path}/.rcode/` already exists.
+- If yes: **STOP.**
+  > "rcode is already initialized in this directory. Run `/rcode-init` to reconfigure, or `/rcode-update` to update skills."
+- Do not proceed further.
+
+### Case E — `.rcode/` does not exist (proceed with consent)
+- Inform the user what will be created:
+  > "I'll add the following to `{target_path}` (existing files will NOT be touched):
+  > - `.rcode/` — rcode config and skills directory
+  > - `.rcode/config.json` — project config (name, language, etc.)
+  >
+  > Shall I proceed?"
+- Wait for explicit confirmation before proceeding.
+- On confirmation: proceed to `step-03-brownfield.md`.
+
+---
+
+## Greenfield Mode (`{brownfield_mode}` = false)
 
 ### Case A — Directory does not exist
 - Safe to proceed.
@@ -17,19 +39,21 @@ Ensure the target directory is safe to scaffold into.
 
 ### Case C — Directory exists and is NOT EMPTY
 - **STOP. Do not touch anything.**
-- Present the user with two options:
+- Present the user with options:
 
   > "The folder `{target_path}` already has files in it. For safety I won't touch it.
   >
   > What would you like to do?
   > **A)** Create a new folder called `{project_name}-new` instead
   > **B)** Give me a different folder name
-  > **C)** Empty the folder yourself first, then tell me when it's ready"
+  > **C)** Empty the folder yourself first, then tell me when it's ready
+  > **D)** Add rcode to this existing project instead (`--here` mode)"
 
 - Wait for user response. Do NOT proceed until user explicitly confirms.
 - If user chooses **A**: set `{target_path}` = `{cwd}/{project_name}-new`, proceed to step-03-clone.md.
 - If user chooses **B**: ask for new name, loop back to step-01-target.md logic.
 - If user chooses **C**: wait. When user says "ready" or "done", re-check the folder. Only proceed if it is now empty.
+- If user chooses **D**: set `{brownfield_mode}` = `true`, proceed to Case E above (brownfield consent).
 
 ## Security Note
 **NEVER delete, move, or modify files in an existing directory.** The user must take that action themselves. This skill only creates new content.

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-03-brownfield.md

@@ -0,0 +1,57 @@
+# Step 3b: Brownfield Initialization
+
+## Goal
+Add rcode structure to an existing project without cloning the template.
+No existing files are ever modified.
+
+## What Gets Created
+
+Only the following paths are written. If any already exist, skip and report:
+
+```
+{target_path}/
+└── .rcode/
+    └── config.json      ← project config (name, language)
+```
+
+## Execution
+
+### 1. Create `.rcode/` directory
+```bash
+mkdir -p "{target_path}/.rcode"
+```
+
+### 2. Write `.rcode/config.json`
+Create with sensible defaults derived from the existing project:
+```json
+{
+  "project_name": "{project_name}",
+  "communication_language": "English",
+  "created_at": "{iso_date}",
+  "mode": "brownfield"
+}
+```
+- Detect language preference from existing README or package.json if present.
+- Set `{iso_date}` from the current date.
+
+### 3. Detect existing project metadata (offer, don't force)
+- If `package.json` exists: read `name` field and offer to use it as `{project_name}` if different.
+- If `README.md` exists: acknowledge it and skip creating a new one.
+
+## Progress Updates
+Narrate each step:
+- "Creating `.rcode/` directory..."
+- "Writing `.rcode/config.json`..."
+- "Done! Proceeding to post-setup..."
+
+## Error Handling
+
+### `.rcode/` creation fails (permissions)
+- Report: "Couldn't create `.rcode/` — check directory permissions."
+- Do NOT retry automatically.
+
+## Output
+Confirm to the user:
+> "rcode structure added to `{target_path}`. No existing files were modified."
+
+Then proceed to `step-04-post-setup.md`.

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-03-clone.md

@@ -1,4 +1,7 @@
-# Step 3: Clone Template
+# Step 3a: Clone Template (Greenfield Only)
+
+> **Brownfield mode:** If `{brownfield_mode}` is `true`, skip this step entirely
+> and proceed to `step-03-brownfield.md` instead.
 
 ## Goal
 Clone the official rcode template repository fresh from GitHub into `{target_path}`.

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-04-post-setup.md

@@ -18,8 +18,9 @@ Finalize the scaffolded project and guide the user on next steps.
 - Run only if user confirms.
 
 ### 3. Summary
-Print a clean summary:
+Print a clean summary based on mode:
 
+**Greenfield:**
 ```
 ✅ Project scaffolded successfully!
 
@@ -33,6 +34,19 @@ Next steps:
   pnpm dev           ← to start development server
 ```
 
+**Brownfield (`--here` mode):**
+```
+✅ rcode initialized in existing project!
+
+📁 Location:  {target_path}
+🗂  Added:     .rcode/config.json
+📝 Note:      No existing files were modified.
+
+Next steps:
+  /rcode-init         ← configure rcode for this project
+  /rcode-new-project  ← design project requirements & roadmap
+```
+
 ### 4. Suggest next rcode skills
 Offer relevant follow-up actions:
 > "What would you like to do next?

package/rcode/skills/actions/4-implementation/rcode-trim/SKILL.md

@@ -66,7 +66,7 @@ Do NOT include: changes that touch behaviour; "while I'm here, also..."; trimmin
 
 **Happy path** — A 220-line component with 4 unused props, 2 dead useState hooks, and 30 lines of commented-out exploration code → trim to 140 lines, behaviour unchanged, tests green.
 
-**Edge case — comment that earns its lines** — `// see issue #234 — Postgres pre-13 doesn't return rowCount on UPSERT, so we re-query`. Don't touch it. The comment captures a constraint that won't be obvious from the code alone.
+**Edge case — comment that earns its lines** — `// see the upstream issue — Postgres pre-13 doesn't return rowCount on UPSERT, so we re-query`. Don't touch it. The comment captures a constraint that won't be obvious from the code alone.
 
 **Negative — "simplify by rewriting"** — User asks to "clean up" a working module. If the rewrite is bigger than the cuts, it's not trimming — it's a refactor. Refuse and route to `rcode-incremental` with a real task.
 

package/rcode/workflows/audit-milestone.md

@@ -141,7 +141,7 @@ If `--report` flag set, also print the report to stdout. Otherwise, just save to
 
 ## On Error
 
-If no SUMMARY.md files found, **do not dead-halt** (closes #234). Probe
+If no SUMMARY.md files found, **do not dead-halt**. Probe
 for executed-phase signals and offer recovery options:
 
 ```bash

package/rcode/workflows/audit.md

@@ -18,6 +18,7 @@ If `$ARGUMENTS` contains `--help` or `-h`:
 
 ```
 /rcode-audit                           # interactive — asks what to audit
+/rcode-audit --auto                    # non-interactive — auto-picks best target from project state
 /rcode-audit plans [--report]         # → audit-plans (structural + status + deps check)
 /rcode-audit phase [<NN>]              # → /rcode-verify-phase
 /rcode-audit milestone [--strict]      # → /rcode-audit-milestone (with synth fallback)
@@ -49,6 +50,8 @@ DISCUSS=$($TOOL config-get workflow.discuss_mode 2>/dev/null || echo "adaptive")
 ```
 
 Parse `$ARGUMENTS`:
+- If `--auto` flag is present: strip it from args and force `MODE=yolo` for this invocation
+  (allows non-interactive runs without permanently changing the project config).
 - First word ∈ {plans, phase, milestone, uat, code, fix, work, lens, worktrees} → set `$TARGET`, drop it from args, jump to Step 4.
 - Empty or unrecognised → continue to Step 2.
 

package/rcode/workflows/brainstorm.md

@@ -40,7 +40,7 @@ AskUserQuestion(
 
 ## Step 2 — Load brainstorming methods
 
-Read `rcode/references/brain-methods.csv` and parse it.
+Read `.rcode/references/brain-methods.csv` and parse it.
 
 If `--method` was specified:
 - Validate the method exists in the CSV

package/rcode/workflows/council.md

@@ -29,9 +29,10 @@ Closure: `rcode ► COUNCIL COMPLETE ✓` + Next Up with decision options.
 
 <required_reading>
 @.rcode/references/auto-init-guard.md
-@.rcode/references/output-format.md
 @.rcode/references/council-protocol.md
 </required_reading>
+<!-- output-format.md removed: council is self-contained via <output_format> above.
+     General banner/todo/spawn patterns are defined inline — no 398-line load needed. -->
 
 <process>
 ## Step 0 — Usage check
@@ -101,6 +102,12 @@ list from INIT_JSON so new agents added to team.yaml are automatically available
 Do not invoke `general-purpose` or any agent type not present in
 `installed_agents`. If the scorer surfaces an unknown agent, drop it
 from the panel silently.
+
+**Post-install agent namespace fallback:** If a `Task(subagent_type="rcode-{id}")` call
+fails with "Agent type not found", the runtime has not yet registered the new agent files
+(requires IDE/window reload). In that case retry with `subagent_type="rihal-{id}"` — the
+`rihal-*` agents are content-identical to `rcode-*` (pre-rebrand names). If neither works,
+skip that panelist and log `[council] agent rcode-{id} not available — reload IDE to register`.
 </available_agent_types>
 
 ## Step 1 — Observe

package/rcode/workflows/create-architecture.md

@@ -9,7 +9,11 @@ Write an Architecture Decision Record (ADR) or system design document. Delegates
 Locate and follow the installed skill:
 
 ```bash
-find .rcode/skills/actions -path "*rcode-create-architecture/workflow.md" 2>/dev/null | head -1
+if [ -f .rcode/skills/rcode-create-architecture/workflow.md ]; then
+  printf '%s\n' ".rcode/skills/rcode-create-architecture/workflow.md"
+else
+  find .rcode/skills/actions -path "*rcode-create-architecture/workflow.md" 2>/dev/null | head -1
+fi
 ```
 
 Read and follow the workflow at that path. If the path is empty:

package/rcode/workflows/create-prd.md

@@ -9,7 +9,11 @@ Create a Product Requirements Document from scratch through guided facilitation.
 Locate and follow the installed skill:
 
 ```bash
-find .rcode/skills/actions -path "*rcode-create-prd/workflow.md" 2>/dev/null | head -1
+if [ -f .rcode/skills/rcode-create-prd/workflow.md ]; then
+  printf '%s\n' ".rcode/skills/rcode-create-prd/workflow.md"
+else
+  find .rcode/skills/actions -path "*rcode-create-prd/workflow.md" 2>/dev/null | head -1
+fi
 ```
 
 Read and follow the workflow at that path. If the path is empty:

package/rcode/workflows/dashboard.md

@@ -33,8 +33,11 @@ if [ -f ./server/dashboard.js ]; then
 # 2. Installed package copy inside project
 elif [ -f ./.rcode/lib/server/dashboard.js ]; then
   DASHBOARD="./.rcode/lib/server/dashboard.js"
+# 3. Local npm dependency install
+elif [ -f ./node_modules/@hanzlaa/rcode/server/dashboard.js ]; then
+  DASHBOARD="./node_modules/@hanzlaa/rcode/server/dashboard.js"
 else
-  # 3. Global installs — check npm, pnpm, and yarn roots
+  # 4. Global installs — check npm, pnpm, and yarn roots
   for ROOT in "$(npm root -g 2>/dev/null)" "$(pnpm root -g 2>/dev/null)" "$(yarn global dir 2>/dev/null)/node_modules"; do
     [ -z "$ROOT" ] && continue
     if [ -f "$ROOT/@hanzlaa/rcode/server/dashboard.js" ]; then
@@ -42,7 +45,7 @@ else
       break
     fi
   done
-  # 4. Last resort — resolve via the rcode/rcode binary symlink
+  # 5. Last resort — resolve via the rcode/rcode binary symlink
   if [ -z "$DASHBOARD" ]; then
     for BIN in rcode; do
       BIN_PATH="$(command -v $BIN 2>/dev/null)" || continue

package/rcode/workflows/discuss-phase.md

@@ -39,21 +39,9 @@ Only include domain-probes.md when `HAS_PRODUCT_SIGNALS` is 0.
 </downstream_awareness>
 
 <philosophy>
-**User = founder/visionary. Claude = builder.**
-
-The user knows:
-- How they imagine it working
-- What it should look/feel like
-- What's essential vs nice-to-have
-- Specific behaviors or references they have in mind
-
-The user doesn't know (and shouldn't be asked):
-- Codebase patterns (researcher reads the code)
-- Technical risks (researcher identifies these)
-- Implementation approach (planner figures this out)
-- Success metrics (inferred from the work)
-
-Ask about vision and implementation choices. Capture decisions for downstream agents.
+User = visionary (knows what, not how). Claude = builder (asks about choices, not implementation).
+Ask about vision and decisions. Capture for downstream agents. Never ask about codebase patterns,
+technical risks, or architecture — those are research/planner territory.
 </philosophy>
 
 <scope_guardrail>
@@ -887,7 +875,7 @@ Display banner:
 Context captured. Launching plan...
 ```
 
-Launch plan using the Skill tool to avoid nested Task sessions (which cause runtime freezes due to deep agent nesting — see #686):
+Launch plan using the Skill tool to avoid nested Task sessions (which cause runtime freezes due to deep agent nesting):
 ```
 Skill(skill="rcode-plan", args="${PHASE} --auto ${RCODE_WS}")
 ```

package/rcode/workflows/execute-milestone.md

@@ -1,5 +1,5 @@
 <purpose>
-Execute all phases in the current milestone in dependency order, with verify gates between waves. Closes #738.
+Execute all phases in the current milestone in dependency order, with verify gates between waves.
 Reads the ROADMAP.md to determine phase ordering, executes each phase via /rcode-execute, runs /rcode-verify-phase after each, and surfaces blockers before advancing.
 </purpose>
 

package/rcode/workflows/execute-regression-gates.md

@@ -32,6 +32,9 @@ if [ -f "package.json" ]; then
 elif [ -f "Cargo.toml" ]; then
   cargo test 2>&1
 elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+  # Python prerequisites: ensure Python 3.10+ is active (python --version).
+  # Install dependencies (pip install -r requirements.txt or uv sync).
+  # Activate your venv if applicable before running tests.
   python -m pytest ${REGRESSION_FILES} -q --tb=short 2>&1
 fi
 ```

package/rcode/workflows/execute-sprint.md

@@ -4,7 +4,7 @@ Execute a phase prompt (SPRINT.md) and create the outcome summary (SUMMARY.md).
 
 <required_reading>
 Read STATE.md before any operation to load project context.
-Read config.json for planning behavior settings.
+Read config.yaml for planning behavior settings.
 
 @.rcode/references/git-integration.md
 @.rcode/references/karpathy-guidelines.md
@@ -17,6 +17,26 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 
 <process>
 
+<preflight name="dependency_check">
+**Check for uninstalled dependencies:** If a `package.json` exists in the project root but `node_modules/` is absent or empty, emit a WARNING and stop:
+
+```
+⚠ WARNING: package.json found but node_modules/ is missing or empty.
+  Run: pnpm install   (or npm install if pnpm is not available)
+  Then re-run the sprint. Proceeding without installed dependencies will cause task failures.
+```
+
+Do NOT auto-run the install. Emit the message and let the user decide.
+
+```bash
+if [ -f package.json ] && [ ! -d node_modules ] || [ -f package.json ] && [ -z "$(ls -A node_modules 2>/dev/null)" ]; then
+  echo "⚠ WARNING: package.json found but node_modules/ is missing or empty."
+  echo "  Run: pnpm install (or npm install if pnpm is not available)"
+  echo "  Then re-run the sprint."
+fi
+```
+</preflight>
+
 <step name="init_context" priority="first">
 Load execution context (paths only to minimize orchestrator context):
 
@@ -104,6 +124,8 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-SPRINT.md
 
 **Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn Task(subagent_type="rcode-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, reset the branch base with `git reset --soft {EXPECTED_BASE}` before starting work. This corrects a known issue on Windows where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD.
 
+**Post-install namespace fallback:** If `Task(subagent_type="rcode-executor")` fails with "Agent type not found", the runtime has not yet registered the agent (requires IDE reload after install). Retry with `subagent_type="rihal-executor"`. If that also fails, fall back to Pattern C (execute in main context) and log `[execute-sprint] rcode-executor not available — reload IDE or executing in main context`.
+
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 
 **Pattern C:** Execute in main using standard flow (step name="execute").
@@ -293,6 +315,12 @@ If a commit is BLOCKED by a hook:
 
 After each task (verification passed, done criteria met), commit immediately.
 
+**Preflight — verify git repo exists:**
+```bash
+git rev-parse --git-dir
+```
+If this fails, stop and emit: `No git repository found. Run git init first, then re-run this workflow.`
+
 **1. Check:** `git status --short`
 
 **2. Stage individually** (NEVER `git add .` or `git add -A`):
@@ -348,7 +376,7 @@ If new untracked files appeared after running scripts or tools, decide for each:
 </task_commit>
 
 <post_step_revert_gate>
-## Post-Step Revert Detection Gate (closes #737)
+## Post-Step Revert Detection Gate
 
 After committing each task, run a diff check to detect accidental reverts. This catches the class of bug where a task's implementation unknowingly undoes work from a previous task or wave.
 

package/rcode/workflows/execute-waves.md

@@ -26,6 +26,12 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
          seen_files[file] = plan
    ```
 
+   **Pseudocode quality checklist — apply before implementing any algorithm derived above:**
+   - No bare `except Exception` — catch specific exceptions
+   - No mutation of a collection while iterating over it
+   - Guard against file overwrites (check if path exists before writing)
+   - Validate inputs before processing
+
    **If overlap is detected:**
    - Warn the user:
      ```

package/rcode/workflows/execute.md

@@ -7,12 +7,22 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator s
 findings BEFORE any subagents are spawned. If any check fails, stop and
 route back to the user.
 
+0. **Project-status preflight:**
+   ```bash
+   PROJECT_STATUS=$(node .rcode/bin/rcode-tools.cjs project-status 2>/dev/null || echo uninitialized)
+   ```
+   If `PROJECT_STATUS` is `uninstalled`, `uninitialized`, or `stub`:
+   ```
+   Project not initialized. Run /rcode-init first (or /rcode-new-project for a greenfield project), then return here.
+   ```
+   Stop. Do not proceed until `project-status` returns `real`.
+
 1. **Init state**: `node .rcode/bin/rcode-tools.cjs init execute {N}`
 2. **Phase index**: list all plans via `phase-plan-index {N}` — extract
    plan count, wave count, autonomy flag per plan, files_modified overlaps
 3. **Anti-patterns**: check for `.continue-here.md` (paused state), STATE.md
    error flag, existing VERIFICATION.md with FAIL items without overrides
-4. **Branch check** (issue #659): confirm current git branch is appropriate
+4. **Branch check**: confirm current git branch is appropriate
    for the work. Two checks, both blocking:
 
    a. **Not on main/master without consent**: if `git branch --show-current`
@@ -773,7 +783,7 @@ node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-${PARENT_PHASE}): resolve U
 
 
 <step name="uat_gate" priority="blocker">
-**UAT gate (added in v3.1.0 after #443 / #448):**
+**UAT gate:**
 
 Before marking the phase complete, verify a passing VERIFICATION.md exists for this phase. Without it, the phase advances to `status: executed` (work done, awaiting verification) — not `status: complete`.
 
@@ -822,7 +832,7 @@ fi
 
 **Only when `VERIFICATION_STATUS` is `pass`** — proceed to `update_roadmap` below.
 
-The previous behaviour (printing "Next Up: /rcode-verify-work" without state-gating) caused phases to reach `status: complete` without any human-verified UAT — see #443 for the failure mode.
+The previous behaviour (printing "Next Up: /rcode-verify-work" without state-gating) caused phases to reach `status: complete` without any human-verified UAT.
 </step>
 
 <step name="update_roadmap">

package/rcode/workflows/new-milestone.md

@@ -22,12 +22,12 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 Parse `$ARGUMENTS` before anything else:
 - `--reset-phase-numbers` flag → restart roadmap phase numbering at `1`
 - `--dry-run` flag → show what would be written, do not commit
-- `--from-draft <path>` flag → use an existing MILESTONE-CONTEXT.md or ROADMAP draft as the milestone definition (closes #740). When present, set `DRAFT_FILE=<path>` and `FROM_DRAFT_MODE=true`.
+- `--from-draft <path>` flag → use an existing MILESTONE-CONTEXT.md or ROADMAP draft as the milestone definition. When present, set `DRAFT_FILE=<path>` and `FROM_DRAFT_MODE=true`.
 - Remaining text → milestone name (optional)
 
 If `--from-draft` is absent, continue phase numbering from the previous milestone.
 
-**From-draft mode (closes #740):**
+**From-draft mode:**
 
 When `FROM_DRAFT_MODE=true`:
 1. Read the draft file at `DRAFT_FILE`. Accept any markdown file — MILESTONE-CONTEXT.md, a scratch doc, or a ROADMAP partial.

package/rcode/workflows/new-project.md

@@ -881,6 +881,10 @@ Present completion summary:
 **[N] phases** | **[X] requirements** | Ready to build ✓
 ```
 
+> **Verify before planning:**
+> (a) `.planning/ROADMAP.md` contains real `## Phase N` headings — open it and add them if the file is still a stub.
+> (b) Run `npx rcode state sync --from-disk` to populate `.rcode/state.json` with the phases array so downstream commands (`/rcode-plan`, `/rcode-execute-sprint`, etc.) can read the phase list.
+
 **If auto mode:**
 
 ```

package/rcode/workflows/plan-research-validation.md

@@ -8,7 +8,7 @@ Sub-steps of plan.md — Steps 5 through 5.7. Handles research, validation archi
 
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
-**If RESEARCH.md missing AND `has_context` is true AND no `--research` flag:** Skip research silently and proceed to step 6. CONTEXT.md already captures the user's design decisions — re-researching adds tokens without new signal. Display: `Research skipped — CONTEXT.md found (use --research to force)`. This closes #588.
+**If RESEARCH.md missing AND `has_context` is true AND no `--research` flag:** Skip research silently and proceed to step 6. CONTEXT.md already captures the user's design decisions — re-researching adds tokens without new signal. Display: `Research skipped — CONTEXT.md found (use --research to force)`.
 
 **If RESEARCH.md missing OR `--research` flag:**
 

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

@@ -3,8 +3,8 @@ Sub-step of plan.md — Step 8 Spawn rcode-planner Agent. Spawns rcode-planner w
 </purpose>
 
 <filename_convention>
-Issue #657 — every SPRINT.md, including the first plan in a phase, uses the
-sequence-numbered form `{phase}-{plan}-SPRINT.md` (no leading zeros per #652).
+Every SPRINT.md, including the first plan in a phase, uses the
+sequence-numbered form `{phase}-{plan}-SPRINT.md` (no leading zeros).
 Examples: `8-1-SPRINT.md`, `8-2-SPRINT.md`. Do NOT emit a bare `{phase}-SPRINT.md`
 or `{phase}-PLAN.md` for the first plan — that creates an inconsistent series
 when a second plan is added later. The plan-number computation in plan.md uses