@tyroneross/build-loop 0.36.0 → 0.43.0

package/plugin-artifacts/codex/references/backlog-system.md

@@ -1,285 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Backlog System — host-agnostic, multi-repo deferred-work tracker
-
-A backlog is the durable list of wanted-but-not-now work for a repo: deferred
-debt, blocked infra, known fixes, pending decisions. This system makes that list
-**host-neutral** (any coding agent — Claude, Codex, or other — reads and writes
-it the same way), **filesystem-first** (grep + frontmatter, no DB/vector/graph),
-and **aggregatable** across all of one user's repos via their personal memory.
-
-## Why it is shaped this way
-
-Five research-grounded principles drive the design (from the memory-architecture
-guide; Letta filesystem-memory benchmark; "don't over-engineer"):
-
-1. **Canonical truth vs derived index.** The items in `items/` are the truth.
-   `INDEX.md` is a *generated, rebuildable* view — never hand-edited.
-2. **Metadata-rich items.** Each item carries provenance, evidence,
-   supersession links, and a TTL (`review_by`) so it can be audited and aged.
-3. **Filesystem-first retrieval.** Reading = `cat BACKLOG.md` → `INDEX.md`, then
-   `grep` over `items/*.md` frontmatter. No index server, no embeddings.
-4. **Lifecycle ops.** Formation (`new`) → consolidation (`sync` archives
-   done/dropped, flags stale) → retrieval (`list`, grep) → forgetting
-   (archive, never delete).
-5. **Governance Level 3.** Every write is logged, timestamped, attributable —
-   git history + `created`/`updated` stamps + archive-not-delete provide it.
-
-## Two scopes (do not conflate)
-
-| Scope | Path | Lifetime | Shared? |
-|---|---|---|---|
-| **Per-repo backlog** | `<repo>/.build-loop/backlog/` | Travels with the repo; committed | Team-shareable (in the repo) |
-| **Personal memory mirror** | `build-loop-memory/projects/<slug>/backlog/` | Per-user, aggregated across ALL the user's repos | Private to the user |
-
-The sync is **one-way**: per-repo backlog → personal memory. The per-repo store
-is the source of truth; the memory mirror is a cross-repo read view for the user
-who downloaded build-loop.
-
-## Structure
-
-```
-<repo>/
-├── BACKLOG.md                      # repo-root pointer → .build-loop/backlog/INDEX.md
-└── .build-loop/backlog/
-    ├── README.md                   # what this dir is + how to use it
-    ├── .gitattributes              # INDEX.md merge=ours (resolve by regeneration)
-    ├── INDEX.md                    # DERIVED — regenerated by `sync`; do not edit
-    ├── items/<ID>.md               # CANONICAL truth — one file per item
-    └── archive/<ID>.md             # done/dropped items (never deleted)
-```
-
-`<ID>` = `<PROJSLUG>-<AREA>-<token>` — e.g. `ATOM-SEARCH-mt3k9p7q`. The prefix is
-derived from the repo basename; the **token** is a coordination-free,
-collision-resistant suffix: 8 Crockford-base32 digits of millisecond time
-(so `ls items/` still roughly sorts by creation) followed by 5 digits of
-`os.urandom` entropy (so the ID is unique across agents, machines, branches, and
-clones with **no shared counter**). Lowercase throughout.
-
-**Why not the old sequential `-NNN`?** A per-area zero-padded counter is a
-single-writer assumption. Two agents in independent worktrees/clones (Claude on
-branch A, Codex on branch B) each read their OWN highest-NNN and both minted the
-SAME `...-001/002/003` for DIFFERENT items — on `git merge` the identical
-filenames/IDs collided or silently lost an item. The token removes the shared
-counter entirely. The readability trade-off (IDs gain a ~13-char token suffix
-instead of `-001`) is paid back by `INDEX.md`, which is the human-ordered
-navigation view; the items themselves are addressed by token.
-
-**Legacy `-NNN` items still read.** Items minted before this change (and any
-hand-authored `-NNN`) remain valid: the ID-shape regex accepts BOTH a token
-suffix and a legacy `\d{3,}` suffix, and no parser assumes a numeric tail.
-Existing IDs are never rewritten — only NEW items get tokens.
-
-## Item schema (frontmatter on every `items/<ID>.md`)
-
-```yaml
-id: ATOM-SEARCH-001
-title: <one line>
-status: open            # open | in-progress | blocked | deferred | done | dropped
-priority: P2            # P0..P3
-type: debt              # feature | fix | debt | infra | decision | cleanup | research
-area: search            # free-ish tag; the grep + filter routing key
-entities: [pg_trgm, keyword-leg]
-gated: db-migration     # none | prod-deploy | db-migration | infra | product-decision
-provenance: { source: followup, ref: <path/commit/PR#/chat-date> }
-evidence: [<commit/PR/retro/followup paths>]
-supersedes: null
-superseded_by: null
-created: 2026-06-16
-updated: 2026-06-16
-review_by: 2026-07-16   # TTL — surfaced by `sync` when passed
-owner: unassigned
-```
-
-Body sections: `## Context`, `## Acceptance`, `## Notes`.
-
-Dates are caller-stamped (`--today YYYY-MM-DD` or the `BACKLOG_TODAY` env var,
-falling back to the system clock) so the tool runs in harnesses where the clock
-is not callable.
-
-## Lifecycle / sync contract
-
-`scripts/backlog.py sync --repo <path>` does three things, in order:
-
-1. **Consolidate.** Move every `status: done` / `status: dropped` item from
-   `items/` to `archive/`. Never deletes. Flags items whose `review_by` has
-   passed as stale. Warns about `.build-loop/{followup,issues,proposals}` files
-   not yet referenced by any item's `evidence`/`provenance.ref` (scattered work
-   not yet triaged into the backlog).
-2. **Regenerate INDEX.** Rebuild `INDEX.md` deterministically from the remaining
-   items' frontmatter — grouped status → area → priority, with a compact table,
-   a summary (active count, open P0/P1, stale count, gated count), and a stale
-   call-out. For a FIXED item set re-rendering is **byte-identical** (no
-   wall-clock in the body), so `sync` is safe to re-run and diff-clean. The INDEX
-   write is atomic (temp file + `os.replace`), so a concurrent `sync` by two
-   agents never leaves a torn file for a reader. **Duplicate-ID guard
-   (defense in depth):** if two items ever share an `id` (a bad merge, a
-   hand-edit), `sync` surfaces them LOUDLY in a `## ⚠ Duplicate IDs` section
-   (id, count, all titles, all paths) instead of silently rendering one — so a
-   collision that did happen is visible.
-3. **Mirror to personal memory.** Copy active item files (+ a mirror INDEX) into
-   `build-loop-memory/projects/<slug>/backlog/`. Each mirror file is written
-   atomically (temp file + `os.replace`), so a parallel session never observes a
-   half-written file; last-writer-wins (the per-repo backlog is the truth).
-   Best-effort: if the memory root is absent or unwritable, sync still succeeds
-   and reports `mirror.skipped`.
-
-### INDEX.md merge handling
-
-`INDEX.md` is fully derived, so two agents that both regenerate it WILL conflict
-on `git merge`. The scaffold (via `adopt` AND any backlog materialisation by
-`new`/`sync`) drops a `.build-loop/backlog/.gitattributes` with:
-
-```gitattributes
-INDEX.md merge=ours
-```
-
-so git resolves the conflict by keeping one side instead of inserting conflict
-markers. **On an `INDEX.md` conflict, run `backlog.py sync` — `items/` is the
-truth and the INDEX regenerates deterministically.** Item files in `items/`
-don't conflict once IDs are unique (token suffix → separate paths), so both
-branches' new items survive a merge.
-
-## How ANY agent uses it (host-neutral)
-
-**Read** (no tools required — just the filesystem):
-1. `cat <repo>/BACKLOG.md` → follow the pointer to `INDEX.md`.
-2. `cat <repo>/.build-loop/backlog/INDEX.md` for the grouped view.
-3. `grep -l 'area: search' <repo>/.build-loop/backlog/items/*.md` to find items
-   by any frontmatter field; read the matching item bodies.
-
-**Write** (via the pure-stdlib CLI — works under bare `python3`, no host SDK):
-```bash
-# create
-python3 scripts/backlog.py new --repo <path> --area search --type debt \
-    --title "pg_trgm for keyword leg" --priority P1 --gated db-migration \
-    --provenance-source followup --provenance-ref .build-loop/followup/x.md \
-    --today 2026-06-16
-# edit the item body / frontmatter by hand in items/<ID>.md
-# then regenerate + mirror
-python3 scripts/backlog.py sync --repo <path> --today 2026-06-16
-# read
-python3 scripts/backlog.py list --repo <path> --status open
-```
-
-The CLI emits structured JSON (machine-readable) on `new`/`sync`; `list` prints
-a text table (or JSON with `--json`). The host LLM reasons over the structured
-data + the convention — it never calls a vendor API.
-
-## Relationship to existing build-loop surfaces
-
-- `.build-loop/issues/` — current-run bugs (short-lived). A persistent issue is
-  triaged INTO the backlog (`new`), then the issue file is referenced as
-  `evidence`/`provenance.ref` so `sync` stops warning about it.
-- `.build-loop/followup/` — iterate-cap overflow. Same triage path.
-- `templates/backlog-item.md` + `build-loop-memory/projects/<slug>/backlog.md`
-  (the legacy single-table durable backlog) remain valid for build-loop's own
-  self-work tracking; this per-item system is the general, multi-repo surface
-  and writes its mirror to the `backlog/` *subdir* (no clobber of `backlog.md`).
-
-## Phase 1 Assess integration
-
-`scripts/context_bootstrap.py` surfaces a compact backlog line at Phase 1 Assess
-when `.build-loop/backlog/INDEX.md` exists: open P0/P1 count, past-`review_by`
-stale count, and gated count. Cheap (reads the generated INDEX summary only) and
-non-fatal when the file is absent.
-
-It also surfaces a one-time **discoverability nudge** (`backlog_discoverability`)
-when there's something to act on:
-
-- **Adoptable** — the repo has scattered work in `.build-loop/{followup,issues}`
-  but no `INDEX.md` yet → *"Backlog available — run `backlog.py adopt
-  --dry-run --repo .`"*.
-- **Won't travel** — `.build-loop/backlog/` exists but is gitignored → *"Backlog
-  won't travel — run `adopt --apply` to fix `.gitignore`"*.
-
-Both are silent when there's nothing to surface, and neither ever raises.
-
-## Download & upgrade safety
-
-This is the contract that makes the backlog safe to **download** with a fresh
-build-loop and **upgrade** in place over an existing one. The guiding rule:
-*every adoption/upgrade step is additive and reversible; nothing the user
-already had is moved, deleted, or rewritten in a lossy way.*
-
-**1. Additive / never-destructive.** Adoption never touches the existing work
-surfaces. `.build-loop/followup/`, `.build-loop/issues/`, `.build-loop/proposals/`,
-and the personal `build-loop-memory` store are read-only inputs to `adopt` — an
-imported item *links* to its source (`provenance.ref` + `evidence[]` +
-`imported_from`); the source file stays exactly where it was as the inbox /
-provenance record. `sync` likewise only ever archives (`done`/`dropped` →
-`archive/`) and regenerates the derived `INDEX.md`; it never deletes a live item.
-
-**2. Lazy / opt-in scaffolding.** A repo gets backlog dirs and pointer files
-*only* when the user runs `adopt` (or `new`). A downloaded build-loop does not
-litter every repo with an empty `backlog/` on first run — the structure
-materialises on demand. `adopt --dry-run` (the default) reports exactly what it
-*would* create without writing anything, so the user previews before opting in.
-
-**3. The `.gitignore` dependency — and how `adopt` fixes it.** `.build-loop/` is
-gitignored by default (confirmed in both `build-loop` and `sample-app`). That is
-correct for transient run state — but it means the backlog would **not commit
-and therefore would not travel** with the repo (no team-sharing, lost on a fresh
-clone). `adopt` detects this by inspecting `.gitignore` (pure text, no git call)
-and, on `--apply`, appends un-ignore rules so the durable backlog escapes the
-broad ignore:
-
-```gitignore
-# build-loop backlog (added by `backlog.py adopt` — keep so the backlog travels)
-!.build-loop/backlog/
-!.build-loop/backlog/**
-!BACKLOG.md
-```
-
-It reports this loudly (`gitignore.was_ignored: true`, `added: [...]`) and is
-idempotent — re-running never appends the block twice. If `.build-loop/` is not
-ignored, `adopt` leaves `.gitignore` untouched.
-
-**4. Idempotent, dry-run-first migration.** `adopt` defaults to a read-only
-dry-run; `--apply` executes. Re-running `--apply` is a no-op: each imported item
-records `imported_from: <source path>`, and a re-run reads that field across
-`items/` **and** `archive/` and skips any source already imported. No duplicate
-items, no churned `.gitignore`. Verified contract: `adopt --apply` twice → the
-second run's diff (items + `.gitignore`) is empty.
-
-**5. Schema-version tolerance (forward/back compatible).** Every item carries
-`schema_version` (current = `1`). The reader (`read_item`) is deliberately
-tolerant: it **defaults missing known fields** and **preserves unknown fields**.
-An item written by an *older* build-loop (no `schema_version`) reads back with
-defaults filled in; an item written by a *newer* build-loop (carrying fields
-this version doesn't know) reads back without error and with those fields intact.
-So a backlog written by one build-loop version always reads on another — neither
-a downgrade nor an upgrade corrupts or rejects it. Bump `SCHEMA_VERSION` only for
-a contract change a reader must actively know about; the tolerant reader absorbs
-purely-additive field changes without a bump.
-
-**6. `build-loop-memory` is the per-user cross-repo long-term store.** The
-per-repo backlog travels *with the repo* (committed, team-shareable). `sync`
-additionally mirrors active items one-way into
-`build-loop-memory/projects/<slug>/backlog/` — the user's private, cross-repo
-aggregate view. The mirror writes to the `backlog/` **subdir**, so it never
-collides with the legacy single-table `backlog.md`, with `lessons/`, or with
-`decisions/` in that project's memory lane. The mirror is additive: its only
-delete path is pruning orphaned item mirrors (ID-shaped stems whose source item
-was removed), and it never touches a hand-dropped note. If the memory root is
-absent or unwritable, `sync` still succeeds and reports `mirror.skipped`.
-
-**Concurrency note (multi-agent) — two distinct collision classes.**
-
-1. **Distributed (cross-worktree/clone/machine).** Independent checkouts share no
-   filesystem and no counter, so IDs must be collision-free *with zero
-   coordination*. The token suffix (time-ordered + `os.urandom`) provides exactly
-   that: two agents in separate worktrees minting in the same area produce
-   DISJOINT ID sets, so a `git merge` of their `items/` trees lands every item
-   with nothing clobbered. This is the bug the token scheme fixes — the retired
-   sequential counter collided here.
-2. **Same-filesystem concurrent processes.** N `new`/`adopt` processes on ONE
-   filesystem still race on the create. That is handled (kept from the prior fix)
-   by the `O_EXCL` atomic create: exactly one process can create a given path;
-   the rest re-mint a fresh token and retry, bounded. So 8 parallel `new` calls
-   in one area yield 8 distinct files, zero loss.
-
-Together these make the backlog safe as a shared multi-agent work surface across
-both separate checkouts AND concurrent processes — not just a single-writer file.
-The INDEX and memory-mirror writes are atomic (temp + `os.replace`) so a reader
-never sees a torn derived file.

package/plugin-artifacts/codex/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/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">
-```