@hanzlaa/rcode 3.6.15 → 4.0.0

package/rcode/workflows/map-codebase.md

@@ -0,0 +1,466 @@
+<purpose>
+Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
+
+Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</purpose>
+
+<required_reading>
+@.rcode/references/output-format.md
+</required_reading>
+
+<output_format>
+Open with banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► MAPPING CODEBASE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use TaskCreate at start:
+- TaskCreate: "Spawn 4 parallel codebase mappers"
+- TaskCreate: "Assemble and commit codebase map"
+
+Spawn indicators as each of the 4 agents completes:
+```
+◆ Spawning 4 mappers in parallel...
+  → Map tech stack and integrations
+  → Map architecture and structure
+  → Map conventions and testing
+  → Map concerns and technical debt
+
+✓ Agent "Map tech stack" completed — STACK.md (324 lines)
+✓ Agent "Map architecture" completed — ARCHITECTURE.md (412 lines)
+✓ Agent "Map conventions" completed — CONVENTIONS.md (198 lines)
+✓ Agent "Map concerns" completed — CONCERNS.md (276 lines)
+```
+
+End with closure banner + top findings summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► CODEBASE MAPPED ✓  ({total} lines across {N} docs)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</output_format>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rcode-map-codebase <argument-here>
+```
+
+**Examples:**
+```
+/rcode-map-codebase example 1
+/rcode-map-codebase example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+Valid rcode subagent types (use exact names — do not fall back to 'general-purpose'):
+- rcode-codebase-mapper — Maps project structure and dependencies
+</available_agent_types>
+
+<philosophy>
+**Why dedicated mapper agents:**
+- Fresh context per domain (no token contamination)
+- Agents write documents directly (no context transfer back to orchestrator)
+- Orchestrator only summarizes what was created (minimal context usage)
+- Faster execution (agents run simultaneously)
+
+**Document quality over length:**
+Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
+
+**Always include file paths:**
+Documents are reference material for the agent when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
+</philosophy>
+
+<process>
+
+<step name="init_context" priority="first">
+Load codebase mapping context:
+
+```bash
+INIT=$(node .rcode/bin/rcode-tools.cjs init map-codebase 2>/dev/null)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_MAPPER=$(node .rcode/bin/rcode-tools.cjs agent-skills rcode-codebase-mapper 2>/dev/null || echo "")
+```
+
+If `INIT` is empty or `INIT.ok` is false, print error and exit:
+```
+Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
+```
+
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `response_language`.
+
+**If `response_language` is set:** include `Respond in {response_language}.` in all spawned subagent prompts.
+</step>
+
+<step name="check_existing">
+Check if .planning/codebase/ already exists using `has_maps` from init context.
+
+If `codebase_dir_exists` is true:
+```bash
+ls -la .planning/codebase/
+```
+
+**If exists:**
+
+```
+.planning/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Update - Keep existing, only update specific documents
+3. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .planning/codebase/, continue to create_structure
+If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .planning/codebase/ directory:
+
+```bash
+mkdir -p .planning/codebase
+```
+
+**Expected output files:**
+- STACK.md (from tech mapper)
+- INTEGRATIONS.md (from tech mapper)
+- ARCHITECTURE.md (from arch mapper)
+- STRUCTURE.md (from arch mapper)
+- CONVENTIONS.md (from quality mapper)
+- TESTING.md (from quality mapper)
+- CONCERNS.md (from concerns mapper)
+
+Continue to spawn_agents.
+</step>
+
+<step name="detect_runtime_capabilities">
+Before spawning agents, detect whether the current runtime supports the `Task` tool for subagent delegation.
+
+**How to detect:** Check if you have access to a `Task` tool (may be capitalized as `Task` or lowercase as `task` depending on runtime). If you do NOT have a `Task`/`task` tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis):
+
+→ **Skip `spawn_agents` and `collect_confirmations`** — go directly to `sequential_mapping` instead.
+
+**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `Task`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `Task` is unavailable, perform the mapping sequentially in-context.
+</step>
+
+<step name="spawn_agents" condition="Task tool is available">
+Spawn 4 parallel rcode-codebase-mapper agents.
+
+Use Task tool with `subagent_type="rcode-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
+
+**CRITICAL:** Use the dedicated `rcode-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly.
+
+**Agent 1: Tech Focus**
+
+```
+Task(
+  subagent_type="rcode-codebase-mapper",
+  model="{model}",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase tech stack",
+  prompt="Focus: tech
+
+Analyze this codebase for technology stack and external integrations.
+
+Write these documents to .planning/codebase/:
+- STACK.md - Languages, runtime, frameworks, dependencies, configuration
+- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+**Agent 2: Architecture Focus**
+
+```
+Task(
+  subagent_type="rcode-codebase-mapper",
+  model="{model}",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase architecture",
+  prompt="Focus: arch
+
+Analyze this codebase architecture and directory structure.
+
+Write these documents to .planning/codebase/:
+- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
+- STRUCTURE.md - Directory layout, key locations, naming conventions
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+**Agent 3: Quality Focus**
+
+```
+Task(
+  subagent_type="rcode-codebase-mapper",
+  model="{model}",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase conventions",
+  prompt="Focus: quality
+
+Analyze this codebase for coding conventions and testing patterns.
+
+Write these documents to .planning/codebase/:
+- CONVENTIONS.md - Code style, naming, patterns, error handling
+- TESTING.md - Framework, structure, mocking, coverage
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+**Agent 4: Concerns Focus**
+
+```
+Task(
+  subagent_type="rcode-codebase-mapper",
+  model="{model}",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase concerns",
+  prompt="Focus: concerns
+
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+Write this document to .planning/codebase/:
+- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
+
+Explore thoroughly. Write document directly using template. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+Continue to collect_confirmations.
+</step>
+
+<step name="collect_confirmations">
+Wait for all 4 agents to complete using TaskOutput tool.
+
+**For each agent task_id returned by the Agent tool calls above:**
+```
+TaskOutput tool:
+  task_id: "{task_id from Agent result}"
+  block: true
+  timeout: 300000
+```
+
+Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
+
+Once all TaskOutput calls return, read each agent's output file to collect confirmations.
+
+**Expected confirmation format from each agent:**
+```
+## Mapping Complete
+
+**Focus:** {focus}
+**Documents written:**
+- `.planning/codebase/{DOC1}.md` ({N} lines)
+- `.planning/codebase/{DOC2}.md` ({N} lines)
+
+Ready for orchestrator summary.
+```
+
+**What you receive:** Just file paths and line counts. NOT document contents.
+
+If any agent failed, note the failure and continue with successful documents.
+
+Continue to verify_output.
+</step>
+
+<step name="sequential_mapping" condition="Task tool is NOT available (e.g. environments that do not support parallel subagents)">
+When the `Task` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`.
+
+**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (Read, Bash, Write, Grep, Glob, list_dir, view_file, grep_search, or equivalent tools available in your runtime).
+
+Perform all 4 mapping passes sequentially:
+
+**Pass 1: Tech Focus**
+- Explore package.json/Cargo.toml/go.mod/requirements.txt, config files, dependency trees
+- Write `.planning/codebase/STACK.md` — Languages, runtime, frameworks, dependencies, configuration
+- Write `.planning/codebase/INTEGRATIONS.md` — External APIs, databases, auth providers, webhooks
+
+**Pass 2: Architecture Focus**
+- Explore directory structure, entry points, module boundaries, data flow
+- Write `.planning/codebase/ARCHITECTURE.md` — Pattern, layers, data flow, abstractions, entry points
+- Write `.planning/codebase/STRUCTURE.md` — Directory layout, key locations, naming conventions
+
+**Pass 3: Quality Focus**
+- Explore code style, error handling patterns, test files, CI config
+- Write `.planning/codebase/CONVENTIONS.md` — Code style, naming, patterns, error handling
+- Write `.planning/codebase/TESTING.md` — Framework, structure, mocking, coverage
+
+**Pass 4: Concerns Focus**
+- Explore TODOs, known issues, fragile areas, security patterns
+- Write `.planning/codebase/CONCERNS.md` — Tech debt, bugs, security, performance, fragile areas
+
+Use the same document templates as the `rcode-codebase-mapper` agent. Include actual file paths formatted with backticks.
+
+Continue to verify_output.
+</step>
+
+<step name="verify_output">
+Verify all documents created successfully:
+
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
+
+**Verification checklist:**
+- All 7 documents exist
+- No empty documents (each should have >20 lines)
+
+If any documents missing or empty, note which agents may have failed.
+
+Continue to scan_for_secrets.
+</step>
+
+<step name="scan_for_secrets">
+**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
+
+Run secret pattern detection:
+
+```bash
+# Check for common API key patterns in generated docs
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**If SECRETS_FOUND=true:**
+
+```
+⚠️  SECURITY ALERT: Potential secrets detected in codebase documents!
+
+Found patterns that look like API keys or tokens in:
+[show grep output]
+
+This would expose credentials if committed.
+
+**Action required:**
+1. Review the flagged content above
+2. If these are real secrets, they must be removed before committing
+3. Consider adding sensitive files to Claude Code "Deny" permissions
+
+Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
+```
+
+Wait for user confirmation before continuing to commit_codebase_map.
+
+**If SECRETS_FOUND=false:**
+
+Continue to commit_codebase_map.
+</step>
+
+<step name="commit_codebase_map">
+Commit the codebase map:
+
+```bash
+node .rcode/bin/rcode-tools.cjs commit "docs: map existing codebase" --files .planning/codebase/*.md
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps.
+
+**Get line counts:**
+```bash
+wc -l .planning/codebase/*.md
+```
+
+**Output format:**
+
+```
+Codebase mapping complete.
+
+Created .planning/codebase/:
+- STACK.md ([N] lines) - Technologies and dependencies
+- ARCHITECTURE.md ([N] lines) - System design and patterns
+- STRUCTURE.md ([N] lines) - Directory layout and organization
+- CONVENTIONS.md ([N] lines) - Code style and patterns
+- TESTING.md ([N] lines) - Test structure and practices
+- INTEGRATIONS.md ([N] lines) - External services and APIs
+- CONCERNS.md ([N] lines) - Technical debt and issues
+
+
+---
+
+## ▶ Next Up
+
+**Initialize project** — use codebase context for planning
+
+`/rcode-new-project`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Re-run mapping: `/rcode-map-codebase`
+- Review specific file: `cat .planning/codebase/STACK.md`
+- Edit any document before proceeding
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .planning/codebase/ directory created
+- If Task tool available: 4 parallel rcode-codebase-mapper agents spawned with run_in_background=true
+- If Task tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent)
+- All 7 codebase documents exist
+- No empty documents (each should have >20 lines)
+- Clear completion summary with line counts
+- User offered clear next steps in rcode style
+</success_criteria>
+
+## Success Criteria
+
+- [ ] `.planning/codebase/` directory created if it did not exist
+- [ ] Four `rcode-codebase-mapper` agents spawned in parallel (or sequentially when Task tool is unavailable)
+- [ ] All 7 codebase documents exist in `.planning/codebase/` with more than 20 lines each — no empty documents
+- [ ] Completion summary printed with document names and line counts
+- [ ] User offered clear next-step commands after mapping completes
+
+## On Error
+
+If arguments are invalid, missing files, or subagent fails:
+- Validate inputs match expected format
+- Check that required files exist
+- Retry with clearer arguments or report the specific error to the user
+
+
+## Next Up
+
+- `/rcode-plan` — plan improvements informed by the codebase analysis
+- `/rcode-scan` — run a targeted scan on a specific area

package/rcode/workflows/memory-audit.md

@@ -0,0 +1,150 @@
+# Workflow: rcode-memory-audit
+
+<purpose>
+Audit the Memory Bank for stale entries, contradictions, missing sections, and content that should be archived. Read-only by default with severity-tagged report; `--fix` patches trivial items per Phase 6 D-1 / D-2.
+</purpose>
+
+Audit the Memory Bank. Default mode is read-only (severity-tagged report).
+Optional `--fix` flag patches trivial items in place per Phase 6 D-1 / D-2.
+
+---
+
+## Inputs
+
+None required.
+
+Optional flags:
+- `--severity {critical|warn|info}` — filter report output
+- `--fix` — opt-in auto-fix mode. Patches only items the auditor classifies
+  as severity=trivial (typos, stale ISO dates, broken relative paths,
+  factually-wrong-and-mechanically-correctable values). Hard-allowlisted
+  in code: items above trivial are never patched. Default OFF.
+
+```bash
+FIX_MODE=false
+if [[ "$ARGUMENTS" =~ (^|[[:space:]])--fix($|[[:space:]]) ]]; then
+  FIX_MODE=true
+fi
+```
+
+## Preconditions
+
+- `.rcode/memory/INDEX.md` exists
+
+## Halt conditions
+
+- Memory Bank not initialised → instruct to run `/rcode-memory-init` first
+
+---
+
+## Steps
+
+### Step 1 — Catalogue files
+
+Walk `.rcode/memory/` and build a list of every file plus its size and modification time. Include `.gitkeep` files for empty-subdir detection.
+
+### Step 2 — Check 1: Stale milestone
+
+Read `milestones/current.md`. Parse the "Target close" date. If `(today - target_close).days >= 30`, emit a `warn` finding.
+
+### Step 3 — Check 2: Resolved issues lingering
+
+For each entry in `incidents/known-issues.md`:
+- Parse "Real fix planned for" field
+- If it names a milestone that has been moved to `milestones/archive/`, emit a `warn` finding
+
+### Step 4 — Check 3: Template placeholders unfilled
+
+For each `*.md` file under `.rcode/memory/`:
+- Count occurrences of `{{` literally (template placeholders)
+- Count occurrences of `_(e.g.` (italicised template hints)
+- If either is non-zero, emit an `info` finding listing the file and count
+
+### Step 5 — Check 4: Stack vs decisions contradiction
+
+For each decision entry in `project/decisions.md` that mentions a technology name:
+- Extract candidate tech terms (proper nouns, capitalised + version)
+- Search `project/stack.md` for the term
+- If not found, emit a `critical` finding
+
+### Step 6 — Check 5: Empty subdirectories
+
+For `change-records/`, `incidents/post-mortems/`, `milestones/archive/`:
+- If only file is `.gitkeep`, emit an `info` finding (not a problem, just visibility)
+
+### Step 7 — Check 6: Distillate freshness
+
+For each `distillates/*.distillate.md`:
+- Read frontmatter `source-digest`
+- Recompute digest of current source files (per `rcode-memory-distill` rules)
+- If mismatch, emit a `warn` finding suggesting `/rcode-memory-distill`
+
+### Step 8 — Render report
+
+Group findings by severity (critical → warn → info), then by file within each severity group. For each finding, print:
+- File path
+- One-line description
+- One-line `Fix:` suggestion (which skill to run, or manual action)
+
+If `--severity` filter passed, hide findings below the threshold.
+
+If zero findings: print `✓ Memory Bank is healthy. 0 findings.`
+
+### Step 9 — Apply fixes (only when `--fix` is set)
+
+<step name="apply_fixes">
+Skip if `FIX_MODE` is false.
+
+For each finding from the audit:
+- If severity is `trivial` (typo, stale ISO date, dead relative path,
+  provably-wrong factual value with an unambiguous replacement), patch in place.
+- For all other severities (`info`, `warn`, `critical`), leave for human review
+  and keep them in the report — never patch.
+
+Patching rule (HARD): use file Read+Edit (NOT regex sed) so fixes are exact
+string replacements that fail loudly on ambiguity. Sed-based mass-replace is
+forbidden because it silently rewrites unintended occurrences.
+
+Atomic commit per fix:
+
+```bash
+git add <file>
+git commit -m "fix(memory): <what was stale> → <what's true now>"
+```
+
+After the loop, log: `Memory --fix applied {N} trivial corrections across {M} commits.`
+
+If a finding marked trivial fails to patch (file changed mid-flight, ambiguous
+replacement, etc.), log it under "Skipped fixes" in the final report and
+continue with the next finding — never abort the whole run on a single failure.
+</step>
+
+---
+
+## Guardrails
+
+- `--fix` NEVER patches above trivial severity, even with a `--force` flag (don't accept --force here)
+- `--fix` uses Read+Edit, not regex sed
+- `--fix` commits each correction atomically (no batched commits)
+- Default behavior (no `--fix`) is unchanged: report-only
+
+## Post-conditions
+
+- When `--fix` is OFF: no files modified; report printed to stdout
+- When `--fix` is ON: only trivial items modified; each as its own commit; report still printed
+
+## Reversibility
+
+- Default mode: read-only — no state to revert.
+- `--fix` mode: each fix is its own atomic git commit, so individual fixes can be reverted with `git revert <hash>`.
+
+## Success criteria
+
+- [ ] Default behavior unchanged — `--fix` off by default; report-only path preserved
+- [ ] `--fix` patches only trivial items, each as atomic commit prefixed `fix(memory):`
+- [ ] Report still printed even in `--fix` mode (so user sees what was/wasn't patched)
+
+## Next Up
+
+- `/rcode-memory-update` — patch stale entries surfaced by the audit
+- `/rcode-memory-distill` — regenerate distillates after updating entries