chore(docs): purge transient plan/spec artifacts missed by post-merge cleanup
- docs/plans + docs/specs (deploy-skill 2026-06-27): predate the BDR-065
lifecycle codification, never swept
- docs/superpowers/{plans,specs} (model-routing 2026-07-15): 6-wave
chantier — final W6 merge closed it without the purge step
Git history at the feature commits is the archive (BDR-065).
This commit is contained in:
Bastien Chanot
File diff suppressed because it is too large
Load Diff
@@ -1,143 +0,0 @@
|
||||
# Model routing — reflection inline (big model) / execution pinned (Sonnet) — design
|
||||
|
||||
**Date**: 2026-07-15 · **Status**: approved (user, 2026-07-15) · **Branch**: `feature/model-routing`
|
||||
**Lifecycle**: transient planning artifact (BDR-065) — committed during the run, deleted post-merge.
|
||||
|
||||
## Principle
|
||||
|
||||
The session model is assumed to be a big reasoning model (Fable 5, or Opus when
|
||||
Fable is unavailable). Everything that **thinks** — brainstorming, planning,
|
||||
technical decisions, audits, loop decisions — runs INLINE in the main
|
||||
conversation, or in subagents that inherit the session model. Everything that
|
||||
**executes** a ready-made plan — writing code, applying fix bundles, commits,
|
||||
deliverable rendering — runs on Sonnet-pinned subagents. A blocking gate
|
||||
enforces the "session = big model" assumption at the entry of every reflection
|
||||
orchestrator.
|
||||
|
||||
User verdicts baked in (2026-07-14/15):
|
||||
- Scope = hybrid: ship-feature/init-project execution → sonnet; `/feat`
|
||||
re-architected (plan inline → dispatch executor); bugfix/hotfix stay fully
|
||||
inline (BDR-050 conserved for them).
|
||||
- Gate = BLOCKING, not advisory.
|
||||
- Audit agents inherit the session model (no opus pin); the gate extends to
|
||||
audit orchestrators.
|
||||
- verifier + security-auditor KEEP `model: sonnet` (job9 decision confirmed).
|
||||
- client-handover-writer → sonnet (requires converting its inline-load to a
|
||||
true dispatch; human gates relocate to the main loop).
|
||||
|
||||
## 1. Blocking model gate
|
||||
|
||||
New `lib/model-check.sh`: resolves the current session model from
|
||||
`settings.json` (physical path resolution — LRN-023 class), normalizes
|
||||
(`claude-fable-5[1m]` → fable, `claude-opus-*` → opus, sonnet, haiku), prints
|
||||
`big|small|unknown`. Exit 0 = big, 2 = small, 3 = unknown.
|
||||
|
||||
New `lib/model-gate.md` snippet (same include pattern as `lib/design-gate.md`):
|
||||
run the check; `small` → STOP the skill: "session model is <X> — reflection
|
||||
requires Fable/Opus. Switch with /model, then relaunch." `unknown` →
|
||||
fail-visible: show the raw value, ask the user to confirm or abort (BDR-025
|
||||
doctrine — unknown never silently passes).
|
||||
|
||||
Wired as a STEP 0 line in the reflection orchestrators:
|
||||
`ship-feature, init-project, feat, bugfix, onboard, seo, geo, web-validate,
|
||||
harden, audit-delta, tour, code-clean`.
|
||||
NOT wired in: `hotfix` (trivial by definition), `commit-change`, `doc`,
|
||||
`status`, `release-candidate`.
|
||||
|
||||
Caveats to prove at implementation time:
|
||||
- `/model` mid-session rewrites settings.json (LRN-098 observed it once —
|
||||
re-prove with a live flip-test before trusting the source).
|
||||
- The helper itself must be flip-tested (LRN-096: an unproven guard is a
|
||||
vacuous guard).
|
||||
|
||||
## 2. Frontmatter pins (`agents/*.md`)
|
||||
|
||||
| Agent | Before | After | Rationale |
|
||||
|---|---|---|---|
|
||||
| feater | (inherit) | **sonnet** | executor as subagent: seo/geo L1 applier + new /feat dispatch |
|
||||
| hotfixer | (inherit) | **sonnet** | L1 applier (seo/geo/web-validate); /hotfix inline unaffected (pin inert on inline load) |
|
||||
| client-handover-writer | opus | **sonnet** | deliverable executor; pin becomes EFFECTIVE only with §5 dispatch conversion (today's opus pin is inert — the agent is inline-loaded) |
|
||||
| analyzer | haiku | **(none — inherit)** | analysis feeds the plan = reflection; runs big via the session model |
|
||||
| verifier | sonnet | keep | F1 confirmed (job9) |
|
||||
| security-auditor | sonnet | keep | F1 confirmed (job9) |
|
||||
| seo-analyzer, geo-analyzer, validator-analyzer | (inherit) | keep (inherit) | audit = reflection = session model; covered by the gate |
|
||||
| code-cleaner | (inherit) | keep (inherit) | audit phase = reflection; fixes hand off to refactorer (sonnet) via CODE-CLEAN-SCOPE.md (job9 H1) |
|
||||
| doc-syncer, onboarder, scaffolder, refactorer, interviewer, plugin-advisor | sonnet | keep | workers/executors |
|
||||
| status-reporter | haiku | keep | mechanical collector |
|
||||
| bugfixer, commit-changer | (inherit) | keep | inline-only playbooks — a pin would be inert |
|
||||
|
||||
## 3. `/feat` re-architecture (partial supersede of BDR-050 — feat only)
|
||||
|
||||
`skills/feat/SKILL.md` absorbs the reflection: analyze-before-plan, design
|
||||
gate, MINI-PLAN, contract (`lib/contract-interview.md`) — all inline. Then
|
||||
dispatches `Agent(subagent_type="feater")` (sonnet via pin) with: the
|
||||
contract, the plan, the branch name, repo conventions.
|
||||
|
||||
`agents/feater.md` is rewritten as a pure executor: implement the plan to the
|
||||
letter, run project checks, commit (no attribution trailers), return a
|
||||
structured summary. No user interaction inside feater (subagents cannot ask) —
|
||||
every decision must be closed pre-dispatch.
|
||||
|
||||
The verify-secure loop moves out of feater.md into the /feat main loop
|
||||
(LRN-083 invariant: loop decisions live in the main loop): fresh verifier →
|
||||
ECARTS → re-dispatch feater with the verdict deltas, bounded 3×; then the
|
||||
security gate. Escalation paths unchanged.
|
||||
|
||||
## 4. SDD execution pinned (ship-feature STEP 4, init-project STEP 8)
|
||||
|
||||
One instruction line in each SKILL.md: every implementation subagent
|
||||
dispatched under `superpowers:subagent-driven-development` MUST carry
|
||||
`model: "sonnet"` in the Agent call. No fork of the superpowers skill — the
|
||||
main loop emits the Agent calls and controls the params.
|
||||
|
||||
## 5. client-handover conversion (inline-load → true dispatch)
|
||||
|
||||
`skills/client-handover/SKILL.md`: collect params inline (URL, logo, options),
|
||||
then `Agent(subagent_type="client-handover-writer")` — the sonnet pin becomes
|
||||
effective. Human gates (per-axis threshold escalation, overrides) RELOCATE to
|
||||
the main loop: the writer returns a structured `GATE NEEDED` status instead of
|
||||
asking; the dispatcher asks the user and re-dispatches (or continues via
|
||||
SendMessage) with the decision. `AskUserQuestion` is removed from the writer's
|
||||
tools.
|
||||
|
||||
OPEN VERIFY POINT: the writer's own nested dispatches (seo/harden re-runs as
|
||||
general-purpose subagents) — verify at implementation what nested children
|
||||
inherit (session model vs parent model). If they inherit the sonnet parent,
|
||||
the re-run audits violate the principle → force the model explicitly in those
|
||||
nested dispatches or lift them to the main loop.
|
||||
|
||||
## 6. web-validate fixes → L1 applier
|
||||
|
||||
STEP 3 stops applying fixes via inline Edit; dispatches `hotfixer` (sonnet)
|
||||
with the fix bundle — same pattern as seo/geo (BDR-061 alignment).
|
||||
|
||||
## 7. Memory / doc / tests
|
||||
|
||||
- New BDR: model-routing principle (reflection inline big / executors sonnet /
|
||||
blocking gate); partial supersede of BDR-050 (feat only); records F1
|
||||
(verifier/security stay sonnet) and the analyzer haiku→inherit change.
|
||||
- README: agent-model table refresh. CHANGELOG Unreleased entry.
|
||||
- Tests: flip-tests for `model-check.sh` (fable[1m] / opus / sonnet / garbage
|
||||
fixtures); gate STOP proven on a small-model fixture (LRN-096); /feat smoke
|
||||
on a throwaway repo (LRN-079): plan inline → dispatch carries sonnet →
|
||||
verify loop decided in main loop; grep census: no executor dispatch without
|
||||
an effective pin.
|
||||
|
||||
## Out of scope / accepted deviations
|
||||
|
||||
- `/doc` and `/commit-change` stay inline on the session model (judgment and
|
||||
execution interleaved; converting them buys little). Revisit under quota
|
||||
pressure.
|
||||
- bugfix/hotfix fully inline (BDR-050 conserved).
|
||||
- No per-agent "fable-else-opus" fallback exists in the harness — the session
|
||||
model IS the fallback mechanism; the gate is its backstop.
|
||||
|
||||
## Risks
|
||||
|
||||
- Model strings in settings.json may change shape with CC updates →
|
||||
model-check must return `unknown` (fail-visible), never guess.
|
||||
- feater as a subagent loses main-conversation context → the plan becomes the
|
||||
contract; weak plans cost verify-loop iterations. Mitigation:
|
||||
contract-interview stays mandatory in /feat.
|
||||
- Nested model inheritance under client-handover-writer unknown → §5 verify
|
||||
point.
|
||||
Reference in New Issue
Block a user