@tyroneross/build-loop 0.36.0 → 0.43.0

package/plugin-artifacts/codex/skills/build-loop/references/capability-routing.md

@@ -1,231 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Capability Routing (full protocol)
-
-> Loaded from `skills/build-loop/SKILL.md` summary. Contains the full capability routing table, trigger conditions, and plugin/hook/skill/agent mandatory routing rules.
-
-## Capability Routing
-
-Build-loop prefers repo-owned agents and bundled skills for core loop decisions. External plugins are accelerators only when explicitly requested or when a row below names them as secondary. Each capability has three tiers: **preferred** (build-loop-owned surface) → **secondary** (another installed plugin or skill that can partially cover) → **inline fallback** (guidance text from `fallbacks.md`, injected verbatim into subagent prompts).
-
-Phase 1 runs `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs` and writes the result to `.build-loop/state.json` under `availablePlugins`. All routing consults that object.
-
-### Core loop skills/assets (always check)
-
-| Skill | Used In | Fallback |
-|-------|---------|----------|
-| `writing-plans` | Phase 2 (Plan) | Write a structured plan directly: goal, tasks with exact file paths, dependency order, test commands |
-| `subagent-driven-development` | Phase 3 (Execute) | Dispatch parallel agents manually using the host's available delegation tool for independent file groups |
-| `verification-before-completion` | Phase 4 sub-step G (Report) | Run all test/build/lint commands and confirm output before claiming completion. For app/UI changes this is NOT sufficient alone — also run the runtime UI⇄source-of-truth parity check (`runtime-parity-verification`); compile-green and a screenshot do not prove the running flow works |
-| `runtime-parity-verification` | Phase 4 Review-B + Phase 5 Iterate (any `uiTarget != null` or user-visible flow) | Cross-check the rendered/queryable UI against the authoritative backend (DB/API/daemon/tool-state), screen-independently, and keep a validated per-repo smoke. Catches the "action does nothing / not showing / shows empty despite real data / stale projection" class. Drivers: web `ui-validator`; macOS `native-ax-driver` / IBR `scan_macos`; iOS `idb`; agent = tool-result vs rendered output. Reference smoke: easy-terminal `tools/smoke_launch.py` |
-| `simplify` (slash: `/simplify`) | Phase 4 sub-step E (Simplify) | Self-review the diff: remove scaffolding, inline single-use helpers, delete dead branches |
-| `complexity_detector.py` (accelerator, not a gate) | Phase 4 sub-step E (Simplify) | Diff-scoped stdlib-AST hotspot detector for changed Python; surfaces high-severity hotspots for a simpler rewrite, apply-vs-advise via existing Review-B + independent-auditor. Optional Python aid — the default Simplify pass reasons over the diff language-agnostically (see `phase-4-review.md` §"Sub-step E: Simplify") |
-| `build-loop:self-improve` | Phase 6 (Learn) | Scan recent runs for recurring patterns, auto-draft experimental skills/agents with A/B tracking, notify user for keep/remove decisions |
-| Intent capability pack | Phases 1-4 | Read `references/intent-capability-pack.md`; write `.build-loop/intent.md`; pass the intent packet to every subagent |
-| Modular systems pack | Phases 1-4 | Read `references/modular-systems-pack.md`; partition files/tasks MECE; prefer modular scalable boundaries unless an exception is documented |
-| Codex subagent adapter | Phase 3 (Execute, Codex only) | Read `references/codex-subagents.md`; use `templates/codex-worker-prompt.md` for authorized Codex workers |
-
-### Spec/Plan author router (intent-driven, ordered)
-
-This router selects the single skill that AUTHORS the plan/spec/task graph for this run. It is a recommendation that DRIVES Phase 2 — recorded into `state.json.intent.spec_router`, consumed by Phase 2 Plan, never a hard block.
-
-**Scope — author selection only.** `prd-bridge` is NOT in this router. It is mandatory in Phase 1 step 10 and only *consumes* an existing PRD (`docs/prd-*.md` → `state.json.prd`); it never authors. PRD-context is orthogonal to author selection — keep them separate.
-
-**Governing rule**: select on intent + goal + context, not on a trigger-word match. A skill's word-overlap activation is not enough to call it (this is why `prd-builder` over-fired during build-loop runs). The router is the intent-side selection; it pairs with the activation-side guard (prd-builder's negative-trigger scope, which excludes in-flight changes and active build-loop runs).
-
-Signals (all set during Phase 1 Assess):
-
-- `run_active` — is a build-loop run active? (`true` for any `/build-loop:run` or build-orchestrator dispatch.)
-- `plan_status` — `no-plan` | `plan-valid`, from the Phase 2 plan-exists gate (`.build-loop/plan.md` absent/empty + last `plan-verify` result).
-- `intent_kind` — `PRD-author` | `build-plan` | `task-graph` | `none`, the LLM's read of what this run needs authored.
-- `code_exists` — does the repo have substantive existing code? (Assess maps architecture: new/empty repo → false, existing repo → true.)
-- `goal_scope` — `new-app` | `existing-app-change` | `in-build-task-breakdown`.
-
-The rows are ORDERED — first match wins, so exactly one author is selected and no case matches two. The final default row makes the table exhaustive: every `(run_active, plan_status, intent_kind)` combination matches exactly one row, so nothing falls through.
-
-| # | Match condition (first true wins) | route_type / action | Author selected | Why |
-|---|---|---|---|---|
-| 1 | `intent_kind == none` — nothing to author (Q&A, status, trivial, read-only, or advisory-context-only) | `noop` (call nothing) | — (`skill: null`) | no plan/spec/task graph needed |
-| 2 | `run_active == false` AND greenfield PRD authoring is explicitly intended (new app with no code, OR `/start-prd` requested for a project) | `call` (or `recommend` outside an interactive session) | `prd-builder` | greenfield authoring + interactive intake; honors prd-builder's negative trigger — never fires inside an active run |
-| 3 | `run_active == true` AND `plan_status == no-plan` | `call` | `build-loop:spec-writing` | author the in-build, non-interactive, gated plan for the orchestrator |
-| 4 | `run_active == true` AND `plan_status == plan-valid` | `call` | `build-loop:writing-plans` (external) | turn the accepted plan into the task / dependency graph |
-| 5 (default) | else (no earlier row matched) — the canonical case is `run_active == false` AND `intent_kind` is `build-plan` or `task-graph`: a direct, out-of-run invocation of plan authoring on an existing repo | `recommend` | `build-loop:spec-writing` | recommend, not auto-call: there is no active run to drive, so surface the author for the lead to run if it chooses |
-
-The order is the contract: row 1 short-circuits before any author runs; row 2 is the only PRD author and is fenced off from active runs; rows 3 and 4 are mutually exclusive on `plan_status`; row 5 is the exhaustive `else` default that catches every remaining combination — its canonical case is an out-of-run `build-plan`/`task-graph` intent, but as the final row it also absorbs any residual (e.g. an out-of-run non-greenfield `PRD-author`) so no signal combination ever falls through. The table extends to any future author skill — add a row at the right precedence above the default, key it on the same signals, and the system still selects exactly one and records why.
-
-`build-loop:writing-plans` (row 4) is the **external** `writing-plans` skill from the superpowers plugin — it is not vendored in this repo (`skills/writing-plans/SKILL.md` does not exist here). When it is absent, fall back to the inline "write a structured plan directly" path in the §"Core loop skills/assets" table above.
-
-> Future refinement (do not over-build now): for monorepos, a `target_code_exists` signal (does the *target sub-path* already have code, vs the repo as a whole) would refine row 2's greenfield test. Out of scope until a monorepo case demands it.
-
-**Phase 1 record (the consumable contract)**. Phase 1 writes the matched decision into `state.json.intent.spec_router` so a Codex lead (no `Skill()` auto-activation) can consume it deterministically:
-
-```json
-{
-  "route_type": "author",
-  "action": "call" | "recommend" | "noop",
-  "skill": "build-loop:spec-writing" | "build-loop:writing-plans" | "prd-builder" | null,
-  "fallback": "<fallbacks.md section or inline guidance> | null",
-  "matched_row": 1 | 2 | 3 | 4 | 5,
-  "signals": { "run_active": true, "plan_status": "no-plan", "intent_kind": "build-plan", "code_exists": true, "goal_scope": "existing-app-change" }
-}
-```
-
-`action: "noop"` → `skill: null`, Phase 2 authors nothing from the router (terminal). `action: "recommend"` → `skill` carries the recommended author name (so the lead knows what to run if it chooses); Phase 2 surfaces the recommendation in the report and does NOT auto-call. `action: "call"` → `skill` is non-null and Phase 2 calls it. The three actions are distinct: `call` auto-invokes, `recommend` surfaces-only, `noop` skips.
-
-**Phase 2 read (the load-bearing wire)**. Phase 2 Plan READS `state.json.intent.spec_router` and acts on `action`/`skill` — it does NOT independently re-decide which author to call. See `references/phase-2-plan.md` step 0.
-
-### Phase quick reference
-
-| # | Phase | Purpose | Sub-steps / key actions |
-|---|---|---|---|
-| 1 | **Assess** | Understand state + define goal & criteria | detect tools, map architecture, load memory, write `intent.md` + `goal.md` |
-| 2 | **Plan** | Break work, identify parallel-safe, optimize | writing-plans skill → dependency graph |
-| 3 | **Execute** | Build per plan | parallel subagents, Sonnet default, Opus escalation |
-| 4 | **Review** | Critic → Validate → Optimize (opt-in) → Fact-Check → Simplify → Auto-Resolve → Report | sub-steps A-G; B-D can route to Iterate; F drains non-destructive items via autonomy_gate; G runs only on final pass |
-| 5 | **Iterate** | Fix Review failures, loop back to Review | max 5x; orchestrator stuck-iteration cascade (evidence-gap repair → memory re-check → parallel assess at 2 fails → causal-tree at 3 fails) |
-| 6 | **Learn** | Cross-build pattern detection + experimental skill drafting | optional; requires `runs[] >= 3`; auto-promote opt-in |
-
-### Capability routing table
-
-| Capability | Preferred | Secondary | Inline fallback section |
-|---|---|---|---|
-| Web UI build | `build-loop:ui-design` + `build-loop:design-contract-specialist` (`trigger_point: phase2-design-direction`) + `calm-precision` + `templates/ui-subagent-prompt.md` | `frontend-design:frontend-design` only when explicitly requested | `fallbacks.md#web-ui` |
-| Web UI validation | `ui-validator` agent + `audit-design-rules.mjs` + browser/screenshot artifact | `showcase:capture` for visual evidence | `fallbacks.md#web-ui` |
-| Orchestrated UI build | `build-loop:ui-design` → build-loop-owned design direction → implementer fan-out → ui-validator/design-contract reconciliation | explicit user-invoked design tool artifacts passed to `design-contract-specialist` | `fallbacks.md#web-ui` |
-| Mobile UI build (`uiTarget: "mobile"` — iOS/watchOS sim) | `build-loop:ui-design` + `build-loop:design-contract-specialist` + `calm-precision` + `apple-dev` | — | `fallbacks.md#mobile-ui` + `fallbacks.md#apple-dev` |
-| Mobile UI validation (iOS sim) | `xcrun simctl io booted screenshot` for static; `idb ui tap` for interaction | `showcase:capture` | `fallbacks.md#mobile-ui` |
-| macOS desktop UI build (`uiTarget: "macos"`) | `build-loop:ui-design` + `build-loop:design-contract-specialist` + `calm-precision` + `apple-dev` | — | `fallbacks.md#mobile-ui` + `fallbacks.md#apple-dev` |
-| macOS desktop UI validation | IBR `scan_macos` when `availablePlugins.ibr == true`; else `native-ax-driver` against the running `.app` (pid-anchored). NEVER `xcrun simctl` (no macOS simulator). NEVER `nm`/`strings` as substitute. | `showcase:capture` for screenshot evidence | `fallbacks.md#mobile-ui` |
-| Design system tokens | `design-contract-specialist` reads project token/theme/component files and records the source in `.build-loop/app-contract/ui.md` | — | `fallbacks.md#design-tokens` (reads consumer project's token files — never hardcodes) |
-| Recent design structures | `design-contract-specialist` reads `references/recent-design-structures.md` and selects by product/workflow/data fit | explicit design-tool artifacts passed as evidence | `fallbacks.md#web-ui` |
-| Screenshot / visual evidence | `showcase:capture`, `showcase:record` | `screenshot` MCP tool | `fallbacks.md#screenshot` |
-| Web content fetching (low LLM) | `scraper-app:web-scraper` SDK | — | `fallbacks.md#web-fetch` (flags LLM cost in report) |
-| Deep debugging | `build-loop:debug-loop` + `build-loop:debugging-memory` native search/store | standalone Coding Debugger only when explicitly installed for cross-project memory | `fallbacks.md#debug` |
-| Bug-pattern memory | `build-loop:debugging-memory` | — | `fallbacks.md#bug-memory` (greps `.build-loop/issues/` + `.bookmark/`) |
-| Agent authoring | `agent-builder:agent-builder-anthropic` | `plugin-dev:agent-development` (if plugin work) | `fallbacks.md#agent-authoring` |
-| DeepAgents / local-LLM agent work | `build-loop:building-with-deepagents` (SubAgent API, middleware stack, per-agent tool scoping, anti-patterns) | — | Read installed `deepagents` source: `python3 -c 'import deepagents, os; print(os.path.dirname(deepagents.__file__))'` then `graph.py` + `middleware/subagents.py` |
-| Structured reports / handoffs | `pyramid-principle:pyramid-short-form` (Review-F reports), `pyramid-long-form` (design docs) | — | `fallbacks.md#structured-writing` (SCQA + MECE skeleton) |
-| Hosted-IDE migration (Replit / Lovable / Bolt / v0) | `replit-migrate:migration-scan`, `migrate-web`, `migrate-ios`; MCP tools `migrate_scan`, `migrate_plan_web`, `migrate_plan_native`, `migrate_map_apis`, `migrate_map_models`, `migrate_check_progress` | — | `fallbacks.md#migration` (manual inventory + stack-translation) |
-| Prompt authoring / review / audit (system prompts, agent prompts, eval judges) | `prompt-builder:prompt-builder` skill; slash commands `/prompt-builder:optimize`, `/score`, `/compare`, `/save`, `/list`. Calibrates to model tier (T1/T2/T3) and deployment (interactive, backend, rag_pipeline, agent, plugin, eval_judge, personal_mobile). Returns 6-Part-Stack prompt + 5-dim score + diagnosis + `[ASSUMED:]` tags + `TEMPERATURE_HINT` | `prompt-builder` (personal skill, same name, loaded via Skill tool) | `fallbacks.md#prompt` |
-| iOS / watchOS / macOS dev + deploy | `apple-dev` personal skill (via `Skill("apple-dev")`) | `replit-migrate:migrate-ios` (when migrating *to* native) | `fallbacks.md#apple-dev` |
-| Web deploy verification (Vercel) | Vercel MCP (`mcp.vercel.com` remote OAuth, only if user adds it to `.mcp.json`) | Vercel CLI via `scripts/verify_deploy.py` | `fallbacks.md#web-deploy-verify` |
-| Strategic frame / PRD grounding (Assess + Review) | `build-loop:prd-bridge` — reads `docs/prd-*.md` frontmatter (`core_principles`, `load_when`) + Navigation Map + Section Index in Phase 1; verifies diff doesn't violate principles in Phase 5 Fact-Check; recommends `prd-builder` skill if no PRD exists. Falls back to grep on principle keywords if frontmatter parser unavailable. | `prd-builder` skill direct invocation | Phase 1 captures north-star + intent fresh into `intent.md` (existing fallback) |
-| Architecture scan / impact trace (Assess + Review) | `build-loop:architecture-scan` (Assess refresh), `build-loop:architecture-impact` (blast-radius), `build-loop:architecture-rules` (Review violation check), `build-loop:architecture-dead` (orphan scan) — read `.navgator/architecture/` JSON; native skills sourced from NavGator with provenance and drift-detection via `build-loop:sync-skills` | `gator:*` commands if installed | Read component → edit → re-read downstream |
-| Debugger memory-first gate (Review + Iterate) | `build-loop:debugging-memory` — verdict gate (`KNOWN_FIX` / `LIKELY_MATCH` / `WEAK_SIGNAL` / `NO_MATCH`) with strict direct-apply triple-gate (file + version + secondary signal) and Review-F outcome feedback. Orchestrator owns the when-to-fire policy (Review-B + every Iterate attempt) and routes to this skill. | `build-loop:debug-loop` direct (when memory says enter the loop or 3 same-criterion failures) | `fallbacks.md#debug` |
-| Runtime visibility / observability (Assess + reactive Review/Iterate) | `build-loop:logging-tracer` — generates stack-appropriate structured logging / OTel with ephemeral-by-default policy (Mechanism A: `DEBUG_TRACE=1` runtime gate; Mechanism B: `git-stash` throwaway). Invoked reactively when an Iterate attempt flags `evidence_gap: true`. Orchestrator runs the passive Assess scan inline (no skill call needed) and only loads this skill when instrumentation is actually being added. | — | `fallbacks.md#logging-fallback` (inline Tier-1 zero-dep JSON logger per stack) |
-| Self-improvement / recurring pattern detection (Phase 6 Learn) | `build-loop:self-improve` — runs after every build; detects recurring failures and manual interventions; drafts experimental skills/agents to `.build-loop/skills/experimental/`. Auto-promote to `.build-loop/skills/active/` requires opt-in (`autoPromote: true`) plus effective non-confounded sample ≥ 8; regressions and inconclusive results write proposals to `.build-loop/proposals/` for user confirmation — never auto-remove. Cross-project promotion via `/build-loop:promote-experiment <name>` | — | Manual review of `.build-loop/state.json.runs[]` |
-| Context recovery after compaction | `bookmark:*` commands | — | Re-read last plan file in `.build-loop/` |
-| Claude Code plugin authoring / review | `plugin-builder` (personal skill), `plugin-dev:*` family | `build-loop:plugin-hygiene-lessons.md` enforces manifest/hook/marketplace rules in Review-D | Read `plugin-hygiene-lessons.md` verbatim |
-
-### Sub-routers (set during Phase 1)
-
-**UI target**: prefer the most specific match — order matters.
-
-1. **macOS desktop (`uiTarget: "macos"`, `platform: "apple"`)** — `*.xcodeproj` or `Package.swift` is present AND any of: (a) project has NO `ios/` directory AND has `Sources/` / `App/` with `*.swift`; (b) Xcode project's `SUPPORTED_PLATFORMS` / deployment target indicates macOS; (c) repo grep shows `import AppKit` or `import SwiftUI` paired with `WindowGroup`/`Window` (macOS scene types) and no `UIKit` import. macOS has no simulator; validation routes to `native-ax-driver` or IBR `scan_macos`, never to `xcrun simctl`.
-2. **iOS/watchOS mobile (`uiTarget: "mobile"`, `platform: "apple"`)** — `ios/` directory present, OR `*.xcodeproj`/`Package.swift` with `UIKit` import / `iOS` deployment target. Validation uses the iOS simulator screenshot path.
-3. **React Native mobile (`uiTarget: "mobile"`, `platform: "react-native"`)** — `app.json` (Expo) or `App.tsx` with `react-native` import.
-4. **Web (`uiTarget: "web"`, `platform: "web"`)** — fallback for everything else with a UI surface.
-
-Tie-breaker: if signals are mixed (an Apple project with both `ios/` and a macOS target), set `uiTarget: "mobile"` and surface a one-line note in Assess; the build can override via `state.json.uiTarget` if the goal targets the macOS surface.
-
-**Migration source**: if `.replit` / `replit.nix` present → `migrationSource: "replit"`. Lovable / Bolt / v0 export markers (e.g. `lovable.config`, `bolt.config`, `v0.dev` in comments) → corresponding source. `replit-migrate` skills generalize — load `migration-scan` for any of the above, override hints as needed.
-
-**Apple deploy**: when `platform: "apple"` AND goal includes "deploy", "TestFlight", or "App Store" → Phase 7/8 invoke `apple-dev` deploy flow using ASC creds from your harness memory store (e.g. `~/.claude/projects/<project-slug>/memory/reference_asc_credentials.md`). Apply deployment policy first: TestFlight/App Store Connect upload/export defaults to `auto`; App Store production release/submission defaults to `confirm`.
-
-**Web deploy verify**: fires when `.vercel/project.json` or `vercel.json` is present AND the build performed a push/deploy → Phase 4 Review-B invokes `scripts/verify_deploy.py` (preferred-tier upgrade: Vercel MCP only if the user has added it to `.mcp.json`). Infra failures return `skipped`, never block the build.
-
-## Trigger Conditions
-
-Some capabilities should fire proactively based on goal phrasing or files touched. Phase 1 ASSESS sets these flags in `.build-loop/state.json.triggers`, and Phase 4 EXECUTE consults them before dispatching each subagent.
-
-**pyramid-principle** (structured writing)
-
-Fires whenever the build produces user-visible prose or professional writing. Even small text should follow pyramid structure, and the logical ordering principle applies to design flow too.
-
-Trigger if any of:
-
-- Task touches user-visible text inside the app: copy, microcopy, empty-state messages, error messages, onboarding flow, help content, tooltips, toasts, form labels, email templates, notification text.
-- Task creates or edits: `README.md`, `CHANGELOG.md`, `docs/**/*.md`, PR descriptions, release notes, design docs, status updates, exec summaries, handoff documents.
-- Goal contains: "write", "draft", "summarize", "document", "one-pager", "brief", "memo", "deck", "slides", "presentation", "status update".
-- Designing information architecture or section ordering: use the pyramid logic for top-down flow (governing thought, then MECE key lines, then support).
-
-Action: load `pyramid-principle:pyramid-principle-core` first for ground rules, then the specific skill matching length and format. If absent, use `fallbacks.md#structured-writing`.
-
-**prompt-builder** (prompt authoring or audit)
-
-Fires when prompts are a core part of the product, not when prompts appear incidentally in code comments or test fixtures.
-
-Trigger if any of:
-
-- Building or editing prompts that the app sends to an LLM at runtime: document-generation prompts (Example App style), chat-with-user system prompts, voice-interaction prompts (example app style), reranker prompts, eval-judge prompts.
-- Robust agent or prompt pipeline present in the product: multi-step prompts, RAG, tool-use flows.
-- Semantic search over user queries: use `prompt-builder` to revise the query before embedding or retrieval.
-- Authoring a new agent's instructions (the body of an `agents/*.md` file serving as LLM guidance).
-- File signals: `prompts/`, `system-prompt.*`, strings passed to `messages[{role:"system"}]`, `anthropic.messages.create`, `openai.chat.completions.create`, prompt templates in `.prompt` or `.txt` held as product assets.
-- Goal contains: "system prompt", "agent prompt", "prompt engineering", "rewrite this prompt", "improve this prompt", "audit prompts", "eval judge".
-
-Existing prompt guardrail: if the task touches an **existing** in-product prompt (not a new one), pause and ask the user before running `prompt-builder`. Prompts are often tuned against real evals; silent rewrites can regress quality. Offer the option, do not auto-apply.
-
-Action: load `prompt-builder:prompt-builder` (plugin) if installed, else the personal `prompt-builder` skill, else `fallbacks.md#prompt`. For existing-prompt edits, capture before-and-after in `.build-loop/prompts/` with version suffixes so regressions are detectable.
-
-**building-with-deepagents** (DeepAgents / local-LLM agent work)
-
-Fires whenever the project uses the open-source `deepagents` package. DeepAgents has subtle API shape (SubAgent dict, middleware stack, per-agent tool scoping) that makes hand-rolled focus modes and flat-tool-list designs silently wrong — small local models exhibit tool-call hallucinations in ways that scoping fixes and prompt injection doesn't.
-
-Trigger if any of:
-
-- Repo grep: `from deepagents` or `import deepagents` in any Python source file
-- `deepagents` in `pyproject.toml`, `requirements*.txt`, `uv.lock`, or `poetry.lock`
-- Goal mentions: "agent", "sub-agent", "subagent", "planner/researcher/writer", "focus mode", "tool-call hallucination", "LangGraph agent", "ChatOllama", "local LLM agent"
-- File signals: `create_deep_agent`, `SubAgent`, `AGENT_ROLES`, `agent_focus_prompt`
-- Pain symptoms in the conversation: "`<namespace>.<tool>` is not a valid tool", "silent thinking", "model loaded forever", "threads vanish on restart"
-
-Existing-agent guardrail: treat agent definitions like existing prompts — pause before rewriting, capture before-and-after in `.build-loop/agents/` with version suffixes. Tool scoping changes downstream behavior for every query; regressions are expensive to spot.
-
-Action: load `build-loop:building-with-deepagents` before any code edit involving agent construction, tool binding, or streaming. The skill's `references/anti-patterns.md` lists 12 concrete bugs we've hit — verify none of your planned changes reintroduce them.
-
-**Judgment: prompt-builder vs inline prompt**
-
-Not every prompt needs the full engine. Use `prompt-builder` when the prompt is load-bearing. Craft a simple inline prompt when it is throwaway.
-
-Use `prompt-builder` when any of these are true:
-
-- The prompt ships in the product and runs at scale.
-- The prompt is sent to end users or generates user-visible output.
-- The prompt is part of an agent, eval judge, RAG pipeline, or semantic-search query rewriter.
-- Output correctness is measured (evals exist or are planned).
-- The prompt will be reused across features, or maintained over time.
-- Token cost matters because it runs millions of times.
-
-Roll your own inline prompt when all of these are true:
-
-- One-shot usage inside the current build loop (dispatching a subagent, asking Claude to transform a file, generating a migration script).
-- Not persisted to the product codebase.
-- Output is checked once by the orchestrator, not by an eval.
-- A short direct instruction is clearer than a 6-Part Stack.
-
-Default when uncertain: if the prompt text will exist in the repo after the build, use `prompt-builder`. If it only exists as a line in an orchestrator message during this build, inline is fine.
-
-### Plugin / hook / skill / agent work — mandatory
-
-If Phase 1 detects that the task touches plugin components, Phase 3 must map each task to the authoritative skill below and Phase 4 must load that skill. **Do not infer plugin formats from memory or by reading another plugin's config.**
-
-| Task surface | Skill (authoritative) | Fallback |
-|---|---|---|
-| `.claude-plugin/plugin.json` | `plugin-dev:plugin-structure` | Read `RossLabs-AI-Toolkit/LESSONS-LEARNED.md` — paths must start with `./` |
-| `hooks/hooks.json` or hook scripts | `plugin-dev:hook-development` + run `plugin-dev/scripts/hook-linter.sh` | Command hooks default; Stop stdout must be valid JSON; advisory/non-blocking unless an explicit safety/security/integrity gate opts into blocking; NO prompt hooks on PostToolUse/Stop/SessionStart |
-| Slash commands (`commands/*.md`) | `plugin-dev:command-development` | — |
-| Subagents (`agents/*.md`) | `plugin-dev:agent-development` + `RossLabs-AI-Toolkit/agents/` | `fallbacks.md#agent-authoring` |
-| MCP servers (`.mcp.json`) | `plugin-dev:mcp-integration` | `.mcp.json` must NOT wrap with `mcpServers` key (Method 1) |
-| `~/.claude/settings.json` | `plugin-dev:plugin-settings` | — |
-| New skill (SKILL.md) | `plugin-dev:skill-development` + `skill-builder` (personal) | Official skill format; SKILL.md ≤200 lines |
-| New plugin end-to-end | `plugin-builder` (personal) → delegates into `plugin-dev:*` | — |
-
-### External knowledge — check before coding
-
-| Source | When | How |
-|---|---|---|
-| `/cookbook` | Claude API patterns: tool calling, PTC, code execution, Agent SDK, RAG, thinking, structured output, batch, caching | Invoke `/cookbook` or read `reference_claude_cookbook.md` from your harness memory store (`~/.claude/projects/<project-slug>/memory/`) |
-| `RossLabs-AI-Toolkit/LESSONS-LEARNED.md` | Any plugin work | Read during Phase 1 ASSESS |
-| `context7` MCP | Any library/framework use | `query-docs` / `resolve-library-id` — do NOT code from training data |
-| `research` skill | Factual claims, pricing, versions | Run `scripts/research_trigger.py` first; T1 official docs → T4 forums; 2-source minimum |

package/plugin-artifacts/codex/skills/build-loop/references/codex-subagents.md

@@ -1,106 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Codex Subagent Adapter
-
-Use this adapter when Build Loop runs inside Codex. It translates Build Loop's host-neutral "parallel subagents" concept into Codex-native delegation without changing Claude Code's `agents/*.md` runtime.
-
-## Core Rule
-
-Codex may use subagents only when the user explicitly authorizes delegation or parallel agent work. Examples: "use subagents", "parallelize this", "delegate", "spin up workers", or `/build-loop --parallel ...`.
-
-If authorization is absent, keep the work local in the lead Codex session. Still write the same MECE plan and ownership packets, but do not spawn workers.
-
-## Role Mapping
-
-| Build Loop need | Codex role | Use when |
-|---|---|---|
-| Codebase question | `explorer` | The answer can be read-only, bounded, and returned as facts with file paths. |
-| Implementation slice | `worker` | The write set is disjoint from other workers and the interface contract is clear. |
-| Phase 4 review passes | lead session inline, or `explorer` if authorized | See the enumerated passes below — the lead owns these whether or not delegation is allowed. |
-| Final integration | lead session | The lead must own merge, validation, and final judgment. |
-
-**Phase 4 review is not one pass — it is a set.** Whether run inline (default) or via an authorized `explorer`, the lead must cover all of these every non-trivial build; do not skip a pass just because Codex lacks a dedicated agent file for it:
-
-- **Adversarial audit (independent-auditor)** — read the diff against intent/goal/PRD/constitution; verdict `yay`/`nay`/`suggest_correction`/`look_again`. Advisory at chunk close, gating at build scope.
-- **Fact-check** — trace every rendered metric (%, $, score, count) to its source; flag absolute claims. *Blocking* when a rendered number is unverifiable.
-- **Mock-data scan** — production paths only; lorem/faker/hardcoded/`Math.random()`-in-display. *Blocking* when it renders to the user.
-- **Security review** — only when Assess flagged a risk-surface change (auth, network, persistence, secrets, external input); OWASP LLM/Agentic/Web top-10. *Blocking* on critical/high (feeds the exit gate).
-
-The first row's "read-only, does not block" applies to the adversarial-audit *critic* pass; the fact-check, mock-scan, and security passes CAN block and route to Iterate.
-
-## Permission Gate
-
-Before spawning any Codex subagent:
-
-1. Confirm user authorization is explicit in the current request or command flags.
-2. Confirm the task is not on the immediate critical path.
-3. Confirm the subtask has a bounded write set or read-only question.
-4. Confirm the prompt includes a MECE ownership packet.
-
-If any condition fails, do the work locally.
-
-## When Not To Delegate
-
-- Ambiguous product decisions.
-- Final integration or final report.
-- Destructive git operations.
-- Push/deploy confirmation.
-- A task whose result is required before the lead can make the next local move.
-- Files already owned by another active worker.
-- Cross-file architecture decisions that were not settled in the plan.
-
-## Prompt Packet Required
-
-Every Codex worker prompt must include:
-
-- `task`: one concrete outcome.
-- `owns`: exact files or directories the worker may edit.
-- `does_not_own`: files, directories, or responsibilities the worker must avoid.
-- `context`: condensed facts from Phase 1 and Phase 2.
-- `interface_contract`: functions, routes, schemas, props, CLI flags, or docs the worker must preserve or expose.
-- `integration_checkpoint`: what the lead will verify before merging the worker result.
-- `validation`: commands the worker should run if feasible.
-- `return_format`: changed files, summary, validation, unresolved risks, integration notes.
-
-Tell every worker: "You are not alone in the codebase. Do not revert edits made by others; adapt around them and report conflicts."
-
-## Context Policy
-
-Prefer explicit prompt packets over full context forks. Use full context only when the worker genuinely needs the thread history to avoid a wrong implementation.
-
-Shared reads should happen once in the lead session, then be condensed into worker prompts. This keeps workers focused and reduces contradictory interpretations.
-
-### Prompt Cache Discipline
-
-OpenAI prompt caching is automatic, so Build Loop cannot call the cache directly from Codex. The lever the Codex adapter controls is prompt shape: keep the reusable prefix stable, and move volatile task state later.
-
-For Codex CLI and Codex app runs, put reusable role rules, output contracts, validation expectations, and ownership schema before task-specific facts. Put Rally state, timestamps, command output, diffs, browser comments, thread IDs, worktree metadata, current claims, and task IDs after the stable contract.
-
-Do not reorder stable sections between worker prompts. Monitoring cached-token counters only detects prefix churn; the improvement comes from preserving the prefix and reducing noisy context before dispatch.
-
-## Parallel Pattern
-
-1. Lead creates the plan and identifies parallel-safe groups.
-2. Lead spawns only independent sidecar work.
-3. Lead continues non-overlapping local work while workers run.
-4. Lead waits only when blocked on a worker result.
-5. Lead reviews changed files and integrates deliberately.
-6. Lead runs final validation locally.
-
-## Return Format
-
-Workers should finish with:
-
-```text
-Changed files:
-- <path>: <what changed>
-
-Validation:
-- <command or "not run">: <result or reason>
-
-Integration notes:
-- <contract, migration, or ordering notes>
-
-Unresolved risks:
-- <risk or "none known">
-```

package/plugin-artifacts/codex/skills/build-loop/references/coordination.md

@@ -1,161 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Coordination — How build-loop consumes agent-rally
-
-Build-loop is a **consumer** of the agent-rally architecture, but it currently
-vendors native embedded copies of the substrate and watcher while the standalone
-repos mature. Treat `agent-rally-point` and `agent-rally-watcher` as
-mini-plugins inside build-loop: grouped scripts, skills, docs, tests, and thin
-build-loop adapters first; full spin-out later. Cross-reference the upstream
-architecture docs before changing how build-loop reads or writes events, but do
-not make build-loop depend on those external repos at runtime yet.
-
-> **Binding constitution** (verdict-gating, MECE briefs, Phase D closeout, peer-no-mutate, release-surface verification) lives in [`references/coordination-rules.md`](../../../references/coordination-rules.md). This file documents the **integration shape**, not the rules of engagement.
-
-## Build-loop's position in the three-layer model
-
-```
-Layer 3 — CONSUMERS (build-loop, codex, claude_code, ...)
-              ▲
-              │  build-loop is one of many
-              ▼
-Layer 2 — agent-rally-watcher (embedded watcher namespace; optional listener)
-              ▲
-              │  build-loop CAN subscribe, OR poll Layer 1 directly
-              ▼
-Layer 1 — agent-rally-point (embedded substrate; channel, schema, post API)
-```
-
-Build-loop **always** uses Layer 1 (it posts events and calls `checkpoint_read`). It uses Layer 2 **opportunistically** — when a peer session is detected via Rally Point presence, the coordination polling gate spins up a `coordination_watch.py` loop or installs a watcher subscription so chunk-close, commit, and feedback events surface within seconds rather than at the next phase boundary.
-
-Native skill entrypoints:
-
-- `skills/agent-rally-point/SKILL.md` — substrate workflow, CLI, boundary,
-  run identity, and spin-out rules.
-- `skills/agent-rally-watcher/SKILL.md` — watcher workflow, JSONL sensor
-  behavior, closeout, and spin-out rules.
-
-The machine-readable boundary is `scripts/rally_point/plugin_boundary.json`.
-
-## What build-loop posts
-
-Every cross-session signal goes through `scripts/rally_point/post.py::post()` (the canonical writer that bumps revision *before* appending — see [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md) for the field-by-field record format). Raw `append_change(...)` without a subsequent `bump_revision(...)` is a silent-no-op for peers (`feedback_codex_pass_is_gate_not_comment`).
-
-| When                                  | `kind`       | `payload` shape                                                  | Triggered by                       |
-|---------------------------------------|--------------|------------------------------------------------------------------|------------------------------------|
-| Chunk closes and lands on the branch  | `phase`      | `{phase: "chunk-close", chunk_id, commit_sha, files_changed}`    | Phase 3 commit step                |
-| Phase boundary (Phase 1, 4, 5)        | `phase`      | `{phase: "<phase-name>", summary, ...}`                          | Orchestrator phase entry           |
-| Build run closes (Phase D)            | `phase`      | `{phase: "run-closeout", session_id, coord_file, outcomes}`      | Phase D closeout sequence          |
-| Peer hands off work to a verifier     | `handoff`    | `{from_tool, to_tool, work_item, deadline_ts}`                   | Sub-step F when a peer is present  |
-| Verifier returns a verdict            | `feedback`   | `{step, verdict: PASS|VARIANCE|BLOCKED, rationale, evidence}`    | After verifier runs on a step      |
-| Architecture scan completes           | `arch-scan-complete` | `{digest_path, files_scanned}`                            | Phase 1 architecture baseline      |
-| Dependency manifest changed           | `dep-change` | `{manifest, added, removed, session_id}`                         | Phase 3 commit step on manifest    |
-| Coordination announcement / take-over | `phase`      | `{phase: "leadership", role, scope}`                             | Multi-orchestrator handoff         |
-
-All writes are fire-and-forget — a coordination failure must never crash the build.
-
-## What build-loop reads
-
-### Phase 1 Assess — inbox pickup + presence check
-
-At Phase 1 entry, the orchestrator (see `agents/build-orchestrator.md` §"Phase 1: Assess") runs:
-
-```bash
-python3 scripts/coordination_status.py --workdir "$PWD" --session-id "$SESSION_ID" --json
-```
-
-The status reports: active peers (live sessions in the channel's `sessions/`), session-ack-aware unread inbox messages (`inbox/<my-tool>.jsonl`, `inbox/all.jsonl`), task-heartbeat health when `--task-ref` is set, and any active coordination file. If `active_peers > 0` OR `inbox_unread_count > 0`, the orchestrator MUST drain the inbox before dispatching any chunk; otherwise the peer's last verdict/handoff is invisible to the new run. After acting on the inbox payload, run `python3 scripts/agent_rally.py ack-inbox --workdir "$PWD" --session-id "$SESSION_ID" --tool "$TOOL_ID" --json` so stale notes stop ringing the doorbell.
-
-### Coordination polling gate — watcher install when a peer is present
-
-When the Phase 1 status returns peers, build-loop installs a cheap continuous watcher:
-
-```bash
-python3 scripts/coordination_watch.py --workdir "$PWD" --session-id "$SESSION_ID" --tool claude_code --task-ref "$TASK_REF" --interval 5 --jsonl --baseline-current
-```
-
-The watcher reports revision changes, inbox deltas, and task-heartbeat health as line-delimited JSON. The orchestrator polls it before commits, before final responses, and after any 30-second work interval. When a peer posts (e.g. a verifier returns a `feedback` verdict), the orchestrator routes the response into the active coordination file's "Codex feedback log" section rather than asking the user to paste it.
-
-For long-running work, write `agent_rally.py heartbeat --task-ref "$TASK_REF"`
-at task start and at least every 10 minutes. Presence says the session is live;
-task heartbeat says it is still on the claimed task.
-
-The watcher process is OPTIONAL — if the daemon process can't start (no FS-watch support, sandboxed environment), the orchestrator falls back to per-checkpoint `coordination_status.py` polls. The same flow works; latency is higher.
-
-### Chunk-close — checkpoint read for downstream chunks
-
-After each chunk's commit step closes, the orchestrator runs `checkpoint_read` against this session's cursor to surface any peer events that landed during the chunk. Reactions (`reinstall`, `re-baseline`, `soft-claim`) are documented in [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md). Reactions are **awareness only** — `soft-claim` warns when a peer touched files this session also plans to touch; the orchestrator decides whether to wait, rebase, or proceed.
-
-## Peer-no-mutate rule
-
-When a peer presence record indicates active work AND that work isn't already merged (`branch_merge_status: unmerged` AND files differ from `origin/main`), build-loop's orchestrator MUST NOT modify the same files. The rule and the merge-status pre-check are in [`references/coordination-rules.md`](../../../references/coordination-rules.md) §"Peer-no-mutate" and `feedback_verify_peer_merged_before_blocking`.
-
-Read-only operations (Phase 1 architecture baseline, plan drafting, fact-check) are always safe and do not invoke the rule.
-
-## Embedded mini-plugin boundary
-
-For now, the Rally Point substrate and watcher still ship inside the
-build-loop plugin, but they are treated as embedded mini-plugins with
-explicit extraction edges:
-
-| Future plugin | Embedded namespace | Build-loop compatibility entrypoints |
-|---|---|---|
-| `agent-rally-point` | `scripts/rally_point/**` | `scripts/agent_rally.py`, `commands/rally-point.md`, `hooks/*rally-point.sh`, `scripts/coordination_status.py`, `scripts/coordination_rally.py`, `scripts/coordination_bootstrap.py` |
-| `agent-rally-watcher` | `scripts/agent_rally_watcher/**` | `scripts/coordination_watch.py` |
-
-The machine-readable contract lives at
-`scripts/rally_point/plugin_boundary.json` and is validated by:
-
-```bash
-python3 scripts/rally_point/boundary.py --repo "$PWD" --check --json
-python3 scripts/agent_rally.py boundary --workdir "$PWD" --check --json
-```
-
-Boundary rule: put substrate behavior in `scripts/rally_point/**`, watcher
-behavior in `scripts/agent_rally_watcher/**`, and leave build-loop files as
-thin adapters. Do not import build-loop memory-store or orchestration internals
-from those namespaces unless the dependency is explicitly isolated as an
-adapter in the boundary manifest.
-
-## Discovery integration (current)
-
-Build-loop uses `scripts/rally_point/discovery_bridge.py` as the shared
-channel resolver. It prefers the standalone `agent-rally-point` discovery
-surface when installed and falls back to build-loop's embedded resolver only
-when needed. Both native discovery and the embedded fallback default to
-`~/.agent-rally-point/apps/...`; the fallback uses the local worktree-aware
-`<slug>` when no native `<repo-id>` is available.
-
-The discovery layer (see
-[`agent-rally-point/docs/DISCOVERY.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/DISCOVERY.md))
-provides:
-
-```python
-from agent_rally_point.discover import discover
-info = discover()  # returns dict with channel_dir, channel_layout, active_revision, active_peers, ...
-channel_dir = info["channel_dir"]   # canonical OR legacy-fallback path
-```
-
-Current build-loop callers route through the bridge:
-
-1. `scripts/agent_rally.py` resolves `where`, `presence`, `handoff`, `lead`,
-   and `boundary` through the shared namespace.
-2. `scripts/coordination_status.py` reads status from the resolved channel
-   instead of deriving a parallel channel path.
-3. `scripts/rally_point/session_probe.py` and `scripts/rally_point/hooks.py`
-   use the resolved channel for session-start and pre-edit hook behavior.
-4. `scripts/coordination_watch.py` remains a compatibility wrapper; watcher
-   behavior lives under `scripts/agent_rally_watcher/`.
-
-## Cross-references
-
-- **Substrate (channel format, post API, presence, lifecycle)** — [`agent-rally-point/ARCHITECTURE.md`](https://github.com/tyroneross/agent-rally-point/blob/main/ARCHITECTURE.md)
-- **Record schema (all 6 kinds + payloads)** — [`agent-rally-point/docs/SCHEMA.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/SCHEMA.md)
-- **Discovery protocol (manifest, CLI, `discover()`)** — [`agent-rally-point/docs/DISCOVERY.md`](https://github.com/tyroneross/agent-rally-point/blob/main/docs/DISCOVERY.md)
-- **Push-based daemon (consumers.toml, sinks)** — [`agent-rally-watcher/ARCHITECTURE.md`](https://github.com/tyroneross/agent-rally-watcher/blob/main/ARCHITECTURE.md)
-- **Binding constitution (verdicts gating, MECE briefs, Phase D closeout)** — [`references/coordination-rules.md`](../../../references/coordination-rules.md)
-- **Per-run coordination file template** — [`references/coordination-file-template.md`](../../../references/coordination-file-template.md)
-
-## Why a separate doc
-
-`coordination-rules.md` is the binding *constitution* — operating rule, verdict gating, MECE field list, closeout sequence. This file is the *integration map* — where build-loop sits in the three-layer architecture, what it posts, what it reads, where the path-hardcoding lives, and what the discovery migration looks like. Conceptually distinct audiences: the rules file is for any participant; this file is for build-loop's orchestrator and anyone modifying how build-loop talks to rally-point.