@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/workflows/docs-update.md

@@ -0,0 +1,271 @@
+# Workflow: rcode-docs-update
+
+<purpose>
+Generate, update, and verify project documentation — both canonical doc types and existing hand-written docs. The orchestrator detects the project's doc structure, assembles a work manifest tracking every item, dispatches parallel doc-writer and doc-verifier agents across waves, reviews existing docs for accuracy, identifies documentation gaps, and fixes inaccuracies via a bounded fix loop. All state is persisted in a work manifest so no work item is lost between steps. Output: Complete, structure-aware documentation verified against the live codebase.
+</purpose>
+
+<available_agent_types>
+Valid rcode subagent types (use exact names — do not fall back to 'general-purpose'):
+- rcode-noor — Writes and updates project documentation files
+- rcode-docs-auditor — Verifies factual claims in docs against the live codebase
+</available_agent_types>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+- Print the usage block below
+- STOP — do not proceed
+
+**Usage:**
+```
+/rcode-docs-update [phase]
+```
+
+**Examples:**
+```
+/rcode-docs-update
+/rcode-docs-update 02
+```
+
+<process>
+
+## Step 1: Initialize context
+
+Initialize docs-update context by scanning the project:
+
+```bash
+# Create docs directory if needed
+test -d docs || mkdir -p docs
+
+# Read agent manifest to get model for doc writers
+AGENT_MANIFEST=".rcode/_config/agent-manifest.csv"
+if [[ -f "$AGENT_MANIFEST" ]]; then
+  DOC_WRITER_MODEL=$(grep -i "rcode-noor" "$AGENT_MANIFEST" | cut -d',' -f3)
+else
+  DOC_WRITER_MODEL="claude-opus"  # fallback
+fi
+```
+
+Extract from project analysis:
+- `doc_writer_model` — model string from agent manifest (never hardcode a model name)
+- `commit_docs` — whether to commit generated files when done (read from `.rcode/config.yaml` via `node rcode-tools.cjs config-get commit_docs`)
+- `response_language` — output language from `.rcode/config.yaml` (null = English); if set, include `Respond in {value}.` in all spawned subagent prompts
+- `existing_docs` — find all existing Markdown files with `find docs -name "*.md" 2>/dev/null`
+- `project_type` — detect from: `package.json`, `src/pages/api` or `pages/api`, `bin/` or `cli/`, `LICENSE`, `vercel.json` or `netlify.toml`, `lerna.json` or `pnpm-workspace.yaml`, `test/` or `__tests__/`
+- `doc_tooling` — detect from: `docusaurus.config.js`, `vitepress.config.js`, `mkdocs.yml`, `storybook.js`
+- `project_root` — `$(pwd)`
+
+## Step 2: Classify project
+
+Map the `project_type` boolean signals from the init JSON to a primary type label and collect conditional doc signals.
+
+**Primary type classification (first match wins):**
+
+| Condition | primary_type |
+|-----------|-------------|
+| `is_monorepo` is true | `"monorepo"` |
+| `has_cli_bin` is true AND `has_api_routes` is false | `"cli-tool"` |
+| `has_api_routes` is true AND `is_open_source` is false | `"saas"` |
+| `is_open_source` is true AND `has_api_routes` is false | `"open-source-library"` |
+| (none of the above) | `"generic"` |
+
+**Conditional doc signals (check independently after primary classification):**
+
+After determining primary_type, check each signal independently. A CLI tool that is also open source with API routes still gets all three conditional docs.
+
+| Signal | Conditional Doc |
+|--------|----------------|
+| `has_api_routes` is true | Queue API.md |
+| `is_open_source` is true | Queue CONTRIBUTING.md |
+| `has_deploy_config` is true | Queue DEPLOYMENT.md |
+
+Present the classification result:
+```
+Project type: {primary_type}
+Conditional docs queued: {list or "none"}
+```
+
+## Step 3: Build doc queue
+
+Assemble the complete doc queue from always-on docs plus conditional docs from Step 2.
+
+**Always-on docs (queued for every project):**
+1. README
+2. ARCHITECTURE
+3. GETTING-STARTED
+4. DEVELOPMENT
+5. TESTING
+6. CONFIGURATION
+
+**Conditional docs (add only if signal matched):**
+- API (if `has_api_routes`)
+- CONTRIBUTING (if `is_open_source`)
+- DEPLOYMENT (if `has_deploy_config`)
+
+**IMPORTANT: CHANGELOG.md is NEVER queued.** The doc queue is built exclusively from the 9 known doc types listed above.
+
+**Doc queue limit:** Maximum 9 docs. Always-on (6) + up to 3 conditional = at most 9.
+
+**CONTRIBUTING.md confirmation (new file only):**
+
+If CONTRIBUTING.md is in the conditional queue AND does NOT exist in `existing_docs`:
+
+1. If `--force` is present in `$ARGUMENTS`: skip confirmation, include CONTRIBUTING.md.
+2. Otherwise, use AskUserQuestion:
+
+```
+AskUserQuestion([{
+  question: "This project appears to be open source. CONTRIBUTING.md does not exist yet. Create it?",
+  header: "Contributing",
+  multiSelect: false,
+  options: [
+    { label: "Yes, create it", description: "Generate CONTRIBUTING.md with project guidelines" },
+    { label: "No, skip it", description: "This project does not need a CONTRIBUTING.md" }
+  ]
+}])
+```
+
+If user selects "No": remove CONTRIBUTING.md from the queue.
+
+## Step 4: Present queue and confirm
+
+Present the assembled doc queue to the user with confirmation:
+
+```
+AskUserQuestion([{
+  question: "Doc queue assembled ({N} docs). Proceed with generation?",
+  header: "Doc queue",
+  multiSelect: false,
+  options: [
+    { label: "Proceed", description: "Generate all {N} docs in the queue" },
+    { label: "Abort", description: "Cancel doc generation" }
+  ]
+}])
+```
+
+If user selects "Abort": exit the workflow.
+
+## Step 5: Spawn doc writers in waves
+
+Create output directories:
+```bash
+mkdir -p docs
+```
+
+For each doc in the queue, spawn a `rcode-noor` agent in parallel waves (up to 3 agents in parallel per wave):
+
+```
+Task(
+  subagent_type="rcode-noor",
+  model="{model}",
+  prompt="
+Generate documentation for {doc_type}.
+Output path: {resolved_path}
+Project type: {primary_type}
+Mode: {create|update}
+
+${EXISTING_CONTENT:+Existing content:\n${EXISTING_CONTENT}}
+
+Write the doc to: {resolved_path}
+Do NOT commit — the orchestrator will handle that.
+  "
+)
+```
+
+## Step 6: Verify generated docs
+
+After all doc writers complete, spawn `rcode-docs-auditor` agents to cross-check all generated content against the live codebase.
+
+For each generated doc:
+```
+Task(
+  subagent_type="rcode-docs-auditor",
+  model="{model}",
+  prompt="
+Verify this documentation file against the live codebase:
+Path: {resolved_path}
+
+Check for:
+- Outdated/incorrect information
+- References to non-existent files/modules
+- Version mismatches
+- API changes not reflected in docs
+
+Report any inaccuracies found. Do NOT fix — just report.
+  "
+)
+```
+
+## Step 7: Persist work manifest and close
+
+Write all work items to `.planning/tmp/docs-work-manifest.json`:
+
+```bash
+mkdir -p .planning/tmp
+# Write manifest with all generated docs, verification results, and any fixes needed
+```
+
+If `commit_docs` is enabled:
+```bash
+# Stage generated docs and commit
+git add docs/*.md
+git commit -m "docs: regenerate and verify project documentation"
+```
+
+```
+## Docs Update Complete
+
+**Project type:** {primary_type}
+**Docs generated:** {count}
+**Docs verified:** {count}
+**Issues found:** {count or "none"}
+
+Generated docs:
+{list with line counts}
+
+${ISSUES:+
+Issues to fix:
+{list}
+
+Run /rcode-docs-update --fix to auto-correct found issues.
+}
+
+Next: Review docs in your editor or run verification again with /rcode-docs-update
+```
+
+</process>
+
+<success_criteria>
+- [ ] Project type correctly classified
+- [ ] Doc queue assembled with always-on + conditional docs
+- [ ] CONTRIBUTING.md confirmation shown when appropriate
+- [ ] User confirmed queue before generation
+- [ ] Doc writers spawned in parallel waves
+- [ ] All docs generated and written to correct paths
+- [ ] Doc verifiers run and report inaccuracies
+- [ ] Work manifest persisted
+- [ ] Docs committed if enabled
+- [ ] Results presented with next steps
+</success_criteria>
+
+## Success Criteria
+
+- [ ] Project type correctly classified and doc queue assembled (always-on + conditional docs)
+- [ ] User confirmed the queue before generation began
+- [ ] `rcode-noor` doc-writer agents spawned in parallel waves; all docs written to their correct destination paths
+- [ ] `rcode-docs-auditor` agents run after writing; inaccuracies flagged and addressed by the fix loop
+- [ ] Work manifest persisted to `.planning/` so an interrupted run can resume without data loss
+- [ ] All generated docs committed when `commit_docs` config is enabled
+
+## 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-verify-work` — verify documentation accuracy against the live codebase
+- `/rcode-ship` — ship with updated docs once verification passes

package/rcode/workflows/document-project.md

@@ -0,0 +1,197 @@
+# Workflow: rcode-document-project
+
+<purpose>
+Load documentation-requirements.csv, audit current documentation for coverage and staleness, identify missing or outdated docs, and file them as SPRINT.md subtasks or separate plan phases.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rcode-document-project <argument-here>
+```
+
+**Examples:**
+```
+/rcode-document-project example 1
+/rcode-document-project example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+- `rcode-docs-auditor` — documentation compliance auditor
+</available_agent_types>
+
+## Step 0 — Initialize
+
+```bash
+INIT=$(node .rcode/bin/rcode-tools.cjs init document-project "$ARGUMENTS" 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. Verify .rcode/ is installed and state.json is valid.
+```
+
+Parse:
+- `flags.csv` — path to documentation-requirements.csv (default: `.rcode/documentation-requirements.csv`)
+- `flags.auto_file_tasks` — auto-create SPRINT.md for missing docs (default: false)
+- `csv_path` — resolved CSV path
+- `audit_output_path` — `.rcode/DOCS-AUDIT.md` (output)
+
+## Step 1 — Load or Create Documentation Requirements
+
+**If `csv_path` exists:**
+Load CSV and parse:
+
+```csv
+Document,Required,Priority,Audience,Last Updated,Status
+README.md,yes,high,all,2026-04-01,current
+API.md,yes,high,developers,2026-03-15,stale
+CONTRIBUTING.md,yes,medium,contributors,2026-02-01,missing
+DEPLOYMENT.md,yes,high,devops,2026-04-01,current
+ARCHITECTURE.md,yes,high,architects,2026-01-01,outdated
+```
+
+**If missing:** Create template at `.rcode/documentation-requirements.csv`:
+
+```bash
+cat > .rcode/documentation-requirements.csv << 'EOF'
+Document,Required,Priority,Audience,Last Updated,Status
+README.md,yes,high,all,,
+API.md,yes,high,developers,,
+CONTRIBUTING.md,yes,medium,contributors,,
+DEPLOYMENT.md,yes,high,devops,,
+ARCHITECTURE.md,yes,high,architects,,
+DEVELOPMENT.md,yes,medium,developers,,
+EOF
+```
+
+## Step 2 — Audit Current Documentation
+
+For each row in CSV, check if document exists and assess staleness:
+
+```bash
+for doc in $(cut -d',' -f1 .rcode/documentation-requirements.csv | tail -n +2); do
+  if [ -f "$doc" ]; then
+    MTIME=$(stat -c %Y "$doc" 2>/dev/null || stat -f %m "$doc" 2>/dev/null)
+    NOW=$(date +%s)
+    AGE_DAYS=$(( ($NOW - $MTIME) / 86400 ))
+    if [ $AGE_DAYS -gt 90 ]; then echo "STALE"; fi
+  else
+    echo "MISSING"
+  fi
+done
+```
+
+## Step 3 — Spawn Docs Auditor
+
+Spawn `rcode-docs-auditor` subagent:
+
+```
+Task tool call:
+  subagent_type: "rcode-docs-auditor"
+  description: "Audit documentation coverage and staleness"
+  prompt: |
+    Audit project documentation against requirements.
+    
+    **Requirements CSV:**
+    {csv_contents}
+    
+    **Audit findings:**
+    {per_doc_status}
+    
+    For each doc, determine:
+    - Status: Missing, Current, Stale (>90 days old), Outdated (references removed features)
+    - Priority: high/medium/low (from CSV)
+    - Estimated effort: 1-4 hours
+    - Who should write: audience from CSV
+    
+    Output format: DOCS-AUDIT.md with:
+    1. Summary table (doc, status, priority, effort)
+    2. Per-doc assessment and recommendations
+    3. Suggested documentation plan
+    
+    Write to: {audit_output_path}
+```
+
+## Step 4 — File Missing Docs as Tasks
+
+**If `flags.auto_file_tasks` is true:**
+
+For each missing or stale doc (status=Missing or Stale):
+
+Create task subtask in state:
+
+```bash
+node .rcode/bin/rcode-tools.cjs state add-task \
+  --title "Write {doc_name}: {purpose}" \
+  --description "Audience: {audience}, Priority: {priority}" \
+  --effort {effort_hours} \
+  --component documentation
+```
+
+Create SPRINT.md if multiple docs needed:
+
+File: `.planning/plans/documentation-updates/SPRINT.md`
+
+```markdown
+# Plan: Documentation Updates
+
+{doc_1_task}
+{doc_2_task}
+...
+```
+
+Print:
+```
+📋 Documentation audit complete: {audit_output_path}
+
+Summary:
+  • {current_count} current
+  • {stale_count} stale (>90 days)
+  • {missing_count} missing
+
+Missing docs filed as tasks. Run:
+
+/rcode-plan .planning/plans/documentation-updates/SPRINT.md
+```
+
+## Step 5 — Auto-inject into Resume-Work
+
+After audit, if resume-work.md exists, prepend to Step 2:
+
+```
+If .rcode/DOCS-AUDIT.md exists, check for missing/stale docs:
+
+<!-- DOCS-AUDIT.md is generated at runtime by rcode-tools.cjs docs-audit — not a tracked file -->
+```
+
+## Success Criteria
+
+- CSV loaded or created
+- All docs in CSV audited for presence/staleness
+- DOCS-AUDIT.md generated with per-doc assessment
+- Missing/stale docs categorized by priority
+- (Optional) Tasks filed in state or SPRINT.md created
+
+## On Error
+
+- If CSV malformed: use template
+- If audit agent fails: provide manual audit template
+- If state write fails: skip task filing, report audit only
+
+## ▶ Next Up
+
+- /rcode-progress
+- /rcode-plan {phase}
+- /rcode-council {question}
+
+## Next Up
+
+- `/rcode-docs-update` — generate or regenerate the documentation
+- `/rcode-plan` — plan documentation phases identified by the audit

package/rcode/workflows/edit-prd.md

@@ -0,0 +1,36 @@
+# Workflow: rcode-edit-prd
+
+<purpose>
+Update an existing PRD with revisions or clarifications. Delegates to the rcode-edit-prd skill.
+</purpose>
+
+## Execution
+
+Locate and follow the installed skill:
+
+```bash
+find .rcode/skills/actions -path "*rcode-edit-prd/workflow.md" 2>/dev/null | head -1
+```
+
+Read and follow the workflow at that path. If the path is empty:
+
+```
+Skill not installed — run: npx @hanzlaa/rcode install
+```
+
+## On Completion
+
+/rcode-validate-prd — validate after edits
+/rcode-plan — re-plan phases from the updated PRD
+/rcode-create-prd — start fresh if edits are too extensive
+
+## ▶ Next Up
+
+- /rcode-validate-prd
+- /rcode-new-milestone
+- /rcode-create-epics-and-stories
+
+## Next Up
+
+- `/rcode-validate-prd` — validate the updated PRD for completeness
+- `/rcode-plan` — re-plan phases if scope changed

package/rcode/workflows/enable-hooks.md

@@ -0,0 +1,112 @@
+# Workflow: rcode-enable-hooks
+
+<purpose>
+Merge rcode opt-in hooks from settings-hooks.json into .claude/settings.json. Creates settings.json if missing. Enables all 8 guardrails: pre-edit (read-before-edit check), pre-workflow (command hint), post-commit (format validation), bash-guard (blocks dangerous commands), pre-compact (refreshes HANDOFF.json before context compaction), stop-verify (syntax-checks files changed during the response), cost-track (logs measured token usage to .rcode/telemetry/cost.jsonl), and compact-nudge (advises /rcode-trim or /clear after many edits).
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rcode-enable-hooks <argument-here>
+```
+
+**Examples:**
+```
+/rcode-enable-hooks example 1
+/rcode-enable-hooks example 2
+```
+
+STOP — do not proceed.
+
+## Step 1 — Load hooks template
+
+```bash
+cat .rcode/templates/settings-hooks.json
+```
+
+Parse the JSON. If file does not exist, print error and stop:
+
+```
+Error: .rcode/templates/settings-hooks.json not found. Run 'npx @hanzlaa/rcode install' to reinstall.
+```
+
+## Step 2 — Load or create settings.json
+
+Check if `.claude/settings.json` exists in the project root.
+
+- **If it exists:** Read and parse it. Merge incoming hooks into the existing `hooks` object (or create if missing).
+- **If it does not exist:** Create a minimal settings.json with the hooks from step 1.
+
+If `.claude/` directory does not exist, create it first.
+
+## Step 3 — Merge hooks
+
+For each hook type (`PreToolUse`, `PostToolUse`):
+
+- If the hook type does not exist in the current settings.json, add it.
+- If it exists, append the new matchers and hook commands (avoid duplicates by checking for exact command matches).
+
+**Duplicate detection:** If a matcher + command pair already exists, skip it.
+
+## Step 4 — Write merged settings.json
+
+Write the merged settings.json back to `.claude/settings.json` with proper JSON formatting (2-space indent).
+
+## Step 5 — Verify hook binary
+
+Verify that the hook binary exists and is executable:
+
+```bash
+if [ ! -f .rcode/bin/rcode-hooks.cjs ]; then
+  echo "⚠ Hook binary missing at .rcode/bin/rcode-hooks.cjs"
+  echo "  Run: npx @hanzlaa/rcode install --force --yes"
+  exit 1
+fi
+node .rcode/bin/rcode-hooks.cjs --help 2>&1 || true
+```
+
+If the binary is missing, print error and stop. Otherwise, test it with `--help` (ignore exit code).
+
+## Step 5.5 — Print confirmation
+
+Print success message:
+
+```
+✓ rcode hooks installed to .claude/settings.json
+
+Enabled guardrails:
+  • pre-edit: Verifies files are Read() before Edit/Write
+  • pre-workflow: Warns if rcode-* commands look suspicious
+  • post-commit: Validates commit format and bans "Generated with Claude" patterns
+  • bash-guard: Blocks unapproved git push, --force, --no-verify, and unscoped rm -rf
+  • pre-compact: Refreshes HANDOFF.json before context compaction
+  • stop-verify: Syntax-checks files changed during the response
+  • cost-track: Logs measured token usage to .rcode/telemetry/cost.jsonl
+  • compact-nudge: Advises /rcode-trim or /clear after many edits
+
+To disable, remove the hooks section from .claude/settings.json or edit .rcode/templates/settings-hooks.json and re-run.
+```
+
+## Success Criteria
+
+- [ ] `.claude/settings.json` created or updated with hooks merged
+- [ ] No duplicate hook entries in merged settings
+- [ ] File written with valid JSON formatting
+- [ ] Confirmation message printed to user
+
+## On Error
+
+- **Template not found:** print error and stop (Step 1).
+- **`.claude/` directory creation fails:** print error and stop.
+- **state.json missing:** continue without error — hooks installation is standalone.
+- **settings.json has invalid JSON:** print error with path and stop.
+- **Permission denied writing .claude/settings.json:** print error and stop.
+- **Merge produces duplicate hooks:** skip duplicates (Step 3).
+
+## Next Up
+
+- `/rcode-settings` — configure additional project settings
+- `/rcode-do` — continue with guardrails now active