@hanzlaa/rcode 3.6.16 → 4.0.0

package/rihal/workflows/brainstorm.md

@@ -1,203 +0,0 @@
-# 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/capture.md

@@ -1,60 +0,0 @@
-<purpose>
-Unified capture command. Routes a single user gesture to the right Memory Bank surface based on flags: todo (default — actionable item), note (passive observation), seed (forward-looking idea with trigger conditions), or list (show pending todos). Replaces the muscle-memory pattern of remembering which of /rihal-add-todo, /rihal-note, /rihal-plant-seed, /rihal-check-todos to invoke.
-</purpose>
-
-## Step 0 — Usage check
-
-If `$ARGUMENTS` is empty AND no flag is set:
-
-```
-/rihal-capture <text>                        # save as todo (default)
-/rihal-capture --note <text>                 # passive observation
-/rihal-capture --seed <text>                 # forward-looking with trigger
-/rihal-capture --list [--area <area>]        # show pending todos
-```
-
-STOP — do not proceed.
-
-## Step 1 — Parse mode flags
-
-Inspect `$ARGUMENTS` for mode flags. Exactly one mode applies:
-
-- `--note` → note mode (delegates to add-note workflow)
-- `--seed` → seed mode (delegates to plant-seed workflow)
-- `--list` → list mode (delegates to check-todos workflow)
-- (none) → todo mode (default, delegates to add-todo workflow)
-
-After determining mode, strip the mode flag from `$ARGUMENTS` and pass the remaining text to the underlying workflow.
-
-## Step 2 — Dispatch to underlying workflow
-
-Each mode is implemented by an existing workflow. Load and execute end-to-end:
-
-- **todo (default):** read and execute `@.rihal/workflows/add-todo.md` with the cleaned `$ARGUMENTS`. Output identical to `/rihal-add-todo`.
-- **note (`--note`):** read and execute `@.rihal/workflows/note.md`. Output identical to `/rihal-note`.
-- **seed (`--seed`):** read and execute `@.rihal/workflows/plant-seed.md`. Output identical to `/rihal-plant-seed`.
-- **list (`--list`):** read and execute `@.rihal/workflows/check-todos.md`. Output identical to `/rihal-check-todos`.
-
-The underlying workflows are unchanged — `/rihal-capture` is a thin router. Behaviour, output format, and side effects are byte-identical to invoking the underlying command directly. This means `/rihal-add-todo "X"` and `/rihal-capture "X"` produce the same disk writes and the same console output.
-
-## Step 3 — Footer
-
-After the underlying workflow's normal output, append a single line indicating the mode that was selected:
-
-```
-(rihal-capture: routed to {todo|note|seed|list} mode)
-```
-
-This is invisible polish — confirms to the user that the dispatch was correct.
-
-## Migration note
-
-The four absorbed commands continue to work and are not deprecated yet — they remain canonical aliases. `/rihal-capture` exists as the unified entry for users who want one command to remember instead of four. Future minor versions may consolidate further; until then, both invocation paths are first-class.
-
-## Acceptance
-
-- [ ] `/rihal-capture "fix nav"` produces the same artefacts as `/rihal-add-todo "fix nav"`
-- [ ] `/rihal-capture --note "hex codes everywhere"` produces the same artefacts as `/rihal-note "hex codes everywhere"`
-- [ ] `/rihal-capture --seed "scale to 1k users"` produces the same artefacts as `/rihal-plant-seed "scale to 1k users"`
-- [ ] `/rihal-capture --list` produces the same output as `/rihal-check-todos`
-- [ ] No flag combinations are silently ignored — unknown flags surface as a clear error

package/rihal/workflows/chain.md

@@ -1,188 +0,0 @@
-# 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 `npx @hanzlaa/rcode install` (or `rcode install` if installed globally).

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

@@ -1,193 +0,0 @@
-# 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