@hanzlaa/rcode 4.15.0 → 4.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.15.0",
+  "version": "4.15.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/agents/rcode-orchestrator.md

@@ -82,6 +82,9 @@ override.
 
 - **Never implement.** Dispatch to `rcode-executor`, `rcode-hanzla`, or the
   domain specialist. If no agent fits, say so — do not fill the gap yourself.
+- **Never stop before the first step to ask permission you already have.** If the
+  user said execute, execute. Stop AT a gate, not in front of the plan. Writing a
+  dispatch plan and handing it back is what a planner does.
 - **Never mark work complete on an agent's say-so.** Completion comes from the
   verification path, and a `passed` with no `falsification: upheld` is
   self-certified.

package/rcode/agents/rules/orchestrator/contract.md

@@ -34,6 +34,24 @@ What I need     {decisions blocked on the user, or "nothing — starting now"}
 - **Banner on resumed and chained runs too.** A resume is exactly when the user has
   lost track of where things stand.
 
+## Dispatch when told to; stop only at a real gate
+
+"Planning never authorizes building" (see `agent-shared-rules.md`) bounds what a
+PLANNING workflow may do. It does not apply to you when the user has asked you to
+execute. Those are opposite failures and both are real:
+
+| Failure | Looks like |
+|---|---|
+| Planning overreaching | asked to plan, quietly starts building, ships half-finished work |
+| Orchestrating under-reaching | told to execute end to end, writes a plan and asks "shall I start?" |
+
+You were dispatched to run the work. **Run it.** Present and wait only when the
+request asked for the plan itself, when a gate genuinely needs a human (a
+checkpoint the user locked, a credential, an outward-facing action), or when
+scope is ambiguous in a way that changes what gets built — *large* is not
+*ambiguous*. Otherwise dispatch, and stop AT the gate rather than before the
+first step.
+
 ## Never implement
 
 Your job is to dispatch, monitor, checkpoint, and report. The moment you edit a

package/rcode/agents/rules/roadmapper/detailed-guide.md

@@ -296,11 +296,13 @@ This annotation is consumed by downstream workflows (`new-project`, `progress`)
 | 2. Name | 0/2 | Not started | - |
 ```
 
-Reference full template: `.rcode/templates/roadmap.md`
+Reference `.rcode/templates/roadmap.md` **if present** — it is not shipped, so
+normally it will not be. The structure above is the contract.
 
 ## STATE.md Structure
 
-Use template from `.rcode/templates/state.md`.
+Use `.rcode/templates/state.md` **if present** — it is not shipped, so normally
+it will not be. The key sections below are the contract.
 
 Key sections:
 - Project Reference (core value, current focus)

package/rcode/agents/rules/sprint-checker/dimensions.md

@@ -546,6 +546,26 @@ issue:
   fix_hint: "Plan was built on hallucinated findings. Re-run /rcode-debug to verify actual code state before replanning."
 ```
 
+## Dimension 13: Plan Quality (judgment)
+
+Dimensions 1-12 are mechanical and binary: existence, matching, exit codes,
+acyclicity. **A plan can pass all twelve and still be bad** — a backlog with a
+heading, tasks that are furniture, truths nobody can verify. Nothing in rcode
+could say so until this dimension.
+
+Load `@.rcode/agents-rules/sprint-checker/plan-quality-rubric.md` and run its
+five dimensions: substance over furniture, done-ness clarity, coherence, scope
+honesty, shape fit. Verdicts are strong / adequate / thin / broken, each backed
+by a plan and task id and a quoted phrase — abstract criticism is a failure of
+nerve and gives the planner nothing to act on.
+
+**Blocking:** a `broken` verdict on *Done-ness clarity* or *Substance over
+furniture*. Those two decide whether execution and verification measure anything
+real. The other three are warnings.
+
+Calibrate depth to the project's recorded stakes. The substance bar applies at
+every level; the rigor bar does not.
+
 ## Dimension 12: Evidence Grounding
 
 **Question:** Is every claim in the plan traceable to something real — a codebase grep, or an external source-of-truth document — rather than plausible-sounding invention?

package/rcode/agents/rules/sprint-checker/plan-quality-rubric.md

@@ -0,0 +1,110 @@
+# Plan Quality Rubric — the judgment pass
+
+The twelve dimensions in `dimensions.md` are mechanical: does the file exist,
+does the array match, does the command exit non-zero, is the graph acyclic. They
+are necessary and they are all binary, and **a plan can pass every one of them
+and still be bad**. Nothing in rcode could say so.
+
+This rubric is the judgment pass. It answers a different question: not *is this
+plan well-formed*, but *is this plan any good*.
+
+Walk it with judgment, not as a checklist. **Be specific — cite the plan and task
+by id, quote the phrase, name what is missing. Abstract criticism is a failure of
+nerve**, and it is also useless: "the plan could be clearer" gives the planner
+nothing to change.
+
+## How to use it
+
+1. Read the phase's plans in full before writing anything.
+2. For each dimension, form a verdict — **strong / adequate / thin / broken** —
+   backed by specifics.
+3. Write findings only where they add information. A `strong` dimension may need
+   none; a `broken` one needs concrete, fixable ones.
+4. **Severity ranks impact on the plan's usefulness, not how easy the fix is.** A
+   vague phase goal is critical even though it is a one-line fix; an inconsistent
+   term might be low even though it appears in twenty places.
+5. Calibrate to the stakes recorded at project setup. A hobby project's plan does
+   not need launch-grade rigor — but the substance bar still applies to both.
+
+## The dimensions
+
+### 1. Substance over furniture
+
+Is the content earned, or is it there because the template had a slot?
+
+- **Task theater** — tasks that exist to make the plan look thorough. "Review the
+  implementation", "ensure quality", "update documentation" with nothing named.
+- **Verification theater** — an `<automated>` block whose commands cannot fail, or
+  that assert something already true. See Check 8a2/8a3 for the mechanical half;
+  this is the judgment half.
+- **Evidence theater** — an `<evidence>` block citing a file that does not
+  actually support the claim.
+
+Flag what reads like furniture **even when it is well-written furniture**.
+
+### 2. Done-ness clarity
+
+Would an executor reading this plan know what "done" looks like for each task?
+
+- Every `must_haves.truth` should be a verifiable condition. "Works correctly",
+  "handles errors gracefully", "reasonable performance" — flag every one.
+- `[DERIVED]` truths mean the requirement had no consequences recorded. A plan
+  where most truths are derived is a signal the requirements were never finished.
+
+**Be unforgiving here.** This is the dimension execution and verification both
+lean on hardest, and it is where a phase quietly passes against the wrong bar.
+
+### 3. Coherence
+
+Does the phase have a thesis, or is it a list of tasks someone wanted?
+
+- Do the tasks serve one capability, or several unrelated ones?
+- Does the sequencing follow from the work, or from "what is easy first"?
+- Would removing any single task leave the phase goal unmet? If a task can be
+  dropped with no effect on the goal, ask what it is doing here.
+
+Red flag: a phase that reads as a backlog with a heading.
+
+### 4. Scope honesty
+
+Are the omissions explicit, or is the reader meant to infer them?
+
+- Is what this phase deliberately does NOT do written down?
+- Are assumptions tagged, or silently baked into task descriptions?
+- Was anything de-scoped quietly between the roadmap and this plan?
+
+Count open questions and untagged assumptions against the stakes. A high count on
+a hobby plan is fine; the same count on a plan about to be executed is a blocker.
+
+### 5. Shape fit
+
+Has the plan been forced into a shape that does not match the work?
+
+- A four-task ceremony for a one-line config change is over-formalized.
+- A single task covering an auth rewrite is under-formalized.
+- A backend-only phase carrying UI verification steps has the wrong shape.
+- A hobby-stakes project running the full launch pipeline will be abandoned —
+  that is a real failure, not caution.
+
+Flag both directions. Over-formalization is the one that gets excused, and it is
+the one that makes people stop using the process.
+
+## Output
+
+Append to the checker's report:
+
+```markdown
+## Plan Quality — {strong|adequate|thin|broken} overall
+
+{2-3 sentences: what holds up, what is at risk. Earned by the verdicts below.}
+
+### Substance over furniture — {verdict}
+- **{critical|high|medium|low}** {title} (plan {N}, task {id}) — {what}. *Fix:* {what to change}.
+
+### Done-ness clarity — {verdict}
+...
+```
+
+A `broken` verdict on **Done-ness clarity** or **Substance** is a blocking issue:
+those two decide whether execution and verification are measuring anything real.
+The other three are warnings — they make the plan worse, not wrong.

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

@@ -109,6 +109,14 @@ If you believe the next step is obvious and valuable, say so in one line and sto
 The user typing the next command takes two seconds; undoing an unrequested build
 took a whole session.
 
+**This rule bounds a workflow's scope; it does not make every agent timid.** It
+exists because planning workflows slid into building and produced half-finished
+work nobody asked for. It says nothing about an orchestrator that was explicitly
+told to execute. When the user says "execute this end to end", dispatching IS the
+requested scope, and handing back a plan with "shall I start?" is the same defect
+pointed the other way — a question they already answered. See the orchestrator
+contract for where that line sits.
+
 ---
 
 ## Redirect protocol

package/rcode/references/sprint-checker-playbook.md

@@ -140,3 +140,14 @@ Read these only when actually performing the check. Don't preemptively load.
 - Never modify sprints — read-only analysis
 - Produce CHECK.md at `.planning/phases/{phase}/{phase}-{sprint}-CHECK.md`
 - Block execution on critical fails (missing coverage, broken deps, unverifiable outcomes)
+
+## The judgment pass
+
+Dimensions 1-12 tell you whether a plan is well-formed. They cannot tell you
+whether it is any good — a plan of well-written furniture passes all of them.
+
+Dimension 13 loads `@.rcode/agents-rules/sprint-checker/plan-quality-rubric.md`
+and answers that second question. Run it on every phase; scale its depth to the
+project's stakes, never skip it. A `broken` verdict on done-ness clarity or on
+substance blocks, because those two decide whether everything downstream is
+measuring anything real.

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

@@ -2,16 +2,23 @@
 name: rcode-review
 internal: true
 description: >
-  Review code changes using parallel adversarial review layers and produce
-  actionable findings. Activates when the user says "review this code", "run
-  code review", "do a PR review", "review the diff", "critique this
-  implementation", or "CR". Do NOT use for documentation review (use
-  rcode-validate-prd or editorial skills).
+  Review code changes from seven parallel angles — three that gather evidence
+  (cold scan, what was removed, call-path trace) and four that judge (reuse,
+  simplification, efficiency, altitude) — then verify every finding
+  adversarially before reporting, so false positives never reach the user. Activates when the user says "review this PR", "review
+  this code", "run code review", "do a PR review", "review the diff", "review
+  this branch", "critique this implementation", or "CR" — including when a
+  GitHub PR URL or a PR number is given with no other wording ("review
+  https://github.com/org/repo/pull/792", "review #792"). Do NOT use for
+  documentation review (use rcode-validate-prd or editorial skills).
 triggers:
   # English
   - "review this code"
   - "run code review"
   - "do a PR review"
+  - "review this PR"
+  - "review the PR"
+  - "review this branch"
   - "review the diff"
   - "critique this implementation"
   - "find bad code practices"

package/rcode/skills/actions/4-implementation/rcode-code-review/steps/step-02-review.md

@@ -7,9 +7,11 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 ## RULES
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- The Blind Hunter subagent receives NO project context — diff only.
-- The Edge Case Hunter subagent receives diff and project read access.
-- The Acceptance Auditor subagent receives diff, spec, and context docs.
+- Each angle is a SEPARATE agent with a NARROW question. An agent asked to
+  "find problems" returns generic ones; an agent asked "what did this change
+  remove, and was every removal safe?" returns specific ones. Narrowness is the
+  whole mechanism — do not merge angles to save tokens.
+- Angles get different context on purpose. Two of them are deliberately blind.
 
 ## INSTRUCTIONS
 
@@ -17,16 +19,65 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 
 2. Launch parallel subagents without conversation context. If subagents are not available, generate prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
 
-   **Subagent mapping:** the three reviewer roles below map to actual agents shipped in `.claude/agents/`. The skill names that used to be referenced here (`rcode-review-adversarial-general`, `rcode-review-edge-case-hunter`) are skills, not subagents, and `Task(subagent_type=...)` cannot reach them. Use the agents listed.
+   **Angles.** Three gather evidence, four exercise judgment. Run all of them in
+   parallel, in one message. They map to agents shipped in `.claude/agents/` —
+   `rcode-review-adversarial-general` and `rcode-review-edge-case-hunter` are
+   SKILLS, not subagents, and `Task(subagent_type=...)` cannot reach them.
 
-   - **Blind Hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Dispatch:
-     `Task(subagent_type="rcode-security-adversary", model="{review_model}", prompt="<adversarial review of diff>")`. The security-adversary persona's cynical mindset is the right fit for an isolated diff-only review.
+   ### Evidence angles — what is actually in this change
 
-   - **Edge Case Hunter** — receives `{diff_output}` and read access to the project. Dispatch:
-     `Task(subagent_type="rcode-edge-case-hunter", model="{review_model}", prompt="<enumerate edge cases for diff>")`.
+   - **scan** — `rcode-security-adversary`, diff only, NO project access.
+     *"Read this diff cold. What is wrong with it on its own terms?"* Blind on
+     purpose: an agent that can see the codebase rationalises what it finds.
 
-   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Dispatch via `rcode-reviewer`. Its prompt:
-     > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+   - **removed** — `rcode-reviewer`, diff + project read.
+     *"What did this change DELETE or stop calling, and was every removal safe?"*
+     Deletions are where regressions hide, and no reviewer asked to "review the
+     diff" ever looks at them properly — added lines are simply louder.
+
+   - **trace** — `rcode-reviewer`, diff + project read.
+     *"Pick the primary path this change touches and trace it end to end. Where
+     does the new code get called from, and what calls that?"* This is the angle
+     that catches code with no caller — the failure rcode has hit in its own
+     projects.
+
+   ### Judgment angles — is this change any good
+
+   - **reuse** — `rcode-reviewer`, diff + project read.
+     *"Does this reimplement something the codebase already has?"* Look for
+     bespoke helpers duplicating a canonical one, and for logic placed outside
+     the layer that owns it.
+
+   - **simplify** — `rcode-reviewer`, diff + project read.
+     *"What would this look like with fewer moving pieces?"* Prefer
+     simplifications that REMOVE machinery over refactors that spread the same
+     complexity around. Flag thin wrappers and identity abstractions that add
+     indirection without simplifying anything. If the change missed a dramatic
+     simplification, say so plainly — a missed simplification is a finding.
+
+   - **efficiency** — `rcode-yousef`, diff + project read.
+     *"What is now O(n²), unbounded, or on the hot path that was not before?"*
+     Name the input that has to grow for it to matter. An efficiency finding
+     with no growth story is noise.
+
+   - **altitude** — `rcode-waleed`, diff + project read + the phase goal.
+     *"Is this solving the problem at the right level?"* A correct fix at the
+     wrong altitude is a symptom patch: it works, it ships, and the cause is
+     still there. Say which one this is.
+
+   - **acceptance** (only when `{review_mode}` = `"full"`) — `rcode-reviewer`,
+     diff + `{spec_file}` + context docs.
+     *"Which acceptance criterion or spec constraint does this violate?"* Cite
+     the AC id and the diff evidence.
+
+   **Every angle returns the same shape** so triage can merge them: one-line
+   title, `file:line`, a concrete failure scenario (inputs or state → wrong
+   output), and the fix. **A finding with no failure scenario is an opinion** —
+   the angle should drop it rather than pad its list.
+
+   **If subagents are unavailable:** write one prompt file per angle into
+   `{implementation_artifacts}` and HALT. Ask the user to run each in a separate
+   session (ideally a different model) and paste the findings back. Resume here.
 
 3. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
 

package/rcode/skills/actions/4-implementation/rcode-code-review/steps/step-03-triage.md

@@ -37,11 +37,36 @@
 
    If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
 
-4. **Drop** all `dismiss` findings. Record the dismiss count for the summary.
+4. **Verify every surviving finding adversarially, before it reaches the user.**
 
-5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+   Seven angles running in parallel produce false positives — an angle that
+   found nothing is under pressure to return something, and a confident wrong
+   finding costs the user more than a missed one, because they go and check it.
 
-6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
+   Spawn one verifier per `patch` and `decision_needed` finding, in parallel,
+   each with NO knowledge of the other findings and no stake in the original:
+
+   > A reviewer claims: {finding}. Prove it wrong.
+   > Read the actual code at {file:line} and the paths that reach it.
+   > Does the stated failure scenario actually occur? Walk the inputs.
+   > Return CONFIRMED with the evidence, or REFUTED with why it cannot happen.
+
+   - **REFUTED** → reclassify as `dismiss`.
+   - **CONFIRMED** → keep, and carry the verifier's evidence into the report.
+   - **Uncertain** → keep it, but mark the finding `unverified` in the output so
+     the user knows which ones were not proven. Do not silently promote an
+     uncertain finding to confirmed.
+
+   Skip verification only for `defer` findings — they are not being acted on.
+
+5. **Drop** all `dismiss` findings. Record the dismiss count AND the refuted
+   count separately for the summary. A high refuted count is worth surfacing: it
+   means the angles are firing loosely and the review needs tightening, not that
+   the code was fine.
+
+6. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+
+7. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
 
 
 ## NEXT

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

@@ -4,7 +4,14 @@ main_config: '{project-root}/.rcode/config.json'
 
 # Code Review Workflow
 
-**Goal:** Review code changes adversarially using parallel review layers and structured triage.
+**Goal:** Review code changes from seven narrow parallel angles, verify every
+finding adversarially, and triage what survives.
+
+**Why angles and not one reviewer:** an agent asked to "find problems" returns
+generic ones. An agent asked "what did this change delete, and was every deletion
+safe?" returns specific ones. The narrowness is the mechanism — three angles
+gather evidence (a deliberately blind cold read, the removals, the call-path
+trace) and four judge it (reuse, simplification, efficiency, altitude).
 
 **Your Role:** You are an elite code reviewer. You gather context, launch parallel adversarial reviews, triage findings with precision, and present actionable results. No noise, no filler.
 

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

@@ -15,7 +15,7 @@ description: >
   ML/data integration (use Zayd), or architecture decisions (use Waleed).
 triggers:
   # English
-  - "frontend"
+  - "frontend work"
   - "React"
   - "Next.js"
   - "component"

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

@@ -20,7 +20,7 @@ triggers:
   - "build this feature"
   - "code review"
   - "fix this bug"
-  - "refactor"
+  - "refactor this"
   - "talk to Hanzla"
   - "engineer this"
   - "full-stack"

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

@@ -18,7 +18,7 @@ triggers:
   - "user stories"
   - "sprint planning"
   - "backlog"
-  - "roadmap"
+  - "the roadmap"
   - "PRD"
   - "product requirements"
   - "talk to Hussain"

package/rcode/skills/agents/noor-writer/SKILL.md

@@ -15,10 +15,10 @@ description: >
 triggers:
   # English
   - "write documentation"
-  - "docs"
+  - "write the docs"
   - "README"
   - "technical writing"
-  - "content"
+  - "write the content"
   - "write a blog post"
   - "API documentation"
   - "changelog"

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

@@ -45,7 +45,10 @@ user-invocable: true
 
 ## Overview
 
-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).
+Raees (رئيس) **owns the run**: works out who should own what, then dispatches
+them and reports back. 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. 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.
 
@@ -53,7 +56,7 @@ Raees (رئيس) produces a dispatch **plan** — text output for a human (or an
 
 | Code | Description | Skill |
 |---|---|---|
-| DP | Dispatch a request to the right specialist(s) | `rcode-raees-dispatch` [planned — not yet implemented] |
+| DP | Dispatch a request to the right specialist(s) | `Task(subagent_type=...)` per the plan's named owners |
 | SQ | Build an execution sequence for a multi-step request | `rcode-raees-sequence` [planned — not yet implemented] |
 | PL | Identify parallel vs sequential work | `rcode-raees-parallel` [planned — not yet implemented] |
 | HO | Set up an explicit handoff between two agents | `rcode-raees-handoff` [planned — not yet implemented] |
@@ -90,14 +93,41 @@ Step 3 (BLOCKING):  <agent> → <skill> — gate
 
 Always show: primary owner, dependencies (arrows or "blocked by"), parallel opportunities.
 
-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).
+Save the plan to `.rcode/progress/dispatch-{date}.md`, then **carry it out**.
 
-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").
+**Raees dispatches. An orchestrator that writes a plan and hands it back is a
+planner with a different name** — and asking "shall I start?" after the user
+already said "execute end to end" spends their turn on a question they have
+already answered.
+
+Present the plan and wait ONLY when one of these is true:
+
+- **The request did not authorize execution.** "Who should own this?", "what
+  order?", "build me a dispatch plan" ask for the plan itself. Deliver it and stop.
+- **A gate needs a human.** A checkpoint the user locked earlier (content review
+  before publish, a credential, a deploy), or an outward-facing action. Run
+  everything up to it, then stop AT the gate and say which step is blocked and why.
+- **Scope is genuinely ambiguous** in a way that changes what gets built — not
+  merely large. Ask the one question that resolves it, not for permission.
+
+Otherwise dispatch: spawn the named agents via `Task()`, in parallel where the
+plan says parallel, report each dispatch as it goes out and each return as it
+lands, and close with what changed, what is still open, and the single next step.
+
+Two things Raees still never does: **implement anything himself** (the moment he
+edits a file instead of dispatching, the run has no orchestrator), and **declare
+work complete** — completion comes from the verification path, and a `passed`
+with no `falsification: upheld` is self-certified.
+
+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. Report dispatch accurately: say "dispatching X" when you are actually spawning X,
+and "recommended: X" only when you are stopping at a gate and X has not been
+spawned. Never claim a dispatch that did not happen, and never describe a real
+dispatch as a recommendation.
 
 ## Examples
 
 **Happy path — feature request**
-"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.
+"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` → then spawns Layla, and on her return spawns Haitham/Yousef/Noor in parallel. Stops at Khalid's ship step, which is outward-facing and needs the user.
 
 **Happy path — government proposal**
 "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.

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

@@ -16,9 +16,9 @@ description: >
   (use Khalid).
 triggers:
   # English
-  - "backend"
+  - "backend work"
   - "API design"
-  - "database"
+  - "database design"
   - "server-side"
   - "Node.js backend"
   - "Python backend"

package/rcode/skills/agents/zayd-ml/SKILL.md

@@ -18,7 +18,7 @@ triggers:
   # English
   - "machine learning"
   - "ML model"
-  - "AI"
+  - "AI feature"
   - "LLM"
   - "prompt engineering"
   - "fine-tuning"

package/rcode/skills/core/rcode-help/SKILL.md

@@ -3,7 +3,8 @@ name: rcode-help
 description: "Answers rcode questions and recommends the next skill to run, based on current project state."
 triggers:
   # English
-  - "help"
+  # NOTE: no bare "help" trigger. It matched almost every message, and
+  # "rcode help" already covers the intent without the false positives.
   - "rcode help"
   - "what should I do next"
   - "what can rcode do"

package/rcode/workflows/execute-sprint.md

@@ -565,7 +565,7 @@ fi
 grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-SPRINT.md | head -50
 ```
 
-If user_setup exists: create `{phase}-USER-SETUP.md` using template `.rcode/templates/user-setup.md`. Per service: env vars table, account setup checklist, dashboard config, local dev notes, verification commands. Status "Incomplete". Set `USER_SETUP_CREATED=true`. If empty/missing: skip.
+If user_setup exists: create `{phase}-USER-SETUP.md` using `.rcode/templates/user-setup.md` if present (not shipped — normally absent; the per-service section list that follows is the contract). Per service: env vars table, account setup checklist, dashboard config, local dev notes, verification commands. Status "Incomplete". Set `USER_SETUP_CREATED=true`. If empty/missing: skip.
 </step>
 
 <step name="create_summary">

package/rcode/workflows/secure-phase.md

@@ -132,7 +132,9 @@ Handle return:
 ## 6. Write/Update SECURITY.md
 
 **State B (create):**
-1. Read template from `.rcode/templates/SECURITY.md`
+1. Read `.rcode/templates/SECURITY.md` **if it exists** — it is not shipped, so
+   normally it will not. Build the document from step 2's section list instead;
+   that list is the contract, the template was only ever a convenience.
 2. Fill: frontmatter, threat register, accepted risks, audit trail
 3. Write to `${PHASE_DIR}/${PADDED_PHASE}-SECURITY.md`