@hanzlaa/rcode 2.1.0

package/rihal/workflows/brainstorm.md

@@ -0,0 +1,203 @@
+# Workflow: rihal:brainstorm
+
+<purpose>
+Guided brainstorming session using structured methods. User provides a challenge; the workflow presents available methods, applies the selected one, and generates ideas in a structured format. Output is a brainstorm artifact stored in `.planning/brainstorms/` with the chosen method, raw ideas, and synthesis.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or only contains `--help` or `-h`:
+
+```
+/rihal:brainstorm <challenge> [--method=METHOD] [--people=N] [--personas=LIST]
+```
+
+**Examples:**
+```
+/rihal:brainstorm how to improve user onboarding
+/rihal:brainstorm --method=SCAMPER reduce API latency
+/rihal:brainstorm --method=Rolestorming --personas=competitor,child reduce churn
+```
+
+STOP — do not proceed. Only proceed when the user provides a challenge.
+
+## Step 1 — Parse arguments
+
+Extract from `$ARGUMENTS`:
+- `$CHALLENGE` — the core challenge/problem text (everything before flags)
+- `--method=METHOD` — optional method name (validate against brain-methods.csv)
+- `--people=N` — optional number of participants (for 6-3-5 method)
+- `--personas=LIST` — optional comma-separated personas (for Rolestorming)
+
+If `$CHALLENGE` is empty, ask:
+```
+AskUserQuestion(
+  header: "Brainstorming Challenge",
+  question: "What challenge do you want to brainstorm?",
+  followUp: null
+)
+```
+
+## Step 2 — Load brainstorming methods
+
+Read `rihal/references/brain-methods.csv` and parse it.
+
+If `--method` was specified:
+- Validate the method exists in the CSV
+- If not found, list all available methods and ask user to select
+- Skip to Step 4
+
+If no method specified:
+- Display all available methods with brief descriptions
+- Prompt user to select one:
+
+```
+Available brainstorming methods:
+
+1. SCAMPER — Apply 7 transformations (Substitute/Combine/Adapt/Modify/etc.)
+2. Random Stimulus — Introduce random word/object, force connections
+3. Reverse Brainstorm — How to make the problem worse, then flip to solutions
+4. Brainwriting — Silent written ideation, pass around for refinement
+5. 6-3-5 — Structured method for teams (6 people, 3 ideas, 5 rounds)
+6. Mind Mapping — Radial structure with main idea + branches
+7. Starbursting — Explore using Who/What/When/Where/Why/How questions
+8. Rolestorming — Generate ideas from different personas
+
+AskUserQuestion(
+  header: "Select Method",
+  question: "Which method? (enter number 1-8 or method name)"
+)
+```
+
+Store selected method as `$METHOD_NAME`.
+
+## Step 3 — Gather input based on method
+
+**For 6-3-5:**
+- Ask: "How many people participating?" (default 6, must be at least 3)
+- Store as `$PARTICIPANT_COUNT`
+- Ask for list of 3 initial ideas per person (or generate 3 yourself as starter ideas)
+
+**For Rolestorming:**
+- Ask: "Which personas? (e.g., competitor, 10-year-old, luddite, expert)" or use `--personas` if provided
+- Store as `$PERSONAS` array (at least 2)
+
+**For Starbursting:**
+- Confirm challenge is clear for question generation
+
+**For others:**
+- Proceed directly with the method
+
+## Step 4 — Execute brainstorm method
+
+### SCAMPER
+
+For each transformation (Substitute, Combine, Adapt, Modify, Put-to-other-uses, Eliminate, Reverse):
+1. Prompt: "{transformation}: What if we {transformation_prompt}?"
+   - Substitute: "replace a key part of this?"
+   - Combine: "merge this with something else?"
+   - Adapt: "borrow from a different domain?"
+   - Modify: "change shape, size, or attributes?"
+   - Put-to-other-uses: "use this for a completely different problem?"
+   - Eliminate: "remove a core feature or step?"
+   - Reverse: "flip the direction or order?"
+2. Capture 1-3 ideas per transformation
+3. Output format: Markdown list grouped by transformation
+
+### Random Stimulus
+
+1. Present a random word: "[word]"
+2. Ask: "How is [challenge] like [word]?"
+3. Capture free associations (no filtering)
+4. Ask: "How can we use this absurd connection to improve [challenge]?"
+5. Refine absurdities into viable ideas
+6. Output format: Stimulus → Associations → Absurd ideas → Refined concepts
+
+### Reverse Brainstorm
+
+1. Restate challenge as opposite: "How to FAIL at [challenge]?"
+2. Generate 8-10 bad outcomes
+3. For each, write the flip (good version)
+4. Output format: Two-column table (Bad idea / Good idea)
+
+### Brainwriting
+
+1. Write 3 initial ideas
+2. Describe: "These ideas are written down. If you were passing this to the next person, how would you extend or refine each?"
+3. Simulate 2-3 rounds of refinement (improve ideas iteratively)
+4. Output format: Evolution markers showing round-by-round refinement
+
+### 6-3-5
+
+1. Generate 3 starter ideas (or use user's)
+2. Simulate `$PARTICIPANT_COUNT` people over 5 rounds
+3. Each round: previous ideas are refined/extended
+4. Output format: Matrix showing idea evolution across 5 rounds
+
+### Mind Mapping
+
+1. Place challenge in center
+2. Ask: "What are the 3-5 main themes or subtopics?"
+3. For each theme, ask: "What are 2-3 sub-ideas?"
+4. Optionally connect related nodes across branches
+5. Output format: ASCII indented tree or text outline
+
+### Starbursting
+
+1. For each of Who/What/When/Where/Why/How, generate 3-5 sub-questions about the challenge
+2. For each question, brainstorm what emerging ideas it suggests
+3. Output format: Six sections (one per letter), each with sub-questions and ideas
+
+### Rolestorming
+
+1. For each persona in `$PERSONAS`, ask: "If you were a [persona], what would you think about [challenge]? What ideas come to mind?"
+2. Capture 5-10 ideas per persona
+3. Output format: Markdown sections by persona, each with ideas
+
+## Step 5 — Synthesize and save
+
+After method execution:
+
+1. Display all generated ideas in the structured format defined by the method
+2. Ask: "Any immediate combinations or refinements?" (optional follow-up ideation)
+3. Create artifact file: `.planning/brainstorms/{TIMESTAMP}-{METHOD_NAME}.md`
+
+**Artifact structure:**
+
+```markdown
+# Brainstorm: {CHALLENGE}
+
+**Method:** {METHOD_NAME}
+**Date:** ISO-DATE
+**Participant count:** N (if applicable)
+
+## Generated Ideas
+
+{structured output from method}
+
+## Synthesis
+
+[User's optional refinements or combinations]
+
+## Next Steps
+
+To turn ideas into features/tickets:
+- `/rihal:plan <idea description>` — for detailed implementation plan
+- `/rihal:council is this idea worth pursuing?` — for strategic discussion
+```
+
+4. Print summary: "{N} ideas generated using {METHOD_NAME}"
+
+## Success Criteria
+
+- User selects or is assigned a brainstorming method
+- Method is executed with structured prompts
+- Ideas are captured in the format defined by the method
+- Artifact is saved to `.planning/brainstorms/`
+- User can see all generated ideas clearly
+
+## On Error
+
+If method execution fails or user cannot articulate challenge:
+- Provide a fallback free-form brainstorm: "Let's just list ideas without structure"
+- Save output as `.planning/brainstorms/{TIMESTAMP}-freeform.md`

package/rihal/workflows/chain.md

@@ -0,0 +1,188 @@
+# Workflow: rihal:chain
+
+<purpose>
+Run a sequential agent pipeline — each agent receives the previous agent's output as input. Unlike `/rihal:council` (parallel debate with cross-talk), chain is a one-way pipeline for "do research → hand to PM → hand to CTO" patterns. Each stage's output is saved as a first-class artifact the next stage reads.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty, print:
+
+```
+Usage: /rihal:chain <preset|agent-list> <topic or question>
+
+Presets (common pipelines):
+  research-plan      Mariam (research) → Hussain-PM (scope) → Planner (SPRINT.md)
+  feasibility        Waleed (architecture) → Fatima (QA gates)
+  gtm-to-build       Mariam (GTM) → Hussain-PM (scope) → Waleed (feasibility)
+  full-discovery     Mariam → Sadiq (kill criteria) → Hussain-PM → Waleed → Planner
+
+Custom agents (comma-separated, in order):
+  /rihal:chain mariam,hussain-pm,waleed <topic>
+
+Examples:
+  /rihal:chain research-plan affiliate site in Dubai for mobile accessories
+  /rihal:chain feasibility migrate our Postgres to Neon serverless
+  /rihal:chain mariam,hussain-pm should we enter the SaaS bookkeeping market in Oman?
+```
+
+STOP here if no arguments.
+
+## Step 0.5 — Detect pure decision questions (redirect to council)
+
+If `$ARGUMENTS` is a pure decision question with no topic to work on (patterns like "should we", "A or B", "is X better than Y", "worth it") and does NOT contain a preset name or agent list:
+
+```
+⚠ /rihal:chain produces deliverables (RESEARCH.md, SCOPE.md, SPRINT.md).
+For decisions only, /rihal:council is the right tool.
+
+For a debate: /rihal:council $ARGUMENTS
+For a research-to-plan pipeline: /rihal:chain research-plan $ARGUMENTS
+```
+
+Only proceed past this step if the input is a topic or deliverable request (e.g., "research affiliate site", "scope mobile app migration", "plan e-commerce platform").
+
+## Step 1 — Resolve the chain
+
+```bash
+INIT=$(node .rihal/bin/rihal-tools.cjs init chain "$ARGUMENTS")
+```
+
+Parse:
+- `chain` — array of agent ids in order (e.g. `["mariam", "hussain-pm", "planner"]`)
+- `topic` — the user's question/topic (arguments minus the preset/agent-list)
+- `preset` — preset name if matched, null otherwise
+- `slug` — kebab-case slug from topic, max 40 chars
+- `chain_dir` — `.planning/chains/{YYYY-MM-DD}-{slug}/`
+- `config`, `paths` — standard
+
+If the chain contains unknown or uninstalled agents, stop and list valid ones.
+
+Print:
+```
+🔗 Chain: {preset or "custom"}
+   Pipeline: {agent 1} → {agent 2} → {agent 3}
+   Topic: {topic}
+   Artifacts: {chain_dir}/
+```
+
+Create the chain directory.
+
+## Step 2 — Run the chain (one stage at a time)
+
+For each agent in `chain`, in order:
+
+### Stage input
+Build the prompt for this stage:
+
+```
+You are stage {N} of {total} in a Rihal chain.
+
+## Topic
+{topic}
+
+## Pipeline
+{full chain list with current stage marked}
+
+## Previous stage artifacts
+{contents of all artifacts from prior stages in chain_dir}
+
+## Your task
+Produce your output as a structured markdown artifact. This is not a conversation —
+the next stage will read your output verbatim. Be specific, cite sources (for Mariam:
+use WebSearch), and end with a clear handoff note for the next stage.
+
+Save your output to: {chain_dir}/{stage_number}-{agent_id}-{artifact_name}.md
+```
+
+Artifact names by agent:
+- `mariam` → `RESEARCH.md`
+- `hussain-pm` → `SCOPE.md`
+- `waleed` → `ADR.md`
+- `fatima` → `QA-GATES.md`
+- `sadiq` → `STRATEGY.md`
+- `planner` → `SPRINT.md`
+
+### Spawn the agent
+Spawn exactly ONE agent at a time via the Agent tool with the prompt above. Wait for completion. Do not spawn the next stage until this one finishes.
+
+### Save the artifact
+The agent writes their artifact to the chain directory. After the agent returns, verify the file exists:
+```bash
+test -f {chain_dir}/{artifact filename}
+```
+
+If missing, the stage failed — print which stage, stop the chain, allow user to re-run.
+
+### Print stage summary
+```
+✅ Stage {N}/{total} — {agent}: {artifact filename}
+```
+
+## Step 3 — Final output
+
+After the last stage:
+
+```
+🔗 Chain complete.
+
+Artifacts in {chain_dir}/:
+  1-mariam-RESEARCH.md       (Mariam, stage 1)
+  2-hussain-pm-SCOPE.md      (Hussain-PM, stage 2)
+  3-planner-SPRINT.md          (Planner, stage 3)
+
+Next step:
+/rihal:execute {chain_dir}/3-planner-SPRINT.md
+
+─── ~5K tokens per stage · {duration}s · {stage-count} agents ───
+```
+
+The "next step" line is a single copy-paste command — see `.rihal/references/command-redirect-format.md`. The footer uses the estimation from `.rihal/references/response-style.md#session-cost-footer`.
+
+## Step 4 — Update state
+
+```bash
+node .rihal/bin/rihal-tools.cjs state record-chain \
+  --slug "{slug}" \
+  --agents "{comma-separated}" \
+  --artifacts "{chain_dir}"
+node .rihal/bin/rihal-tools.cjs state record-session
+```
+
+Silent on failure — state tracking is optional.
+
+## Success Criteria
+
+- [ ] All agents in the chain spawned and executed sequentially
+- [ ] Each stage produces an artifact file in chain_dir
+- [ ] Artifact filenames follow naming convention: `{stage}-{agent_id}-{artifact_name}.md`
+- [ ] State updated with chain record and session timestamp
+
+## Presets reference
+
+| Preset | Chain | Use when |
+|--------|-------|----------|
+| `research-plan` | mariam → hussain-pm → planner | Have an idea, want SPRINT.md |
+| `feasibility` | waleed → fatima | Technical decision with QA gate |
+| `gtm-to-build` | mariam → hussain-pm → waleed | Market → scope → tech reality check |
+| `full-discovery` | mariam → sadiq → hussain-pm → waleed → planner | Full validation before committing |
+
+## Differences from /rihal:council
+
+| | /rihal:council | /rihal:chain |
+|--|--|--|
+| Execution | Parallel (Round 1 + cross-talk Round 2) | Sequential (one at a time) |
+| Output | One session artifact with all agent voices | One artifact per agent |
+| Best for | Debate, disagreement, multiple perspectives | Pipelines where each stage builds on the last |
+| Subsequent use | `/rihal:plan {session}` converts follow-ups to plans | Last stage often IS a SPRINT.md already |
+
+## On Error
+
+- **No arguments:** print usage block, stop.
+- **Pure decision question detected:** redirect to council (Step 0.5).
+- **Unknown preset:** list valid presets, stop.
+- **Agent not installed:** print installed agents, suggest closest match.
+- **state.json missing or corrupted:** continue without error — chain artifacts are mandatory, state tracking is optional.
+- **Stage fails to produce artifact:** print stage number, allow `/rihal:chain --continue` to resume.
+- **Agent returns empty output:** print "Agent produced no output. Check input and retry."
+- **`rihal-tools.cjs` missing:** tell user to run `rihal-code install-v2`.

package/rihal/workflows/check-implementation-readiness.md

@@ -0,0 +1,193 @@
+# Workflow: rihal:check-implementation-readiness
+
+<purpose>
+Pre-execution gate: verify PRD approved, architecture approved, external dependencies identified, and no blocking assumptions remain. Return pass/fail report. Used as guard in plan.md Step 0.8 and execute.md Step 0.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:check-implementation-readiness <argument-here>
+```
+
+**Examples:**
+```
+/rihal:check-implementation-readiness example 1
+/rihal:check-implementation-readiness example 2
+```
+
+STOP — do not proceed.
+
+## Step 0 — Initialize
+
+```bash
+INIT=$(node .rihal/bin/rihal-tools.cjs init check-implementation-readiness "$ARGUMENTS")
+```
+
+Parse:
+- `flags.phase` — specific phase to check (optional, default: current_phase)
+- `current_phase` — from state if --phase not provided
+- `checklist_po_master_path` — `.rihal/references/checklist-po-master.md`
+
+## Step 1 — Load Readiness Checklist
+
+Read `.rihal/references/checklist-po-master.md` for required approval gates:
+
+Expected sections:
+1. **PRD Sign-Off** — requirements approved by stakeholders
+2. **Architecture Approval** — design approved by tech lead
+3. **Dependencies Identified** — all external APIs, services, data sources listed
+4. **Assumptions Surfaced** — no blocking unknowns
+
+## Step 2 — Check Each Gate
+
+### Gate 1: PRD Approved
+
+Check if `.rihal/PRD.md` or equivalent exists and has approval signature:
+
+```bash
+if grep -q "Approved by:" .rihal/PRD.md 2>/dev/null; then
+  GATE_PRD="✓ PASS"
+else
+  GATE_PRD="✗ FAIL — PRD not approved"
+fi
+```
+
+### Gate 2: Architecture Approved
+
+Check if `.rihal/ARCHITECTURE.md` exists and has approval:
+
+```bash
+if grep -q "Approved by:" .rihal/ARCHITECTURE.md 2>/dev/null; then
+  GATE_ARCH="✓ PASS"
+else
+  GATE_ARCH="✗ FAIL — Architecture not approved"
+fi
+```
+
+### Gate 3: External Dependencies
+
+Check if `.rihal/DEPENDENCIES.md` exists with identified external integrations:
+
+```bash
+if test -f .rihal/DEPENDENCIES.md && grep -q "^##" .rihal/DEPENDENCIES.md; then
+  GATE_DEPS="✓ PASS"
+else
+  GATE_DEPS="✗ FAIL — External dependencies not documented"
+fi
+```
+
+### Gate 4: No Blocking Assumptions
+
+Check `.rihal/ASSUMPTIONS.md` for unresolved assumptions:
+
+```bash
+if grep -q "BLOCKING:" .rihal/ASSUMPTIONS.md 2>/dev/null; then
+  GATE_ASSUMPTIONS="✗ FAIL — Blocking assumptions exist"
+else
+  GATE_ASSUMPTIONS="✓ PASS"
+fi
+```
+
+## Step 3 — Generate Readiness Report
+
+Collect gate results:
+
+```bash
+GATES=$(node .rihal/bin/rihal-tools.cjs state read-gates)
+OVERALL_STATUS=$([[ "$GATE_PRD" == "✓"* ]] && [[ "$GATE_ARCH" == "✓"* ]] && [[ "$GATE_DEPS" == "✓"* ]] && [[ "$GATE_ASSUMPTIONS" == "✓"* ]] && echo "READY" || echo "BLOCKED")
+```
+
+Write `.rihal/READINESS-REPORT.md`:
+
+```markdown
+# Implementation Readiness Check
+
+**Status:** {READY|BLOCKED}
+**Checked:** {timestamp}
+
+## Gating Criteria
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| PRD Approval | {✓/✗} | {message} |
+| Architecture Approval | {✓/✗} | {message} |
+| Dependencies Identified | {✓/✗} | {message} |
+| No Blocking Assumptions | {✓/✗} | {message} |
+
+## Blockers (if any)
+
+{list_of_failed_gates_with_remediation}
+
+## Remediation
+
+{steps_to_resolve_blockers}
+```
+
+## Step 4 — Return Result
+
+Print:
+```
+🛡️ Implementation Readiness: {READY|BLOCKED}
+
+Gates:
+  {GATE_PRD}
+  {GATE_ARCH}
+  {GATE_DEPS}
+  {GATE_ASSUMPTIONS}
+
+{IF_BLOCKED:
+  Blockers:
+  • {list}
+  
+  Resolve with:
+  {remediation_commands}
+}
+```
+
+**If READY:** return `{ status: "READY" }`
+**If BLOCKED:** return `{ status: "BLOCKED", blockers: [...] }` and STOP plan/execute
+
+## Integration: plan.md Guard
+
+In plan.md workflow, **Step 0.8 — Pre-execution Gate** (after decision checkpoint):
+
+```bash
+if [[ "$FLAGS_SKIP_GATES" != "true" ]]; then
+  READINESS=$(node .rihal/bin/rihal-tools.cjs check-implementation-readiness)
+  if [[ "$READINESS" != "READY" ]]; then
+    echo "⚠ Implementation not ready. Resolve blockers before proceeding."
+    exit 1
+  fi
+fi
+```
+
+## Integration: execute.md Guard
+
+In execute.md workflow, **Step 0 — Pre-execution Validation**:
+
+```bash
+READINESS=$(node .rihal/bin/rihal-tools.cjs check-implementation-readiness --phase "$PHASE")
+if [[ "$READINESS" != "READY" ]]; then
+  echo "Cannot execute plan — implementation not ready."
+  exit 1
+fi
+```
+
+Allow `--skip-gates` flag to override for emergency situations only.
+
+## Success Criteria
+
+- READINESS-REPORT.md created
+- All 4 gates checked
+- Status returned (READY or BLOCKED)
+- Blockers clearly listed with remediation
+
+## On Error
+
+- If checklist files missing: treat as FAIL on that gate
+- If state read fails: skip and report gates manually
+- If file not found: treat as FAIL, suggest file location