@hanzlaa/rcode 4.7.2 → 4.8.0

package/rcode/references/plan-gaps-mode.md

@@ -0,0 +1,89 @@
+# plan.md — `--gaps` Mode (Handle `--gaps` Mode)
+
+Extracted from `plan.md` step 3.6. Only loaded when `GAPS_MODE=true` — see the conditional include at that point in `plan.md`.
+
+**Skip unless:** `GAPS_MODE=true`.
+
+**Purpose:** Read `NNN-VERIFICATION.md`, extract failing/partial gaps, count existing plan files, and prepare a `gap_list` payload to feed the planner. On completion, control flow continues at step 8 (skipping CONTEXT.md gating, research, and validation-strategy creation).
+
+**Step 1: Locate VERIFICATION.md**
+
+```bash
+PHASE_DIR=$(node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "${PHASE}" --pick dir 2>/dev/null || echo "")
+# Fallback if --pick dir not supported. TODO(#118): expose roadmap --pick dir cleanly.
+if [[ -z "$PHASE_DIR" ]]; then
+  PHASE_DIR=$(ls -d .planning/phases/${padded_phase}-* 2>/dev/null | head -1)
+fi
+
+VERIFICATION_FILE=$(ls "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1)
+```
+
+**If `VERIFICATION_FILE` is empty:**
+```
+Error: No VERIFICATION.md found for Phase {X}. Gap-closure planning requires the phase to have run through the verifier first.
+
+Try:
+  /rcode-execute {X} ${RCODE_WS}      # run or re-run execution + verification
+```
+Exit workflow.
+
+**Step 2: Extract gaps from VERIFICATION.md**
+
+Parse the file for gap entries with `status: gap_found` or `status: partial`. Inspect these sections:
+- `## Automated Gap` (or `## Automated Gaps`)
+- `## Human Verification Required`
+- Any findings block that includes a `status:` field set to `gap_found` or `partial`
+
+Collect into `GAP_LIST` (an ordered list where each entry has: id, title, expected, actual, status, source_section, severity if present).
+
+If `GAP_LIST` is empty, display:
+```
+Phase {X} VERIFICATION.md contains no gap_found or partial items — nothing to close.
+Report: {VERIFICATION_FILE}
+```
+Exit workflow.
+
+**Step 3: Determine next plan number**
+
+```bash
+EXISTING_PLAN_COUNT=$(ls "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null | wc -l | tr -d ' ')
+# Issue #652 — no leading zeros in planning artifacts. Phase 8 not 08, plan 2 not 02.
+NEXT_PLAN_NUMBER=$((EXISTING_PLAN_COUNT + 1))
+PADDED_PHASE="${PHASE}"
+GAP_PLAN_FILENAME="${PADDED_PHASE}-${NEXT_PLAN_NUMBER}-SPRINT.md"
+GAP_PLAN_PATH="${PHASE_DIR}/${GAP_PLAN_FILENAME}"
+```
+
+If `EXISTING_PLAN_COUNT == 0`, there is no prior execution to reference. Display a warning but proceed — the planner can still close verification gaps.
+
+**Step 4: Gather prior plans for planner context**
+
+```bash
+EXISTING_PLAN_FILES=$(ls "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null | tr '\n' ' ')
+EXISTING_SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null | tr '\n' ' ')
+```
+
+**Step 5: Display banner**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► GAP-CLOSURE PLANNING — Phase {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Verification report: {VERIFICATION_FILE}
+Gaps to close:       {count(GAP_LIST)}
+Existing plans:      {EXISTING_PLAN_COUNT}
+New plan file:       {GAP_PLAN_FILENAME}
+```
+
+**Step 6: Skip ahead**
+
+Control flow jumps directly to step 8 (Spawn rcode-planner). Steps 4 (CONTEXT.md), 5 (Research), and 5.5 (Validation) are ALL skipped when `GAPS_MODE=true`.
+
+Step 8 will consume these variables when filling the planner prompt:
+- `GAP_LIST` — serialized list of gaps (id, title, expected, actual, status)
+- `GAP_PLAN_PATH` — exact output path the planner must write
+- `EXISTING_PLAN_FILES` / `EXISTING_SUMMARY_FILES` — prior phase context
+- `VERIFICATION_FILE` — authoritative source-of-truth
+
+After the planner returns, the existing plan-checker / revision loop (step 10 onward) runs unchanged — gap plans are verified just like normal plans.

package/rcode/references/plan-thinking-partner.md

@@ -0,0 +1,20 @@
+# plan.md — Thinking Partner for Architectural Tradeoffs
+
+Extracted from `plan.md` step 11. Only loaded when `features.thinking_partner` is enabled — see the conditional include at that point in `plan.md`.
+
+If `features.thinking_partner` is enabled, scan the checker's issues for architectural tradeoff keywords
+("architecture", "approach", "strategy", "pattern", "vs", "alternative"). If found:
+
+```
+The sprint-checker flagged an architectural decision point:
+{issue description}
+
+Brief analysis:
+- Option A: {approach_from_plan} — {pros/cons}
+- Option B: {alternative_approach} — {pros/cons}
+- Recommendation: {choice} aligned with {phase_goal}
+
+Apply this to the revision? [Yes] / [No, I'll decide]
+```
+
+If yes: include the recommendation in the revision prompt. If no: proceed to revision loop as normal.

package/rcode/references/plan-windows-troubleshooting.md

@@ -0,0 +1,25 @@
+# plan.md — Windows Troubleshooting
+
+Extracted from `plan.md`'s `<windows_troubleshooting>` block. Only loaded on Windows — see the conditional include at that point in `plan.md`.
+
+**Windows users:** If sprint-plan freezes during agent spawning (common on Windows due to
+stdio deadlocks with MCP servers — see Claude Code issue anthropics/claude-code#28126):
+
+1. **Force-kill:** Close the terminal (Ctrl+C may not work)
+2. **Clean up orphaned processes:**
+   ```powershell
+   # Kill orphaned node processes from stale MCP servers
+   Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.StartTime -lt (Get-Date).AddHours(-1)} | Stop-Process -Force
+   ```
+3. **Clean up stale task directories:**
+   ```powershell
+   # Remove stale subagent task dirs (Claude Code never cleans these on crash)
+   Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\tasks\*" -ErrorAction SilentlyContinue
+   ```
+4. **Reduce MCP server count:** Temporarily disable non-essential MCP servers in settings.json
+5. **Retry:** Restart Claude Code and run `/rcode-plan` again
+
+If freezes persist, try `--skip-research` to reduce the agent chain from 3 to 2 agents:
+```
+/rcode-plan N --skip-research
+```

package/rcode/references/planner-playbook.md

@@ -160,42 +160,36 @@ Sprint-checker enforces this — see `rcode-sprint-checker.md` Mandatory Output
 
 ```markdown
 ---
-[frontmatter with phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves]
+phase: {phase}
+plan_number: {N}
+wave: {N}
+depends_on: []
+autonomous: true|false
+files_modified: [...]
+requirements: [...]
+must_haves: {truths, artifacts, key_links}
 ---
 
-<objective>
-[What this plan accomplishes]
-Purpose: [Why this matters]
-Output: [Artifacts created]
-</objective>
-
+<objective>...</objective>
 <execution_context>
-@.rcode/workflows/execute.md
+@.rcode/workflows/execute-sprint.md
 @.rcode/templates/summary.md
 </execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-[Only prior SUMMARY refs if genuinely needed]
-</context>
-
+<context>...</context>
 <tasks>
-[2-3 tasks max, each 15-60 min]
+<task id="{phase}.{plan}.{N}" type="auto">
+<title>...</title>
+<read_first>...</read_first>
+<files>...</files>
+<action>...</action>
+<verify><automated>...</automated></verify>
+<done>...</done>
+<evidence>...</evidence>
+</task>
 </tasks>
-
-<verification>
-[Overall phase checks]
-</verification>
-
-<success_criteria>
-[Measurable completion]
-</success_criteria>
-
-<output>
-Create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
-</output>
+<verification>...</verification>
+<success_criteria>...</success_criteria>
+<output>Create `.planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md`</output>
 ```
 
 ## Common Planning Mistakes to Avoid

package/rcode/skills/_shared/state-sync-rule.md

@@ -8,7 +8,7 @@ Immediately after appending content to any of:
 
 - `.planning/ROADMAP.md` — milestones and phases
 - `.planning/epics.md` — epics and stories
-- `.rcode/phases/{phase}/sprint-{N}.md` — sprint commitments
+- `.planning/phases/{phase-dir}/{phase}-{plan}-SPRINT.md` — sprint commitments
 
 Call the state-sync helper:
 

package/rcode/skills/actions/1-analysis/rcode-document-project/SKILL.md

@@ -16,6 +16,8 @@ triggers:
   - "create LLM-friendly docs"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/1-analysis/rcode-prfaq/SKILL.md

@@ -11,6 +11,8 @@ triggers:
   - "forge a product idea"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/2-plan/rcode-create-epics-and-stories/SKILL.md

@@ -27,8 +27,19 @@ triggers:
   - "تحليل وثيقة المتطلبات"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
+> **Note (experimental, no execution consumer):** the epics/stories/dev-story pipeline this
+> skill is part of is not wired to `/rcode-execute` today — `rcode-executor` only reads
+> `*-SPRINT.md` files (see `rcode/agents/rcode-executor.md`). The only way to "run" a story
+> produced here is the manual `/rcode {dev-prompt-file}` invocation documented in
+> `rcode/workflows/dev-story.md`, which has none of `/rcode-execute`'s atomic-commit,
+> checkpoint, wave, or verification machinery. Treat this pipeline as experimental /
+> unsupported for production execution until a decision is made to either wire it to
+> `/rcode-execute` or deprecate it in favor of the SPRINT.md pipeline (see
+> `AUDIT-redundant-work.md` finding 2).
 
 ## Overview
 

package/rcode/skills/actions/2-plan/rcode-create-prd/SKILL.md

@@ -29,6 +29,8 @@ triggers:
   - "صمم المتطلبات"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/2-plan/rcode-create-story/SKILL.md

@@ -27,8 +27,19 @@ triggers:
   - "جهّز القصة للتنفيذ"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
+> **Note (experimental, no execution consumer):** the epics/stories/dev-story pipeline this
+> skill is part of is not wired to `/rcode-execute` today — `rcode-executor` only reads
+> `*-SPRINT.md` files (see `rcode/agents/rcode-executor.md`). The only way to "run" a story
+> produced here is the manual `/rcode {dev-prompt-file}` invocation documented in
+> `rcode/workflows/dev-story.md`, which has none of `/rcode-execute`'s atomic-commit,
+> checkpoint, wave, or verification machinery. Treat this pipeline as experimental /
+> unsupported for production execution until a decision is made to either wire it to
+> `/rcode-execute` or deprecate it in favor of the SPRINT.md pipeline (see
+> `AUDIT-redundant-work.md` finding 2).
 
 ## Overview
 

package/rcode/skills/actions/2-plan/rcode-edit-prd/SKILL.md

@@ -16,6 +16,8 @@ triggers:
   - "change the scope in the PRD"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/2-plan/rcode-validate-prd/SKILL.md

@@ -16,6 +16,8 @@ triggers:
   - "audit the PRD"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/3-solutioning/rcode-check-implementation-readiness/SKILL.md

@@ -17,6 +17,8 @@ triggers:
   - "can we start building"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/3-solutioning/rcode-create-architecture/SKILL.md

@@ -20,6 +20,8 @@ triggers:
   decision to use X"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/4-implementation/rcode-checkpoint-preview/SKILL.md

@@ -12,6 +12,8 @@ triggers:
 user-invocable: true
 ---
 
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
+
 ## Overview
 
 Checkpoint preview skill for rcode.

package/rcode/skills/actions/4-implementation/rcode-code-review/SKILL.md

@@ -29,6 +29,8 @@ triggers:
   - "جودة الكود"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/4-implementation/rcode-correct-course/SKILL.md

@@ -18,6 +18,8 @@ triggers:
   - "change story mid-way"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

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

@@ -29,8 +29,8 @@ triggers:
   - "تتبّع السبب"
 user-invocable: false
 ---
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
-
 ## The Iron Law
 
 ```

package/rcode/skills/actions/4-implementation/rcode-dev-story/SKILL.md

@@ -17,6 +17,8 @@ triggers:
   - "implement .rcode/phases/{phase}/stories/{file}"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

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

@@ -16,6 +16,8 @@ triggers:
   - "extract learnings from this sprint"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

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

@@ -28,6 +28,8 @@ triggers:
   - "add rcode to existing project"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/actions/4-implementation/rcode-sprint-planning/SKILL.md

@@ -40,8 +40,9 @@ Follow the instructions in ./workflow.md.
 
 ## Output Format
 
-- Output: .rcode/phases/{phase}/sprint-{N}.md
-- Fixed structure: Sprint Goal (one sentence) | Assumptions | Duration | Stories (with owners) | Capacity Used/Available | Risks | Definition of Done
+- Output: sprint-status.yaml (path from {status_file}, per workflow.md step 4) — an epic/story status tracker, NOT a SPRINT.md
+- Fixed structure: generated/last_updated/project metadata + development_status (epic -> stories -> retrospective, ordered)
+- Distinct from `/rcode-sprint-planning` the slash command (`rcode/workflows/sprint-planning.md`), which writes a SPRINT.md via a separate in-line flow
 - Stories ranked by priority from epics.md
 - Leave 20% capacity buffer
 - Do NOT commit to stories without explicit owners

package/rcode/skills/actions/4-implementation/rcode-sprint-status/SKILL.md

@@ -15,6 +15,8 @@ triggers:
   - "where are we in the sprint"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/agents/haitham-frontend/SKILL.md

@@ -53,6 +53,12 @@ This skill embodies Haitham (هيثم), senior frontend engineer archetype. Hait
 
 rcode's frontend stack: **React 18+, Next.js 15 App Router, TypeScript strict, Tailwind v4, shadcn/ui, Framer Motion, next-intl for Arabic-English localization.** Haitham follows these conventions without needing to be told.
 
+## Dispatch Mode
+
+Invoking this skill directly (triggers like "talk to Haitham", "build this UI") loads Haitham's persona instructions **inline into the current session** — no isolated context, no `Task()` call. This is structured roleplay, not a spawned subagent.
+
+For genuine isolated Task-tool dispatch, Haitham is separately registered as a Task-dispatchable agent (`rcode-haitham`, see `rcode/agents/rcode-haitham.md`) and is spawned for real, isolated-context dispatch by `/rcode-council`. It is **not yet** wired into `/rcode-execute` — that workflow currently spawns only the generic `rcode-executor` subagent type; routing execution work to persona-specific agents like this one is pending issue #1003 (in progress in parallel on branch `fix-execute-routing`). Unlike Hanzla, there is currently no `@haitham` shortcut in `do.md`'s `@persona CODE` alias table.
+
 ## Identity
 
 Senior frontend engineer specializing in Next.js App Router, TypeScript, Tailwind, shadcn/ui, and bilingual (Arabic-English) web apps. Committed to pixel-perfect craft, accessibility, and performance.

package/rcode/skills/agents/hanzla-engineer/SKILL.md

@@ -49,6 +49,12 @@ user-invocable: true
 
 This skill embodies Hanzla (حنظلة), senior full-stack engineer archetype. It executes approved stories with strict adherence to story details, writes tests before marking work complete, and refactors only incrementally. Hanzla never rewrites code from scratch, never commits code he doesn't understand, and never lies about test status.
 
+## Dispatch Mode
+
+Invoking this skill directly (triggers like "talk to Hanzla", "implement this") loads Hanzla's persona instructions **inline into the current session** — no isolated context, no `Task()` call. This is structured roleplay, not a spawned subagent.
+
+For genuine isolated Task-tool dispatch, Hanzla is separately registered as a Task-dispatchable agent (`rcode-hanzla`, see `rcode/agents/rcode-hanzla.md`) and is spawned for real, isolated-context dispatch by `/rcode-council`. It is **not yet** wired into `/rcode-execute` — that workflow currently spawns only the generic `rcode-executor` subagent type; routing execution work to persona-specific agents like this one is pending issue #1003 (in progress in parallel on branch `fix-execute-routing`). `do.md`'s `@persona CODE` shortcut table already has an alias for this persona (`@hanzla`, aliases: hanzla/dev/engineer) as its deterministic API surface.
+
 ## Identity
 
 Senior software engineer who executes approved stories with strict adherence to story details and team standards. Pragmatic, test-driven, and allergic to premature abstractions.

package/rcode/skills/agents/hussain-pm/SKILL.md

@@ -142,7 +142,7 @@ State the rule by name when refusing.
    - What's explicitly out of scope?
    - Kill criteria: when would we stop this project?
 2. After answers, draft PRD with: Problem, User, Scope, Success Metrics, Kill Criteria, Out-of-Scope
-3. Save to `.rcode/phases/{current}/prd.md`
+3. Save to `.planning/prd.md`
 
 ### Edge Case: Vague Request
 **Input:** "We need a feature for notifications"

package/rcode/skills/agents/hussain-sm/SKILL.md

@@ -79,7 +79,7 @@ Crisp and checklist-driven. Every word has a purpose. Zero tolerance for ambigui
 | SP | Generate or update the sprint plan that sequences tasks for the dev agent | rcode-sprint-planning |
 | CS | Prepare a story with all required context for implementation | rcode-create-story |
 | SS | Generate sprint status report from current epics and stories | rcode-sprint-status |
-| ER | Multi-agent review of all work completed across an epic (retrospective) | rcode-retrospective |
+| ER | Structured single-session retrospective roleplay covering all work completed across an epic | rcode-retrospective |
 | CC | Determine how to proceed if major change is discovered mid-implementation | rcode-correct-course |
 
 ## Workflow
@@ -108,7 +108,7 @@ Crisp and checklist-driven. Every word has a purpose. Zero tolerance for ambigui
 **Input:** "Prepare the next story from the backlog"
 
 **Expected behavior:**
-1. Read `.rcode/phases/{current}/epics.md` and find next unstarted story
+1. Read `.planning/epics/EPIC-{NN}.md` and find next unstarted story
 2. Create story file with ALL sections populated:
    - Goal (one sentence)
    - Context (references to PRD, architecture, UX)
@@ -117,7 +117,7 @@ Crisp and checklist-driven. Every word has a purpose. Zero tolerance for ambigui
    - Dependencies (other stories, external systems)
    - File List (empty — for Hanzla to fill)
    - Dev Agent Record (empty — for Hanzla to fill)
-3. Save to `.rcode/phases/{current}/stories/story-{id}.md`
+3. Save to `.planning/epics/stories/{N}.{M}.md`
 4. Report: "Story {id} ready. Assign to Hanzla with `rcode-dev-story {path}`."
 
 ### Edge Case: Ambiguous Story from User

package/rcode/skills/agents/majlis-council/references.md

@@ -30,13 +30,23 @@ In Omani and Arab tradition, a Majlis is a gathering where voices are heard befo
 
 ## Dispatch modes
 
-Majlis has two execution modes:
-
-**Real mode (default).** Dispatches actual subagents via the `Task` tool. Each agent runs in isolated context, genuinely parallel, with uncontaminated reasoning. Use for high-stakes decisions and demos.
-
-**Fast mode.** Single-Claude structured roleplay following each agent's SKILL.md principles. Fallback for harnesses without subagent support, or for quick sanity checks. Faster but reasoning runs in shared context.
-
-When in doubt, use real mode.
+Within this skill, the CV/CVF/QC/DM/CM convene-mode sub-skills listed in SKILL.md's
+Capabilities table are **not yet implemented** — do not claim real Task-tool dispatch
+is available through this skill today.
+
+**For genuine parallel, isolated-context subagent dispatch, use the separate
+`/rcode-council` slash command** (`rcode/workflows/council.md`) — a different,
+already-working implementation: deterministic panel scoring, parallel Task-tool
+spawning (not sequential roleplay), and structured artifact output to
+`.planning/council-sessions/`.
+
+**Fast mode (the only mode this skill currently supports).** Single-Claude
+structured roleplay following each agent's SKILL.md principles, in shared context.
+Use this skill (phrase-triggered: "convene the majlis", "consult the team", etc.)
+only when a `/rcode-council` slash-command invocation isn't available or a quick
+sanity check is enough.
+
+When real, isolated-context dispatch matters, prefer `/rcode-council` over this skill.
 
 ---
 

package/rcode/skills/agents/raees-orchestrator/SKILL.md

@@ -45,7 +45,9 @@ user-invocable: true
 
 ## Overview
 
-Raees (رئيس) dispatches the right specialists for execution. Where Majlis convenes the full council for discussion, Raees runs the dispatch desk. He knows every agent's authority and dependencies, parallelises ruthlessly where possible, sequences strictly where necessary, and escalates to Majlis when a question crosses into strategy. The full dispatch matrix and rcode-specific context awareness live in [`references.md`](references.md).
+Raees (رئيس) produces a dispatch **plan** — text output for a human (or another workflow) to act on, not a dispatch action. Where Majlis convenes the full council for discussion, Raees works out who should own what: he reasons about every agent's authority and dependencies, identifies what can run in parallel vs. what must sequence strictly, and flags when a question should escalate to Majlis instead. The full dispatch matrix and rcode-specific context awareness live in [`references.md`](references.md).
+
+**No live routing mechanism exists yet.** The DP/SQ/PL/HO sub-skills in the Capabilities table below are planned, not implemented — there is no `Task()` call, no `rcode-raees*` subagent, and no automatic handoff. Raees writes the plan; a human or another command (e.g. `/rcode-execute`) is what actually carries it out today.
 
 ## Capabilities
 
@@ -76,10 +78,10 @@ Raees (رئيس) dispatches the right specialists for execution. Where Majlis co
 
 ## Output Format
 
-Dispatch plans use this exact structure:
+Dispatch plans use this exact structure — this is the deliverable, a document, not a log of actions taken:
 
 ```
-Dispatch: <request summary>
+Dispatch Plan: <request summary>
 
 Step 1 (BLOCKING):  <agent> → <skill> — delivers: <output>
 Step 2 (PARALLEL):  <agent A> → <task A> | <agent B> → <task B>
@@ -88,29 +90,29 @@ Step 3 (BLOCKING):  <agent> → <skill> — gate
 
 Always show: primary owner, dependencies (arrows or "blocked by"), parallel opportunities.
 
-Save dispatch plans to `.rcode/progress/dispatch-{date}.md`.
+Save the plan to `.rcode/progress/dispatch-{date}.md`. Raees does not invoke the agents named in the plan — no `Task()` call is made. Executing the plan is a separate, manual step for the user (or a workflow like `/rcode-execute`, once persona routing lands there).
 
-Do NOT include: diffuse responsibility, unowned tasks, or silent handoffs. Do NOT synthesise strategic decisions — that's Majlis's job. Do NOT override specialist authority.
+Do NOT include: diffuse responsibility, unowned tasks, or silent handoffs. Do NOT synthesise strategic decisions — that's Majlis's job. Do NOT override specialist authority. Do NOT phrase output as if dispatch already happened ("invoked", "dispatching X now") — phrase it as a recommendation ("plan calls for X", "recommended: assign to X").
 
 ## Examples
 
 **Happy path — feature request**
-"Add Arabic RTL support to our dashboard" → touches UX (Layla), FE (Haitham), BE (Yousef), QA (Fatima), localisation (Noor) → 5-step plan with Layla blocking, Haitham/Yousef/Noor in parallel, Fatima gate, Khalid ship → saved to `.rcode/progress/dispatch-{date}.md` → Layla invoked first.
+"Add Arabic RTL support to our dashboard" → touches UX (Layla), FE (Haitham), BE (Yousef), QA (Fatima), localisation (Noor) → produces a 5-step plan with Layla blocking, Haitham/Yousef/Noor in parallel, Fatima gate, Khalid ship → saved to `.rcode/progress/dispatch-{date}.md`. The plan lists Layla as step 1; nothing is actually invoked.
 
 **Happy path — government proposal**
-"Ministry of Housing wants a property management proposal" → context triggers compliance-first + Arabic-first + data residency → Sadiq (research) → Waleed (compliance) → parallel Mariam + Zayd → Noor (full document Arabic + English) → Sadiq final review.
+"Ministry of Housing wants a property management proposal" → context triggers compliance-first + Arabic-first + data residency → plan sequences: Sadiq (research) → Waleed (compliance) → parallel Mariam + Zayd → Noor (full document Arabic + English) → Sadiq final review.
 
 **Edge case — single-owner task**
-"Fix the typo in the footer" — don't build a plan. "Single-owner task. Dispatching Haitham directly. No coordination needed."
+"Fix the typo in the footer" — don't build a multi-step plan. Output: "Single-owner task. Recommended: assign to Haitham directly. No coordination needed." (a recommendation, not an action).
 
 **Edge case — strategic question**
-"Should we enter the Saudi market?" — don't dispatch. Escalate: "Cross-domain strategic question — handing to Majlis. I'll reconvene for execution once Majlis has a verdict."
+"Should we enter the Saudi market?" — don't produce a dispatch plan. Recommend escalation: "Cross-domain strategic question — recommend routing to Majlis. Re-run this once Majlis has a verdict."
 
 **Edge case — conflicting specialists**
-Waleed wants approach A, Yousef wants approach B. Do NOT pick. Escalate to Majlis with the conflict framed.
+Waleed wants approach A, Yousef wants approach B. Do NOT pick. Recommend escalation to Majlis with the conflict framed.
 
 **Negative — single-domain UX question**
-"What colour should the button be?" — Layla owns this directly. Redirect.
+"What colour should the button be?" — Layla owns this directly. Redirect, don't produce a plan.
 
 ## Memory Bank Hooks
 

package/rcode/skills/agents/yousef-backend/SKILL.md

@@ -50,6 +50,12 @@ user-invocable: true
 
 This skill embodies Yousef (يوسف), senior backend engineer archetype. Yousef builds APIs, databases, data pipelines, and integration services — with particular expertise in data management, RPA (Robotic Process Automation), and enterprise/government integrations.
 
+## Dispatch Mode
+
+Invoking this skill directly (triggers like "talk to Yousef", "build the backend") loads Yousef's persona instructions **inline into the current session** — no isolated context, no `Task()` call. This is structured roleplay, not a spawned subagent.
+
+For genuine isolated Task-tool dispatch, Yousef is separately registered as a Task-dispatchable agent (`rcode-yousef`, see `rcode/agents/rcode-yousef.md`) and is spawned for real, isolated-context dispatch by `/rcode-council`. It is **not yet** wired into `/rcode-execute` — that workflow currently spawns only the generic `rcode-executor` subagent type; routing execution work to persona-specific agents like this one is pending issue #1003 (in progress in parallel on branch `fix-execute-routing`). Unlike Hanzla, there is currently no `@yousef` shortcut in `do.md`'s `@persona CODE` alias table.
+
 ## Identity
 
 Senior backend engineer specializing in REST/GraphQL APIs, relational and time-series databases, data pipelines, and system integrations. Focused on correctness, reliability, and observability.

package/rcode/templates/github/epic-template.md

@@ -54,4 +54,4 @@
 
 ---
 
-<sub>Generated by rcode — `.rcode/phases/{{phase}}/tasks/{{source_file}}`</sub>
+<sub>Generated by rcode — `.planning/phases/{{phase}}/{{source_file}}`</sub>

package/rcode/templates/github/feature-template.md

@@ -52,4 +52,4 @@
 
 ---
 
-<sub>Generated by rcode — `.rcode/phases/{{phase}}/stories/{{source_file}}`</sub>
+<sub>Generated by rcode — `.planning/phases/{{phase}}/{{source_file}}`</sub>

package/rcode/templates/github/task-template.md

@@ -49,4 +49,4 @@
 
 ---
 
-<sub>Generated by rcode — `.rcode/phases/{{phase}}/tasks/{{source_file}}`</sub>
+<sub>Generated by rcode — `.planning/phases/{{phase}}/{{source_file}}`</sub>