@tyroneross/build-loop 0.30.3

package/codex-skills/knowledge/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: knowledge
+description: "Main Build Loop knowledge entrypoint. Use when recording decisions, ADRs, lessons, procedural memory, or repo-local knowledge that should be durable across future runs — AND when reviewing existing memory: surfacing the review queue, detecting decision rot, finding stale procedures, or resolving open conflicts."
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Knowledge
+
+This is the public Codex entrypoint for Build Loop knowledge capture. The
+canonical implementation remains internal:
+
+```text
+../skills/knowledge/SKILL.md          # capture: decisions, ADRs, lessons, procedures
+../skills/knowledge-review/SKILL.md   # review: review queue, decision rot, stale procedures, open conflicts
+```
+
+Keep captures factual, scoped to the current repo or decision, and validated
+against the files or commands that prove the lesson. Use the review path when
+asked to surface what's gone stale or conflicting in existing memory rather than
+to record something new.

package/codex-skills/optimize/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: optimize
+description: "Main Build Loop optimization entrypoint. Use when the user wants to make something faster, cheaper, smaller, simpler, or better against a measurable metric."
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Optimize
+
+This is the public Codex entrypoint for Build Loop optimization. The canonical
+implementation remains internal:
+
+```text
+../skills/optimize/SKILL.md
+```
+
+Define the metric first, identify factors, measure each run, keep only changes
+that improve the metric, and revert changes that do not.

package/codex-skills/research/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: research
+description: "Main Build Loop research entrypoint. Use for pre-build research, option evaluation, API/framework investigation, and repo-grounded decision packets before implementation."
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Research
+
+This is the public Codex entrypoint for Build Loop research. The canonical
+implementation remains internal:
+
+```text
+../skills/research/SKILL.md
+```
+
+Ground claims in the repo first, then use current external docs only when the
+decision depends on unstable or third-party behavior.

package/commands/agent-rally-point.md

@@ -0,0 +1,301 @@
+---
+description: "Inspect or invoke build-loop's multi-session coordination (Rally Point + per-run coord file). Subcommands: status (default), watch, heartbeat, ack-inbox, announce, init, lead, escalate, boundary, docs, help."
+allowed-tools: Bash, Read
+argument-hint: "[status|watch|heartbeat|announce|init|lead|escalate|boundary|docs|help] [args]"
+model: inherit
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+Parse `{{ARGUMENTS}}` as `<subcommand> [args...]`. **If `<subcommand>` is omitted or empty, default to `status`** (the no-args case — most common interactive use).
+
+## Subcommands
+
+### `status` (default — no-args runs this)
+
+Cheap (~100-token) sensor poll. Reports active peer sessions, unresolved verifier verdicts, dirty files, task-heartbeat health, and the active coord file path. Run this BEFORE any step-boundary decision (next-step recommendation, subagent dispatch, commit, version bump, archive/delete).
+
+Executes:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/coordination_status.py \
+  --workdir "$PWD" \
+  --session-id "user-rally-$(date +%s)" \
+  --json
+```
+
+(If the user passed `--coordination-file=<path>`, `--task-ref=<id>`, or
+`--task-heartbeat-grace-seconds=<seconds>` in subcommand args, forward it.)
+
+Example output (clear):
+
+```json
+{
+  "status": "clear",
+  "active_peers": [],
+  "unresolved": [],
+  "coordination_file": null
+}
+```
+
+Example output (warn — peer overlap on owned files):
+
+```json
+{
+  "status": "warn",
+  "active_peers": [{"session_id": "codex-...", "tool": "codex", "phase": "review"}],
+  "overlaps": [{"peer": "codex-...", "files": ["scripts/foo.py"], "severity": "warning"}],
+  "required_action": "review_peer_overlap_or_dirty_files"
+}
+```
+
+### `watch`
+
+Continuous cheap sensor loop. Use this while waiting on another coding host,
+during active shared-file work, or whenever an inbox message is expected. The
+watcher prints only state transitions, revision changes, dirty-file risk, and
+inbox unread count. When `--task-ref` is set, it also wakes on task-heartbeat
+health changes.
+
+Executes:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/coordination_watch.py \
+  --workdir "$PWD" \
+  --session-id "user-rally-$(date +%s)" \
+  --tool "claude_code" \
+  --interval 5 \
+  --jsonl \
+  --baseline-current
+```
+
+If the user passed `--tool=<name>`, `--files-in-flight=<csv>`,
+`--coordination-file=<path>`, `--task-ref=<id>`, or
+`--task-heartbeat-grace-seconds=<seconds>` in subcommand args, forward them. Claude Code uses
+`--tool claude_code`; Codex uses `--tool codex`; other hosts should choose a
+stable lowercase tool id.
+
+When the watcher emits an event with a higher `revision`,
+`direct_inbox_unread_count > 0`, or `broadcast_inbox_unread_count > 0`, run
+`status`, read the addressed inbox plus `inbox/all.jsonl`, and respond through
+the channel before continuing. Watch/status output also includes
+`inbox_latest_messages`: compact metadata and a short preview for the newest
+direct/broadcast inbox records. Treat it as a doorbell only; read the inbox
+file for full payloads before acting. After the message is handled, run
+`ack-inbox` so old direct notes do not keep appearing as unread.
+
+### `heartbeat`
+
+Write a structured task heartbeat for long-running work. This is separate from
+presence: presence answers "process can still write"; heartbeat answers "the
+agent is still on the claimed task and when the next check-in is due."
+
+Use it at the start of a long-running task, then at least every 10 minutes or
+after each meaningful phase boundary. Set `--task-ref` to the claim, issue,
+pillar, or run id that status/watch should expect.
+
+Executes:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py heartbeat \
+  --workdir "$PWD" \
+  --session-id "user-rally-$(date +%s)" \
+  --tool "claude_code" \
+  --model "inherit" \
+  --run-id "<run-id>" \
+  --task-ref "<claim-or-issue-id>" \
+  --status running \
+  --progress "<short progress since last check-in>" \
+  --evidence "<csv refs: files/tests/commits/handoffs>" \
+  --json
+```
+
+Use `--status blocked --attention-reason "<why>"` or
+`--status needs_attention --attention-reason "<why>"` when a human or lead must
+act. Use `--not-on-task` only to make drift explicit.
+
+### `ack-inbox`
+
+Mark the current direct/broadcast inbox tail as seen for this tool/session.
+This writes an ack cursor under `inbox/.acks/`; it does not rewrite or delete
+the append-only inbox messages.
+
+Executes:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py ack-inbox \
+  --workdir "$PWD" \
+  --session-id "user-rally-$(date +%s)" \
+  --tool "claude_code" \
+  --json
+```
+
+Run this only after reading and acting on the current inbox payloads. Pass
+`--no-broadcast` when a broadcast message should remain visible.
+
+### `announce [message]`
+
+Publish lightweight Rally Point presence + a `kind=handoff` rally record for the current app slug, without creating a durable coordination file. Use this when another host (Codex, Claude Code, CI verifier) needs to see that this agent is present before work ownership is split, or when dogfooding coordination from outside a full build-loop run.
+
+Executes:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/coordination_rally.py \
+  --workdir "$PWD" \
+  --session-id "user-rally-$(date +%s)" \
+  --tool "claude_code" \
+  --model "inherit" \
+  --to "peer" \
+  --message "<message or 'Agent is present and ready to coordinate.'>" \
+  --json
+```
+
+If the user passed `--owns=<csv>` or `--does-not-own=<csv>` in subcommand args, forward those values as `--owns` / `--does-not-own`. If omitted, the rally is presence-only and owns no files.
+
+Example output:
+
+```json
+{
+  "action": "rally-point-posted",
+  "app_slug": "example-ios-app",
+  "channel_revision": 1,
+  "presence_written": true
+}
+```
+
+### `init <topic> <scope-one-liner>`
+
+Bootstrap a NEW coord file at `.build-loop/coordination/<topic>-YYYY-MM-DD.md` from `references/coordination-file-template.md`. Writes own presence, posts a `kind=handoff` record so peers see it. **Idempotent and atomic** (per v0.12.10): if the coord file already exists OR a concurrent peer creates it between our check and our write, joins (writes presence + posts `phase=joined-existing-coord`) instead of overwriting.
+
+Executes:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/coordination_bootstrap.py \
+  --workdir "$PWD" \
+  --topic "<topic-slug>" \
+  --scope "<scope-one-liner>" \
+  --session-id "user-rally-$(date +%s)" \
+  --json
+```
+
+Example invocation: `/agent-rally-point init v0130-feature-x "Add new feature X across orchestrator + bootstrap + tests"`
+
+Example output:
+
+```json
+{
+  "coord_file": ".build-loop/coordination/v0130-feature-x-2026-05-21.md",
+  "action": "bootstrapped",
+  "channel_revision": 65,
+  "session_id": "user-rally-1779320000"
+}
+```
+
+### `lead <claim|renew|transfer|relinquish|status>`
+
+Operate the leadership lease (G1). A multi-agent run has exactly ONE lead
+with a liveness lease; "lead" used to be implicit in whoever opened the
+coord file. The orchestrator auto-claims at Phase 1, renews at each
+phase-start, and relinquishes at Phase D closeout — use this command for
+manual lead inspection, an out-of-band takeover, or dogfooding.
+
+All `lead` ops shell out to the host-neutral CLI:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py lead <op> \
+  --workdir "$PWD" \
+  --session-id "user-rally-$(date +%s)" \
+  --tool "claude_code" \
+  --run-id "<run-id>"
+```
+
+- `claim` — become lead if the channel has no lead or the lease expired.
+  Returns `{"claimed": bool, "lead": {...}}`. A second claim while a valid
+  lease is held returns `claimed: false` with the incumbent.
+- `renew` — extend the current lease (lead only; `--renew-every-minutes`,
+  default 15). `renew_every_minutes` is the lease clock — distinct from the
+  `watch` poll cadence.
+- `transfer` — hand the lead to another session (`--to-session-id`,
+  `--to-tool`, `--to-model`); rejected from a non-lead.
+- `relinquish` — give up the lead so the next `claim` succeeds immediately.
+- `status` — read the current lead + `lease_valid`.
+
+Example: `/agent-rally-point lead status`
+
+### `escalate <reason>`
+
+Post a `kind=escalation` change record (G3) — "needs lead or user
+attention now", distinct from routine `phase`/`feedback`. An open
+escalation makes `status` report `blocked` until acknowledged.
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py escalate \
+  --workdir "$PWD" \
+  --session-id "user-rally-$(date +%s)" \
+  --tool "claude_code" \
+  --run-id "<run-id>" \
+  --reason "<why this needs attention>"
+```
+
+### `boundary`
+
+Validate the embedded mini-plugin boundary used to keep Rally Point and the
+watcher extractable while they still ship inside build-loop.
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py boundary \
+  --repo "${CLAUDE_PLUGIN_ROOT}" \
+  --check \
+  --json
+```
+
+This checks `scripts/rally_point/plugin_boundary.json` and reports the
+current `agent-rally-point` and `agent-rally-watcher` extraction surfaces.
+
+### `docs`
+
+Prints the binding coordination constitution at `references/coordination-rules.md`. Use this when onboarding a peer (Codex, second Claude session, CI verifier) so they read the same rules — the verdict-gating operating rule, the `post()` helper mandate, MECE packets for every write-handoff, release-surface verification, Phase D closeout.
+
+Executes:
+
+```bash
+cat ${CLAUDE_PLUGIN_ROOT}/references/coordination-rules.md
+```
+
+### `help`
+
+Shows the subcommand reference table (replaces what the no-args case used to do pre-v0.12.10).
+
+Outputs:
+
+```
+/agent-rally-point — inspect or invoke build-loop's multi-session coordination
+
+Subcommands:
+  status (default)        Sensor poll: active peers, unresolved verdicts, coord file
+  watch                   Continuous sensor loop for peer/inbox changes
+  heartbeat               Write a long-running task check-in
+  announce [message]      Publish Rally Point presence + handoff without coord file
+  init <topic> <scope>    Bootstrap a coord file from template; atomic + idempotent
+  lead <op>               Inspect or update the leadership lease
+  escalate <reason>       Post an urgent coordination escalation
+  boundary                Validate embedded agent-rally extraction boundaries
+  docs                    Print the binding coordination constitution
+  help                    This message
+
+No-args invocation runs `status` (the most common interactive use).
+
+When auto-invoke is enough:
+  The build-orchestrator agent auto-invokes coordination at three trigger
+  points (Phase 1 Assess preamble, Phase 3 chunk-close, Phase 4 Review-A).
+  See agents/build-orchestrator.md §"Auto-invoke coordination". Use `watch`
+  when waiting on an async peer response or targeted inbox message. Use
+  `status`, `heartbeat`, `announce`, or `init` for manual peer setup, debugging
+  coordination state, or onboarding a fresh verifier session.
+```
+
+## Dispatch
+
+Based on the parsed subcommand (or `status` when `{{ARGUMENTS}}` is empty), run the corresponding bash command above using the Bash tool. Quote the result and surface key fields (status / coord_file / unresolved) in the response.
+
+For `status`, if `unresolved: []` is non-empty, hold and resolve them before the user's intended step proceeds.

package/commands/assess.md

@@ -0,0 +1,41 @@
+---
+description: "Run parallel domain assessment for complex debugging symptoms"
+allowed-tools: Bash, Read, Task
+argument-hint: "<symptom>"
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+{{#if ARGUMENTS}}
+
+Analyze "{{ARGUMENTS}}" across multiple domains in parallel.
+
+**1. Detect domains** from symptom keywords (database, frontend, API, performance)
+
+**2. Launch assessors in parallel** using Task tool with these agents:
+- `database-assessor` - query, schema, migration issues
+- `frontend-assessor` - React, component, render issues
+- `api-assessor` - endpoint, auth, middleware issues
+- `performance-assessor` - slow, memory, bottleneck issues
+
+Spawn multiple Task calls in a single message for detected domains.
+
+**3. Search memory** for similar past incidents via native build-loop memory:
+```
+Skill("build-loop:debugging-memory-search") with input { symptom: "{{ARGUMENTS}}" }
+```
+
+**4. Present results** ranked by confidence, with recommended action sequence.
+
+{{else}}
+
+Provide a symptom: `/assess <description>`
+
+Examples:
+- `/assess search is slow and returns wrong results`
+- `/assess 500 error on user registration`
+- `/assess react component re-renders infinitely`
+
+For simple issues, use `/debugger` instead.
+
+{{/if}}

package/commands/debug.md

@@ -0,0 +1,20 @@
+---
+description: "(Advanced override — `/build-loop:run` auto-routes here on symptom language; use this to force debug mode.) Deep iterative debugging — causal-tree investigation, fix, verify, critique. Up to 5 iterations."
+argument-hint: "<symptom>"
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+{{#if ARGUMENTS}}
+Load the `build-loop:debug-loop` skill. Symptom: `{{ARGUMENTS}}`
+{{else}}
+Load the `build-loop:debug-loop` skill. Ask the user what failure to investigate.
+
+Examples:
+- `/build-loop:debug tests pass locally but fail in CI`
+- `/build-loop:debug login works once then breaks on refresh`
+- `/build-loop:debug API returns wrong data intermittently`
+
+For quick memory lookup, use `/build-loop:debugger` instead.
+For multi-domain assessment, use `/build-loop:assess` instead.
+{{/if}}

package/commands/debugger-detail.md

@@ -0,0 +1,34 @@
+---
+description: "Load full build-loop incident or pattern details from native debugging memory"
+allowed-tools: Read, Grep
+argument-hint: "<INC_* or PTN_* id>"
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Debugger Detail
+
+Load full details for a specific incident or pattern from debugging memory.
+
+## Usage
+
+```
+/debugger-detail <ID>
+```
+
+Where `<ID>` is an incident ID (INC_*) or pattern ID (PTN_*).
+
+## What to do
+
+1. Search `.build-loop/issues/` for the requested incident or pattern ID.
+
+2. Present the result to the user in a readable format:
+   - For incidents: show symptom, root cause, fix approach, file changes, verification status
+   - For patterns: show detection signature, solution template, success rate, usage history
+
+3. If the ID is from a progressive search result, explain how this detail relates to the user's current issue.
+
+## Examples
+
+- `/debugger-detail INC_API_20260215_143022_a1b2` — loads full incident
+- `/debugger-detail PTN_REACT_HOOKS` — loads full pattern

package/commands/debugger-scan.md

@@ -0,0 +1,15 @@
+---
+description: "Capture recent debugging incidents into build-loop native memory"
+allowed-tools: Read, Grep, Bash
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+Review recent build-loop run notes, reports, and validation failures for debugging work from the past 7 days. Store confirmed incidents as Markdown files under `.build-loop/issues/`.
+
+Prioritize:
+- Root cause analysis documents
+- Error tracking logs
+- Fix reports
+
+Do not call external debugger packages by default. Use standalone Coding Debugger only when the user explicitly asks for cross-project memory.

package/commands/debugger-status.md

@@ -0,0 +1,20 @@
+---
+description: "Show build-loop native debugging memory statistics"
+allowed-tools: Bash, Read
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+Display the current state of build-loop's native debugging memory:
+
+```bash
+find .build-loop/issues -type f -name '*.md' 2>/dev/null | wc -l
+```
+
+This shows:
+- Number of stored incidents
+- Number of extracted patterns
+- Storage size
+- Recent activity
+
+Use this to understand what debugging knowledge has been accumulated and whether the memory system is working correctly.

package/commands/debugger.md

@@ -0,0 +1,32 @@
+---
+description: "Search build-loop native debugging memory before debugging"
+allowed-tools: Read, Grep
+argument-hint: "<symptom>"
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+Search build-loop's native debugging memory for similar past incidents before investigating a new bug.
+
+{{#if ARGUMENTS}}
+
+Run the native memory-first workflow with the provided symptom:
+
+```
+Skill("build-loop:debugging-memory-search") with input { symptom: "{{ARGUMENTS}}" }
+```
+
+After running the search:
+1. If a match is found with >70% confidence, try that solution first
+2. Review the root cause and fix approach from past incidents
+3. Apply the documented fix, adapting as needed for the current context
+4. If the fix works, no need to store again (already in memory)
+5. If a different fix is needed, document it as a new incident
+
+{{else}}
+
+No symptom provided. Read recent local incidents from `.build-loop/issues/` if present, then ask the user to describe what they are debugging.
+
+Use standalone Coding Debugger only when the user explicitly asks for cross-project debugger memory.
+
+{{/if}}

package/commands/handoff.md

@@ -0,0 +1,113 @@
+---
+description: "Compose a complete build-loop handoff from current run state. Optional --launch starts a fresh session in the stable checkout with the handoff injected."
+argument-hint: "[--launch] [--workdir DIR]"
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+{{#if ARGUMENTS}}
+{{#contains ARGUMENTS "--launch"}}
+
+## Step 1 — Compose the handoff doc
+
+Run from the STABLE checkout (not a worktree):
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/handoff --workdir "$PWD" --output .build-loop/handoff-latest.md
+```
+
+Report the sources used and any warnings from stderr.
+
+## Step 2 — Identify the stable checkout path
+
+Run:
+```bash
+git worktree list --porcelain | grep "^worktree" | head -1 | awk '{print $2}'
+```
+
+This is the canonical repo root. The new session MUST open there, not in any `.build-loop/worktrees/` sub-path (those may be GC'd).
+
+## Step 3 — Launch a fresh session with handoff injected
+
+Determine the host. Then:
+
+**Claude Code host** — use `claude --print` in a new terminal:
+```bash
+HANDOFF=$(cat .build-loop/handoff-latest.md)
+echo "RESUME_FROM_HANDOFF: The following handoff document captures the current build-loop run state. Use it to resume work.\n\n${HANDOFF}" | claude --print
+```
+If the trust prompt fires on the new session, type `y` and press Enter.
+
+**Codex host** — pass the doc as context:
+```bash
+codex --context "$(cat .build-loop/handoff-latest.md)" "Resume from the attached handoff document."
+```
+
+**Unknown / unsupported host** — print the path and instructions:
+```
+Handoff doc written to: .build-loop/handoff-latest.md
+To resume: open a fresh session at <stable-checkout-path>, share the handoff doc as your opening message, and load the build-loop:build-loop skill.
+```
+
+In all cases: exit 0 (degrade gracefully — the doc is the deliverable, launch is a convenience).
+
+{{else}}
+
+## Compose the handoff document
+
+Run:
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/handoff --workdir "$PWD"
+```
+
+Present the full output as your response. Also report:
+- Sources used (from the `sources` field if `--json` was used)
+- Any warnings
+
+{{/contains}}
+{{else}}
+
+## Compose the handoff document
+
+Run:
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/handoff --workdir "$PWD"
+```
+
+Present the full output. Also note:
+- What sources were found vs missing
+- Any errors/warnings
+
+To launch a fresh session after handoff, re-run with `--launch`:
+```
+/build-loop:handoff --launch
+```
+
+{{/if}}
+
+---
+
+## Reference
+
+**Emit to stdout (default)**
+```
+/build-loop:handoff
+```
+
+**Write to file**
+```
+/build-loop:handoff --workdir /path/to/repo
+```
+(Use `--output` flag in the script directly for file output.)
+
+**Emit + launch fresh session**
+```
+/build-loop:handoff --launch
+```
+
+**JSON envelope (for programmatic use)**
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/handoff --workdir "$PWD" --json
+```
+Returns `{document, sources, errors, ts}`.
+
+See `skills/handoff/SKILL.md` for the full 8-section template, source table, and host-agnostic design notes.

package/commands/knowledge-review.md

@@ -0,0 +1,16 @@
+---
+description: "Surface review-needing items across episodic memory: review queue, decision rot, open conflicts, stale procedures."
+argument-hint: "[--rot-threshold-days N] [--no-db]"
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+Load the `build-loop:knowledge-review` skill.
+
+{{#if ARGUMENTS}}
+Run with arguments: `{{ARGUMENTS}}`
+{{else}}
+Run with defaults (`--rot-threshold-days 90`).
+{{/if}}
+
+Invoke `python3 scripts/knowledge_review.py --workdir "$PWD" {{ARGUMENTS}}` and present the markdown output to the user. Read-only; do not auto-resolve any item.