@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/workflows/replay.md

@@ -0,0 +1,165 @@
+# Workflow: rcode-replay
+
+<purpose>
+Re-run a past council session with the same question for a fresh panel round. Useful when:
+
+- The first council was inconclusive and you want a second pass
+- Facts or context have shifted and the original question deserves re-evaluation
+- You want to see how a different panel composition answers the same question
+
+This is NOT `--resume` (which asks a follow-up question with prior context). Replay re-asks the original question from a clean slate, then links the new artifact back to the original for comparison.
+</purpose>
+
+<output_format>
+Open with banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► REPLAY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+End with a single-line redirect (per `command-redirect-format.md`) so the user copy-pastes the resulting `/rcode-council` invocation.
+</output_format>
+
+<required_reading>
+@.rcode/references/command-redirect-format.md
+@.rcode/references/output-format.md
+</required_reading>
+
+<process>
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` / `-h`:
+
+```
+/rcode-replay <session-path-or-slug> [--agents a,b,c]
+
+  <session-path-or-slug>   Full path to .planning/council-sessions/council-YYYY-MM-DD-<slug>.md
+                           OR just the slug (e.g. "should-i-ship-v2") — the first matching
+                           file, newest-first, will be used.
+  --agents a,b,c           Override the panel for the replay (otherwise council auto-selects)
+```
+
+STOP — do not proceed.
+
+## Step 1 — Resolve the session file
+
+Parse `$ARGUMENTS` — first positional token is the session identifier, remaining tokens pass through.
+
+```bash
+SESSIONS_DIR=".planning/council-sessions"
+ARG="${1}"
+
+# Full path: use as-is
+if [ -f "$ARG" ]; then
+  SESSION_FILE="$ARG"
+# Slug: find newest matching file
+elif ls "${SESSIONS_DIR}" >/dev/null 2>&1; then
+  SESSION_FILE=$(ls -t "${SESSIONS_DIR}"/council-*"${ARG}"*.md 2>/dev/null | head -1)
+fi
+
+if [ -z "$SESSION_FILE" ] || [ ! -f "$SESSION_FILE" ]; then
+  echo "No session matched \"$ARG\". Available:"
+  ls -t "${SESSIONS_DIR}"/council-*.md 2>/dev/null | head -10
+  exit 0
+fi
+```
+
+If no sessions directory exists at all:
+
+```
+No council sessions on disk yet. Run /rcode-council "<question>" to create the first one.
+```
+
+STOP.
+
+## Step 2 — Extract the original question
+
+Read `SESSION_FILE` and pull the text block under the `## Question` heading (until the next `##` heading or EOF). Trim leading/trailing whitespace. Strip surrounding blank lines.
+
+```bash
+QUESTION=$(awk '/^## Question$/{flag=1;next} /^## /{flag=0} flag' "$SESSION_FILE" | sed '/./,$!d' | awk 'NF{found=1} found')
+```
+
+If the extracted question is empty:
+
+```
+Could not extract "## Question" heading from $SESSION_FILE. The artifact may be malformed. Open it and copy the question manually:
+
+/rcode-council <question>
+```
+
+STOP.
+
+Also capture the original slug for the replay annotation:
+
+```bash
+ORIGINAL_SLUG=$(basename "$SESSION_FILE" .md | sed 's/^council-[0-9-]*-//')
+ORIGINAL_DATE=$(basename "$SESSION_FILE" .md | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' | head -1)
+```
+
+## Step 3 — Show the replay preview
+
+Print a short summary so the user can confirm before the redirect:
+
+```
+Replaying session: {SESSION_FILE}
+Original date:    {ORIGINAL_DATE}
+Original slug:    {ORIGINAL_SLUG}
+
+Question to re-ask:
+  {QUESTION}
+```
+
+If `--agents` was passed, also print:
+```
+Panel override:   {agents_csv}
+```
+
+## Step 4 — Emit the redirect
+
+Per `command-redirect-format.md`, one line, copy-pastable:
+
+```
+Re-running the council with a fresh panel on the original question.
+
+Copy-paste this:
+
+/rcode-council {QUESTION}{agents_suffix}
+```
+
+Where `{agents_suffix}` is `  --agents=a,b,c` if `--agents` was passed, else empty.
+
+## Step 5 — Record the replay intent
+
+Append a lightweight replay record so history is traceable even before council runs:
+
+```bash
+node .rcode/bin/rcode-tools.cjs state add-decision \
+  "Replay of council session ${ORIGINAL_SLUG} (${ORIGINAL_DATE}) — re-asking: ${QUESTION:0:80}" \
+  2>/dev/null || true
+```
+
+The subsequent `/rcode-council` run will attach its own artifact; pairing the two by date + slug lets `/rcode-decisions` and state readers show the replay chain.
+</process>
+
+## Success Criteria
+
+- Slug argument resolves to the newest matching session file
+- Full path argument works as-is
+- `## Question` text is extracted verbatim, including any multi-line body
+- Malformed or empty question artifacts produce a clear error (not a crash)
+- Redirect is a single line, in the copy-paste format required by the command-redirect reference
+- `--agents` override passes through to the council invocation unchanged
+
+## On Error
+
+- Missing session directory → tell the user to run `/rcode-council` first
+- Slug ambiguity → list the top 10 newest matches so the user can paste a fuller path
+- Extraction returns empty → print the path and ask the user to copy the question manually
+
+## Next Up
+
+- `/rcode-plan` — plan next steps based on the fresh council round
+- `/rcode-decisions` — review decisions the replayed council produced

package/rcode/workflows/rerun.md

@@ -0,0 +1,82 @@
+<purpose>
+Re-execute a previously completed phase or plan. Resets its state to pending and re-runs the execute workflow, creating new commits (not amending old ones).
+</purpose>
+
+## Step 0: Usage Check
+
+Verify argument: `/rcode-rerun <phase-id|plan-id>`
+
+Examples:
+- `/rcode-rerun 03` — re-run all plans in phase 3
+- `/rcode-rerun 03-02` — re-run specific plan
+
+If empty: `Usage: /rcode-rerun <phase-id|plan-id> (e.g., /rcode-rerun 03 or /rcode-rerun 03-02)`
+
+## Step 0.5: Detect Target via Resolve
+
+Run: `node .rcode/bin/rcode-tools.cjs state resolve-id "$ARGUMENTS"`
+
+If type === "unknown": Return error `ID not found: $ARGUMENTS`
+
+Store: `target.type` (phase or plan) and `target.id`
+
+## Step 1: Confirm via AskUserQuestion
+
+Ask user:
+
+```
+Re-run {target.type} {target.id}?
+
+This will:
+  (a) Reset {target.type} tasks to status: pending in state.json
+  (b) Re-execute all plans in {target.type}
+  (c) New commits will be created (not amendments to existing commits)
+
+Proceed? (yes/no)
+```
+
+If user says "no" or does not confirm: Stop, return `Cancelled.`
+
+## Step 2: Mark as Pending in state.json
+
+Read `.rcode/state.json`
+
+If `target.type === "phase"`:
+- Find all `executions[].plan_id` in this phase
+- Set `executions[].status = "pending"` for each
+- Update `executions[].reset_at = ISO_TIMESTAMP`
+
+If `target.type === "plan"`:
+- Find `executions[].plan_id === target.id`
+- Set `status = "pending"`
+- Set `reset_at = ISO_TIMESTAMP`
+
+Write updated state.json back
+
+## Step 3: Invoke Execute
+
+Route to `/rcode-execute {target.id}`
+
+The executor will:
+- See status=pending in state.json
+- Re-run all tasks
+- Create new commits
+
+## Success Criteria
+
+- [ ] ID resolves
+- [ ] User confirms
+- [ ] state.json updated with pending status
+- [ ] Execute workflow triggered
+- [ ] New commits logged (not amendments)
+
+## On Error
+
+- ID unresolvable → Show error
+- state.json corrupt → "Cannot read state. Check .rcode/state.json"
+- User declines → Stop gracefully
+
+## Next Up
+
+- `/rcode-verify-phase` — verify the phase goal after the re-run
+- `/rcode-status` — confirm state reflects the re-run

package/rcode/workflows/research-phase.md

@@ -0,0 +1,113 @@
+<purpose>
+Research how to implement a phase. Spawns rcode-phase-researcher with phase context.
+
+Standalone research command. For most workflows, use `/rcode-plan` which integrates research automatically.
+</purpose>
+
+<available_agent_types>
+Valid rcode subagent types (use exact names — do not fall back to 'general-purpose'):
+- rcode-phase-researcher — Researches technical approaches for a phase
+</available_agent_types>
+
+<process>
+
+## Step 0: Resolve Model Profile
+
+@.rcode/references/model-profile-resolution.md
+
+Resolve model for:
+- `rcode-phase-researcher`
+
+## Step 1: Normalize and Validate Phase
+
+@.rcode/references/phase-argument-parsing.md
+
+```bash
+PHASE_INFO=$(node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "${PHASE}")
+```
+
+If `found` is false: Error and exit.
+
+## Step 2: Check Existing Research
+
+```bash
+ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null || true
+```
+
+If exists: Offer update/view/skip options.
+
+## Step 3: Gather Phase Context
+
+```bash
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "${PHASE}" 2>/dev/null)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# If INIT is empty or INIT.ok is false: print "Error: rcode-tools init failed." and exit.
+# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path, response_language
+# If response_language is set, include "Respond in {value}." in all spawned subagent prompts.
+AGENT_SKILLS_RESEARCHER=$(node ".rcode/bin/rcode-tools.cjs" agent-skills rcode-phase-researcher 2>/dev/null || echo "")
+```
+
+## Step 4: Spawn Researcher
+
+```
+Task(
+  prompt="<objective>
+Research implementation approach for Phase {phase}: {name}
+
+Why this phase matters: {description}
+Broader goal: this research output must enable the planning step to break
+Phase {phase} into concrete, buildable sprints — a sufficient result gives
+planning specific approaches, libraries (with versions/rationale), and known
+pitfalls, not a vague survey.
+</objective>
+
+<objective_context>
+Phase {phase} goal: {description}
+Downstream consumer: /rcode-plan reads {phase}-RESEARCH.md to structure sprints.
+</objective_context>
+
+<files_to_read>
+- {context_path} (USER DECISIONS from /rcode-discuss-phase)
+- {requirements_path} (Project requirements)
+- {state_path} (Project decisions and history)
+</files_to_read>
+
+${AGENT_SKILLS_RESEARCHER}
+
+<additional_context>
+Phase description: {description}
+</additional_context>
+
+<output>
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
+</output>",
+  subagent_type="rcode-phase-researcher",
+  model="{researcher_model}"
+)
+```
+
+## Step 5: Handle Return
+
+@.rcode/references/iterative-retrieval.md
+
+**Sufficiency loop (runs before routing):** When `rcode-phase-researcher`
+returns its `## RESEARCH COMPLETE` summary, evaluate it for sufficiency
+against the Step-4 objective — does it cover every dimension the phase goal
+asked for, are recommendations specific (versions/rationale) not vague, and
+were any `## RESEARCH INCONCLUSIVE` or blocked signals returned. If
+insufficient, re-dispatch `rcode-phase-researcher` with a follow-up prompt
+that names the specific gaps and includes the prior result, asking only for
+the missing pieces. This loop is hard-capped at 3 cycles (initial + up to 2
+follow-ups). After the cap, proceed with the best result and note residual
+gaps in the RESEARCH.md artifact. Then offer the routing options below.
+
+- `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
+- `## CHECKPOINT REACHED` — Present to user, spawn continuation
+- `## RESEARCH INCONCLUSIVE` — Show attempts, offer: Add context/Try different mode/Manual
+
+</process>
+
+## Next Up
+
+- `/rcode-plan` — plan the phase using research findings
+- `/rcode-discuss-phase` — discuss research findings before planning

package/rcode/workflows/resume-work.md

@@ -0,0 +1,336 @@
+<trigger>
+Use this workflow when:
+- Starting a new session on an existing project
+- User says "continue", "what's next", "where were we", "resume"
+- Any planning operation when .planning/ already exists
+- User returns after time away from project
+</trigger>
+
+<purpose>
+Instantly restore full project context so "Where were we?" has an immediate, complete answer.
+</purpose>
+
+<required_reading>
+@.rcode/references/continuation-format.md
+</required_reading>
+
+<process>
+
+<step name="initialize">
+Load all context in one call:
+
+```bash
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init resume 2>/dev/null)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+If `INIT` is empty or `INIT.ok` is false, print error and exit:
+```
+Error: rcode-tools init failed. Is .rcode/ installed? Run: npx @hanzlaa/rcode install
+```
+
+Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`.
+
+**If `state_exists` is true:** Proceed to load_state
+**If `state_exists` is false but `roadmap_exists` or `project_exists` is true:** Offer to reconstruct STATE.md
+**If `planning_exists` is false:** This is a new project - route to /rcode-new-project
+</step>
+
+<step name="load_state">
+
+Read and parse STATE.md, then PROJECT.md:
+
+```bash
+cat .planning/STATE.md
+cat .planning/PROJECT.md
+```
+
+**From STATE.md extract:**
+
+- **Project Reference**: Core value and current focus
+- **Current Position**: Phase X of Y, Plan A of B, Status
+- **Progress**: Visual progress bar
+- **Recent Decisions**: Key decisions affecting current work
+- **Pending Todos**: Ideas captured during sessions
+- **Blockers/Concerns**: Issues carried forward
+- **Session Continuity**: Where we left off, any resume files
+
+**From PROJECT.md extract:**
+
+- **What This Is**: Current accurate description
+- **Requirements**: Validated, Active, Out of Scope
+- **Key Decisions**: Full decision log with outcomes
+- **Constraints**: Hard limits on implementation
+
+</step>
+
+<step name="check_incomplete_work">
+Look for incomplete work that needs attention:
+
+```bash
+# Check for structured handoff (preferred — machine-readable)
+cat .planning/HANDOFF.json 2>/dev/null || true
+
+# Check for continue-here files (mid-plan resumption)
+ls .planning/phases/*/.continue-here*.md 2>/dev/null || true
+
+# Check for plans without summaries (incomplete execution)
+for plan in .planning/phases/*/*-SPRINT.md; do
+  [ -e "$plan" ] || continue
+  summary="${plan/PLAN/SUMMARY}"
+  [ ! -f "$summary" ] && echo "Incomplete: $plan"
+done 2>/dev/null || true
+
+# Check for interrupted agents (use has_interrupted_agent and interrupted_agent_id from init)
+if [ "$has_interrupted_agent" = "true" ]; then
+  echo "Interrupted agent: $interrupted_agent_id"
+fi
+```
+
+**If HANDOFF.json exists:**
+
+- This is the primary resumption source — structured data from `/rcode-pause-work`
+- Parse `status`, `phase`, `plan`, `task`, `total_tasks`, `next_action`
+- Check `blockers` and `human_actions_pending` — surface these immediately
+- Check `completed_tasks` for `in_progress` items — these need attention first
+- Validate `uncommitted_files` against `git status` — flag divergence
+- Use `context_notes` to restore mental model
+- Flag: "Found structured handoff — resuming from task {task}/{total_tasks}"
+- **After successful resumption, delete HANDOFF.json** (it's a one-shot artifact)
+
+**If .continue-here file exists (fallback):**
+
+- This is a mid-plan resumption point
+- Read the file for specific resumption context
+- Flag: "Found mid-plan checkpoint"
+
+**If PLAN without SUMMARY exists:**
+
+- Execution was started but not completed
+- Flag: "Found incomplete plan execution"
+
+**If interrupted agent found:**
+
+- Subagent was spawned but session ended before completion
+- Read agent-history.json for task details
+- Flag: "Found interrupted agent"
+  </step>
+
+<step name="present_status">
+Present complete project status to user:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PROJECT STATUS                                               ║
+╠══════════════════════════════════════════════════════════════╣
+║  Building: [one-liner from PROJECT.md "What This Is"]         ║
+║                                                               ║
+║  Phase: [X] of [Y] - [Phase name]                            ║
+║  Plan:  [A] of [B] - [Status]                                ║
+║  Progress: [██████░░░░] XX%                                  ║
+║                                                               ║
+║  Last activity: [date] - [what happened]                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+[If incomplete work found:]
+⚠️  Incomplete work detected:
+    - [.continue-here file or incomplete plan]
+
+[If interrupted agent found:]
+⚠️  Interrupted agent detected:
+    Agent ID: [id]
+    Task: [task description from agent-history.json]
+    Interrupted: [timestamp]
+
+    Resume with: Task tool (resume parameter with agent ID)
+
+[If pending todos exist:]
+📋 [N] pending todos — /rcode-check-todos to review
+
+[If blockers exist:]
+⚠️  Carried concerns:
+    - [blocker 1]
+    - [blocker 2]
+
+[If alignment is not ✓:]
+⚠️  Brief alignment: [status] - [assessment]
+```
+
+</step>
+
+<step name="determine_next_action">
+Based on project state, determine the most logical next action:
+
+**If interrupted agent exists:**
+→ Primary: Resume interrupted agent (Task tool with resume parameter)
+→ Option: Start fresh (abandon agent work)
+
+**If HANDOFF.json exists:**
+→ Primary: Resume from structured handoff (highest priority — specific task/blocker context)
+→ Option: Discard handoff and reassess from files
+
+**If .continue-here file exists:**
+→ Fallback: Resume from checkpoint
+→ Option: Start fresh on current plan
+
+**If incomplete plan (PLAN without SUMMARY):**
+→ Primary: Complete the incomplete plan
+→ Option: Abandon and move on
+
+**If phase in progress, all plans complete:**
+→ Primary: Advance to next phase (via internal transition workflow)
+→ Option: Review completed work
+
+**If phase ready to plan:**
+→ Check if CONTEXT.md exists for this phase:
+
+- If CONTEXT.md missing:
+  → Primary: Discuss phase vision (how user imagines it working)
+  → Secondary: Plan directly (skip context gathering)
+- If CONTEXT.md exists:
+  → Primary: Plan the phase
+  → Option: Review roadmap
+
+**If phase ready to execute:**
+→ Primary: Execute next plan
+→ Option: Review the plan first
+</step>
+
+<step name="offer_options">
+Present contextual options based on project state:
+
+```
+What would you like to do?
+
+[Primary action based on state - e.g.:]
+1. Resume interrupted agent [if interrupted agent found]
+   OR
+1. Execute phase (/rcode-execute {phase} ${RCODE_WS})
+   OR
+1. Discuss Phase 3 context (/rcode-discuss-phase 3 ${RCODE_WS}) [if CONTEXT.md missing]
+   OR
+1. Plan Phase 3 (/rcode-plan 3 ${RCODE_WS}) [if CONTEXT.md exists or discuss option declined]
+
+[Secondary options:]
+2. Review current phase status
+3. Check pending todos ([N] pending)
+4. Review brief alignment
+5. Something else
+```
+
+**Note:** When offering phase planning, check for CONTEXT.md existence first:
+
+```bash
+ls .planning/phases/XX-name/*-CONTEXT.md 2>/dev/null || true
+```
+
+If missing, suggest discuss-phase before plan. If exists, offer plan directly.
+
+Wait for user selection.
+</step>
+
+<step name="route_to_workflow">
+Based on user selection, route to appropriate workflow:
+
+- **Execute plan** → Show command for user to run after clearing:
+  ```
+  ---
+
+  ## ▶ Next Up
+
+  **{phase}-{plan}: [Plan Name]** — [objective from SPRINT.md]
+
+  `/clear` then:
+
+  `/rcode-execute {phase} ${RCODE_WS}`
+
+  ---
+  ```
+- **Plan phase** → Show command for user to run after clearing:
+  ```
+  ---
+
+  ## ▶ Next Up
+
+  **Phase [N]: [Name]** — [Goal from ROADMAP.md]
+
+  `/clear` then:
+
+  `/rcode-plan [phase-number] ${RCODE_WS}`
+
+  ---
+
+  **Also available:**
+  - `/rcode-discuss-phase [N] ${RCODE_WS}` — gather context first
+  - `/rcode-research-phase [N] ${RCODE_WS}` — investigate unknowns
+
+  ---
+  ```
+- **Advance to next phase** → ./transition.md (internal workflow, invoked inline — NOT a user command)
+- **Check todos** → Read .planning/todos/pending/, present summary
+- **Review alignment** → Read PROJECT.md, compare to current state
+- **Something else** → Ask what they need
+</step>
+
+<step name="update_session">
+Before proceeding to routed workflow, update session continuity:
+
+Update STATE.md:
+
+```markdown
+## Session Continuity
+
+Last session: [now]
+Stopped at: Session resumed, proceeding to [action]
+Resume file: [updated if applicable]
+```
+
+This ensures if session ends unexpectedly, next resume knows the state.
+</step>
+
+</process>
+
+<reconstruction>
+If STATE.md is missing but other artifacts exist:
+
+"STATE.md missing. Reconstructing from artifacts..."
+
+1. Read PROJECT.md → Extract "What This Is" and Core Value
+2. Read ROADMAP.md → Determine phases, find current position
+3. Scan \*-SUMMARY.md files → Extract decisions, concerns
+4. Count pending todos in .planning/todos/pending/
+5. Check for .continue-here files → Session continuity
+
+Reconstruct and write STATE.md, then proceed normally.
+
+This handles cases where:
+
+- Project predates STATE.md introduction
+- File was accidentally deleted
+- Cloning repo without full .planning/ state
+  </reconstruction>
+
+<quick_resume>
+If user says "continue" or "go":
+- Load state silently
+- Determine primary action
+- Execute immediately without presenting options
+
+"Continuing from [state]... [action]"
+</quick_resume>
+
+<success_criteria>
+Resume is complete when:
+
+- [ ] STATE.md loaded (or reconstructed)
+- [ ] Incomplete work detected and flagged
+- [ ] Clear status presented to user
+- [ ] Contextual next actions offered
+- [ ] User knows exactly where project stands
+- [ ] Session continuity updated
+      </success_criteria>
+
+## Next Up
+
+- `/rcode-next` — auto-advance to the next logical step
+- `/rcode-status` — review full project state after context is restored