@hanzlaa/rcode 2.1.0

package/rihal/references/context-budget.md

@@ -0,0 +1,104 @@
+# Context Budget Reference
+
+Defines 4 degradation tiers for token usage and how workflows should adapt behavior based on remaining context.
+
+## Configuration
+
+Add to `config.yaml`:
+
+```yaml
+context_window_tokens: 200000  # default; adjust per model profile
+```
+
+Estimation rule: **1 token ≈ 4 characters**. Use this to predict token cost of reads.
+
+## Degradation Tiers
+
+### PEAK (0–30% used)
+**Tokens remaining: >140,000**
+
+- ✅ Full context available — deep reads encouraged
+- ✅ Subagent dispatch OK (Explore, Research, etc.)
+- ✅ Read entire files without hesitation
+- ✅ Batch parallel reads (5+ files simultaneously)
+- ✅ Fetch documentation and external context freely
+
+**Behavior:** Aggressive exploration, thorough analysis.
+
+---
+
+### GOOD (30–60% used)
+**Tokens remaining: 80,000–140,000**
+
+- ✅ Full context still available
+- ⚠️ Prefer Grep/Glob over Read for files >500 lines
+- ⚠️ Read only necessary sections, use `limit` + `offset` parameters
+- ✅ Batch parallel reads OK, but max 3–4 simultaneously
+- ⚠️ Defer non-essential documentation fetches
+
+**Behavior:** Balanced — read strategically, ask for sections not summaries.
+
+---
+
+### DEGRADING (60–80% used)
+**Tokens remaining: 40,000–80,000**
+
+- ⚠️ Read only frontmatter (first 50–100 lines) for files >500 lines
+- ⚠️ Defer non-critical reads; consolidate questions
+- ⚠️ No subagent dispatch — complete locally
+- ⚠️ Warn user: **"Context at {percent}% usage. Work may slow."**
+- ✅ Continue essential tasks
+
+**Behavior:** Careful — read only what blocks progress.
+
+---
+
+### POOR (80%+ used)
+**Tokens remaining: <40,000**
+
+- 🚨 **Emergency mode**
+- 🛑 Read ONLY what's strictly required to unblock next action
+- 🛑 No exploratory reads, no documentation
+- 🛑 Suggest `/rihal:pause-work` if task requires more context
+- 🛑 Warn user: **"Context critical ({percent}%). Resume work to continue."**
+
+**Behavior:** Survival — preserve tokens for final output only.
+
+---
+
+## How Workflows Check Budget
+
+Place this check at the start of a heavy read phase:
+
+```python
+def check_budget(current_tokens, config):
+    budget = config.get('context_window_tokens', 200000)
+    used_pct = (current_tokens / budget) * 100
+    
+    if used_pct >= 80:
+        return 'POOR', "Context critical. Suggest /rihal:pause-work"
+    elif used_pct >= 60:
+        return 'DEGRADING', "Context at {used_pct}%. Read frontmatter only."
+    elif used_pct >= 30:
+        return 'GOOD', "Balanced. Prefer Grep for large files."
+    else:
+        return 'PEAK', "Full context. Aggressive exploration OK."
+
+# Usage in workflow:
+tier, msg = check_budget(tokens_used, config)
+if tier == 'POOR':
+    return escalate_to_user(msg)
+```
+
+---
+
+## Token Estimation Rules
+
+- **Small file (<100 lines):** ~2,000 tokens
+- **Medium file (100–500 lines):** ~10,000 tokens
+- **Large file (500–2000 lines):** ~30,000 tokens
+- **Grep result (50 matches):** ~3,000 tokens
+- **Bash output (typical):** ~1,000 tokens
+- **Conversation history (N turns):** ~500 tokens per turn
+
+When close to limits, ask: *"Would reading this file block progress?"* If no, defer.

package/rihal/references/continuation-format.md

@@ -0,0 +1,249 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, SPRINT.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/rihal:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/rihal:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/rihal:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/rihal:plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/rihal:discuss-phase 2` — gather context first
+- `/rihal:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/rihal:plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/rihal:discuss-phase 3` — gather context first
+- `/rihal:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/rihal:plan-phase 3`
+
+**To discuss context first:** `/rihal:discuss-phase 3`
+
+**To research unknowns:** `/rihal:research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/rihal:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from SPRINT.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/rihal:execute-phase 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/rihal:plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/rihal:plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/rihal/references/council-protocol.md

@@ -0,0 +1,91 @@
+# Rihal Council Protocol
+
+Shared reference document `@`-included by every council-related workflow.
+
+## The 5-step majlis
+
+Every Rihal council session follows the same five steps. This is the protocol the orchestrator implements:
+
+1. **Initialize** — load config, state, installed agent list, parse arguments.
+2. **Observe** — run a cheap, bounded codebase scan (config, state, git log, top-level files). Produces a 5-8 line factual summary every subagent will be briefed on.
+3. **Select** — pick 3-5 agents via deterministic keyword scoring. User can override with `--agents=` or force all with `--full`.
+4. **Consult** — spawn selected agents in parallel via the Task tool. Each agent gets the same observed-context brief and the user's question. Cross-talk rounds include previous panelists' responses.
+5. **Record** — save the session artifact under `.planning/council-sessions/council-{date}-{slug}.md`.
+
+Never collapse steps. Never skip the observe step — a council that answers from vibes is worse than no council.
+
+## Cross-talk convention
+
+When agents speak in a council, they can and should reference each other by name when they build on or disagree with a point. The orchestrator passes previous-agent responses as context to later panelists.
+
+Good cross-talk:
+
+> 🛡️ **Fatima:** Waleed's migration plan is solid on the forward path, but he's
+> skipping the rollback test. If the backfill fails at row 2M of 5M, how do
+> we recover? Not covered in the plan.
+
+Bad cross-talk:
+
+> 🛡️ **Fatima:** I agree with Waleed.
+
+Agreements without new information are silence. If an agent genuinely has nothing to add, they should say so in one sentence rather than pad.
+
+## Panel selection (deterministic scoring)
+
+Rihal's council uses a pure-function keyword scorer (`cli/lib/council-panel.cjs`) instead of LLM judgment. This is intentional:
+
+- **Deterministic:** same question produces same panel every time
+- **Testable:** the scoring function has unit tests
+- **Auditable:** users can pass `--explain` to see why each agent was picked or skipped
+- **Cheap:** zero LLM calls before the council starts
+
+The scoring table is versioned with the package. Users who want different weights edit the source and rebuild — there is no runtime config knob for this, and that's by design. The panel selection must be reproducible across machines.
+
+**Padding rules:**
+
+- Strategic questions (containing "should i", "worth", "kill", "pivot", "start new") always include Sadiq even if topic keywords score low.
+- Scope/feature questions (containing "scope", "feature", "roadmap", "prd") always include Hussain-PM.
+- If fewer than the minimum panel size (default 3) score non-zero, the panel is padded with the STRATEGIC_PADDING_ORDER list: sadiq, hussain-pm, waleed, fatima, nasser.
+
+**v2 prototype note:** only Sadiq, Waleed, and Fatima are installed as first-class subagents. The scorer may select agent ids that don't yet have subagent files — the orchestrator must filter to installed agents and fall back to the 3-agent panel.
+
+## Response presentation
+
+Subagent responses are presented **verbatim and in panel order**. The orchestrator never summarizes, paraphrases, or condenses agent output. The user came to the council to hear the agents speak in their own voices — summary defeats the point.
+
+After all verbatim responses, the orchestrator may add a single **Orchestrator Note** (max 3 sentences) that flags a disagreement worth following up on or recommends a second round. The Orchestrator Note is clearly labeled so it's not confused with agent speech.
+
+## Session artifact format
+
+Every council session is saved to `.planning/council-sessions/council-{YYYY-MM-DD}-{slug}.md`. The slug is lowercase-hyphenated from the first 6 words of the question. Format:
+
+```markdown
+# Council Session — {short summary}
+
+**Date:** {ISO date}
+**Panel:** {names}
+**Mode:** {guided|yolo}
+**Project:** {project name from .rihal/config.yaml}
+
+## Question
+{original question}
+
+## Observed Context
+{the Step 2 summary block}
+
+## Panel Responses
+### 🧭 Sadiq
+{verbatim}
+### 🏗️ Waleed
+{verbatim}
+### 🛡️ Fatima
+{verbatim}
+
+## Orchestrator Note
+{if any}
+
+## Follow-ups
+- [ ] {action items}
+```
+
+The artifact is a first-class project document. It's committed to git, reviewed in retros, and referenced when the same question comes up again. The Follow-ups section is the bridge between council and execution.

package/rihal/references/domain-probes.md

@@ -0,0 +1,213 @@
+# Domain Probes
+
+When exploring an unfamiliar domain, ask structured questions to rapidly build a mental model. These probes are organized by category: **technical**, **product**, and **execution**. Use selectively — don't ask all 50 questions. Instead, identify which categories are most relevant to the current decision and ask 2-4 probes per category.
+
+---
+
+## Technical Probes
+
+Ask these when exploring a tech stack, architecture, or infrastructure question.
+
+### Stack & Constraints
+
+- "What languages/frameworks does your codebase use?"
+- "Are you locked into a specific tech stack, or can you choose?"
+- "What's the oldest codebase you need to support — what Node/Python/Go version?"
+- "Do you have legacy systems you must integrate with?"
+- "What databases are currently in use, and can they be replaced?"
+
+### Scale & Performance
+
+- "How many requests/events per second does the system handle?"
+- "What's your average response time today, and what's acceptable?"
+- "How much data do you store, and is it growing? At what rate?"
+- "Are you bottlenecked by computation, I/O, database, or something else?"
+- "Do you need real-time or is eventual consistency acceptable?"
+
+### Deployment & Operations
+
+- "How is your code deployed — CI/CD, manual, containers, or serverless?"
+- "Who operates the system? Is it self-managed or delegated to a platform team?"
+- "How often do you deploy? Daily, weekly, or rare releases?"
+- "Do you have monitoring/alerting, or is it seat-of-the-pants troubleshooting?"
+- "What's your acceptable downtime — 99% uptime, 99.9%, or critical 24/7?"
+
+### Dependencies & Integrations
+
+- "What external APIs or services does this system depend on?"
+- "Are there hard version requirements for any dependency?"
+- "Do you have vendored (local copy) versions of any libs, or always use package managers?"
+- "Are there compliance/licensing constraints — GPL, LGPL, commercial?"
+
+---
+
+## Product Probes
+
+Ask these when exploring user needs, value, or competitive positioning.
+
+### Users & Jobs to Be Done
+
+- "Who is the primary user? (Developer, end-user, operator, etc.)"
+- "What is the user trying to accomplish, and what currently gets in their way?"
+- "How often do users interact with this? (Daily, weekly, one-time setup?)"
+- "Are users internal (your team) or external (customers)?"
+- "How many users are we talking about — 10s, 1000s, 1M+?"
+
+### Success & Metrics
+
+- "How will we know this feature is successful?"
+- "What metric matters most — speed, reliability, cost, user satisfaction?"
+- "What would constitute failure?"
+- "Is there a measurable target — e.g., 'reduce bugs by 50%' or 'ship 3x faster'?"
+
+### Constraints & Competition
+
+- "Is there a competitive product your users might switch to?"
+- "If so, what does the competitor do better/worse?"
+- "Do you have unique IP or must you catch up on features first?"
+- "Are there regulatory or compliance constraints (GDPR, SOC2, etc.)?"
+
+### Business Context
+
+- "Is this a revenue-generating feature or a cost-reduction tool?"
+- "What happens if we don't build this — what's the status quo?"
+- "Who funded this decision, and what's their main concern?"
+
+---
+
+## Execution Probes
+
+Ask these when planning how to deliver and coordinate the work.
+
+### Timeline & Resources
+
+- "When do you need this ready — weeks, months, or after Q2?"
+- "How many people can work on this? (You, a pair, a team?)"
+- "Are people allocated full-time or splitting across projects?"
+- "Do you have time for testing/QA, or is speed the only goal?"
+
+### Knowledge & Unknowns
+
+- "Has anyone on the team built something like this before?"
+- "What's the biggest risk — technology, people, timeline, or budget?"
+- "What do you NOT know yet, and when will you find out?"
+- "Do you need research/spike, or can you start building immediately?"
+
+### Handoff & Ownership
+
+- "Who owns this after launch — the team that built it?"
+- "Will someone need to operate/maintain this, and do they exist?"
+- "Is this one-shot delivery, or ongoing iteration?"
+
+### Decision Authority
+
+- "Who decides if we're 'done' — you, a product owner, customers?"
+- "Can decisions be changed mid-project, or are they locked?"
+- "Who has veto power — budget, timeline, or technical choices?"
+
+---
+
+## How to Use Domain Probes
+
+### In Conversation
+
+1. **Identify the domain** — Technical? Product? Execution?
+2. **Pick 2-3 relevant probes** from that category
+3. **Ask conversationally** — Don't fire 10 at once
+4. **Listen for gaps** — If an answer raises new questions, follow up
+5. **Document assumptions** — Write down what you learned and what you're still unsure about
+
+### In Written Briefs
+
+If gathering info async:
+
+```markdown
+## Technical Questions
+
+- [ ] What's your current tech stack?
+- [ ] What's your scale — requests/sec, data volume?
+- [ ] Bottleneck today: compute, I/O, database, or something else?
+```
+
+### Red Flags (Answer These First)
+
+If you hear these answers, prioritize deeper exploration:
+- "I don't know" (indicates missing context)
+- "We haven't decided yet" (decision needed before planning)
+- "It depends" (multiple scenarios — map them)
+- Contradictory statements (reconcile before proceeding)
+
+---
+
+## Examples by Scenario
+
+### Scenario: Adding a Search Feature
+
+**Technical probes:**
+- "How much data do you search across — 1K records, 1M?"
+- "Real-time results or can it be eventual consistent?"
+
+**Product probes:**
+- "What do users search for — documents, users, something else?"
+- "How many search queries per day?"
+
+**Execution probes:**
+- "Do you have a search library already (Elasticsearch, SQLite)?"
+- "How much time to ship a basic version?"
+
+### Scenario: Migrating to a New Framework
+
+**Technical probes:**
+- "How big is the current codebase — 10k, 100k, 1M+ lines?"
+- "Are there third-party integrations we'd lose?"
+- "What deployment platform — AWS, Docker, something custom?"
+
+**Product probes:**
+- "Does the end-user experience change, or is this internal?"
+- "Will customers tolerate downtime during migration?"
+
+**Execution probes:**
+- "Can you migrate incrementally or must it be all-or-nothing?"
+- "How much team momentum will this consume?"
+
+### Scenario: Performance Crisis
+
+**Technical probes:**
+- "Bottleneck — slow queries, not enough cache, network bound?"
+- "What's the acceptable latency target?"
+
+**Product probes:**
+- "How many users are affected?"
+- "When did this start?"
+
+**Execution probes:**
+- "How urgent is this — hours or can we take a week?"
+- "Who can debug this — someone on your team or do you need specialists?"
+
+---
+
+## Probe Patterns to Avoid
+
+| Anti-Pattern | Problem | Better Approach |
+|---|---|---|
+| **Leading probes** | "You want to use Kubernetes, right?" | "What deployment platform are you considering?" |
+| **Assumption stacking** | "Do you scale to 1M users with sub-100ms latency?" | Ask scale and latency separately |
+| **Vague probes** | "What are your constraints?" | "What's your timeline, budget, and team size?" |
+| **Too specific** | "Should we use PostgreSQL 14.5 or 15.2?" | "What database systems are you considering?" |
+| **Skip unknowns** | Assume team knows answer | "Is this something you've solved before?" |
+
+---
+
+## Recovery: User Doesn't Know the Answer
+
+If a user can't answer a probe:
+
+1. **Validate uncertainty** — "That's common at this stage"
+2. **Offer a default** — "Typical targets are X. Should we assume that?"
+3. **Defer to research** — "We can spike on this before planning"
+4. **Document the assumption** — "Assuming X. We'll revisit if wrong."
+
+Example:
+- Probe: "What's your scale target?"
+- User: "I don't know"
+- Response: "Typical starting point is 1K users. Should we design for that and revisit when you have clearer data?"

package/rihal/references/elicitation-methods.csv

@@ -0,0 +1,16 @@
+name,description,when-to-use,sample-prompt
+Socratic,Ask layered questions to unearth unstated assumptions and let the answerer discover contradictions themselves,When someone claims confidence but hasn't tested assumptions; before greenfield projects,"What would happen if your assumption about X were reversed? Walk me through the scenario."
+First Principles,Break a complex problem into atomic facts; rebuild understanding from these basics rather than analogy,When innovating or the current model feels stuck; during greenfield architecture,"Forget existing solutions. What are the 3 irreducible facts about this problem? Now build up from there."
+Red Team,Assume adversarial intent; argue against your own proposal to surface failure modes,Before launch or high-stakes decisions; risk assessment,"Imagine you're trying to make this product fail. What's your attack vector? Be ruthless."
+Six Hats,Assign six perspectives (facts/logic/emotion/intuition/creativity/control) and rotate through them,When opinions clash or you need full-spectrum thinking; team debates,"Let's do white hat (facts only): what do we actually know? No opinions. Just data."
+Pre-Mortem,Imagine the project failed; work backward to name all the ways it could have failed,At project launch; before milestones with high downside risk,"It's 90 days from now and this shipped with a critical bug. Rewind. What went wrong?"
+5 Whys,Ask "why" five times in a chain; each answer becomes the subject of the next why,Root-cause analysis; understanding motivation,"Why did the user leave the product? Why? Why? Why? Why? (Keep going until you see the pattern.)"
+MECE,Ensure your categories are Mutually Exclusive and Collectively Exhaustive,When classifying options or risks; building decision trees,"List every way this could be architected. Now prove they don't overlap and nothing is missing."
+Reverse Brainstorm,Instead of "how do we solve X", ask "how do we cause X or make it worse",Unblocking stuck ideation; surfacing hidden constraints,"How would we actively DESTROY user retention? [List] Now flip each: how do we ensure the opposite?"
+SCAMPER,Apply transformations (Substitute / Combine / Adapt / Modify / Put-to-other-uses / Eliminate / Reverse) to existing products or features,Innovation sprints; feature expansion,"Can we Substitute a part? Combine it with something? Adapt it from another domain?"
+Reverse Storming,Start from the desired end state and work backward to the starting conditions,Greenfield planning; moonshot thinking,"In 5 years this is the market leader. Trace back: what had to be true 5 years ago? 2 years ago? Now?"
+Fishbone (Ishikawa),Organize causes into categories (people/process/product/environment) to ensure no angle is missed,Quality analysis; incident postmortems,"Chart all the ways this could fail. Bucket them by category. Does one bucket have suspiciously few entries?"
+Starbursting,Ask reporters' questions (Who/What/When/Where/Why/How) as a framework for exploration,Before launching a product; during discovery,"Who will use this and who won't? When will they abandon it? Where will they expect it to work?"
+Brainwriting,Silent written ideation (no discussion) followed by synthesis; avoids groupthink,When dominant voices drown out ideas; neurodivergent-friendly brainstorm,"Write down 5 ideas in silence. Pass it around. Each person adds to or builds on ideas without debate."
+Rolestorming,Adopt a persona (customer/competitor/alien/child) and answer from that perspective,When internal teams lose perspective; innovation workshops,"You are a competitor's product manager. What would you do to destroy our roadmap? Why?"
+Nominal Group Technique,Individual ranking + group discussion + re-rank; balances democracy with expertise,Prioritization in large groups; high-stakes decisions,"Everyone ranks these options 1-5. Discuss the outliers. Re-rank. Avoids tyranny of the loudest voice."