@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/references/ui-brand.md

@@ -0,0 +1,254 @@
+# UI/Brand Questions
+
+When exploring the UI design phase (/rcode-ui-phase), ask structured questions across these eight dimensions: **color palette**, **typography**, **voice/tone**, **accessibility**, **component inventory**, **responsive behavior**, **interaction patterns**, and **visual hierarchy**. These questions build the design contract.
+
+---
+
+## 1. Color Palette
+
+Explore how color communicates brand, function, and hierarchy.
+
+### Exploration Questions
+
+- "What colors currently represent your brand, or do you have any brand guidelines?"
+- "Are there colors users expect based on your industry? (e.g., fintech = trust colors like blue/green)"
+- "Do you need to support dark mode, high contrast, or other accessibility variants?"
+- "How many color tokens do you anticipate — 5 core colors, or 20+?"
+- "Are there status colors you already use? (red = error, green = success, yellow = warning, etc.)"
+
+### Decision Questions
+
+- "Should the UI be vibrant (playful) or muted (professional)?"
+- "Do you have a secondary/accent color for CTAs and emphasis?"
+- "Is brand consistency more important than functional clarity, or equally weighted?"
+
+---
+
+## 2. Typography
+
+Explore font choices, scales, and readability.
+
+### Exploration Questions
+
+- "Are you using a system font (e.g., -apple-system) or custom web fonts?"
+- "Do you have a type scale already — how many sizes? (e.g., 12, 14, 16, 18, 20, 24, 32)"
+- "What's your target reading audience — highly technical, general public, elderly users?"
+- "Do you need to support non-Latin scripts?"
+- "What font stack do you prefer — serif, sans-serif, or is it flexible?"
+
+### Decision Questions
+
+- "How many typefaces? (Most modern designs: 1 for body, 1 for headings, or monospace for code)"
+- "Line height for body text — compact (1.4) or generous (1.6)?"
+- "Font weight usage — do you plan bold, regular, and light variants?"
+
+---
+
+## 3. Voice & Tone
+
+Explore how language reflects brand personality.
+
+### Exploration Questions
+
+- "Is your brand formal, conversational, playful, or something else?"
+- "How do you address users — 'you', your name, or impersonal?"
+- "Are there words/phrases that feel core to your brand?"
+- "Do you use emojis, or is that out of brand?"
+- "Is the product educational (explains features) or assumes user knowledge?"
+
+### Decision Questions
+
+- "For error messages, should you apologize ('Sorry!') or be neutral?"
+- "For empty states, is humor appropriate or distracting?"
+- "How verbose are labels/help text — minimal or descriptive?"
+
+---
+
+## 4. Accessibility
+
+Explore inclusivity and compliance needs.
+
+### Exploration Questions
+
+- "Do you need to meet WCAG 2.1 Level AA, AAA, or no formal requirement?"
+- "Are there users with color blindness, low vision, or screen readers?"
+- "Do you need keyboard navigation only, or mouse/touch?"
+- "What's your minimum font size you're comfortable with?"
+- "Do you animate heavily, and are there users sensitive to motion (vestibular disorders)?"
+
+### Decision Questions
+
+- "Contrast ratio — are you aiming for 4.5:1 (AA) or 7:1 (AAA)?"
+- "Focus indicators — visible outlines or your own custom style?"
+- "For interactive elements, what's the minimum touch target size? (iOS: 44x44, WCAG: 24x24)"
+
+---
+
+## 5. Component Inventory
+
+Explore what UI components you need and their behavior.
+
+### Exploration Questions
+
+- "What components do you already have, or are you starting from scratch?"
+- "Do you use a component library (Material Design, shadcn/ui, Chakra, etc.), or custom?"
+- "Are components documented in Figma, Storybook, or somewhere else?"
+- "What interactions are essential? (dropdowns, modals, tooltips, tabs, forms, etc.)"
+- "Do you need to match a design system someone else is using?"
+
+### Decision Questions
+
+- "How many variations per component? (e.g., button: primary, secondary, danger sizes: sm, md, lg)"
+- "Is consistency more important than flexibility?"
+- "Should components have built-in theming or external theming?"
+
+---
+
+## 6. Responsive Behavior
+
+Explore how the UI adapts across devices.
+
+### Exploration Questions
+
+- "What devices do you support — mobile, tablet, desktop, or all?"
+- "What are your breakpoints? (e.g., mobile: <480px, tablet: 481-1024px, desktop: >1024px)"
+- "On mobile, do you use a hamburger menu or always show navigation?"
+- "Is there a mobile app, or web-only?"
+- "Do you support landscape orientation on mobile, or portrait-only?"
+
+### Decision Questions
+
+- "Is mobile-first (design mobile, enhance desktop) or desktop-first your approach?"
+- "For touch vs. click, do you need different interaction patterns?"
+- "How does form layout change on mobile vs. desktop?"
+
+---
+
+## 7. Interaction Patterns
+
+Explore how users move through the UI and how feedback is provided.
+
+### Exploration Questions
+
+- "Are there standard flows (login, checkout, onboarding) that need special care?"
+- "How do users discover features — obvious UI, help docs, or video?"
+- "Do you use animations to guide attention, or are they minimal?"
+- "How long can a user wait before showing feedback? (instant vs. 100ms vs. 500ms)"
+- "What happens on errors — inline messages, toasts, modal?"
+
+### Decision Questions
+
+- "For loading states, show spinners, skeleton screens, or placeholders?"
+- "Confirmation dialogs on destructive actions — always, or context-dependent?"
+- "How many steps before requiring a 'save' action? (inline autosave or explicit save)"
+
+---
+
+## 8. Visual Hierarchy
+
+Explore how users navigate information density and prioritization.
+
+### Exploration Questions
+
+- "What information is most important on a typical page?"
+- "Do you show everything upfront, or progressive disclosure (reveal on interaction)?"
+- "How much whitespace feels right — minimal density or generous spacing?"
+- "Are there sections or cards that should stand out visually?"
+- "Is information dense (dashboards, data tables) or content-light (marketing sites)?"
+
+### Decision Questions
+
+- "For dense tables/lists, how do you break visual monotony?"
+- "Should less-important info be visible or hidden behind 'more' links?"
+- "Sidebar navigation vs. top navigation — what fits your use case?"
+
+---
+
+## Workflow: Asking UI/Brand Questions
+
+### Step 1: Orient (2-3 min)
+Ask an opening question from **each dimension** that gives you quick context:
+- "What does your brand look like today?" (Color, Voice)
+- "Who are your users?" (Accessibility, Responsive)
+- "What's the main interface — a dashboard, a simple form, a marketplace?" (Component Inventory, Hierarchy)
+
+### Step 2: Deep-Dive (5-10 min)
+For dimensions that revealed ambiguity or strong opinions, ask 1-2 follow-ups:
+- User said "professional" → "WCAG AA or AAA?" + "Serif or sans-serif?"
+- User said "mobile-first" → "Minimum font size?" + "Touch target size?"
+
+### Step 3: Document (1-2 min)
+Summarize decisions into a **UI Contract** (see example below).
+
+---
+
+## Example: UI Contract Output
+
+```markdown
+## UI/Brand Design Contract
+
+### Color Palette
+- **Primary:** #2563EB (trust blue)
+- **Secondary:** #F59E0B (accent gold)
+- **Status:** green=success, red=error, yellow=warning, gray=disabled
+- **Dark mode:** Full support, auto-detect OS preference
+
+### Typography
+- **Font family:** Inter (sans-serif), Fira Code (monospace)
+- **Scale:** 12, 14, 16, 18, 20, 24, 28, 32
+- **Body line-height:** 1.6 (generous for readability)
+
+### Voice & Tone
+- Friendly, not corporate
+- Address users as "you"
+- Explain features clearly for non-technical users
+- Minimal emoji (only for status icons)
+
+### Accessibility
+- WCAG 2.1 Level AA minimum
+- Focus indicators: 2px solid outline in primary color
+- Touch targets: 44x44px minimum (iOS standard)
+- Contrast: 4.5:1 minimum
+
+### Components
+- **Core set:** Button, Input, Select, Modal, Toast, Badge, Card, Stepper
+- **Variants:** Each has primary/secondary/danger + small/medium/large
+
+### Responsive
+- Mobile-first approach
+- Breakpoints: 640px (tablet), 1024px (desktop)
+- Mobile menu: Hamburger (hidden nav)
+
+### Interactions
+- Confirmations on delete/archive actions
+- Loading states: skeleton screens for lists, spinner for single items
+- Error messaging: inline + toast for non-field errors
+- Autosave on form fields (debounced 500ms)
+
+### Visual Hierarchy
+- Progressive disclosure: Show essential info, collapse advanced options
+- Cards for content grouping, generous spacing (24px padding min)
+- Table rows highlight on hover
+- Whitespace: Minimum 16px margins between sections
+```
+
+---
+
+## Red Flags When Asking
+
+| Flag | What It Means | Follow-Up |
+|---|---|---|
+| "I don't know" | Missing brand/design | Offer defaults: "Shall we start with a simple blue/white palette?" |
+| "It depends" | Multiple contexts | "What's the primary use case?" |
+| Contradictions | User unsure | "Earlier you said formal, now conversational. Which feels right?" |
+| All micro-decisions | Overthinking | Simplify: "Choose 1 primary color and 1 accent. We refine later." |
+
+---
+
+## Time Box
+
+A complete UI/Brand discussion should take **15-30 minutes**:
+- **0-5 min:** Quick orientation (1 q per dimension)
+- **5-20 min:** Deep dives on 2-3 dimensions where clarity matters
+- **20-25 min:** Clarifying closes ("Did I get that right?")
+- **25-30 min:** Document and confirm contract

package/rcode/references/universal-anti-patterns.md

@@ -0,0 +1,59 @@
+# Universal Anti-Patterns
+
+Patterns that show up across every rcode project. When a planning workflow surfaces these, halt and discuss before proceeding — they're cheap to fix during planning, expensive to fix after execution.
+
+## Scope anti-patterns
+
+### "While we're at it…"
+Phase plan picks up scope adjacent to the actual goal. Symptom: phase description starts with the real goal but acceptance criteria reference 3 unrelated files. Fix: spin the side-scope into its own phase, even if it's a 1-day phase. Linear roadmaps are easier to verify than tangled ones.
+
+### Implicit prerequisites
+Phase assumes another phase has shipped without declaring the dependency. Symptom: plan refers to a file or table that doesn't exist yet. Fix: surface the dependency in the phase's `Depends on` line in ROADMAP.md.
+
+### Vague acceptance
+Acceptance criterion is "users can do X" with no measurable threshold. Fix: make every acceptance criterion observable from outside the system — a CLI command, an API response, a log line, a UI assertion.
+
+## Estimation anti-patterns
+
+### Round-number capacity
+Sprint commits to "30 points this week" because that's what last week was. No data-backed velocity. Fix: use 80% of the trailing 3-sprint average, never a round number.
+
+### Hidden multitasking
+Phase plan assumes the dev works on it full-time when in reality they're also on-call, in interviews, and at standups. Fix: explicit `effective_dev_hours` field in sprint capacity.
+
+## Decision anti-patterns
+
+### Reversible vs irreversible confusion
+Treating reversible decisions (CSS framework choice) like irreversible ones (database engine), and vice versa. Fix: tag every recorded decision with `reversibility: reversible | one-way | nuanced`.
+
+### Council asked, council ignored
+Council session produces a clear recommendation, the team builds the rejected option anyway. Fix: if you reject a council recommendation, explicitly log the override in `state.decisions[]` with `override_council: <session-id>` so the disagreement is searchable later.
+
+## Implementation anti-patterns
+
+### Defensive code for impossible states
+Adding null checks, fallbacks, and validation for inputs that can never occur in this code path. Fix: trust internal contracts. Validate at system boundaries (user input, network, FS), not internally.
+
+### "Just in case" abstractions
+Building a generic helper because someday three callers might need it, when right now there's one. Fix: three concrete callers first, then extract.
+
+### Comments that explain what
+"// increment counter by 1" — the code says that. Fix: comments only for *why* (hidden constraint, surprising behaviour, workaround for specific bug, invariant that's not obvious from reading).
+
+### Silent failures
+`try { ... } catch { /* ignore */ }`. Fix: every catch block has either a logged warning, a metric increment, or a re-throw. Never bare empty catches.
+
+## Process anti-patterns
+
+### Half-merged migrations
+Old code path and new code path both running in production "for safety". Fix: complete migrations within one phase. Both paths existing forever doubles the maintenance burden.
+
+### Documentation that ages out silently
+README written once, never updated. Code drifts. README lies. Fix: documentation that references specific files / functions includes a sentinel marker; CI fails if the docs reference paths that no longer exist.
+
+### "We'll fix it in v2"
+Known broken behaviour that ships anyway because the deadline. Fix: the phase doesn't ship if known-broken behaviour reaches users. Cut the broken feature, don't ship it broken.
+
+---
+
+When a phase plan or sprint hits any of these patterns during discussion, halt. Surface it explicitly. Adjust before execution starts. The cost compounds.

package/rcode/references/ux-designer-playbook.md

@@ -0,0 +1,74 @@
+# UX Designer Playbook
+
+Loaded by `rcode-ux-designer` via `@-include`. Contains the full thinking
+framework, specialization descriptions, workflow steps, and worked examples.
+
+The agent stub holds the role identity, response format, principles,
+anti-patterns, redirects, and constraints.
+
+---
+
+## How you think
+
+Every UX question has four pressure points:
+1. **What is the user's goal in this moment?** — Not the feature, the goal. User completes checkout, not "user sees payment form"
+2. **What feedback does the user need to feel in control?** — Loading states, progress, errors, success. Silence kills trust.
+3. **What will confuse this user?** — Name one specific misconception and design around it
+4. **How does this serve the 10th-time user, not the first?** — Delight happens through invisible efficiency
+
+---
+
+## Specializations
+
+### Usability Audits
+
+- Audit existing interfaces for clarity, consistency, friction
+- Map user journeys and identify drop-off points
+- Test against accessibility standards (WCAG 2.1 AA minimum)
+- Recommend low-cost, high-impact improvements
+
+### Design System Work
+
+- Define component library philosophy: when to have variants vs. separate components
+- Establish typography, color, spacing scales
+- Document patterns for forms, tables, modals, navigation
+- Ensure consistency across surfaces without becoming rigid
+
+### Accessibility Strategy
+
+- Audit for WCAG violations (color contrast, keyboard navigation, screen reader support)
+- Design for real disability, not sympathy: cognitive load, motor control, sensory limitations
+- Plan gradual remediation: quick wins vs. architectural changes
+- Educate team on accessible design as capability, not compliance checkbox
+
+### Design-Driven Decisions
+
+- Evaluate features through UX lens: launch simpler version first, layer complexity
+- Design for different user segments (power users vs. newcomers)
+- Plan onboarding and progressive disclosure (novice → expert)
+- Define "done" through user success metrics, not design completion
+
+---
+
+## Workflow
+
+1. **Identify the user's goal** — not the feature request. What is the user trying to accomplish?
+2. **Map current friction** — where do users get stuck, abandon, or misunderstand?
+3. **Propose flows** — user journey maps, not wireframes. What sequence of interactions gets the user to their goal?
+4. **Apply four pressure points** — goal clarity, feedback needs, confusing elements, 10th-time efficiency.
+5. **Handle edge cases** — empty states, error states, loading states, rare-but-valid paths.
+6. **Define success metrics** — how will we know the design worked? Conversion, task completion time, error rate.
+7. **Route** — implementation to Haitham, prioritization to Hussain-PM, technical feasibility to Waleed.
+
+---
+
+## Examples
+
+**Happy path** — design lead management flow
+> 🎨 **UX Designer:** Goal: sales rep records a lead during a call, in under 30 seconds. Current friction: 7-field form with required fields. Per 10th-time-user, after 100 leads they know the required fields — but they still tab through all 7. Proposed: 3-field quick-add (name, phone, source) → drawer to fill rest later. Empty state for missing data shows inline edit prompt. Error state gives field-specific guidance, not generic "please fix errors."
+
+**Edge case** — designing for RTL and LTR simultaneously
+> 🎨 **UX Designer:** Navigation flows left-to-right cognitively in LTR but right-to-left in Arabic RTL. "Next step" arrow direction inverts. Breadcrumbs reverse. Checklist item position mirrors. Route to Haitham for logical-properties implementation — these are implementation decisions once the direction hierarchy is defined.
+
+**Negative** — asked to evaluate a feature request for business fit
+> 🎨 **UX Designer:** "Should we build X?" is a strategy question, not a UX question. I evaluate HOW to design X once it's in scope. Route to Sadiq for "should we build it" and Hussain-PM for scope and prioritization: `/rcode-council sadiq hussain-pm — feature fit for [X]`.

package/rcode/references/verb-dictionary.md

@@ -0,0 +1,186 @@
+# Verb Dictionary — multilingual intent matching
+
+**Purpose:** single source of truth for action verbs across all rcode workflows that do intent matching. Without this, each workflow's matcher diverges and Roman Urdu / Hindi / Arabic instructions silently miss.
+
+**How to use from a workflow:** include this file via `@.rcode/references/verb-dictionary.md` and reference categories by name (e.g. *"verbs from §Create"*) instead of restating English-only lists inline.
+
+**Arabic priority:** rcode's primary user base operates in Arabic. Native Arabic script (المشروع, مرحلة, راجع) MUST be in every category — transliteration is a fallback for keyboard input only. When you see a new Arabic phrasing in user input, add the native script first, then the transliteration.
+
+---
+
+## §Create — make / start / new / open
+
+Match if `$QUESTION` contains any of these (case-insensitive):
+
+- **English:** `create`, `make`, `start`, `build`, `set up`, `setup`, `kick off`, `spin up`, `open`, `begin`, `draft`, `generate`, `produce`, `initialize`, `init`, `bootstrap`, `establish`, `form`, `new`
+- **Roman Urdu / Hindi:** `bnao`, `banao`, `bana do`, `bnado`, `banaa`, `banade`, `banayein`, `banadijiye`, `shuru karo`, `shuro karo`, `start karo`, `create karo`, `naya banao`, `nya banao`, `draft karo`, `banalo`, `khol do`, `khol lo`, `kholiye`
+- **Arabic native:** `أنشئ`, `أنشأ`, `ابدأ`, `اعمل`, `افتح`, `كوّن`, `كون`, `أسس`, `اصنع`, `أوجد`, `سوّي`, `سوي`, `جديد`, `جديدة`, `ابني`, `ابن`, `هيّئ`
+- **Arabic transliteration:** `anshi'`, `inshaa'`, `ibda'`, `i3mal`, `iftah`, `kawwen`, `asses`, `isna3`, `awjid`, `sawwi`, `jadid`, `jadida`
+
+## §Add — append / include / attach / extend
+
+- **English:** `add`, `append`, `include`, `attach`, `insert`, `extend`, `expand`, `register`
+- **Roman Urdu / Hindi:** `add karo`, `daal do`, `daalo`, `daal de`, `jor do`, `jor de`, `lagao`, `lagado`, `shamil karo`, `shaamil karo`, `barhao`
+- **Arabic native:** `أضف`, `زِد`, `ضمّ`, `أرفق`, `أدمج`, `ألحق`, `أدخل`, `أضِف`
+- **Arabic transliteration:** `adhif`, `azif`, `zid`, `dhomm`, `arfeq`, `admij`, `alheq`
+
+## §Plan — design / scope / outline
+
+- **English:** `plan`, `design`, `draft`, `scope`, `outline`, `architect`, `lay out`, `schedule`
+- **Roman Urdu / Hindi:** `plan karo`, `design karo`, `sochlo`, `soch lo`, `layout banao`, `tarteeb do`, `tartib karo`
+- **Arabic native:** `خطّط`, `خطط`, `صمّم`, `صمم`, `رتّب`, `رتب`, `نظّم`, `حدّد`, `هيكلة`, `خطة`, `تصميم`
+- **Arabic transliteration:** `khattit`, `tasmim`, `sammim`, `rattib`, `nazzim`, `haddid`, `hayakla`
+
+## §Execute — run / build / ship / implement / do
+
+- **English:** `execute`, `run`, `build`, `ship`, `complete`, `do`, `implement`, `deliver`, `finish`, `wrap up`, `compile`
+- **Roman Urdu / Hindi:** `chalao`, `chala do`, `run karo`, `kar do`, `kardo`, `kar lo`, `karlo`, `implement karo`, `mukammal karo`, `complete karo`, `khatam karo`, `pura karo`
+- **Arabic native:** `نفّذ`, `نفذ`, `أكمل`, `اكمل`, `أنجز`, `شغّل`, `شغل`, `حقّق`, `سلّم`, `بنّ`, `ابنِ`, `أنهِ`, `جهّز`
+- **Arabic transliteration:** `naffidh`, `nafidh`, `aakmel`, `akmil`, `anjiz`, `shaghghil`, `haqqiq`, `sallim`, `jahhiz`
+
+## §Review — audit / check / inspect / verify / validate
+
+- **English:** `review`, `audit`, `check`, `inspect`, `verify`, `validate`, `examine`, `assess`, `evaluate`, `look over`, `go over`, `spot check`
+- **Roman Urdu / Hindi:** `dekho`, `dekh lo`, `dekhlo`, `check karo`, `audit karo`, `verify karo`, `validate karo`, `parkho`, `parakhh`, `mulahiza karo`, `nazar dalo`, `jaiza lo`
+- **Arabic native:** `راجع`, `تحقّق`, `تحقق`, `افحص`, `دقّق`, `دقق`, `تأكّد`, `تأكد`, `فتّش`, `فتش`, `قيّم`, `قيم`, `تفقّد`, `مراجعة`, `فحص`, `تدقيق`
+- **Arabic transliteration:** `raji3`, `tahaqqaq`, `ifhas`, `daqqaq`, `ta'akkad`, `fattish`, `qayyim`, `tafaqqad`
+
+## §Show — list / display / get / fetch / see
+
+- **English:** `show`, `list`, `display`, `get`, `fetch`, `see`, `view`, `print`, `output`, `summarize`
+- **Roman Urdu / Hindi:** `dikhao`, `dikha do`, `dikhado`, `dikha de`, `list karo`, `batao`, `bata do`, `bata de`, `kholo`, `khol do`
+- **Arabic native:** `أظهر`, `أرني`, `اعرض`, `اعرضها`, `شاهد`, `اطبع`, `لخّص`, `لخص`, `بيّن`, `بين`, `قائمة`, `اعرض القائمة`
+- **Arabic transliteration:** `azhir`, `arini`, `i3rid`, `shahid`, `itba3`, `lakhkhis`, `bayyin`, `qa'ima`
+
+## §Remove — delete / drop / undo / revert / kill
+
+- **English:** `remove`, `delete`, `drop`, `undo`, `revert`, `rollback`, `kill`, `purge`, `uninstall`, `clear`, `wipe`, `erase`
+- **Roman Urdu / Hindi:** `hatao`, `hata do`, `hatado`, `mita do`, `mita lo`, `mitao`, `delete karo`, `ulto`, `revert karo`, `nikalo`, `nikal do`, `khaali karo`
+- **Arabic native:** `احذف`, `أزل`, `ألغِ`, `الغ`, `امسح`, `أبطل`, `تراجع`, `أرجع`, `أزِل`, `حذف`
+- **Arabic transliteration:** `ihdhif`, `azil`, `alghi`, `imsah`, `ibtil`, `taraja3`, `arji3`
+
+## §Update — modify / change / edit / refresh / fix
+
+- **English:** `update`, `modify`, `change`, `edit`, `refresh`, `fix`, `patch`, `tweak`, `adjust`, `correct`, `repair`
+- **Roman Urdu / Hindi:** `update karo`, `badlo`, `badal do`, `badal de`, `change karo`, `edit karo`, `theek karo`, `theek kar do`, `thiek karo`, `fix karo`, `behtar karo`, `behter karo`, `improve karo`
+- **Arabic native:** `غيّر`, `غير`, `عدّل`, `عدل`, `أصلح`, `اصلح`, `حدّث`, `حدث`, `رقّع`, `صحّح`, `صحح`, `حسّن`, `حسن`, `تحديث`, `تعديل`
+- **Arabic transliteration:** `ghayyir`, `aslih`, `haddith`, `raqqi3`, `sahheh`, `hassen`, `ta3deel`, `tahdeeth`
+
+## §Pause — stop / wait / hold / cancel
+
+- **English:** `pause`, `stop`, `wait`, `hold`, `cancel`, `abort`, `halt`, `freeze`, `defer`
+- **Roman Urdu / Hindi:** `ruko`, `ruk jao`, `band karo`, `band kardo`, `cancel karo`, `roko`, `rok do`, `rok de`, `pause karo`, `wapas karo`
+- **Arabic native:** `توقّف`, `توقف`, `انتظر`, `أوقف`, `علّق`, `علق`, `إلغاء`, `أجّل`, `أجل`
+- **Arabic transliteration:** `tawaqqaf`, `intazir`, `awqif`, `3alliq`, `ajjil`, `ilgha'`
+
+## §Resume — continue / pick up / restart
+
+- **English:** `resume`, `continue`, `pick up`, `restart`, `re-run`, `replay`, `re-do`, `keep going`, `proceed`
+- **Roman Urdu / Hindi:** `phir se shuru karo`, `aage barho`, `aage chalao`, `continue karo`, `wapas chalao`, `dobara chalao`, `dobara karo`
+- **Arabic native:** `استمرّ`, `استمر`, `أعد`, `تابع`, `أكمل`, `ارجع`, `استأنف`, `كمّل`, `واصل`
+- **Arabic transliteration:** `astamir`, `i'ad`, `tabi3`, `akmil`, `arji3`, `ista'naf`, `kammil`, `wasel`
+
+## §Find — search / locate / discover / hunt
+
+(New category — captures "find edge cases", "find bugs", "look for", which the original dictionary missed.)
+
+- **English:** `find`, `search`, `locate`, `discover`, `hunt`, `surface`, `uncover`, `look for`, `identify`, `detect`
+- **Roman Urdu / Hindi:** `dhoondo`, `dhoondh do`, `talash karo`, `khojo`, `dekho kahan`, `pata karo`, `find karo`, `search karo`
+- **Arabic native:** `ابحث`, `جِد`, `اكتشف`, `استكشف`, `حدّد`, `بيّن`, `اعثر`, `استخرج`, `بحث`
+- **Arabic transliteration:** `ibhath`, `jid`, `iktashif`, `i3thar`, `istakhrij`, `bahath`
+
+## §Quality — bad code / smell / issues / problems
+
+(New category — captures "bad code practices", "code smells", "issues" used in audit-style requests.)
+
+- **English:** `bad code`, `code smell`, `smells`, `issues`, `problems`, `bugs`, `gotchas`, `pitfalls`, `anti-patterns`, `bad practices`, `tech debt`, `quality gaps`, `lint issues`
+- **Roman Urdu / Hindi:** `kharab code`, `bad code`, `mistakes`, `ghaltiyan`, `masail`, `bug bug karo`, `quality check`
+- **Arabic native:** `كود سيّئ`, `كود سيء`, `أخطاء`, `مشاكل`, `عيوب`, `ثغرات`, `جودة الكود`, `أنماط سيّئة`
+- **Arabic transliteration:** `code sayyi'`, `akhta'`, `mashakil`, `3uyub`, `thaghrat`, `jawdat al-code`
+
+---
+
+## Scope nouns (paired with verbs to detect intent)
+
+These are matched alongside §Create / §Add / §Plan verbs to determine the dispatch route.
+
+| Scope noun | Aliases (English + Urdu + Arabic) | Maps to (workflow) |
+|---|---|---|
+| milestone | `milestone`, `milestones`, `release`, `version`, `cycle`, **AR:** `معلم`, `إصدار`, `دورة`, `مرحلة كبرى` | `/rcode-new-milestone` |
+| phase | `phase`, `phases`, **AR:** `مرحلة`, `مراحل`, `طور`, `فاز` | `/rcode-add-phase` |
+| story | `story`, `stories`, `user story`, `kahani`, **AR:** `قصة`, `قصص`, `قصة مستخدم` | `/rcode-create-story` |
+| epic | `epic`, `epics`, `epics and stories`, **AR:** `ملحمة`, `ملاحم`, `فصل`, `فصول` | `/rcode-create-epics-and-stories` |
+| sprint | `sprint`, `iteration`, **AR:** `سباق`, `جولة`, `دورة عمل`, `سبرنت` | `/rcode-sprint-planning` |
+| PRD | `PRD`, `requirements doc`, `product requirements`, **AR:** `وثيقة المتطلبات`, `متطلبات المنتج`, `وثيقة المنتج` | `/rcode-create-prd` |
+| roadmap | `roadmap`, `plan` (top-level), **AR:** `خارطة طريق`, `خريطة الطريق`, `خطة عامة` | `/rcode-create-milestone` |
+| council | `council`, `majlis`, `panel`, `mashwara`, `salah`, **AR:** `مجلس`, `شورى`, `لجنة`, `استشارة` | `/rcode-council` |
+| plan (verb form — "plan phase N") | `plan`, **AR:** `خطّط`, `خطة` | `/rcode-plan` |
+| story (impl) | `dev story`, `implement story`, `build story`, **AR:** `نفذ القصة`, `طبّق القصة` | `/rcode-dev-story` |
+| brainstorm | `brainstorm`, `ideas`, `sochain`, `sochna`, **AR:** `عصف ذهني`, `أفكار`, `تفكير` | `/rcode-brainstorm` |
+| review (code) | `code review`, `karpathy`, `check my diff`, **AR:** `مراجعة الكود`, `راجع الكود`, `فحص الكود` | `/rcode-review [--karpathy]` |
+| edge cases | `edge cases`, `edge case hunt`, `find edge cases`, `corner cases`, **AR:** `حالات استثنائية`, `حالات حدية`, `حالات نادرة` | `/rcode-review-edge-case-hunter` |
+| debug | `debug`, `fix`, `bug`, `error`, `crash`, `kharab`, `theek`, **AR:** `صحّح`, `أصلح`, `خطأ`, `مشكلة`, `عطل` | `/rcode-debug` |
+| audit | `audit`, `quality audit`, `health check`, **AR:** `تدقيق`, `مراجعة شاملة`, `فحص الجودة`, `جودة` | `/rcode-audit` |
+
+---
+
+## Usage examples
+
+**From a workflow (e.g. `do.md`):**
+
+```markdown
+## Step: Match intent
+
+Apply §Create + scope-noun match per @.rcode/references/verb-dictionary.md.
+
+If `$QUESTION` contains any verb from §Create AND any scope noun from the
+table above, dispatch directly to the mapped workflow without an
+ambiguity prompt.
+
+Example: "milestone bnao" → §Create matches "bnao", scope matches
+"milestone" → /rcode-new-milestone (with state-aware redirect to
+/rcode-add-phase if a milestone is already active).
+
+Example: "ابدأ مرحلة جديدة" (Arabic — "start a new phase") → §Create
+matches `ابدأ` + scope `مرحلة` + intensifier `جديدة` → /rcode-add-phase.
+```
+
+**From an agent file (e.g. `rcode-codebase-mapper.md`) when interpreting the orchestrator prompt:**
+
+```markdown
+@.rcode/references/verb-dictionary.md
+
+## Workflow
+
+Recognize §Show / §Review / §Update verbs against the codebase. Honor
+multilingual phrasing — never silently fall through because a Roman
+Urdu, Hindi, or Arabic instruction was the verb form.
+```
+
+**From a SKILL.md `triggers:` array** — DO NOT restate the dictionary inline. Instead, copy the most-likely surface phrases per language so Claude Code's literal trigger matcher fires:
+
+```yaml
+triggers:
+  # English
+  - "review the code"
+  - "code review"
+  - "check the diff"
+  - "find bad practices"
+  # Roman Urdu / Hindi
+  - "code check karo"
+  - "review karo"
+  # Arabic native
+  - "راجع الكود"
+  - "مراجعة الكود"
+  - "افحص الكود"
+```
+
+5-12 triggers per skill is the spec. Always include English + Roman Urdu + Arabic for skills used in user-facing dispatch (council, do, add-phase, create-*, review-*).
+
+---
+
+## Maintenance
+
+Every entry must be a verb actually observed in user input — not invented. When you discover a new phrasing that broke matching, add it to the relevant category here rather than to the consuming workflow's local list. Single source of truth.
+
+**Arabic verbs:** add native script first (e.g. `أنشئ`), transliteration second (e.g. `anshi'`). Native script is what users actually type; transliteration is a keyboard fallback.

package/rcode/references/verification-patterns-index.md

@@ -0,0 +1,76 @@
+# Verification Patterns — Quick Index
+
+How to verify different types of artifacts are real implementations, not stubs or placeholders.
+
+## Core Principle
+
+**Existence ≠ Implementation**
+
+A file existing does not mean the feature works. Verification must check:
+1. **Exists** - File is present at expected path
+2. **Substantive** - Content is real implementation, not placeholder
+3. **Wired** - Connected to the rest of the system
+4. **Functional** - Actually works when invoked
+
+Levels 1-3 can be checked programmatically. Level 4 often requires human verification.
+
+## Universal Stub Patterns
+
+These patterns indicate placeholder code regardless of file type:
+
+**Comment-based stubs:**
+- Search for: `TODO`, `FIXME`, `XXX`, `HACK`, `PLACEHOLDER`
+- Search for: `implement`, `add later`, `coming soon`, `will be`
+- Search for: `// ...`, `/* ... */`, `# ...`
+
+**Placeholder text in output:**
+- Search for: `placeholder`, `lorem ipsum`, `coming soon`, `under construction`
+- Search for: `sample`, `example`, `test data`, `dummy`
+- Search for: `[...]`, `<...>`, `{...}` (unfilled template brackets)
+
+**Empty or trivial implementations:**
+- Functions that `return null`, `return undefined`, `return {}`, `return []`
+- Search for: `pass`, `...`, `nothing`
+- Log-only functions: `console.log('clicked')` (no actual behavior)
+
+**Hardcoded values where dynamic expected:**
+- Hardcoded string IDs instead of using variables
+- Hardcoded counts/lengths instead of computing
+- Hardcoded prices like `$50.00` instead of from database
+
+## By Artifact Type
+
+### React/Next.js Components
+- Returns actual JSX, not `return null` or placeholder divs
+- Uses props or state (`useState`, `useContext`, `props.field`)
+- Includes meaningful event handlers (not empty callbacks)
+- Imports and uses real data sources (API calls, database)
+
+### API Routes
+- More than 10-15 lines (real logic, not stub)
+- Interacts with data source (Prisma, database, query)
+- Has error handling (`try-catch`, throw)
+- Returns meaningful response, not "not implemented"
+
+### Database Migrations
+- Creates/alters real tables with columns
+- Defines constraints, foreign keys, indexes
+- Has up() and down() functions for reversibility
+- Not just comments or placeholder table names
+
+### Tests
+- Actually inverts assertions (test "should pass" then "should fail")
+- Tests multiple cases (happy path + edge cases)
+- Mocks dependencies properly
+- Checks actual outputs, not just checking function exists
+
+## How to Use
+
+1. **Choose your artifact type** (React component, API route, test, migration, etc.)
+2. **Run checks progressively** — Does it exist → Is it substantive → Is it wired → Does it work
+3. **For failing checks** — Look for stub patterns above to diagnose what's missing
+4. **For functional verification** — Often needs human testing (can't automate "does it look good?")
+
+## Full Details
+
+For complete patterns with grep examples, file-type specifics, and advanced verification strategies, see `/rcode/references/verification-patterns.md` (detailed reference).