Decision Assist
A public, local plugin for model-tier and skill-selection advice over small, explicit task packets. Version 0.4.3 includes verified file-input boundary repairs and defaults to deterministic rules and shadow advice. It runs on Python 3.12+ with no dependencies, cloud account or server. Package and installed-host checks verify packaging and explicit skill execution; they do not establish model quality or token savings.
python3 -m decision_assist prepare --task-file examples/task.txt --profile examples/profile.json --risk low --policy allowed --output operator-packet.json
python3 -m decision_assist preview --packet examples/packet.json
python3 -m decision_assist doctor
python3 -m decision_assist decide --packet examples/packet.json
python3 -m decision_assist evaluate
Run from this repository or the extracted plugin root. The example returns the
caller's baseline tier and required review skill. To choose a deterministic tier,
add task_class to the packet and its mapping to class_routes in a separate
config. The plugin does not infer risk labels or task classes in rules mode.
Workflow stage routing
examples/workflow-stages.config.json (with the matching
examples/workflow-stages.profile.json tiers) maps agent workflow stages to
tiers through class_routes:
task_class | Tier | Typical model (caller-mapped) |
|---|---|---|
read-summarize | middle | Sonnet |
fact-check | middle | Sonnet |
implement | middle | Sonnet |
mechanical-small-schema | small | Haiku |
final-judge | top | Opus |
Tier IDs are caller-owned. The profile descriptions state task properties
(mechanical, small flat output, no judgment / reads and summarizes, multi-file
reasoning, structured output / final judgment, synthesis, high-stakes decision),
not model vendors, and the workflow script maps the returned tier to a concrete model id. A workflow
script asks for a stage's tier by putting the class in the packet and reading
model from the result:
python3 -m decision_assist prepare --task-file stage.txt --profile examples/workflow-stages.profile.json --risk low --policy allowed --task-class fact-check --output stage-packet.json
python3 -m decision_assist decide --packet stage-packet.json --config examples/workflow-stages.config.json
An unknown or absent class is not an error: with the rules provider it
returns the profile baseline (middle, reason rules_baseline). A pin, denied
policy or non-low risk still overrides the class route. Keep
mechanical-small-schema to 3-4 flat fields; prose-heavy schemas belong in
the middle tier (use fact-check, read-summarize or implement).
Install from this repository in Codex or Claude Code using
the host installation guide. For Claude Code, run
claude plugin install decision-assist --marketplace gmcluckie1/decision-assist
with Claude Code 2.1.292 or newer. Older clients should use the two-step Claude
Code instructions in the installation guide.
Both hosts use the same runtime
and explicitly invoked skill. No automatic hooks run. Rules are the supported
release path; local d1 and cloud adapters remain experimental opt-in choices.
Optional LM Studio, Cloudflare Clef Flash and NVIDIA hosted Chat Completions adapters are included. Example cloud configs keep remote and metered flags off. See provider setup and proof limits before enabling either. The local adapter uses an already loaded decision model; no models are bundled.
The schema-version-2 result contains independent route and per-skill status,
confidence/probability, candidate IDs, a reason code, policy status, packet hash,
byte and candidate counts, and elapsed time. Weak optional skills do not veto a
strong route; an uncertain route does not veto confident skills. Ambiguous
optional skills retain baseline membership. Required skills always survive. Ordinary preview and decisions never print task
text or upstream failures.
preview --show-task deliberately exposes the supplied task on stdout so the
operator can inspect it; avoid capturing that output in shared logs. Invalid
input exits 2 with fixed safe field paths, codes and corrective hints. Valid advice or
abstention
exits 0, so integrations must check reason and policy_allowed, not exit code
alone. evaluate exits 1 if a synthetic fixture fails.
See the packet/config contract and platform fit. Model accuracy, reduced subscription-limit pressure, provider billing and production benefit require separate measurements. This implementation neither dispatches work nor modifies conversations, native skills, model profiles, permission gates or task routing.
From the source checkout, validation and local packaging:
python3 -m unittest discover -s tests -v
python3 scripts/validate_package.py
python3 -m decision_assist package --output "$(mktemp -d)/decision-assist-0.4.3.zip"
Choose a new archive path for each build. Packaging refuses overwrite and paths
inside this source tree; the archive includes runtime, skills, manifests,
examples, package validator and docs, and excludes tests, .git, caches and
credentials. This creates a source archive only; no release tag or assets are
published and no marketplace cache or installed host is updated. A package contract check is
not proof that a host has installed or discovered the skill.
The v0.2 handoff experience is documented in handoff:
preview the explicit packet, optionally check the already running local endpoint,
request advice, then attach a caller-reported outcome. doctor --check-local
sends exactly one small synthetic request to an LM Studio loopback config; it
never tests cloud endpoints. outcome prints a hash-linked receipt without
storing anything or calculating savings. Unknown measurements remain null.
Version 0.3 adds explicit preparation and receipt summaries.
prepare writes one new validated packet with mode 0600 from a bounded UTF-8
task and reusable candidate profile; risk and policy are required each time.
It refuses overwrites and symlinks, including symlink ancestors (on macOS use
physical paths such as /private/tmp). summarize --receipts FILE [FILE...]
validates a bounded explicit receipt collection, rejects duplicate decision
hashes, and reports unknown measurements separately from measured zero. It
makes no provider comparison or savings claim.
Version 0.4 records partial adoption explicitly: new outcome input supplies
route_followed and skills_followed separately, and a v2 outcome receipt
derives full adoption. Legacy six-field input continues to emit unchanged v1
receipts. Summary schema v2 keeps legacy claims separate and treats their
per-dimension/full-adoption status as unknown. See adoption semantics
for truth-table rules, labels and compatibility examples.
Version 0.4.1 added safe evaluator-config errors, --version, useful command
help, and runtime/manifest version parity checks. A small four-condition trial
did not justify default d1 routing; deterministic rules remain the default.
License
MIT. See LICENSE.