@hanzlaa/rcode 4.3.3 → 4.4.0

package/rcode/workflows/execute.md

@@ -2,6 +2,16 @@
 Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents.
 </purpose>
 
+## Orchestrator Constraint — No Inline Implementation
+
+**The execute orchestrator MUST NOT implement code directly.** Its only role is to dispatch, monitor, and checkpoint. All implementation is delegated to `rcode-executor` subagents.
+
+If you are reading this as the main conversation loop and are tempted to write code, create files, or make commits directly instead of spawning a subagent:
+
+> **STOP.** Spawn `rcode-executor` as a subagent with the sprint plan as context. The main loop's job is to call the agent, present checkpoints, and update state — not to implement.
+
+Bypassing this constraint produces a built project with no execution trace, no SUMMARY.md, and a dashboard frozen at `planned`. See issue #915.
+
 <pre_flight>
 **Mandatory before execution begins.** Run these checks first and surface
 findings BEFORE any subagents are spawned. If any check fails, stop and
@@ -173,11 +183,11 @@ via filesystem and git state.
 @.rcode/references/git-preflight.md
 Read STATE.md before any operation to load project context.
 
-@.rcode/references/agent-contracts.md
-@.rcode/references/context-budget.md
-@.rcode/references/gates.md
 @.rcode/references/karpathy-guidelines.md
 @.rcode/references/execution-protocol.md
+<!-- Read .rcode/references/agent-contracts.md only if debugging agent contract violations -->
+<!-- Read .rcode/references/context-budget.md only if context degradation guidance is needed -->
+<!-- Read .rcode/references/gates.md only if implementing or troubleshooting gate logic -->
 </required_reading>
 
 <available_agent_types>
@@ -356,6 +366,7 @@ checkpoints between tasks. The user can review, modify, or redirect work at any
       their feedback before continuing. Otherwise proceed to next task.
 
    e. **After plan complete:** Show results, commit, create SUMMARY.md, then present next plan.
+      **Overwrite guard:** If the SUMMARY.md file already exists from a previous run, delete it first with `rm -f <path>` before writing the new version. Never append to or skip an existing SUMMARY.md — always overwrite with the current sprint's completion data.
 
 3. After all plans: proceed to verification (same as normal mode).
 
@@ -1036,6 +1047,9 @@ Read and follow `.rcode/workflows/transition.md`, passing through the `--auto` f
 /rcode-execute {next} — execute next phase
 ```
 
+**Next step — paste this to verify:**
+> /rcode-verify {X}
+
 Only suggest the commands listed above. Do not invent or hallucinate command names.
 </step>
 

package/rcode/workflows/new-milestone.md

@@ -17,6 +17,24 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 
 <process>
 
+## --from-draft mode
+
+When `--from-draft <path>` is passed:
+1. Check for the file at `<path>`. Accept any markdown file — MILESTONE-CONTEXT.md, a scratch doc, or a ROADMAP partial.
+2. If found: read it as the milestone definition — do NOT re-run the interactive goal-gathering interview (steps 2–4). Jump directly to step 5 (Requirements scoping) using the draft as the source of truth.
+3. If not found: abort with:
+   ```
+   Error: --from-draft file not found: {path}
+   ```
+   Do not fall back to standard mode — an explicit path that does not exist is a user error, not a signal to start fresh.
+
+Surface a one-line banner when the draft is loaded:
+```
+◆ From-draft mode: using {path} as milestone definition (skipping goal interview)
+```
+
+This mode exists to skip expensive re-derivation when a human or prior agent has already drafted the milestone scope.
+
 ## 1. Parse arguments and load context
 
 Parse `$ARGUMENTS` before anything else:
@@ -27,20 +45,14 @@ Parse `$ARGUMENTS` before anything else:
 
 If `--from-draft` is absent, continue phase numbering from the previous milestone.
 
-**From-draft mode:**
+**From-draft mode (see dedicated section above):**
 
 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.
 2. Extract milestone name (first `# Heading` or the filename stem), goals list, and any explicit phase list.
 3. Skip the interactive goal-gathering interview (steps 2–4). Jump directly to step 5 (Requirements scoping) using the draft as the source of truth.
-4. Surface a one-line banner:
-   ```
-   ◆ From-draft mode: using {DRAFT_FILE} as milestone definition (skipping goal interview)
-   ```
-5. If `DRAFT_FILE` does not exist, abort:
-   ```
-   Error: --from-draft file not found: {DRAFT_FILE}
-   ```
+4. Surface the one-line banner (see `## --from-draft mode` above).
+5. If `DRAFT_FILE` does not exist, abort (see `## --from-draft mode` above).
 
 Read these files in parallel:
 - `.planning/PROJECT.md` — existing project, validated requirements, decisions

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

@@ -41,6 +41,8 @@ Create roadmap:
 6. Return ROADMAP CREATED with summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
+
+**Scope constraint:** rcode-roadmapper creates ONLY: ROADMAP.md, STATE.md, and one PHASE.md per phase directory (if requested). It MUST NOT create SPRINT.md, PLAN.md, or any sprint-level planning files. Sprint planning is handled exclusively by `/rcode-plan`. If you find yourself about to write a SPRINT.md file, STOP — that file is out of scope for this agent.
 </instructions>
 ", subagent_type="rcode-roadmapper", model="${ROADMAPPER_MODEL}", description="Create roadmap")
 ```

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

@@ -199,6 +199,8 @@ Create roadmap:
 6. Return ROADMAP CREATED with summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
+
+**Scope constraint:** rcode-roadmapper creates ONLY: ROADMAP.md, STATE.md, and one PHASE.md per phase directory (if requested). It MUST NOT create SPRINT.md, PLAN.md, or any sprint-level planning files. Sprint planning is handled exclusively by `/rcode-plan`. If you find yourself about to write a SPRINT.md file, STOP — that file is out of scope for this agent.
 </instructions>
 ", subagent_type="rcode-roadmapper", model="{roadmapper_model}", description="Create roadmap")
 ```

package/rcode/workflows/new-project.md

@@ -885,6 +885,9 @@ Present completion summary:
 > (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.
 
+**Next step — paste this to start planning:**
+> /rcode-plan 1 — [Phase 1 Name from ROADMAP.md]
+
 **If auto mode:**
 
 ```

package/rcode/workflows/plan.md

@@ -49,9 +49,9 @@ Read all files referenced by the invoking prompt's execution_context before star
 ${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 @.rcode/references/revision-loop.md
 @.rcode/references/gate-prompts.md
-@.rcode/references/agent-contracts.md
-@.rcode/references/gates.md
 @.rcode/references/karpathy-guidelines.md
+<!-- Read .rcode/references/agent-contracts.md only if defining or debugging agent contracts -->
+<!-- Read .rcode/references/gates.md only if implementing or troubleshooting gate logic -->
 @.rcode/references/thinking-models-planning.md
 </required_reading>
 
@@ -64,6 +64,16 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 
 <process>
 
+## --from-stub mode
+
+When `--from-stub` is passed:
+1. Check for existing `PLAN.md` in the phase directory
+2. If found: read it as the planning skeleton — do NOT re-derive phase goals or re-research the phase
+3. Expand the stub into full SPRINT.md files using the stories already listed in PLAN.md
+4. If no PLAN.md exists: fall back to standard planning mode (derive from ROADMAP + RESEARCH.md)
+
+This mode exists to skip expensive re-derivation when a human or prior agent has already produced a planning skeleton.
+
 ## 0. Project-Status Preflight
 
 ```bash
@@ -1023,6 +1033,9 @@ Verification: {Passed | Passed with override | Skipped}
 
 /rcode-execute {X} ${RCODE_WS}
 
+**Next step — paste this to execute:**
+> /rcode-execute {X}
+
 ───────────────────────────────────────────────────────────────
 
 **Also available:**