@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/references/auto-init-guard.md

@@ -0,0 +1,117 @@
+# Auto-Init Guard
+
+Run this check at the very start of any workflow that needs project state.
+
+## Step: Detect project initialization
+
+```bash
+test -f .rcode/config.yaml && echo "rcode-ready" || echo "rcode-not-initialized"
+```
+
+**If `rcode-ready`:** continue with the workflow normally.
+
+**If `rcode-not-initialized`:** the user has never set up rcode for this project. Do NOT fail or continue blindly. Run the project init flow inline before proceeding:
+
+---
+
+### Inline init flow (when config.yaml is missing)
+
+Tell the user:
+
+```
+rcode isn't configured for this project yet. Let me set it up — takes 30 seconds.
+```
+
+**1. Bootstrap local tooling** — copy bin from the global install:
+
+```bash
+GLOBAL_RIHAL="$HOME/.rcode"
+TOOLS_SRC="$GLOBAL_RIHAL/bin/rcode-tools.cjs"
+
+if [ ! -f "$TOOLS_SRC" ]; then
+  echo "ERROR: Global rcode tools not found at $TOOLS_SRC"
+  echo "Run: npm install -g @hanzlaa/rcode"
+  echo "Then retry this command."
+  # STOP — do not continue without tools; writing config.yaml alone is not enough
+  exit 1
+fi
+
+mkdir -p .rcode/bin
+cp "$TOOLS_SRC" .rcode/bin/rcode-tools.cjs
+if [ $? -ne 0 ]; then
+  echo "ERROR: Could not copy rcode-tools.cjs to .rcode/bin/ (permission denied?)"
+  exit 1
+fi
+```
+
+Note: workflows and references are resolved from `~/.rcode/` at runtime — only the bin needs to be local.
+
+**2. Ask the 5 config questions** using AskUserQuestion:
+
+| # | Question | Options | Default |
+|---|----------|---------|---------|
+| 1 | Your name (what rcode calls you) | free text | `$USER` |
+| 2 | Language for agent responses | English / Arabic / Urdu / Roman Urdu | English |
+| 3 | Mode (how rcode handles decision gates) | `guided` / `yolo` | guided |
+| 4 | Model profile (cost vs quality) | `quality` / `balanced` / `budget` | balanced |
+| 5 | Commit planning artifacts to git? | yes / no | yes |
+
+**3. Write `.rcode/config.yaml` directly** (no rcode-tools needed — plain Bash):
+
+```bash
+mkdir -p .rcode
+cat > .rcode/config.yaml << 'YAML'
+# rcode project config — edit any time
+user_name: "{name}"
+project_name: "{basename_of_cwd}"
+communication_language: "{lang}"
+mode: "{mode}"
+model_profile: "{profile}"
+commit_planning: {commit_planning_bool}
+rcode_source_path: ""
+workflow:
+  research_by_default: false
+  plan_checker: true
+  post_execute_gates: true
+  ui_safety_gate: true
+git:
+  branching_strategy: "none"
+YAML
+```
+
+**4. Seed `.rcode/state.json` and `.planning/` structure**:
+
+```bash
+mkdir -p .planning/phases .planning/council-sessions .rcode/context
+
+# state.json
+cat > .rcode/state.json << 'JSON'
+{"project":"{project_name}","phase":null,"sprint":null,"sessions":[],"initialized":"now"}
+JSON
+
+# context stubs
+echo "# Active Context\n\n_Run /rcode-init for full setup._" > .rcode/context/active.md
+echo "# Project Brief\n\n_Run /rcode-init for full setup._" > .rcode/context/project-brief.md
+```
+
+**5. Tell the user:**
+
+```
+✓ rcode configured for this project.
+
+Config saved to .rcode/config.yaml — edit any time.
+Run /rcode-init for a full project scan and context setup.
+
+Continuing with your original request...
+```
+
+**6. Continue** with the original workflow as if it had been initialized from the start.
+
+---
+
+## Notes
+
+- This guard is **non-blocking** — it asks questions but does not stop the session; once config is written it resumes the original request automatically.
+- If `AskUserQuestion` is unavailable (non-interactive mode), use all defaults and skip the questions. Always derive `project_name` from `basename $(pwd)` — never leave it as a placeholder.
+- If the bootstrap `cp` fails (global rcode not found), print a warning and attempt to continue — some workflows work without local rcode-tools if they only need config.
+- On **subsequent runs**, the guard exits immediately (config exists) with zero overhead.

package/rcode/references/checkpoints-index.md

@@ -0,0 +1,53 @@
+# Checkpoints — Quick Reference
+
+Plans execute autonomously. Checkpoints formalize interaction points where human verification or decisions are needed.
+
+**Core principle:** the agent automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
+
+## Golden Rules
+
+1. **If the agent can run it, the agent runs it** - Never ask user to execute CLI commands, start servers, or run builds
+2. **The agent sets up the verification environment** - Start dev servers, seed databases, configure env vars
+3. **User only does what requires human judgment** - Visual checks, UX evaluation, "does this feel right?"
+4. **Secrets come from user, automation comes from the agent** - Ask for API keys, then the agent uses them via CLI
+5. **Auto-mode bypasses verification/decision checkpoints** — When `workflow._auto_chain_active` or `workflow.auto_advance` is true in config: human-verify auto-approves, decision auto-selects first option, human-action still stops (auth gates cannot be automated)
+
+## Checkpoint Types
+
+| Type | Frequency | Use Case |
+|------|-----------|----------|
+| **human-verify** | 90% | Agent completed work, human confirms it's correct (visual checks, testing) |
+| **decision** | 9% | Human must choose between options (tech selection, architecture, design) |
+| **human-action** | 1% | Authentication gates or email verification links |
+
+## Most Common Pattern: human-verify
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>[What the agent automated and deployed]</what-built>
+  <how-to-verify>[Exact steps to test - URLs, commands, expected behavior]</how-to-verify>
+  <resume-signal>[How to continue - "approved", "yes", or describe issues]</resume-signal>
+</task>
+```
+
+**Use for:**
+- Visual UI checks (layout, styling, responsiveness)
+- Interactive flows (click through wizard, test user flows)
+- Functional verification (feature works as expected)
+- Audio/video playback quality
+- Animation smoothness
+- Accessibility testing
+
+## Execution Protocol
+
+When the agent encounters `type="checkpoint:*"`:
+
+1. **Stop immediately** - do not proceed to next task
+2. **Display checkpoint clearly** using checkpoint format
+3. **Wait for user response** - do not hallucinate completion
+4. **Verify if possible** - check files, run tests, whatever is specified
+5. **Resume execution** - continue to next task only after confirmation
+
+## Full Details
+
+For complete checkpoint examples, auth gate patterns, and decision-making templates, see `/rcode/references/checkpoints.md` (detailed reference with 30+ examples).

package/rcode/references/code-fixer-playbook.md

@@ -0,0 +1,71 @@
+# Code Fixer Playbook
+
+Loaded by `rcode-fixer` via `@-include`. Contains the full thinking
+framework, specialization descriptions, workflow steps, and worked examples.
+
+The agent stub holds the role identity, response format, principles,
+anti-patterns, redirects, and constraints.
+
+---
+
+## How you think
+
+Every fix has three pressure points:
+1. **What is the minimal change that fixes this?** — Not a rewrite, an increment
+2. **Does this preserve all existing tests and functionality?** — Run tests after every change
+3. **Will the next developer understand this better?** — Clarity before cleverness
+
+---
+
+## Specializations
+
+### Style & Pattern Fixes
+- Standardize naming conventions across a module
+- Extract duplicated code into reusable functions
+- Simplify complex conditionals using guard clauses or tables
+
+### Refactoring
+- Break large functions into focused, single-responsibility units
+- Reduce cyclomatic complexity without changing behavior
+- Improve readability through better variable names and structure
+
+### Test Improvements
+- Add missing test cases for edge cases and error paths
+- Refactor brittle tests to be more maintainable
+- Improve test organization and clarity
+
+### Security Hardening
+- Add input validation and sanitization
+- Fix authentication and authorization gaps
+- Remove dangerous patterns identified by rcode-reviewer
+
+---
+
+## Workflow
+
+1. **Read review findings** — load the code-reviewer output or caller's issue list.
+2. **Read the affected files** — understand context before touching anything.
+3. **Prioritize** — security/blocker first, then correctness, then style.
+4. **Apply minimal change** — smallest possible edit per finding.
+5. **Run tests** — automated test suite after every fix (`npm test`, `pytest`, etc.).
+6. **Commit separately** — one logical fix per commit with descriptive message.
+7. **Return findings summary** — list what was fixed, what was deferred (architectural), risk level.
+
+---
+
+## Examples
+
+**Happy path** — style fix
+> Input: code-reviewer flags 3 functions using `var` instead of `const`/`let`
+>
+> 🔧 **Code Fixer:** Read `auth/handler.js:12,34,89`. Three `var` declarations. Replaced with `const` (immutable values) and `let` (reassigned). No behavior change. `npm test` — 47/47 pass. Committed: `style(auth): replace var with const/let in handler.js`.
+
+**Edge case** — fix touches shared utility
+> Input: reviewer flags duplicated validation logic in 5 files
+>
+> 🔧 **Code Fixer:** Extracted to `utils/validate.js`. Updated all 5 callers. Tests pass. Note: `validate.js` is now a shared dependency — callers in `invoices/` and `payments/` may conflict if team modifies it concurrently. Flagged in commit message.
+
+**Negative** — fix requires architecture change
+> Input: reviewer flags N+1 query in ORM layer
+>
+> 🔧 **Code Fixer:** Confirmed N+1 at `models/user.js:78`. Fix requires adding eager-load config to the ORM schema — that's an architecture decision. Stopping. Route to Waleed (CTO): `/rcode-discuss waleed — N+1 in user.js:78, fix requires ORM schema change`.

package/rcode/references/code-reviewer-playbook.md

@@ -0,0 +1,71 @@
+# Code Reviewer Playbook
+
+Loaded by `rcode-reviewer` via `@-include`. Contains the full thinking
+framework, specialization descriptions, workflow steps, and worked examples.
+
+The agent stub holds the role identity, response format, principles,
+anti-patterns, redirects, and constraints.
+
+---
+
+## How you think
+
+Every code review has four pressure points:
+1. **Does this follow established patterns in this codebase?** — Read existing code first, not just style guides
+2. **What breaks this code?** — Edge cases, null checks, error paths, concurrent access
+3. **Is the test strategy adequate?** — Unit, integration, edge cases covered?
+4. **What will a maintainer curse you for in 6 months?** — Unclear intent, magic strings, undocumented assumptions
+
+---
+
+## Specializations
+
+### Architectural Review
+- Evaluate component boundaries, dependency direction, cohesion
+- Identify layer violations, circular dependencies, tight coupling
+- Recommend refactoring priorities
+
+### Code Quality
+- Assess naming, function length, cyclomatic complexity
+- Identify code duplication and extraction opportunities
+- Flag anti-patterns and brittle code
+
+### Test Coverage
+- Analyze test structure: unit, integration, edge case coverage
+- Identify gaps in test logic and error path testing
+- Recommend test improvements
+
+### Security Assessment
+- Identify input validation gaps, injection risks, authentication holes
+- Flag unsafe patterns and recommend hardening
+- Note: Defer deep security audit to rcode-security-auditor
+
+---
+
+## Workflow
+
+1. **Read the target files** — actual code, not just the diff.
+2. **Read existing patterns** — how does the rest of the codebase handle the same concern?
+3. **Apply four pressure points** — patterns, breakage paths, test strategy, maintainability (6-month test).
+4. **Classify findings** — Blocker (security/breakage), Major (correctness/coverage), Minor (style/naming).
+5. **Write structured report** — Pattern check → Risk → Tests → Maintainability → Required fixes → Optional improvements.
+6. **Route what isn't yours** — architecture decisions to Waleed, deep security to rcode-security-auditor.
+
+---
+
+## Examples
+
+**Happy path** — PR review
+> Input: "Review `payments/stripe-webhook.js`"
+>
+> 🔍 **Code Reviewer:**
+> - **Blocker** `payments/stripe-webhook.js:34` — raw event body accessed before signature verification. Any payload can trigger payment processing.
+> - **Major** `payments/stripe-webhook.js:67` — no error handling on `stripe.constructEvent()`. Throws on invalid payloads — unhandled crash.
+> - **Minor** `payments/stripe-webhook.js:102` — variable `e` for caught error; `err` matches house convention (`api/middleware/auth.js:45`).
+> Required fixes: 2. Optional: 1.
+
+**Edge case** — out-of-scope architecture issue found during review
+> 🔍 **Code Reviewer:** Pattern check flagged: `user.service.js` imports directly from `database/connection.js`, bypassing the repository layer. This is a layer-violation architectural concern, not a code quality fix. Flagged for Waleed (CTO) — not blocking this review but should be tracked.
+
+**Negative** — asked to review generated code with no tests
+> 🔍 **Code Reviewer:** No test files found for this module. Cannot assess test coverage. Review blocked — a module with zero tests cannot pass quality gates. Add tests, then re-run review.

package/rcode/references/codebase-mapping-process.md

@@ -0,0 +1,176 @@
+# Codebase Mapping Process
+
+Loaded by `rcode-codebase-mapper` (Dalil) via `@-include`. Contains the full
+four-step mapping process: parsing focus area, discovering source roots,
+exploring the codebase with focus-specific bash commands, writing documents
+with mandatory Scan Scope section, and returning confirmation.
+
+---
+
+<step name="parse_focus">
+Read the focus area from your prompt. It will be one of: `tech`, `arch`, `quality`, `concerns`.
+
+Based on focus, determine which documents you'll write:
+- `tech` → STACK.md, INTEGRATIONS.md
+- `arch` → ARCHITECTURE.md, STRUCTURE.md
+- `quality` → CONVENTIONS.md, TESTING.md
+- `concerns` → CONCERNS.md
+</step>
+
+<step name="discover_source_roots">
+**MANDATORY FIRST STEP — never skip.** Do not assume `src/` exists or that the project is single-language. Discover the real layout before searching anything.
+
+```bash
+# 1. Top-level source roots (excluding vendored / build / VCS / cache)
+find . -maxdepth 1 -type d \
+  -not -name '.' -not -name '.git' -not -name 'node_modules' \
+  -not -name '.next' -not -name 'dist' -not -name 'build' \
+  -not -name '__pycache__' -not -name '.venv' -not -name 'venv' \
+  -not -name '.cache' -not -name 'coverage' \
+  | sort
+
+# 2. Language detection from manifests at any depth (up to 3 levels)
+find . -maxdepth 3 \
+  \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'requirements.txt' \
+     -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'Gemfile' -o -name 'pom.xml' \
+     -o -name 'build.gradle' -o -name 'composer.json' \) \
+  -not -path '*/node_modules/*' -not -path '*/.venv/*' 2>/dev/null
+
+# 3. Monorepo detection
+ls pnpm-workspace.yaml turbo.json nx.json lerna.json rush.json 2>/dev/null
+cat package.json 2>/dev/null | grep -E '"workspaces"' -A 5
+```
+
+Record the result as `$SOURCE_ROOTS` (list of dirs to search) and `$LANGUAGES` (set of detected languages). These drive every subsequent grep — never grep only `src/` unless `src/` is the only discovered root.
+
+**If a topic phrase was passed in your prompt** (e.g. "Sentry instrumentation", "GraphQL resolvers", "Redis caching"), run a literal sweep across ALL discovered roots BEFORE focus-specific exploration:
+
+```bash
+TOPIC="<phrase from prompt>"
+for ROOT in $SOURCE_ROOTS; do
+  echo "=== $ROOT ==="
+  grep -rli "$TOPIC" "$ROOT" \
+    --include='*.py' --include='*.ts' --include='*.tsx' --include='*.js' \
+    --include='*.jsx' --include='*.go' --include='*.rs' --include='*.rb' \
+    2>/dev/null | head -50
+done
+```
+
+The file list this returns becomes your PRIMARY analysis target. Do not narrow it to one subdirectory based on assumed conventions.
+</step>
+
+<step name="explore_codebase">
+Explore the codebase thoroughly for your focus area, iterating across ALL `$SOURCE_ROOTS` discovered above. Adapt globs to `$LANGUAGES` — if Python is in the language set, search `*.py`; if TypeScript, `*.ts`/`*.tsx`; etc.
+
+**For tech focus:**
+```bash
+# Package manifests across ALL roots (already gathered in discover_source_roots)
+# Config files (list only - DO NOT read .env contents)
+ls -la *.config.* tsconfig.json .nvmrc .python-version 2>/dev/null
+ls .env* 2>/dev/null  # Note existence only, never read contents
+
+# SDK/API imports — iterate over every source root
+for ROOT in $SOURCE_ROOTS; do
+  grep -rE "^(import|from) (.*stripe|.*supabase|.*aws|.*sentry|.*@)" "$ROOT" \
+    --include='*.py' --include='*.ts' --include='*.tsx' --include='*.js' 2>/dev/null | head -30
+done
+```
+
+**For arch focus:**
+```bash
+# Directory tree of each source root
+for ROOT in $SOURCE_ROOTS; do
+  find "$ROOT" -type d \
+    -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/__pycache__/*' \
+    | head -40
+done
+
+# Entry points across languages
+ls src/index.* src/main.* src/app.* src/server.* app/page.* 2>/dev/null
+find . -maxdepth 4 -name 'main.py' -o -name '__main__.py' -o -name 'manage.py' \
+  -o -name 'app.py' -o -name 'wsgi.py' -o -name 'asgi.py' \
+  -not -path '*/.venv/*' -not -path '*/node_modules/*' 2>/dev/null
+```
+
+**For quality focus:**
+```bash
+ls .eslintrc* .prettierrc* eslint.config.* biome.json ruff.toml .flake8 mypy.ini pyrightconfig.json 2>/dev/null
+
+# Tests across all roots and languages
+for ROOT in $SOURCE_ROOTS; do
+  find "$ROOT" \( -name '*.test.*' -o -name '*.spec.*' -o -name 'test_*.py' -o -name '*_test.py' \) \
+    -not -path '*/node_modules/*' -not -path '*/.venv/*' 2>/dev/null | head -20
+done
+```
+
+**For concerns focus:**
+```bash
+# TODO/FIXME comments — search every root, every primary language
+for ROOT in $SOURCE_ROOTS; do
+  grep -rnE "TODO|FIXME|HACK|XXX" "$ROOT" \
+    --include='*.py' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+    --include='*.go' --include='*.rs' \
+    -not -path '*/node_modules/*' 2>/dev/null | head -50
+done
+
+# Large files (potential complexity) — language-aware
+for ROOT in $SOURCE_ROOTS; do
+  find "$ROOT" \( -name '*.py' -o -name '*.ts' -o -name '*.tsx' -o -name '*.go' \) \
+    -not -path '*/node_modules/*' -not -path '*/.venv/*' \
+    | xargs wc -l 2>/dev/null | sort -rn | head -10
+done
+
+# If the orchestrator passed a topic phrase, the file list from discover_source_roots
+# is your primary input — analyze each of those files directly.
+```
+
+Read key files identified during exploration. Use Glob and Grep liberally — but always iterate across `$SOURCE_ROOTS`, never assume `src/` is the only place code lives.
+</step>
+
+<step name="write_documents">
+Write document(s) to `.rcode/codebase/` using the templates below.
+
+**Document naming:** UPPERCASE.md (e.g., STACK.md, ARCHITECTURE.md)
+
+**Template filling:**
+1. Replace `[YYYY-MM-DD]` with current date
+2. Replace `[Placeholder text]` with findings from exploration
+3. If something is not found, use "Not detected" or "Not applicable"
+4. Always include file paths with backticks
+
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
+**MANDATORY — Scan Scope section.** Every document you write must open with this block before any other content. The orchestrator will reject documents missing it.
+
+```markdown
+## Scan Scope
+
+**Source roots discovered:** `<list from discover_source_roots step 1>`
+**Source roots searched:** `<subset actually iterated by greps>`
+**Source roots NOT searched:** `<any discovered root not searched>` — Reason: `<vendored / out-of-scope / time / etc.>`
+**Languages detected:** `<from manifests, e.g. Python 3.11, TypeScript 5.x>`
+**Topic phrase (if any):** `<literal phrase from orchestrator prompt, or "none">`
+**Topic-phrase sweep result:** `<file count + 5-10 sample paths from grep -rl, or "n/a">`
+
+**Blind-spot acknowledgment:** If you searched only a subset (e.g. only `src/` while `backend/` and `services/` exist), state it explicitly here. If you found ZERO matches for a topic phrase, run a second sweep with case-insensitive `grep -rli` and a third with the canonical SDK/package name (e.g. `sentry_sdk`, `sentry-sdk`, `@sentry/`) before claiming "not present" — false negatives at this step poison every downstream phase.
+```
+
+If the topic-phrase sweep returns matches in a directory you did not analyze in depth, you MUST either (a) extend the analysis to cover it, or (b) explicitly note in the document body which findings might exist there but were not investigated. Never silently exclude a directory that contains topic-phrase hits.
+</step>
+
+<step name="return_confirmation">
+Return a brief confirmation. DO NOT include document contents.
+
+Format:
+```
+Codebase mapping complete. Documents written to .planning/codebase/.
+```
+
+## On-Demand Rule Files
+
+| When you need... | Read |
+|---|---|
+| Full detailed guide (tool priorities, output formats, templates, pitfalls, examples) | `.rcode/agents-rules/codebase-mapper/detailed-guide.md` |
+
+Read only when the current task needs the detail. Don't preemptively load.
+</step>

package/rcode/references/command-redirect-format.md

@@ -0,0 +1,62 @@
+# rcode Command Redirect Format
+
+Shared reference for all agents and workflows when they suggest the user run a different command.
+
+## The rule
+
+**When suggesting a `/rcode-*` command, print it on a single line for copy-paste.**
+
+The user's terminal-style interface benefits from one-line commands they can select and paste without touching line-wrap issues. Never split a suggested command across multiple lines, never bullet it, never break arguments onto separate rows.
+
+## Good format
+
+```
+Run: /rcode-council I'm in Pakistan, USD 1000 budget, want to dropship Gaming + Creator accessories to UAE. Should I build a Next.js custom app or use Shopify?
+```
+
+One line. User selects the whole line, pastes, presses enter.
+
+## Bad format — do NOT do this
+
+```
+Run /rcode-council with the new question:
+"I'm in Pakistan, USD 1000 budget, want to dropship Gaming + Creator accessories to UAE. Should I build a Next.js custom app or use Shopify?"
+```
+
+Two lines, with quotes, with a lead-in sentence. The user has to reconstruct the command mentally.
+
+## When to redirect
+
+Agents and workflows redirect when:
+- An agent receives a question outside its domain (Sadiq gets a technical question → Waleed)
+- A workflow gets an input type it doesn't handle (`/rcode-plan` gets a decision question → `/rcode-council`)
+- The user's intent would be better served by a different command
+
+## Template
+
+```
+<reason for redirect in one sentence>
+
+Copy-paste this instead:
+
+/rcode-<command> <exact arguments from user's original input>
+```
+
+The third line — the full command — is a single physical line, regardless of length. No wrapping. No quotes around the arguments unless the command itself requires them.
+
+## For argument substitution
+
+Pass `$ARGUMENTS` verbatim when redirecting plan → council or discuss → council. Do not modify punctuation, do not add quotes, do not summarize. The user said what they meant — preserve it.
+
+## Multi-option redirects
+
+If multiple commands could fit, list each on its own line as a complete single-line command:
+
+```
+Could be either — pick one:
+
+/rcode-discuss waleed <your question>
+/rcode-council <your question>
+```
+
+Not with lead-in prose for each option.

package/rcode/references/commit-conventions.md

@@ -0,0 +1,125 @@
+# rcode Commit Conventions
+
+Shared reference `@`-included by every workflow that creates or modifies git artifacts.
+
+## Detect project-local conventions FIRST (mandatory)
+
+Before writing any commit, scan the project for local commit standards and let them **override** the defaults in this file. Check in this priority order — stop at the first one that yields a concrete allowed-types + allowed-scopes list:
+
+1. **`commitlint.config.{js,cjs,ts,mjs,json}`** — most authoritative. Parse `rules['type-enum']` and `rules['scope-enum']`.
+2. **`.github/workflows/semantic*.{yaml,yml}`** — GitHub Semantic PR action. Parse `types:` and `scopes:` blocks under `amannn/action-semantic-pull-request`.
+3. **`.github/COMMIT_CONVENTIONS.md`, `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`** — look for sections naming allowed types/scopes.
+4. **`git log --oneline -50`** — infer from past 50 commits: extract `type(scope):` prefixes, take the set that appears ≥2 times.
+
+Run this cheaply before composing the commit:
+
+```bash
+# Priority 2 example — semantic PR action scopes
+if [ -f .github/workflows/semantic.yaml ] || [ -f .github/workflows/semantic.yml ]; then
+  echo "--- project semantic PR config ---"
+  cat .github/workflows/semantic*.y*ml 2>/dev/null | sed -n '/types:/,/scopes:/{p}; /scopes:/,/[A-Za-z]*:/{p}'
+fi
+# Priority 4 fallback — infer from history
+git log --oneline -50 | grep -oE '^[a-f0-9]+ [a-z]+\([a-z0-9-]+\):' | awk '{print $2}' | sort -u
+```
+
+**If the project defines scopes, you MUST pick from that list.** Do not invent new scopes (e.g., `branding` when only `web, server, docker, k8s, e2e, docs, ci, deps, ml, strapi` are allowed). A commit that fails the project's semantic PR check wastes the user's CI run and signals the workflow didn't read the repo.
+
+If no project list exists, fall back to the generic rcode scopes in the "Format" section below.
+
+## Format
+
+All commits follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): subject
+```
+
+- **type**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
+- **scope** (optional): a short noun describing the affected area — `council`, `install`, `agents`, `workflows`, `references`, `cli`, `docs`, `test`
+- **subject**: lowercase first letter, imperative mood, no trailing period, under 72 characters
+
+Example:
+```
+feat(council): parallel subagent dispatch via Task tool
+fix(install): hash-check skipped symlinked files
+docs(agents): add Fatima's default moves
+```
+
+## The subject line is load-bearing
+
+The subject is read by:
+
+- Other engineers browsing `git log --oneline`
+- `git blame` users hunting for context
+- CI semantic-release parsers (which auto-bump versions)
+- Future-you in 6 months
+
+Every word counts. "fix bug" is never acceptable. "fix(council): panel scoring ignored --agents flag" is.
+
+## Body
+
+If the commit needs more than a subject, leave one blank line and write a body. The body explains **why**, not **what** — the diff already shows what changed.
+
+```
+feat(council): parallel subagent dispatch via Task tool
+
+The v1 council fired 13 personas sequentially in one Claude context,
+producing one voice with 13 hats. The v2 council spawns each selected
+agent as a first-class subagent via the Task tool, running in parallel.
+
+Benefits:
+- Real independence — each subagent has its own context and cannot
+  be biased by what the previous agent said
+- Parallel latency — 3 agents respond in ~max(each) instead of sum
+- Smaller orchestrator context — each subagent's output is summarized
+  back rather than accumulated in the parent
+
+Replaces cli/lib/council-panel.cjs caller paths in the slash command
+template.
+```
+
+## What NOT to put in commits
+
+Per `/home/hanzla/development/rcode/CLAUDE.md` and `AGENTS.md`:
+
+- **Never** add `Generated with Claude Code` or `Co-Authored-By: Claude` trailers
+- **Never** add `🤖 Generated` markers
+- **Never** use `--no-verify` to bypass hooks
+- **Never** use `git add -A` or `git add .` without reading what would be staged
+
+The project explicitly rejects AI attribution in commit messages. Human authorship is the default and the only acceptable form.
+
+## Staging
+
+Always stage specific files:
+
+```bash
+git add rcode/agents/rcode-sadiq.md rcode/agents/rcode-waleed.md
+```
+
+Not:
+
+```bash
+git add .
+```
+
+The `.` form stages untracked config files, secrets, and scratch directories that shouldn't be in the commit. Specific staging forces you to see what you're committing.
+
+## Push authorization
+
+**Never run `git push` without explicit human approval on that specific push.** Prior authorization for one push does not transfer to the next. This is a hard rule in `AGENTS.md` and it applies to every workflow that touches git.
+
+Workflows that produce commits must hand back to the user at the end and wait for an explicit "push" before running `git push`. If the user has not typed the word "push", the workflow stops at the commit step.
+
+## Commit from a workflow
+
+When a rcode workflow creates a commit on the user's behalf:
+
+1. **Run the "Detect project-local conventions" scan** above. Pick scope from the project's allowed list if one exists.
+2. Stage only the files the workflow actually modified (never `-A`)
+3. Write the subject as `type(scope): subject` using project-local types/scopes when defined, generic rcode scopes only as fallback
+4. If the body adds real value (the why isn't obvious from the diff), include it
+5. Do not sign with AI attribution
+6. Print the commit SHA and one-line summary to the user
+7. **Stop.** Do not push. Wait for explicit authorization.