Skip to content

notque/vexjoy-agent / skills/meta/d

Router that runs the work in the main loop: picks skill, pipeline, and stack with /do's rules; Jev checks intent and attaches skills.

FileKindSize
EVAL.mdmarkdown8.4 KB
SKILL.mdskill md15.1 KB
SPEC.mdmarkdown10.2 KB
references/jev-classifier-design.mdmarkdown11.6 KB
references/model-task-fit.mdmarkdown13.6 KB
references/router-metrics.mdmarkdown4.3 KB
# SPEC: /d — session-pick router, main loop, Jev validation

Maintenance contract. Load only when creating, evaluating, or redesigning
this skill — not during ordinary routing (SKILL.md's phases are the runtime
contract).

## Purpose
Alternate entry point to `/do`, and the comparison arm for the single-loop
setup (plans/009 L6). The session model picks the skill, pipeline, and stack
from the full routing manifest with `/do`'s own rule text, then does the work
in the main loop with the skill loaded. It dispatches only when a dispatch
pays. Jev validates that the restated outcome survives the route and answers
the attachment questions. Intent preservation is production behavior: the
router must return the requested apple, not expand it into an orchard. The
owner judges whether this setup beats `/do`.

## Scope
- Run the force-route guard and one Jev attachment evaluation before the pick,
  via `scripts/jev-route.py` (prepare).
- Validate the pick against the live manifest and compute `attach` after it,
  via `scripts/jev-route.py --finalize`.
- Print `/do`'s Phase 2 rule text for the pick, via `scripts/print-route-rules.py`.
- Execute Phase 5 through `build-dispatch.py` with `"router": "d"`: main loop
  by default; a dispatch names one reason (`fan-out`, `worktree`,
  `haiku-gather`, `verifier`, `overlay-agent`, `context-budget`) and hands the
  worker the skill's references (optional for `overlay-agent`). A Medium or
  Complex main route names its acceptance check and closes with a verifier.
- Report gate costs for planned paths before work, via `scripts/d-preflight.py`.

## Intent alignment
Every `/d` route, Trivial included, receives a required runtime intent
restatement. One batched
Jev judgment checks that the intended outcome and constraints survive routing;
it reports scope loss, added work, route mismatch, and essential ambiguity
without fabricating a task. `jev-intent-align.py` writes a receipt on every
path (hashes and verdict only, session-scoped temp dir, 6-hour life). The /d
execute step refuses without a receipt matching `request_verbatim` and
`intent`, on a clarification without `task_spec.clarification`, and on
`review` with empty `gaps`, and prints the command to run. There is no
hook-time baseline: the route does not exist until the session model picks it.
The gate lives in a script the model calls, not in a hook: skipping the script
skips the gate, so the user remains the final backstop.

This is a production requirement grounded in repeated daily use: preventing
unrequested scope expansion is the feature's primary value.

## Non-goals
- Not a replacement for `/do`: `/d` shares `/do`'s rule text and manifest, and
  adds Jev's attachment answers and outcome validation.
- Not a new manifest format, INDEX schema, or `build-dispatch.py` contract
  change.
- Not a new telemetry schema. `/d` emits the same `[do-route]` marker through
  `build-dispatch.py` plus two additive tokens (`reason=`, `router=d`) that the
  recorder writes to `route-events.jsonl` only. No SQLite column changes.
- Jev does not pick the skill, pipeline, or workers. A 2026-10 paired
  measurement showed the session model with `/do`'s rule text beating Jev's
  two-stage pick (`references/jev-classifier-design.md`).

## Invariants
1. `scripts/pre-route.py`'s deterministic force-route guard always runs
   first. Its pr-workflow, pr-pipeline, and security matches override the
   picked skill and pipeline in `--finalize` (`/do` Phase 2 Step 1(a)). Other
   force matches are not carried into `JEV_RESULT`, matching `/do` Step 1(b).
2. Every skill, worker skill, and pipeline name in the route is validated
   against the live `SKILLS:`/`PIPELINES:` manifest membership in
   `--finalize`. The agent is `general-purpose` unless the decision names a
   private overlay agent; a retired or unknown agent name is dropped.
   A name outside it is dropped and listed in `problems`. `d` and `do` are
   never valid skills.
3. The rule text is single-sourced. `/d` prints `/do`'s Phase 2 span with
   `print-route-rules.py` and never copies it.
   `scripts/tests/test_print_route_rules.py` fails when an anchor or a rule
   leaves `/do`'s SKILL.md.
4. `JEV_TRANSPORT=auto|vercel|direct` selects the transport. Auto prefers
   `AI_GATEWAY_API_KEY`, then `TYPESAFE_API_KEY`. Credential values are never
   passed as arguments, logged, printed, or persisted.
5. `skills/meta/do/SKILL.md` and `commands/do.md` are never modified by this
   skill or its scripts.
6. Jev failure never blocks routing. Without attachment evidence the route
   keeps the pre-route stack and the domain floor (the decision's own `stack`). The Phase 2 validator
   reports `unavailable`, and the request continues.
7. `jev-route.py` uses the shared transport selector. A missing Gateway bridge
   or unavailable direct API must never crash `/d`.
8. `/d` uses at most two Vercel AI Gateway Jev evaluations per request: one
   for the attachment questions (prepare) and one batched intent-alignment
   evaluation (Phase 2). Neither makes one request per question. `--finalize`
   never calls Jev. The Vercel transport is a supported production dependency.
9. Every route carries `attach`: manifest-valid extra skills from code policy
   (`_attachments` in `jev-route.py`), at most three. `/d` passes it as the
   dispatch `stack` unchanged. An empty skill takes `workflow`.
10. `/d` executes in the main loop unless the decision says
    `"execution": "dispatch"` with a `dispatch_reason` from
    `d_gate.DISPATCH_REASONS` whose precondition holds, plus `references` from
    the skill's `references/` directory when it has one (optional for
    `overlay-agent`, whose precondition is that `agent` names a live private
    overlay agent; and `context-budget`, whose precondition is that
    `task_spec.files` names 10+ existing files or 50+ KB, measured).
    `build-dispatch.py` enforces this; Trivial routes go through the same call.
11. `/do`'s `build-dispatch.py` output is byte-identical with and without the
    `/d` mode: every `/d` rule is behind `"router": "d"`.
12. A pipeline's phases run in order in the main loop; only an independent
    fan-out or verifier phase leaves it.
13. Every `/d` route needs an intent receipt, Trivial and force routes
    included. No route skips the intent validator.
14. A Medium or Complex main-loop route needs `task_spec.acceptance`, plus
    `task_spec.scenario` when `task_spec.files` touches the installer, hooks,
    or routing scripts (`d_gate.SCENARIO_PREFIXES`/`SCENARIO_FILES`). It
    carries `verify=required` and gets the closing verifier step;
    `router-metrics.py` reports how often a verifier dispatch followed.
15. When Jev gives no signals, `--finalize` attaches from the decision's own
    `signals` (`signals_source: "session"`).
16. `d-preflight.py` reports gate costs for planned paths from the hooks' own
    rules, read-only; it never blocks and prints redacted findings only.

## Dependencies
- `scripts/jev-route.py`, `scripts/print-route-rules.py`, `scripts/jev_intent_align.py`
- `scripts/pre-route.py`, `scripts/routing-manifest.py`, `scripts/get-routing-manifest.sh` (reused, unmodified)
- `scripts/build-dispatch.py` (`"router": "d"` mode) and `scripts/d_gate.py` (receipt, dispatch reasons, references, verify)
- `scripts/d-preflight.py` (imports `pretool-unified-gate.py`, `pretool-adr-creation-gate.py`, `pretool-synthesis-gate.py`, `pretool-private-name-leak-gate.py` read-only; runs `security-review-scan.py`)
- Metrics and evals: `scripts/router-metrics.py`, `scripts/golden_eval/` (`references/router-metrics.md`)
- Jev transport selector (`scripts/jev_transport.py`), Vercel AI Gateway bridge
  (`scripts/jev_vercel.py` and `scripts/jev_gateway/jev_vercel_gateway.mjs`),
  direct client (`scripts/jev_router_common.py`), and their credentials
- Eval drivers: `scripts/d_route_model.py`, `scripts/jev-eval.py`,
  `scripts/jev-eval-live.py`, `scripts/router_attachment/run_eval.py`

## Known limitations (not blocking, tracked)
- The pick is one model reply. A rerun with unchanged code changes the pick on
  about 11% of corpus rows, so compare arms only with two runs each and count a
  row as changed when both runs agree.
- Route classification has no independent verification beyond the session
  model's own reasoning and the manifest-membership check. A confident wrong
  pick is dispatched as-is. Monitored via the corpus run, not solved
  structurally — see `references/jev-classifier-design.md` "Confident-wrong risk".
- The pick reads the whole manifest (about 10k tokens) and `/do`'s rule text
  (about 2k tokens) in the session. Jev's two-stage pick kept them out of the
  session; `/d` now spends that context for a higher pair accuracy.
- Main-loop work grows the session context: every file the skill reads stays
  in this thread. That is the trade the article names; fan-out stays available
  when parallel parts need fresh context.
- Skill-load accuracy is observable for main-loop routes only; a worker's
  Skill calls mostly do not land under the parent session
  (`references/router-metrics.md`).
- The Jev attachment call adds network latency. Vercel is preferred in `auto`
  mode because it is the required, currently cost-free production path; direct
  Jev remains the explicit alternative.

## Release criteria
- The instructions require a runtime receipt for the exact proposed intent
  before acting, unless validation is explicitly reported unavailable and the
  fail-open contract is followed.
- Added work, lost scope, route mismatch, and essential ambiguity exercise the
  alignment gates in `EVAL.md`.
- Vercel `auto` preference, explicit transport isolation, retry bounds,
  credential redaction, and direct-transport parity remain covered.
- Force-route, unavailable, error, and invalid-pick paths resolve according to
  their documented contracts.
- `scripts/tests/test_d_gate.py`, `test_router_metrics.py`, and
  `test_golden_eval.py` pass.
- `scripts/tests/test_router_attachment_eval.py` passes, and a live run of
  `scripts/router_attachment/` does not drop below the last recorded run in
  `EVAL.md`.
- `SAFETY_BUCKETS` have no critical regressions in any new full-corpus run.

Historical percentages are not release criteria. Only results present in the
repository and reproducible with the current corpus and manifest may be cited;
missing or superseded verdict files are not evidence against production use.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall