@hanzlaa/rcode 4.11.0 → 4.12.1

package/AGENTS.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `init`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, `benchmarks`, `eval`, `scan`, `verifier`, `discuss-phase`, `ui-phase`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `init`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, `benchmarks`, `eval`, `scan`, `verifier`, `discuss-phase`, `ui-phase`, `state-sync`, `autonomous`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CLAUDE.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `init`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, `verifier`, `discuss-phase`, `ui-phase`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `init`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, `verifier`, `discuss-phase`, `ui-phase`, `state-sync`, `autonomous`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CONTRIBUTING.md

@@ -369,6 +369,8 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `verifier` — `rcode-verifier` agent, verification playbook/rules, VERIFICATION.md flow
 - `discuss-phase` — `/rcode-discuss-phase` workflow and its gray-area/standing checks
 - `ui-phase` — `/rcode-ui-phase` workflow, UI-SPEC.md/WIREFRAMES.md generation, design-library
+- `state-sync` — `state sync --from-disk`, phase-status reconciliation, ROADMAP↔state.json drift
+- `autonomous` — `/rcode-autonomous` workflow, the greenfield prerequisite gate
 - `<phase-id>` — numeric phase scope when committing inside a phase (e.g. `docs(15)`, `feat(8.3)`)
 - `<sprint-id>` — numeric sprint scope inside a phase (e.g. `feat(15.1)`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.11.0",
+  "version": "4.12.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-planner.md

@@ -9,6 +9,7 @@ color: green
 @.rcode/references/karpathy-guidelines-full.md
 @.rcode/references/output-realism.md
 @.rcode/brain/best-practices/no-theoretical-suggestions.md
+@.rcode/references/source-of-truth-grounding.md
 @.rcode/references/planner-playbook.md
 
 <role>

package/rcode/agents/rcode-project-researcher.md

@@ -8,6 +8,7 @@ color: cyan
 
 @.rcode/references/response-style.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/source-of-truth-grounding.md
 @.rcode/references/researcher-shared.md
 
 <role>

package/rcode/agents/rcode-roadmapper.md

@@ -9,6 +9,7 @@ color: purple
 @.rcode/references/response-style.md
 @.rcode/references/output-realism.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/source-of-truth-grounding.md
 @.rcode/references/roadmapper-playbook.md
 
 <role>

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

@@ -7,6 +7,7 @@ color: green
 
 @.rcode/references/response-style.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/source-of-truth-grounding.md
 @.rcode/references/sprint-checker-playbook.md
 
 <role>

package/rcode/agents/rcode-ux-designer.md

@@ -29,7 +29,8 @@ Named rules. Cite by name when applying.
 - **10th-time-user** — delight happens through invisible efficiency. Design for the person who has done this 10 times, not just the first-timer.
 - **Ship-then-layer** — recommend the simplest version that ships, then layer complexity. Perfect designs that never launch are zero value.
 - **Name-one-misconception** — for every confusing design element, name the specific misconception and design around it.
-- **Library-not-invention** — when producing UI-SPEC.md or WIREFRAMES.md, ground tokens and palette choices in `rcode/references/design-library/`, not invented values. WIREFRAMES.md's loading/empty/error/populated coverage per screen is Silence-kills-trust made concrete, per-screen.
+- **Library-not-invention** — when producing UI-SPEC.md or WIREFRAMES.md, ground tokens and palette choices in `rcode/references/design-library/` AND real reference sites actually looked at (not just search snippets), not invented values. WIREFRAMES.md's loading/empty/error/populated coverage per screen is Silence-kills-trust made concrete, per-screen.
+- **Variants-not-a-verdict** — visual direction is a taste-and-tradeoff decision, not a data lookup with one right answer. When asked to propose a design direction, generate genuinely distinct options and let the user pick — don't rank them or present a "recommended" one, that's the same failure as silently locking in a stack choice without asking.
 
 ## Anti-Patterns / Refuse List
 

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

@@ -483,6 +483,61 @@ issue:
   fix_hint: "Plan was built on hallucinated findings. Re-run /rcode-debug to verify actual code state before replanning."
 ```
 
+## 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?
+
+This dimension has two halves. Both exist because agents produce fluent,
+confident, wrong output when nothing forces them to cite a real source —
+codebase claims and domain-terminology claims fail the same way, just
+against different ground truths.
+
+### 12a — Codebase Evidence (issue #649)
+
+Every task body that names a file count, component, pattern, or existing
+behavior MUST include an `<evidence>` block citing real grep hit counts,
+real `path:line` ranges, or an explicit `creates:` justification (for
+genuinely new files/symbols that can't have prior evidence). A task claiming
+"13 usages of `useAuth`" with no evidence, or citing a grep that doesn't
+actually return 13, is theoretical — reject it.
+
+**Process:**
+1. For each task with a factual claim about existing code, check for an `<evidence>` block.
+2. If present, re-run a sample of the cited greps/searches yourself. If the claimed count doesn't match reality, downgrade to blocker regardless of what the task otherwise looks like.
+3. If absent for a claim that isn't a `creates:` (brand new file/symbol), flag as blocker — the claim is unfalsifiable as written.
+
+### 12b — Source-Document Evidence
+
+If PROJECT.md/REQUIREMENTS.md/CONTEXT.md reference an external source-of-truth
+document (a spreadsheet, transcript, spec, glossary — see
+`source-of-truth-grounding.md`) that defines domain terminology, enum values,
+or a data model, any task creating schema fields, enum values, or seed data
+for that domain MUST cite the source document and use its verbatim values —
+not an invented approximation that merely sounds plausible for "this kind of
+system." This is exactly how a competency-tracking app once shipped invented
+category names (`TECH`, `DELIV`, `COLLAB`) instead of the real Excel's actual
+categories (`Technical Skills`, `Delivery & Quality`, `Communication &
+Collaboration`) — plausible, well-formatted, and wrong.
+
+**Process:**
+1. Check whether PROJECT.md/REQUIREMENTS.md mention a source document for this domain.
+2. If yes, for each schema/seed-data task touching that domain, verify the task cites the source document path and that its field/enum values are traceable to it (spot-check by reading the source yourself if it's available).
+3. A schema/seed task for a domain with a known source document, with no citation and no traceable match, is a blocker — not a style nitpick. This is exactly the class of mistake that's expensive to unwind once it's in a live database.
+
+**Severity rules:**
+- **blocker:** 12a claim with no evidence and no `creates:` justification, evidence that doesn't check out on re-run, OR 12b schema/seed task for a known-source domain with no citation/traceable match
+- **warning:** evidence present but thin (e.g. cites a grep pattern too broad to actually confirm the specific claim)
+
+**Example issue:**
+```yaml
+issue:
+  dimension: evidence_grounding
+  severity: blocker
+  description: "Task 3 seeds 'competency' enum with TECH/DELIV/COLLAB/GROWTH/IMPACT — PROJECT.md references docs/Competency-Matrix.xlsx as the source of truth for these categories, but no task reads it or cites its actual values"
+  plan: "01"
+  fix_hint: "Read docs/Competency-Matrix.xlsx (or its extracted contents) and replace the enum values with what it actually defines, verbatim"
+```
+
 </verification_dimensions>
 
 <verification_process>

package/rcode/bin/rcode-tools.cjs

@@ -3418,9 +3418,20 @@ function cmdState(subArgs) {
       // landed as 'planned' regardless of what the doc said.
       function normalizeStatus(raw) {
         if (!raw) return 'planned';
-        const s = String(raw).toLowerCase().replace(/[✅\s]/g, '');
-        if (['complete','completed','shipped','verified','done'].includes(s)) return 'complete';
-        if (['executing','in_progress','inprogress','active','started'].includes(s)) return 'in_progress';
+        // Match on the LEADING word, not exact string equality — ROADMAP.md
+        // status lines legitimately carry trailing detail beyond the bare
+        // status word (e.g. "Complete (verification: human_needed — live
+        // deploy deferred)"), which an exact-match check silently drops to
+        // 'planned' since the full string never equals 'complete'. A real
+        // "Complete (...)" phase would then look un-synced forever.
+        // Strip trailing detail (anything from the first paren/colon/em-dash
+        // onward — "(verification: ...)", ": some note") before matching, then
+        // collapse whitespace/underscores so "Complete (...)", "In Progress",
+        // and "in_progress" all normalize the same way.
+        const leading = String(raw).toLowerCase().replace(/[✅]/g, '')
+          .split(/[(:—]/)[0].trim().replace(/[\s_]+/g, '');
+        if (['complete','completed','shipped','verified','done'].includes(leading)) return 'complete';
+        if (['executing','inprogress','active','started'].includes(leading)) return 'in_progress';
         return 'planned';
       }
 
@@ -3443,7 +3454,43 @@ function cmdState(subArgs) {
         // Status precedence for advancement: complete > in_progress > planned.
         // A phase should never be downgraded by ROADMAP re-sync.
         const statusRank = { complete: 2, in_progress: 1, planned: 0 };
-        const incomingStatus = normalizeStatus(phaseStatus);
+        let incomingStatus = normalizeStatus(phaseStatus);
+
+        // Cross-check against VERIFICATION.md before trusting a 'complete' claim
+        // from ROADMAP prose. A phase can be hand-edited to say "Complete" (or
+        // "gaps_found → closed") without ever re-running the verifier — confirmed
+        // live: an agent wrote that exact phrase into ROADMAP.md while the phase's
+        // own VERIFICATION.md frontmatter still said `status: gaps_found`,
+        // bypassing execute.md's uat_gate entirely via a direct file edit. Don't
+        // let a prose claim override what the actual verification artifact says.
+        if (incomingStatus === 'complete') {
+          try {
+            const phasesRootDir = path.join(PLANNING_DIR, 'phases');
+            const phaseDirName = fs.existsSync(phasesRootDir)
+              ? fs.readdirSync(phasesRootDir).find(d => d === phaseNum || d.startsWith(`${phaseNum}-`))
+              : null;
+            if (phaseDirName) {
+              const verFile = fs.readdirSync(path.join(phasesRootDir, phaseDirName))
+                .find(f => /-VERIFICATION\.md$/i.test(f));
+              if (verFile) {
+                const verText = fs.readFileSync(path.join(phasesRootDir, phaseDirName, verFile), 'utf8');
+                const verStatusMatch = verText.match(/^status:\s*(\S+)/m);
+                const verStatus = verStatusMatch ? verStatusMatch[1].trim() : null;
+                if (verStatus && verStatus !== 'passed') {
+                  incomingStatus = 'in_progress';
+                  parsed.unverified_complete_claims = parsed.unverified_complete_claims || [];
+                  parsed.unverified_complete_claims.push({
+                    phase: phaseNum,
+                    roadmap_claim: phaseStatus,
+                    verification_file: verFile,
+                    verification_status: verStatus,
+                  });
+                }
+              }
+            }
+          } catch { /* best-effort cross-check — never fail sync over it */ }
+        }
+
         if (existingIdx >= 0) {
           // Backfill both id and number so future readers using either schema find it.
           state.phases[existingIdx].number = state.phases[existingIdx].number || phaseNum;
@@ -4660,7 +4707,7 @@ When creating, planning, or modifying a phase, you MUST go through the rcode too
 
 **Why this is enforced**: every direct \`Write\` to \`.planning/phases/**/SPRINT.md\` without registration is a silent state divergence. Future \`/rcode-status\` reports under-count work. \`/rcode-execute\` can't find the plan. \`/rcode-progress\` shows wrong percentages.
 
-If you have a real reason to bypass (e.g. retroactively documenting a phase that already shipped), put \`<!-- rcode-bypass: <one-line reason> -->\` at the top of the file so it's auditable later. The PreToolUse hook will allow the write through.
+If you have a real reason to bypass (e.g. retroactively documenting a phase that already shipped), put \`<!-- rcode-bypass: <one-line reason> -->\` at the top of the file so it's auditable later. **This rule is currently convention, not mechanically enforced** — no hook blocks an unregistered direct write today, so following it is on you (and any agent reading this), not a safety net catching you if you don't.
 
 ---
 

package/rcode/references/source-of-truth-grounding.md

@@ -0,0 +1,80 @@
+# Source-of-Truth Grounding
+
+Loaded by any workflow/agent that generates domain terminology, schema fields,
+enum values, or seed data — discuss-phase, roadmapper, project-researcher,
+planner, sprint-checker.
+
+## The failure this prevents
+
+A real incident: a competency-tracking app's requirements referenced an
+authoritative Excel file (the actual HR competency matrix) and a meeting
+transcript explaining it. The planner never opened the Excel — it invented
+plausible-sounding competency names (`TECH`, `DELIV`, `COLLAB`, `GROWTH`,
+`IMPACT`) and level names (`Junior`, `Associate`, `Senior I/II/III`) that
+*sounded* right for a generic engineering-competency system. The real Excel
+defined different names (`Technical Skills`, `Delivery & Quality`,
+`Communication & Collaboration`, `Leadership & Coaching`, `Strategic Impact`,
+`Innovation & Improvement`) and different levels (`Potential`, `Competency`,
+`Proficiency`, `Expertise`, `Mastery`). The invented values got baked into
+the database schema, seed data, and UI labels — an entire app built on
+plausible-sounding fiction instead of the actual source of truth, discovered
+only when the user manually re-fed the same files back in and asked for a
+gap check.
+
+This is not a hypothetical edge case. Any project with domain-specific
+terminology defined by an external document (an HR/compliance matrix, a
+partner's API spec, a legal/regulatory definition list, a brand's existing
+design system, a client's glossary) is exposed to this failure the moment a
+planner treats "sounds plausible" as good enough.
+
+## The rule
+
+**If a source document exists — the user references it, provides a file
+path, pastes its content, or it's already sitting in the project (`docs/`,
+an attached spreadsheet, a transcript, an existing spec) — and it defines
+domain terminology, categories, enum values, or a data model that the
+current work touches, that document MUST be read in full before generating
+anything that uses those concepts. Extract the actual values verbatim.**
+
+- Don't paraphrase a defined term into a shorter or "cleaner" one. If the
+  source says `Communication & Collaboration`, the schema/seed/UI say
+  `Communication & Collaboration` — not `COLLAB`, not `Comm & Collab`.
+- Don't guess the count or order. If the source defines 6 categories, use
+  the 6 it defines — don't invent 5 that seem close enough.
+- Don't treat "I've seen similar systems before" as a substitute for reading
+  this one's actual source. Training-data familiarity with how competency
+  matrices *usually* look is exactly what produces plausible-but-wrong output.
+- Excel/spreadsheet files: read the actual cell contents (via a script,
+  `openpyxl`/`pandas`-equivalent, or unzipping the `.xlsx` and parsing the
+  shared-strings XML if no library is available) — not the filename, not an
+  assumption about what a file named "Competency Matrix" probably contains.
+- Transcripts/recordings-as-text: read the whole thing, not just the first
+  few lines — the real values are often stated once, in the middle, in
+  passing ("we have six core competencies, which is technical skills,
+  delivery quality, communication, collaboration...").
+
+## Self-check before presenting or committing
+
+After generating requirements/schema/seed-data/UI copy that should be
+grounded in a source document, do one pass comparing what you generated
+against the source: does every category/level/field name match verbatim?
+If you can't point to the specific line/cell in the source for a value you
+used, that value is invented — fix it before presenting, not after the user
+catches it.
+
+## Where this applies
+
+- **discuss-phase / new-project**: when a source document is mentioned or
+  present, read it during context-gathering, before requirements get
+  drafted — not after.
+- **project-researcher / phase-researcher**: cite the source document's
+  actual terminology in STACK.md/FEATURES.md, not an approximation.
+- **roadmapper**: phase success criteria referencing domain concepts use the
+  source's exact terms.
+- **planner**: schema fields, enum values, and seed-data tasks cite the
+  source document path and use its verbatim values — a task creating seed
+  data for a domain concept with a known source document is incomplete if
+  it doesn't reference that source.
+- **sprint-checker**: if PROJECT.md/REQUIREMENTS.md reference a source
+  document, flag as a blocker any schema/seed-data task whose field/enum
+  values aren't traceable to it.

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

@@ -2,7 +2,7 @@
 
 **Goal:** Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value, creating detailed, actionable stories with complete acceptance criteria for development teams.
 
-**Your Role:** In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals.
+**Your Role:** In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals. Ground the product-strategist half of this role in `rcode-hussain-pm`'s calibrated judgment (MoSCoW/RICE prioritization, JTBD framing, explicit scope defense) rather than generic story-writing — same reasoning as `rcode-create-prd`'s workflow: this is a live, halt-and-wait conversation, so you take on the role directly instead of spawning a subagent.
 
 ## State-sync rule (NO EXCEPTIONS)
 

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

@@ -7,7 +7,15 @@ outputFile: '{planning_artifacts}/prd.md'
 
 **Goal:** Create comprehensive PRDs through structured workflow facilitation.
 
-**Your Role:** Product-focused PM facilitator collaborating with an expert peer.
+**Your Role:** Product-focused PM facilitator collaborating with an expert peer. This
+is a live, menu-driven, halt-and-wait conversation — spawning a subagent here would
+break that interactivity, so you take on the role directly rather than delegating it.
+Ground that role in `rcode-hussain-pm`'s actual calibrated judgment, not a generic
+"PM" framing: MoSCoW/RICE prioritization, JTBD framing over feature lists, defend
+scope by naming what's explicitly OUT of v1 and why, defer technical feasibility
+calls to Waleed and strategic go/no-go calls to Sadiq rather than making them
+yourself. See `rcode/agents/rcode-hussain-pm.md` for the full principle set if you
+need it — the summary above is what actually changes PRD-writing behavior day to day.
 
 You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
 

package/rcode/templates/settings-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "pre-edit hook is currently advisory (logs warning, does not block). Full session-read tracking requires PostToolUse Read hook to write state file. Implemented in follow-up. prompt-router (UserPromptSubmit) is advisory — emits additionalContext to nudge toward the right rcode command; never blocks. session-start (SessionStart) emits a one-line project status primer at session open.",
+  "_comment": "pre-edit hook is currently advisory (logs warning, does not block). Full session-read tracking requires PostToolUse Read hook to write state file. Implemented in follow-up. prompt-router (UserPromptSubmit) is advisory \u2014 emits additionalContext to nudge toward the right rcode command; never blocks. session-start (SessionStart) emits a one-line project status primer at session open.",
   "hooks": {
     "PreToolUse": [
       {
@@ -7,11 +7,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs pre-edit"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" pre-edit || exit 0'"
           },
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs compact-nudge"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" compact-nudge || exit 0'"
           }
         ]
       },
@@ -20,7 +20,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs pre-workflow"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" pre-workflow || exit 0'"
           }
         ]
       },
@@ -29,7 +29,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs bash-guard"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" bash-guard || exit 0'"
           }
         ]
       }
@@ -40,7 +40,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs post-commit"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" post-commit || exit 0'"
           }
         ]
       }
@@ -51,7 +51,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs pre-compact"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" pre-compact || exit 0'"
           }
         ]
       }
@@ -62,15 +62,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs stop-verify"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" stop-verify || exit 0'"
           },
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs cost-track"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" cost-track || exit 0'"
           },
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs stop"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" stop || exit 0'"
           }
         ]
       }
@@ -81,7 +81,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs prompt-router"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" prompt-router || exit 0'"
           }
         ]
       }
@@ -92,7 +92,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .rcode/bin/rcode-hooks.cjs session-start"
+            "command": "sh -c 'H=\".rcode/bin/rcode-hooks.cjs\"; [ -f \"$H\" ] || { G=$(git rev-parse --git-common-dir 2>/dev/null) && H=\"$(cd \"$(dirname \"$G\")\" 2>/dev/null && pwd)/.rcode/bin/rcode-hooks.cjs\"; }; [ -f \"$H\" ] && exec node \"$H\" session-start || exit 0'"
           }
         ]
       }

package/rcode/workflows/autonomous.md

@@ -52,30 +52,51 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 ## 0. Prerequisite check (greenfield guard)
 
-Before any phase work, verify the methodology chain has run:
+rcode supports two valid project-initialization paths, and this gate must
+accept either:
+- **Full chain:** `/rcode-create-prd` → `/rcode-new-milestone` → `/rcode-create-epics-and-stories`
+- **Direct roadmap path:** `/rcode-new-project` → `rcode-roadmapper` writes
+  ROADMAP.md directly with phases, no prd.md/epics.md produced — this is a
+  first-class supported path, not an edge case, and autonomous execution
+  only actually needs a ROADMAP.md with real phases in it to do phase work.
+
+Before any phase work, verify at least one path's minimum requirement is met:
 
 ```bash
 HAS_PRD=$( ( ls .planning/prd.md .planning/PRD.md .planning/prds/*.md .planning/milestones/*/PRD.md 2>/dev/null | head -1 ) && echo true || echo false)
-HAS_ROADMAP_MILESTONES=$(grep -qE "^## Milestone\s+M[0-9]+" .planning/ROADMAP.md 2>/dev/null && echo true || echo false)
 HAS_EPICS=$( ( ls .planning/epics.md .planning/EPICS.md .planning/epics/*.md .planning/milestones/*/EPICS.md 2>/dev/null | head -1 ) && echo true || echo false)
+# Milestone marker: accepts heading style ("## Milestone M1"), bold-prose style
+# ("**Milestone:** M1 — ..."), or PROJECT.md's own style ("## Current Milestone: M3 — ...")
+# — roadmapper's actual output uses the bold-prose form, which the old heading-only
+# regex never matched, permanently failing this gate for every project that used
+# the direct roadmap path. Fixed live: confirmed against a real project's ROADMAP.md.
+HAS_ROADMAP_MILESTONES=$(grep -qEi "milestone[:*]*\s*M[0-9]" .planning/ROADMAP.md 2>/dev/null && echo true || echo false)
+# Direct roadmap path's actual minimum: a ROADMAP.md with at least one real phase.
+HAS_ROADMAP_PHASES=$(grep -qE "^##\s*Phase\s+[0-9]|^\|\s*[0-9]+\s*\|" .planning/ROADMAP.md 2>/dev/null && echo true || echo false)
 SKIP_FLAG=$(echo "$ARGUMENTS" | grep -qE "\-\-skip-prerequisites" && echo true || echo false)
+
+FULL_CHAIN_OK=$([ "$HAS_PRD" = "true" ] && [ "$HAS_ROADMAP_MILESTONES" = "true" ] && [ "$HAS_EPICS" = "true" ] && echo true || echo false)
+DIRECT_PATH_OK=$([ "$HAS_ROADMAP_PHASES" = "true" ] && echo true || echo false)
 ```
 
-If `SKIP_FLAG=false` AND any prerequisite is missing, HALT with a clear message:
+If `SKIP_FLAG=false` AND both `FULL_CHAIN_OK` and `DIRECT_PATH_OK` are false, HALT with a clear message:
 
 ```
-⚠ Cannot run autonomous: missing prerequisite — {what}.
+⚠ Cannot run autonomous: no valid project initialization found.
 
-The autonomous flow assumes a project that has already gone through:
-  1. /rcode-create-prd               → produces .planning/prd.md
-  2. /rcode-new-milestone         → produces ROADMAP.md with M1..Mn
-  3. /rcode-create-epics-and-stories → produces .planning/epics.md
-  4. THEN /rcode-autonomous           ← you are here
+The autonomous flow needs either:
+  A) Full chain: /rcode-create-prd → /rcode-new-milestone → /rcode-create-epics-and-stories
+  B) Direct roadmap: /rcode-new-project (produces ROADMAP.md with phases directly)
 
-Suggested first step: /rcode-{first-missing-command}
+Neither was found — no ROADMAP.md with real phases exists, and the full
+chain's artifacts (prd.md, milestone-marked ROADMAP.md, epics.md) are also
+missing.
 
-If you genuinely want to skip these (rare — usually inverted methodology),
-re-invoke with: /rcode-autonomous --skip-prerequisites
+Suggested first step: /rcode-new-project (recommended — simpler, fully
+supported) or /rcode-create-prd if you specifically want the full chain.
+
+If you genuinely want to skip this check, re-invoke with:
+/rcode-autonomous --skip-prerequisites
 ```
 
 If `SKIP_FLAG=true`: print a warning that downstream workflows may produce low-quality output without upstream artifacts, then proceed.
@@ -463,7 +484,7 @@ Task(
 )
 ```
 
-Store the agent task_id. The workflow can now start discussing the next phase while this phase executes in the background. Before starting post-execution routing for this phase, wait for the execute agent to complete.
+Store the agent task_id. The workflow can now start discussing the next phase while this phase executes in the background. Before starting post-execution routing for this phase, wait for the execute agent to complete, then run the mandatory reconciliation command below (same as the non-interactive path) before continuing.
 
 **If `INTERACTIVE` is NOT set (default):** Run execute inline as before.
 
@@ -471,6 +492,24 @@ Store the agent task_id. The workflow can now start discussing the next phase wh
 Skill(skill="rcode-execute", args="${PHASE_NUMBER} --no-transition")
 ```
 
+**Mandatory reconciliation (run this bash command directly, every phase, no exceptions):**
+`execute.md`'s own state-write steps (`phase set-status`/`phase complete`) are
+documented but not mechanically guaranteed — a real unattended multi-phase
+run was observed skipping them, leaving `state.json` stuck at every phase's
+planning-time status while ROADMAP.md correctly showed them complete. Don't
+rely on remembering to do this; run it as its own step, immediately after
+execute returns, before moving to post-execution routing:
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" state sync --from-disk >/dev/null 2>&1 || true
+```
+
+This is idempotent and cheap — it re-derives phase status from ROADMAP.md's
+actual `**Status:**` text (never downgrades an already-advanced status), so
+running it here closes the gap even if execute.md's own inline state-write
+steps were skipped during a long run. Do this for every phase in the loop,
+not just once at the end.
+
 ### 3c.5. Code Review and Fix
 
 Auto-invoke code review and fix chain. Autonomous mode chains both review and fix.

package/rcode/workflows/discuss-phase.md

@@ -6,6 +6,7 @@ You are a thinking partner, not an interviewer. The user is the visionary — yo
 
 <required_reading>
 @.rcode/references/universal-anti-patterns.md
+@.rcode/references/source-of-truth-grounding.md
 </required_reading>
 
 <conditional_reading>

package/rcode/workflows/enable-hooks.md

@@ -90,6 +90,12 @@ Enabled guardrails:
   • session-start: Greets the session with one-line phase status and suggested next command
 
 To disable, remove the hooks section from .claude/settings.json or edit .rcode/templates/settings-hooks.json and re-run.
+
+Note: .rcode/bin/ is gitignored by design, so a `git worktree add` checkout
+won't have it — each hook command resolves this automatically via
+`git rev-parse --git-common-dir` (finds the main checkout's .rcode/bin/ and
+runs from there), falling back to a silent no-op if genuinely not found
+anywhere. No action needed in worktrees; this is handled for you.
 ```
 
 ## Success Criteria

package/rcode/workflows/new-milestone.md

@@ -541,7 +541,11 @@ Write files first, then return.
 
 **If `## ROADMAP BLOCKED`:** present the blocker, collect resolution from user, re-spawn the roadmapper with revision context.
 
-**If `## ROADMAP CREATED`:** read ROADMAP.md, present inline:
+**If `## ROADMAP CREATED`:**
+
+**Team review pass (once per roadmap draft; skip in auto/yolo mode — see `new-project-roadmap.md`'s identical step for the full rationale):** spawn `rcode-waleed` and `rcode-fatima` in parallel, same prompts as `new-project-roadmap.md`'s team review pass (feasibility sanity check / release-risk sanity check, 3 bullets max or "no concerns" in one line). Fold genuine concerns into a **Team Review Notes** section in the presentation below, before the phase table — skip the section if both say no concerns.
+
+Read ROADMAP.md, present inline:
 
 ```
 ## Proposed Roadmap

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

@@ -310,6 +310,28 @@ Display research complete banner and key findings:
 Files: `.planning/research/`
 ```
 
+**Mandatory stack-choice confirmation (before proceeding to roadmap):**
+Tech stack is the single most foundational, hardest-to-reverse decision in
+the project — every phase gets built on top of it, and un-picking it later
+means rework, not a config change. Do not let it get silently locked in.
+
+Check `.planning/research/STACK.md` for language indicating this was a
+judgment call, not a forced single-option pick — phrases like "judgment
+call," "flagging explicitly," a comparison table between 2+ named
+platforms/frameworks, or an explicit confidence caveat on the top-level
+choice. (A stack choice with genuinely no alternative — e.g. "must integrate
+with the client's existing Salesforce" — doesn't need this; skip only in
+that case, and say why.)
+
+If it's a judgment call, use AskUserQuestion before continuing:
+- **question:** "Research recommends {stack} over {alternative(s)} for {one-line reason}. Confirm, or pick differently?"
+- **options:** "Confirm {stack}" / "Use {alternative}" / "Something else — I'll specify"
+
+If the user picks differently, note the override as a decision and don't
+silently keep researching the original recommendation — the chosen stack
+from here on is whatever the user picked, not STACK.md's original
+recommendation, and downstream phases/roadmap should reflect that.
+
 **If "Skip research":** Continue to Step 7.
 
 

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

@@ -215,6 +215,25 @@ Write files first, then return. This ensures artifacts persist even if context i
 
 **If `## ROADMAP CREATED`:**
 
+**Team review pass (once per roadmap draft, not per phase — keep this cheap; skip entirely in auto/yolo mode — an unattended loop shouldn't pay this round-trip on every roadmap, and there's no user present to read the notes anyway):**
+Before presenting the roadmap for approval, spawn two focused reviewers in
+parallel against the freshly-written ROADMAP.md — a single async round, not a
+council debate, so this adds one round-trip, not multiple:
+
+```
+Task(prompt="Read .planning/ROADMAP.md and .planning/PROJECT.md. As Waleed (CTO/architect), flag ONLY real feasibility/scalability concerns you'd actually block a real project over — a phase sequencing a schema-breaking change after the API that depends on it, a scale ceiling the phase structure doesn't account for, a missing foundational/shell phase for a UI project. If there are none, say so in one line. Keep it to 3 bullets max — this is a sanity check, not a full architecture review.", subagent_type="rcode-waleed", model="{roadmapper_model}", description="Architecture sanity check")
+
+Task(prompt="Read .planning/ROADMAP.md and .planning/PROJECT.md. As Fatima (QA Lead), flag ONLY real release-risk concerns — a phase with no way to verify its success criteria, a security/compliance-sensitive area with no phase covering it, a dependency ordering that makes a phase unverifiable until a later one lands. If there are none, say so in one line. Keep it to 3 bullets max — this is a sanity check, not a full QA strategy doc.", subagent_type="rcode-fatima", model="{roadmapper_model}", description="Release-risk sanity check")
+```
+
+Run both, collect their one-line-or-3-bullets responses. If either flags a
+concern that would make the roadmap actually wrong (not a nitpick), add a
+**Team Review Notes** section to the presentation below, before the phase
+table, so the user sees it as part of deciding whether to approve — don't
+silently drop it, and don't block on it either; the approval gate right
+after this is where the user decides what to do with it. If both reviewers
+say "no concerns," skip the section entirely — don't manufacture filler.
+
 Read the created ROADMAP.md and present it nicely inline:
 
 ```

package/rcode/workflows/plan.md

@@ -625,12 +625,27 @@ Task(
 - **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
 - **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
 
-**Thinking partner for architectural tradeoffs (conditional):**
+**Thinking partner for architectural tradeoffs (default ON in guided mode, OFF in yolo/autonomous):**
 ```bash
-THINKING_PARTNER_ENABLED=$(node ".rcode/bin/rcode-tools.cjs" config-get features.thinking_partner 2>/dev/null || echo "false")
+THINKING_PARTNER_CONFIG=$(node ".rcode/bin/rcode-tools.cjs" config-get features.thinking_partner 2>/dev/null || echo "")
+if [ -n "$THINKING_PARTNER_CONFIG" ]; then
+  THINKING_PARTNER_ENABLED="$THINKING_PARTNER_CONFIG"
+elif [ "$MODE" = "yolo" ] || [ -n "$AUTONOMOUS" ]; then
+  THINKING_PARTNER_ENABLED="false"
+else
+  THINKING_PARTNER_ENABLED="true"
+fi
 ```
 ${THINKING_PARTNER_ENABLED === 'true' ? '@.rcode/references/plan-thinking-partner.md' : ''}
-If `features.thinking_partner` is disabled: skip this block entirely.
+If `THINKING_PARTNER_ENABLED` is `false`: skip this block entirely. An explicit
+`features.thinking_partner` in config.yaml always wins over the mode-based
+default (set it `false` to silence even in guided mode, or `true` to keep it
+on during autonomous runs if you want that). The check itself is cheap — a
+keyword scan over the checker's existing issues, not a new agent spawn —
+which is why it defaults on for guided/interactive planning: a second-opinion
+sanity check on architectural tradeoffs is exactly the kind of thing "does
+this actually get built right" needs, and it only activates when the checker
+already flagged a tradeoff-shaped issue.
 
 ## 12. Revision Loop (Max 3 Iterations, 1 in autonomous/yolo mode)
 

package/rcode/workflows/ui-phase.md

@@ -50,7 +50,7 @@ If `flags.existing_ui` or `flags.design_system` provided:
 EXISTING=$(node .rcode/bin/rcode-tools.cjs find-files --type=design-tokens)
 ```
 
-Load existing design system, extract into `EXISTING_DESIGN_SYSTEM_DATA` (a text block passed verbatim into Step 2's prompt):
+Load existing design system, extract into `EXISTING_DESIGN_SYSTEM_DATA` (a text block passed verbatim into Step 2b's prompt):
 - Color palette (hex, variable names)
 - Typography scales (font family, sizes, weights, line heights)
 - Component list (buttons, forms, layouts, modals, etc.)
@@ -60,7 +60,10 @@ If `$EXISTING` is empty or extraction finds nothing usable, treat this the
 same as "no existing system found" and fall through to Step 1b — don't leave
 `EXISTING_DESIGN_SYSTEM_DATA` half-populated.
 
-If an existing design system was found and `EXISTING_DESIGN_SYSTEM_DATA` is populated, skip Step 1b (don't override what's already decided) and go straight to Step 2.
+If an existing design system was found and `EXISTING_DESIGN_SYSTEM_DATA` is
+populated, there's nothing to choose between — skip Step 1b, Step 1c, AND
+Step 2 (variant generation + user confirmation) entirely, and go straight to
+Step 2b using `EXISTING_DESIGN_SYSTEM_DATA` as the chosen direction.
 
 ## Step 1b — Ground the design in the reference library (no existing system found)
 
@@ -73,11 +76,85 @@ first so there's a project category to ground the design in." Otherwise look up:
 2. **Style detail** — take the recommended style name from step 1 and look it up in `styles.csv` for concrete hex values, effects, accessibility rating, and an implementation checklist. Capture as `STYLE_DETAIL`.
 3. **UX rules** — grep `ux-guidelines.csv` for the categories relevant to this project's screens (Navigation, Forms, etc.) for concrete do/don't rules with code examples. Capture as `UX_RULES`.
 
-`CATEGORY_MATCH` + `STYLE_DETAIL` + `UX_RULES` together are what Step 2's
-prompt calls `DESIGN_LOOKUP_RESULT` below — assemble them into one text block
-before spawning the agent.
+`CATEGORY_MATCH` + `STYLE_DETAIL` + `UX_RULES` together are what Step 1c and
+Step 2 below call `DESIGN_LOOKUP_RESULT` — assemble them into one text block.
+
+## Step 1c — Look at real reference sites (skip only if Step 1 found an existing system)
+
+A CSV row is a starting hypothesis, not a substitute for actually looking at
+what real sites in this space look like. A style-data table can't tell you
+that every competitor uses a specific hero-image treatment, or that the
+category's "expected" look has drifted since the data was written. Do this
+before committing to a direction:
+
+1. **Find real reference sites.** WebSearch for the project's actual
+   industry/niche (from PROJECT.md — e.g. "best interior design websites
+   Pakistan", "top mobile repair shop websites", not a generic "SaaS
+   landing page examples" search unrelated to the real domain). Aim for
+   3-5 real, currently-live sites — direct competitors if findable, strong
+   examples in the same category otherwise.
+2. **Actually look at them**, don't just read search-result snippets. If a
+   browser tool is available in this session, navigate to each and take a
+   screenshot. If not, WebFetch each URL and read the rendered content/
+   structure description it returns. Note concretely, per site: layout
+   pattern (hero style, nav placement, content density), color mood, type
+   feel (serif/sans, weight, size), imagery style (photography vs.
+   illustration vs. none), and anything that reads as dated or as a
+   red flag to avoid repeating.
+3. Capture this as `REFERENCE_SITE_FINDINGS` — a short per-site note, not a
+   full audit. This feeds variant generation next, not a standalone report.
+
+If WebSearch/WebFetch/browser tools are genuinely unavailable in this
+session, skip with an explicit note ("Step 1c skipped — no web/browser
+tools available; design-library data only") rather than silently omitting
+real-site grounding — this is a real reduction in design quality and should
+be visible, not silent.
+
+## Step 2 — Generate design variants, get user confirmation (mandatory — do not skip to a single locked-in direction)
+
+Visual design direction is the same class of decision as tech-stack choice:
+foundational, expensive to redo once screens are built against it, and a
+matter of taste as much as data — it must not get silently locked in by an
+agent picking "the" recommended style. Generate 2-3 concrete, genuinely
+distinct variants (not the same direction with a different accent color),
+each grounded in `DESIGN_LOOKUP_RESULT` (Step 1b) and `REFERENCE_SITE_FINDINGS`
+(Step 1c), before writing anything to UI-SPEC.md:
 
-## Step 2 — Spawn UI Designer
+Spawn `rcode-ux-designer` subagent:
+
+```
+Task tool call:
+  subagent_type: "rcode-ux-designer"
+  description: "Generate design variants"
+  prompt: |
+    Ground every variant in {EXISTING_DESIGN_SYSTEM_DATA if Step 1 found one, else DESIGN_LOOKUP_RESULT + REFERENCE_SITE_FINDINGS} —
+    do not invent a palette/style from nothing when reference data or real
+    reference sites were found.
+
+    Propose 2-3 genuinely distinct design variants for this project. For each:
+    - **Name** (short, e.g. "Warm Editorial", "Minimal Trust", "Bold Craft")
+    - **One-paragraph description** — mood, layout approach, what it borrows from
+      the reference sites found (name which one(s)) vs. the design-library data
+    - **Color direction** — 2-3 representative hex values, not a full token system yet
+    - **Typography direction** — font pairing feel (serif/sans, weight)
+    - **Best for / worst for** — one line each, honest tradeoffs
+
+    Do NOT pick a winner or rank them — present as genuine options. Do NOT
+    write UI-SPEC.md yet.
+
+    Return the variants as your response text (not a file write).
+```
+
+Present the variants to the user via AskUserQuestion:
+- **question:** "Which design direction fits this project?"
+- **options:** one per variant (label = variant name, description = the one-paragraph summary), plus the tool's built-in "Other" for a custom direction
+- If the user picks "Other" and describes something different, treat their description as the chosen direction instead of any generated variant.
+
+Only after the user picks does Step 2b below proceed — using the chosen
+variant's color/typography direction as the seed for the full spec, not
+re-deriving from scratch.
+
+## Step 2b — Spawn UI Designer (full spec, chosen direction)
 
 Spawn `rcode-ux-designer` subagent:
 
@@ -86,7 +163,10 @@ Task tool call:
   subagent_type: "rcode-ux-designer"
   description: "Generate UI-SPEC.md and WIREFRAMES.md"
   prompt: |
-    Ground every choice below in {EXISTING_DESIGN_SYSTEM_DATA if Step 1 found one, else DESIGN_LOOKUP_RESULT from Step 1b} —
+    Build out the full spec from {EXISTING_DESIGN_SYSTEM_DATA if Step 1 found
+    one, else the user-chosen variant's full description, color direction,
+    and typography direction from Step 2}.
+    Ground every choice in {EXISTING_DESIGN_SYSTEM_DATA if Step 1 found one, else DESIGN_LOOKUP_RESULT from Step 1b} —
     do not invent a palette/style from nothing when reference data or an existing system exists.
 
     Write UI-SPEC.md with:
@@ -101,7 +181,7 @@ Task tool call:
     Write to: {ui_spec_path}
 ```
 
-## Step 2b — Spawn Wireframes (per-role screen inventory)
+## Step 2c — Spawn Wireframes (per-role screen inventory)
 
 Read REQUIREMENTS.md/PROJECT.md for the project's user roles (if any) and the
 IA decision — `roadmapper-playbook.md`'s Information Architecture step (Workflow
@@ -221,7 +301,9 @@ Run /rcode-ui-phase, then return to /rcode-plan
 
 ## Success Criteria
 
-- UI-SPEC.md created with all 7 sections, design direction grounded in `design-library/` lookup (or an existing design system), not invented
+- Real reference sites looked at (Step 1c), not just design-library data alone — or explicitly noted as skipped with a reason
+- 2-3 genuinely distinct design variants presented and the user explicitly picked one via AskUserQuestion — no direction silently locked in (skipped only when Step 1 found an existing design system, where there's nothing to choose between)
+- UI-SPEC.md created with all 7 sections, design direction grounded in the chosen variant / `design-library/` lookup / real reference sites (or an existing design system), not invented
 - Color tokens documented with contrast ratios
 - Component inventory complete with variants
 - Accessibility checklist included
@@ -233,7 +315,7 @@ Run /rcode-ui-phase, then return to /rcode-plan
 - If subagent fails: provide template UI-SPEC.md
 - If frontend detection fails: skip suggestion
 - If config.yaml missing ui_safety_gate: default to true (suggest)
-- If no IA decision exists in ROADMAP.md or IA.md yet: WIREFRAMES.md cannot be produced meaningfully — stop Step 2b and say so rather than writing a screen list with no basis
+- If no IA decision exists in ROADMAP.md or IA.md yet: WIREFRAMES.md cannot be produced meaningfully — stop Step 2c and say so rather than writing a screen list with no basis
 
 ## Next Up