<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.

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 RCODE ► {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:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 RCODE ► 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):
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 RCODE ► 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.

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 RCODE ► 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 `RCODE ►` 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>
