@hanzlaa/rcode 2.1.0

package/rihal/references/output-format.md

@@ -0,0 +1,319 @@
+<ui_patterns>
+
+Visual patterns for user-facing Rihal 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 /rihal:do, /rihal:next, /rihal: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: /rihal:{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 rihal-executor...
+
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+
+✓ rihal-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 rihal-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:**
+- `/rihal:alternative-1` — description
+- `/rihal: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%       |
+```
+
+---
+
+## Rihal-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.
+
+---
+
+## 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 rihal's UX
+
+</ui_patterns>

package/rihal/references/output-realism.md

@@ -0,0 +1,52 @@
+# Output Realism — Batch, Confirm, Don't Silently Overrun
+
+Shared contract for all Rihal 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.
+
+## Rihal Agent Specifics
+
+- **rihal-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.
+- **rihal-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.
+- **rihal-roadmapper:** Phase size cap: one phase = one coherent batch that a solo developer + AI can reasonably ship in 1-3 focused sessions.
+- **/rihal:autonomous** and **/rihal: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/rihal/references/project-types.yaml

@@ -0,0 +1,270 @@
+# Project Type Signals & Discovery Framework
+#
+# This file maps project signals (technology mentions, keywords) to project types,
+# defining which sections are required/skipped and what discovery questions drive
+# requirements gathering for each type.
+#
+# Usage in workflows: Load this YAML, detect project type from user input + file scan,
+# then adapt discovery questions and section requirements per type.
+
+api-backend:
+  display_name: "API / Backend Service"
+  signals:
+    - express
+    - fastapi
+    - flask
+    - django
+    - rails
+    - spring boot
+    - nestjs
+    - rest api
+    - graphql
+    - rpc
+    - microservice
+    - serverless
+    - lambda
+    - cloud function
+  required_sections:
+    - endpoints
+    - authentication
+    - authorization
+    - rate-limiting
+    - error-responses
+    - data-models
+    - versioning
+  skip_sections:
+    - ux-flows
+    - accessibility
+    - branding
+    - ui-components
+  discovery_questions:
+    - "What is the expected RPS (requests per second) at peak load?"
+    - "What authentication model? (API keys, OAuth2, JWT, mTLS)"
+    - "Are there SLA requirements (uptime, latency targets)?"
+    - "What is your data retention policy?"
+    - "Do you need idempotency or exactly-once semantics?"
+    - "What deployment environment? (AWS, GCP, self-hosted)"
+
+mobile-app:
+  display_name: "Mobile Application"
+  signals:
+    - ios
+    - android
+    - react native
+    - flutter
+    - swift
+    - kotlin
+    - expo
+    - native mobile
+    - app store
+    - google play
+  required_sections:
+    - offline-support
+    - push-notifications
+    - store-compliance
+    - deep-links
+    - permissions
+    - local-storage
+    - sync-strategy
+  skip_sections:
+    - server-scaling
+    - horizontal-scaling
+  discovery_questions:
+    - "Target platforms? (iOS only, Android only, or both)"
+    - "Minimum OS version you support?"
+    - "Is offline-first mode required?"
+    - "Do you need push notifications?"
+    - "What's your backend API? (REST, GraphQL, WebSocket)"
+    - "Are there App Store / Play Store specific requirements?"
+
+saas-b2b:
+  display_name: "SaaS / B2B Platform"
+  signals:
+    - multi-tenant
+    - subscription
+    - stripe
+    - billing
+    - saas
+    - b2b
+    - team management
+    - roles and permissions
+    - data isolation
+  required_sections:
+    - multi-tenancy
+    - billing
+    - subscription-management
+    - audit-logging
+    - data-isolation
+    - role-based-access
+    - compliance
+    - onboarding
+  skip_sections: []
+  discovery_questions:
+    - "How many customers do you expect in Y1 and Y5?"
+    - "What's your pricing model? (per-seat, per-usage, fixed)"
+    - "Do you need compliance certifications? (SOC2, GDPR, HIPAA)"
+    - "How do you isolate customer data?"
+    - "What's your maximum acceptable data migration time for offboarding?"
+    - "Are there audit or compliance logging requirements?"
+
+cli-tool:
+  display_name: "Command-Line Interface / Tool"
+  signals:
+    - cli
+    - command line
+    - terminal
+    - shell
+    - npm
+    - pip
+    - cargo
+    - go cli
+    - console app
+    - argparse
+    - commander.js
+  required_sections:
+    - commands
+    - help-text
+    - exit-codes
+    - error-messages
+    - config-file
+    - env-vars
+  skip_sections:
+    - ux-flows
+    - responsive-design
+    - browser-compatibility
+  discovery_questions:
+    - "Who is the primary user? (developers, DevOps, end-users)"
+    - "Does it need a config file? Where should it live?"
+    - "What are the main commands and subcommands?"
+    - "Do you need shell completion (bash, zsh, fish)?"
+    - "How will users install it? (npm, pip, binary download)"
+
+web-app:
+  display_name: "Web Application / SPA"
+  signals:
+    - react
+    - vue
+    - angular
+    - next.js
+    - nuxt
+    - svelte
+    - sveltekit
+    - astro
+    - web app
+    - single page app
+    - spa
+    - browser
+    - responsive
+  required_sections:
+    - ui-components
+    - state-management
+    - routing
+    - authentication
+    - performance
+    - accessibility
+    - ux-flows
+  skip_sections:
+    - offline-support
+    - push-notifications
+    - app-store-compliance
+  discovery_questions:
+    - "Who is your primary user? (internal team, paying customers, public)"
+    - "What browsers and versions must you support?"
+    - "What's your target Lighthouse score?"
+    - "Do you need server-side rendering (SSR) or is CSR fine?"
+    - "What is the expected concurrent user count?"
+    - "Are there accessibility requirements? (WCAG 2.1 level AA)"
+
+desktop-app:
+  display_name: "Desktop Application"
+  signals:
+    - electron
+    - tauri
+    - desktop
+    - macos
+    - windows
+    - linux
+    - native app
+    - dmg
+    - exe
+    - .app
+  required_sections:
+    - auto-updates
+    - file-handling
+    - system-integration
+    - permissions
+    - installer
+    - signing-and-notarization
+  skip_sections:
+    - responsive-design
+  discovery_questions:
+    - "Target operating systems? (Windows, macOS, Linux, or all)"
+    - "Do you need auto-updates? (code signing, channels)"
+    - "What file types does your app work with?"
+    - "Do you need system tray integration or file associations?"
+    - "Does the app need to run on startup?"
+
+iot:
+  display_name: "IoT / Embedded Device"
+  signals:
+    - iot
+    - embedded
+    - firmware
+    - microcontroller
+    - arduino
+    - esp32
+    - rust
+    - c
+    - mqtt
+    - zigbee
+    - lorawan
+    - edge computing
+  required_sections:
+    - hardware-specs
+    - power-consumption
+    - communication-protocol
+    - firmware-updates
+    - reliability
+    - monitoring
+  skip_sections:
+    - responsive-design
+    - accessibility
+  discovery_questions:
+    - "What hardware platform? (specific board, custom design)"
+    - "Power consumption targets? (battery life, continuous power)"
+    - "Communication protocol? (WiFi, cellular, MQTT, Bluetooth)"
+    - "How often do devices need firmware updates?"
+    - "What's the deployment scale? (10s, 1000s, millions of devices)"
+    - "Do you need edge processing or cloud-based analytics?"
+
+dev-tool:
+  display_name: "Developer Tool / IDE Extension / Library"
+  signals:
+    - library
+    - sdk
+    - npm package
+    - framework
+    - plugin
+    - extension
+    - vscode extension
+    - ide plugin
+    - compiler
+    - linter
+    - formatter
+  required_sections:
+    - api-documentation
+    - usage-examples
+    - error-messages
+    - performance-benchmarks
+    - compatibility-matrix
+    - migration-guide
+  skip_sections:
+    - ux-flows
+    - branding
+  discovery_questions:
+    - "What developers use this? (experience level, pain point)"
+    - "Is this a library, framework, tool, or extension?"
+    - "What's your versioning strategy? (semver, rolling release)"
+    - "What are the minimum dependency versions?"
+    - "How will developers discover and install this?"
+    - "Do you need a community or plugin ecosystem?"