Skip to content

gmcluckie1/decision-assist

v0.4.3MIT

Rules-first advisory coding decisions; experimental inference adapters.

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_classTierTypical model (caller-mapped)
read-summarizemiddleSonnet
fact-checkmiddleSonnet
implementmiddleSonnet
mechanical-small-schemasmallHaiku
final-judgetopOpus

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.