@hanzlaa/rcode 3.6.15 → 4.0.0

package/rcode/references/output-format.md

@@ -0,0 +1,398 @@
+<ui_patterns>
+
+## Workflow Step Heading (canonical format)
+
+All workflows MUST use `## Step N — {Name}` for top-level steps. No other format.
+
+```
+## Step 1 — Parse arguments
+## Step 2 — Load state
+## Step 3 — Spawn agents
+```
+
+**Deprecated forms (do not use in new or updated workflows):**
+- `<step name="...">` — XML-tag format (legacy, still accepted by agents but not for new workflows)
+- `### Step N` — wrong heading level
+- `**Step N:**` — bold-text format
+
+When refactoring a workflow, convert its steps to `## Step N — {Name}` incrementally. Do not leave a mix of formats within the same workflow.
+
+---
+
+## Subagent Output Format Contract
+
+When spawning a subagent with `Task()`, the spawning prompt MUST include a brief expected output section so the sub-agent produces machine-parseable results. Minimal template:
+
+```
+## Expected output format
+{One of: JSON object / Markdown report / Plain text / VERIFICATION.md schema}
+Return exactly this format — no extra commentary before or after.
+```
+
+Workflows that omit this cause silent format mismatches where the orchestrator cannot parse the sub-agent's response.
+
+---
+
+
+Visual patterns for user-facing rcode output. Orchestrators @-reference this file.
+
+## Stage Banners
+
+Use for major workflow transitions.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► {STAGE NAME}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Stage names (uppercase):**
+- `ROUTING`
+- `QUESTIONING`
+- `RESEARCHING`
+- `PLANNING SPRINT {NN.S}`
+- `EXECUTING WAVE {N}`
+- `VERIFYING SPRINT {NN.S}`
+- `SPRINT {NN.S} COMPLETE ✓`
+- `PHASE {NN} COMPLETE ✓`
+- `MILESTONE COMPLETE 🎉`
+- `COUNCIL CONVENING`
+- `MAJLIS CONVENING`
+- `BROWNFIELD DETECTED`
+- `ERROR`
+
+---
+
+## Routing Output (for /rcode-do, /rcode-next, /rcode-progress)
+
+Use this when a router command dispatches to another command:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► ROUTING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Input: {user's question or intent}
+Scope: {one-line summary of detected scope}
+{optional: Blocker: {any blockers detected}}
+
+Routing to: /rcode-{target-command}
+Reason: {one-line why this command fits}
+
+Handing off to the workflow now.
+```
+
+---
+
+## Checkpoint Boxes
+
+User action required. 62-character width.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Content}
+
+──────────────────────────────────────────────────────────────
+→ {ACTION PROMPT}
+──────────────────────────────────────────────────────────────
+```
+
+**Types:**
+- `CHECKPOINT: Verification Required` → `→ Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` → `→ Select: option-a / option-b`
+- `CHECKPOINT: Action Required` → `→ Type "done" when complete`
+
+---
+
+## Status Symbols
+
+```
+✓  Complete / Passed / Verified
+✗  Failed / Missing / Blocked
+◆  In Progress
+○  Pending / Planned
+⚡ Auto-approved
+⚠  Warning
+🎉 Milestone complete (only in banner)
+▶  Next up / active selection
+```
+
+---
+
+## Progress Display
+
+**Phase/milestone level:**
+```
+Progress: ████████░░ 80%
+```
+
+**Story level:**
+```
+Stories: 2/4 done
+```
+
+**Sprint level:**
+```
+Sprint 01.1: 8/13 points ████████░░░░░ 61%
+```
+
+**Velocity:**
+```
+Velocity: avg 11 pts (last 3 sprints)
+```
+
+---
+
+## Spawning Indicators
+
+```
+◆ Spawning rcode-executor...
+
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+
+✓ rcode-executor complete: SUMMARY.md written
+```
+
+---
+
+## TODO Lists (MANDATORY for multi-step workflows)
+
+Any workflow with 3+ discrete steps MUST use `TaskCreate` to show a visible
+todo list, and `TaskUpdate` as each completes. This gives users live
+visibility into progress.
+
+**Pattern at workflow start:**
+
+```
+TaskCreate: "Collect workflow config"
+TaskCreate: "Write PROJECT.md"
+TaskCreate: "Run domain research (4 parallel agents)"
+TaskCreate: "Define REQUIREMENTS.md"
+TaskCreate: "Build ROADMAP.md"
+TaskCreate: "Finalize state + commit"
+```
+
+**As each completes, update status:**
+
+```
+TaskUpdate(taskId: <N>, status: "completed")
+```
+
+**Display pattern:**
+
+```
+✔ Map codebase: spawn 4 parallel mappers
+✔ Collect workflow config (mode, granularity, git, agents)
+◼ Write and commit PROJECT.md           ← currently in_progress
+◻ Run domain research (4 parallel agents + synthesizer)
+◻ Define REQUIREMENTS.md
+◻ Spawn rcode-roadmapper to build ROADMAP.md
+◻ Finalize: STATE.md, CLAUDE.md refresh, commit
+```
+
+**Status symbols in TODO lists:**
+- `✔` completed
+- `◼` in_progress (exactly one active)
+- `◻` pending
+- `✗` failed / blocked
+
+**Rule:** Never leave all tasks in `pending` after starting. Always mark
+one `in_progress` before beginning work on it, and `completed` immediately
+after finishing (not batched at the end).
+
+---
+
+## Insight Block (pre-execution observations)
+
+When a workflow inspects state/plans/scope before acting, emit a compact
+insight block with 2-3 load-bearing observations. Format exactly:
+
+```
+★ Insight ─────────────────────────────────────
+  - {observation 1: specific scope reality with files/IDs}
+  - {observation 2: overlap / forced sequential / blocker}
+  - {observation 3: checkpoint or human-in-loop flag}
+─────────────────────────────────────────────────
+```
+
+Rules:
+- Exactly 2-3 bullets (never 1, never 4+)
+- Name specific file paths, plan IDs, agent names
+- No generic advice ("consider testing", "might be slow")
+- No restating what user already asked for
+
+Use before Execution Plan tables and Three-Options blocks.
+
+---
+
+## Execution Plan Table (before multi-step work)
+
+Render waves × plans with autonomy flags:
+
+```
+Execution Plan
+
+Phase {NN}: {name} — {N} plans across {M} waves.
+
+┌──────┬───────┬───────────────┬──────────────────────────────────────┐
+│ Wave │ Plan  │   Autonomy    │           What it builds             │
+├──────┼───────┼───────────────┼──────────────────────────────────────┤
+│ 1    │ NN-01 │ 🛑 checkpoint │ {one-line outcome}                   │
+│ 1    │ NN-02 │ auto          │ {one-line outcome}                   │
+│ 2    │ NN-03 │ auto          │ {one-line outcome}                   │
+└──────┴───────┴───────────────┴──────────────────────────────────────┘
+```
+
+Below table: one-line reality check about scope size, then one-line flag
+for any wave forced to sequential and why (file overlaps, auth gates).
+
+---
+
+## Three-Options Block (before long-running execution)
+
+Offer autonomy tradeoffs via AskUserQuestion:
+
+- **A) Autonomous** — subagent per plan, fastest, highest token cost, least visibility
+- **B) Interactive** (`--interactive`) — inline execution, pair-programming, lower cost, catches mistakes early
+- **C) Wave-only** (`--wave N`) — staged, review between waves, lowest risk
+
+Always end with a recommendation line: `My recommendation: {letter} because {one-clause reason}.`
+
+Never silently pick for the user on large scope.
+
+---
+
+## Next Up Block
+
+Always at end of major completions.
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{Identifier}: {Name}** — {one-line description}
+
+`/clear` then:
+
+`{copy-paste command}`
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/rcode-alternative-1` — description
+- `/rcode-alternative-2` — description
+
+───────────────────────────────────────────────────────────────
+```
+
+---
+
+## Error Box
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## Tables
+
+Use standard markdown pipe tables with status symbols:
+
+```
+| Phase | Status | Sprints | Progress |
+|-------|--------|---------|----------|
+| 01    | ✓      | 2/2     | 100%     |
+| 02    | ◆      | 1/3     | 33%      |
+| 03    | ○      | 0/2     | 0%       |
+```
+
+---
+
+## rcode-Specific Elements
+
+**Majlis banner** (multi-agent council):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► MAJLIS CONVENING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Agent header** (when an agent responds in council/discuss):
+```
+🧭 **Sadiq (صادق) — Director of Strategy:**
+```
+
+Use agent emoji + bilingual name prefix once per turn. No repeat in same response.
+
+---
+
+## RTL / Arabic Output Safety
+
+When `response_language` is Arabic or another RTL language, bidi-unaware terminals
+corrupt fixed-width ASCII art (banners, progress bars) when Arabic text is embedded
+inside them. Follow these rules to avoid visual corruption:
+
+**Banner stage names:** Always keep stage names in **English** even when
+`response_language` is Arabic. The `━━━` border lines are width-sensitive; mixed
+RTL characters inside them break alignment. Place the Arabic description **below**
+the banner, not inside it.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► PLANNING SPRINT 01.1
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+التخطيط للسباق 01.1 — يرجى الانتظار
+```
+
+**Progress bars:** Keep the bar characters (`█░`) and percentages on their own line.
+Put the Arabic label on a separate preceding line:
+
+```
+التقدم:
+████████░░ 80%
+```
+
+Do **not** embed Arabic text inside the bar line — it reverses the order of `%` and digits in bidi terminals.
+
+**Checkpoint boxes:** The `╔ ═ ╚` box characters are LTR-anchored. Place Arabic
+content in the body paragraph below the box, not as the box heading:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: Verification Required                           ║
+╚══════════════════════════════════════════════════════════════╝
+
+هل تمت المراجعة؟ اكتب "approved" للمتابعة.
+```
+
+**General rule:** ASCII-art structure (borders, bars, arrows) stays in LTR. All
+translated prose goes outside the art, on its own line(s).
+
+---
+
+## Anti-Patterns
+
+- Varying box/banner widths within same output
+- Mixing banner styles (`===`, `---`, `***`)
+- Skipping `RIHAL ►` prefix in stage banners
+- Random emoji (`🚀`, `✨`, `💫`) outside the approved set
+- Missing Next Up block after workflow completions
+- Hardcoding references to other methodologies in rcode's UX
+- Embedding Arabic/RTL text inside fixed-width ASCII banners or progress bars
+
+</ui_patterns>

package/rcode/references/output-realism.md

@@ -0,0 +1,52 @@
+# Output Realism — Batch, Confirm, Don't Silently Overrun
+
+Shared contract for all rcode agents and workflows that take user requests. Enforces honest pushback when scope can't fit one response, instead of producing thin or truncated output.
+
+## The Rule
+
+**A single agent response has finite output capacity.** Approximate working budget: **32,000 output tokens** (~12,000 words of prose, or ~1,500 lines of code). Large-context models extend *input*, not *output*.
+
+Before committing to execute a request, estimate output size. If the work exceeds one response's budget, **STOP and propose a batch plan**. Do not start executing and stop mid-way — the user gets unfinished work and a confused transcript.
+
+## When to Invoke
+
+Any time a request implies output volume like:
+
+- "Write N blog posts / pages / stories" where N × 1000 words > 10,000 words
+- "Implement all of these features in one go" spanning > 10 files or > 1500 lines
+- "Complete everything in this roadmap/backlog" without a scoped phase
+- "Don't stop until done" paired with ambitious open-ended scope
+- Generating long documentation sets (API docs, migration guides, full READMEs for multiple modules)
+- Any refactor touching > 20 files
+
+## The Response Pattern
+
+When the budget analysis says the request can't complete in one response, reply with **four blocks**:
+
+1. **Honest scope audit** — one-sentence summary of what the user actually asked for, then the realistic size (word/line/file count).
+2. **Why one response won't fit** — specific bound (output tokens, file count, context window pressure on coherence). Name the constraint.
+3. **Proposed batches** — 2-5 batches with clear names, contents, and acceptance. Highest-ROI batch first.
+4. **Explicit ask** — "Batch 1 start karun?" / "Shall I start with Batch 1?" — wait for confirmation before any edits/writes.
+
+Keep the whole response under ~300 words. Tone: colleague-honest, not apologetic.
+
+## Anti-Patterns — Do Not
+
+- **Silent truncation.** Writing 3 of 12 items without telling the user.
+- **Thin content to fit.** Generating 12 × 300-word blog posts when 12 × 1000 was asked — Google penalizes thin/duplicate content.
+- **"Let me try anyway."** Trying to cram → runs out mid-stream → user loses trust + has to re-prompt.
+- **Refusing without a plan.** "Too big" alone isn't useful. Always propose batches.
+- **Asking after starting.** Batch audit happens *before* the first edit/write, not after.
+
+## rcode Agent Specifics
+
+- **rcode-planner:** If `## Scope` from orchestrator implies > 8 tasks of real work, return a PLANS.md with *multiple* SPRINT.md files (waves) instead of one overloaded plan.
+- **rcode-executor:** If a SPRINT.md would require > 1500 lines of new/changed code to execute, stop at Step 2 (load plan) and return a "plan too large — suggest wave split" checkpoint instead of executing.
+- **rcode-roadmapper:** Phase size cap: one phase = one coherent batch that a solo developer + AI can reasonably ship in 1-3 focused sessions.
+- **/rcode-autonomous** and **/rcode-do --auto:** Even in auto mode, pause at the first batch boundary that exceeds output budget. "Don't stop until done" authorizes local commits, not output-budget violations.
+
+## The Core Philosophy
+
+> Quality > quantity. Confirming a batch plan takes 10 seconds. Recovering from a half-truncated response wastes both sides' time and erodes trust.
+
+Honest pushback is a feature, not a bug.

package/rcode/references/persona-engineer-shared.md

@@ -0,0 +1,61 @@
+# Engineer Persona Shared Rules
+
+Loaded by `rcode-haitham`, `rcode-omar`, and `rcode-yousef` via `@-include`.
+Contains the shared communication discipline, heuristic protocol, and
+operational constraints that all three engineer personas inherit.
+
+Persona-specific content (identity, capabilities, named heuristics,
+examples, redirects) lives in each agent's own file.
+
+---
+
+## Communication Discipline
+
+- Response prefix with persona glyph. No emojis beyond the persona glyph (each stub defines its own glyph).
+- **STRICTLY FORBIDDEN from starting with "Great", "Certainly", "Okay", "Sure"** — direct, never conversational.
+- Never end with "Let me know if you have questions".
+- Never opens with generic context-setting ("In React, you typically…", "Generally speaking…"). Opens with what the actual code does.
+
+---
+
+## Named-Heuristic Protocol
+
+Every engineer persona operates five named heuristics. The specific heuristics differ per persona — the protocol for applying them is shared:
+
+- When refusing or recommending, cite the heuristic **by name** (e.g., "Per [heuristic name], …").
+- "Cite by name" is mandatory, not stylistic.
+- Never refuse or recommend without connecting the decision back to a named rule.
+- When asked to explain a decision, name the heuristic first, then the reasoning.
+
+---
+
+## Anti-Pattern Enforcement Protocol
+
+Every engineer persona maintains an Anti-Patterns / Refuse List. The shared meta-instruction for applying it:
+
+- **State the rule by name when refusing.** Never refuse with vague language ("I wouldn't do that") — name the specific anti-pattern rule from the list.
+- The anti-pattern list is a first-class part of the persona, not an afterthought.
+- Refusing is not optional when the request violates a named rule.
+
+---
+
+## Engineer Workflow Invariants
+
+These steps appear in every engineer persona's workflow and are non-negotiable:
+
+1. **Read the actual code before any proposal.** No speculation about patterns the codebase doesn't use. Use the `Read` tool.
+2. **Grep/find existing patterns before inventing new ones.** Match the house pattern — don't introduce a new one when an established one exists.
+3. **Cite the framework heuristic by name** when refusing or recommending.
+
+---
+
+## Shared Operational Constraints
+
+Constraints that are identical across all three engineer personas:
+
+- MUST `Read` (or `Read`/`Grep`/`Bash`) before proposing any change to the codebase.
+- File:line citations for every specific claim about code.
+- Cite the framework heuristic by name when refusing or recommending.
+- **STRICTLY FORBIDDEN from starting with "Great", "Certainly", "Okay", "Sure"**.
+- Never end with "Let me know if you have questions".
+- Never make architecture-level or product decisions — those belong to other lanes (Waleed, Layla, Hussain-PM, Sadiq, etc.).

package/rcode/references/phase-argument-parsing.md

@@ -0,0 +1,35 @@
+# Phase Argument Parsing
+
+Workflows that take a phase argument (`/rcode-plan 04`, `/rcode-execute-phase 999.5`, `/rcode-research-phase 12`) all use the same parsing rules.
+
+## Accepted forms
+
+| Input | Resolves to | Notes |
+|-------|-------------|-------|
+| `04` | Phase 04 | Zero-padded NN |
+| `4` | Phase 04 | Auto-pads |
+| `999.5` | Decimal parking-lot phase 999.5 | See `docs/parking-lot-convention.md` |
+| `04.1` | Sub-phase 04.1 | Inserted-phase / urgent work |
+| `current` | The phase currently in `state.current_phase` | Useful when looping |
+| `next` | The next planned phase after current | Looks at ROADMAP.md ordering |
+| (empty) | Same as `current` if state has one; else error | Most workflows refuse empty |
+
+## Resolution
+
+1. Strip whitespace.
+2. Match against the patterns above (regex per row).
+3. Look up the resolved number in `state.phases[]`.
+4. If not found, fall back to looking on disk under `.planning/phases/<NN>-*/`.
+5. If neither, exit non-zero with: `Phase X not found. Run /rcode-status to list known phases.`
+
+## Strict vs lenient
+
+Workflows pass `--strict` if a missing phase should hard-fail rather than offering to create. By default, planning workflows ask "Phase X doesn't exist — create it now?" before erroring. Execution workflows hard-fail because executing a phase that doesn't exist is always a bug.
+
+## Error messages
+
+Always include the resolved (or attempted-resolve) value in the error. Never just say "phase not found" — say "Phase 12 not found in state.json (3 phases registered: 04, 05, 999.5)".
+
+## Multi-phase invocations
+
+Some workflows accept `04..06` to operate on a range, or `04 05 06` as space-separated. Each gets parsed by the rules above; the workflow operates on the resolved set in roadmap order.

package/rcode/references/phase-id-conventions.md

@@ -0,0 +1,101 @@
+# Phase ID Conventions
+
+The canonical rule for naming a phase in rcode. Issue #718.
+
+---
+
+## TL;DR
+
+| Shape | Example | Use case |
+|-------|---------|----------|
+| `<int>` | `19`, `22`, `103` | Top-level phase added at the end of the current milestone |
+| `<int>.<int>` | `19.1`, `19.2`, `22.3` | Sub-phase inserted under an existing parent |
+| anything else | `A1`, `B5`, `phase-x`, `06` | **REJECTED** |
+
+Validate any ID with:
+
+```bash
+node .rcode/bin/rcode-tools.cjs validate-phase-id <id>
+```
+
+Scan an entire ROADMAP at once:
+
+```bash
+node .rcode/bin/rcode-tools.cjs validate-roadmap
+```
+
+---
+
+## Why these are the only two shapes
+
+**Integer phases (`19`, `22`)** are the natural unit of milestone progress.
+They're added to the end of the roadmap by `/rcode-add-phase` and the
+`phase add` CLI calculates the next number automatically. This is the
+default — 99% of phases should be integers.
+
+**Decimal sub-phases (`19.1`, `19.2`)** exist for one purpose: inserting
+focused work under an already-defined parent without renumbering everything
+after it. Use `/rcode-phase insert 19.1` (the `phase` subcommand) — the
+parent phase stays `19`, the sub-phase fits between `19` and `20` without
+shifting `20→21→22…`.
+
+**Anything else is freestyling.** Audit-style outputs that produce `A1`,
+`B5`, "Audit Phase 1", or domain-prefixed names (`auth-1`, `sec-2`) break:
+
+- ROADMAP.md parsing — the `## Phase <id>` regex assumes a number
+- State.json schema — `phases[].id` is typed as a number-or-decimal string
+- Dashboard rendering — sorts phases by numeric value
+- Cross-phase references in SUMMARY.md, PLAN.md, etc.
+
+If you find yourself wanting `A1` or `B1`, you actually want **two
+milestones**: one for audit, one for implementation. Run
+`/rcode-complete-milestone` on the audit milestone before the
+implementation work starts.
+
+---
+
+## Leading zeros: never
+
+Per feedback memory: `19`, not `019`. `6`, not `06`. The validator
+rejects leading-zero forms explicitly because they cause downstream
+sorting bugs and inconsistent file naming (`.planning/phases/06-foo`
+vs `.planning/phases/6-foo`).
+
+---
+
+## Where the validator fires
+
+- **`/rcode-add-phase`** — runs `milestone-health` after adding, nudges
+  toward `/rcode-complete-milestone` when ≥8 phases are open.
+- **`/rcode-status`** — surfaces milestone-health gauge when not `healthy`.
+- **CI** (`test/scope-history-parity.test.cjs` style) — a future test
+  can call `validate-roadmap` against the committed ROADMAP.md.
+
+Workflows that produce phase IDs from AI freestyle (`/rcode-plan`,
+`/rcode-audit-milestone`) MUST call `validate-phase-id` before writing
+to disk. If they don't, file an issue.
+
+---
+
+## Milestone health thresholds
+
+| Open phases | Recommendation | Behavior |
+|-------------|----------------|----------|
+| 0–7 | `healthy` | Quiet — no nudge |
+| 8–11 | `consider-closing` | Soft nudge after `/rcode-add-phase` |
+| ≥12 | `should-close` | Hard nudge with both close + fork commands |
+
+Bump thresholds in a future PR if real-world data shows users want bigger
+milestones. Current numbers are conservative on purpose — long milestones
+without closure are the original symptom.
+
+---
+
+## Related
+
+- `rcode/workflows/add-phase.md` — milestone-health check after adding
+- `rcode/workflows/status.md` — milestone-health gauge in status output
+- `rcode/workflows/complete-milestone.md` — the closure workflow
+- `rcode/bin/rcode-tools.cjs` — `validate-phase-id`, `validate-roadmap`,
+  `milestone-health` subcommands
+- Issue #718 (this file's origin)