Skip to content

feat(spec): Model and Reasoning routing hints (SPEC-002) - #150

Merged
joshuaboys merged 1 commit into
mainfrom
work/spec-002
Sep 14, 2026
Merged

joshuaboys merged 1 commit into
mainfrom
work/spec-002

Conversation

@joshuaboys

Copy link
Copy Markdown
Contributor

Adds optional-but-preferred Model: and Reasoning: fields so a plan can say
which AI model should execute a work item and how hard it should think.
Implements SPEC-002 under decision D-047.

The spec

  • Work items take - **Model:** (free-form identifier, e.g. claude-opus-5)
    and - **Reasoning:** (low | medium | high | max, case-insensitive).
  • Modules can carry Model and Reasoning metadata-table columns as a
    module-wide default. An item field overrides the column, mirroring the
    existing Packages: inheritance.
  • Neither field is required, so no existing plan gains a warning by omission.
    Templates, aps-rules.md, the planning-skill reference, and the prompts
    steer authors to fill them in.

CLI behaviour

Landed in lockstep across Rust, bash, and PowerShell per D-039.

  • W023 warns only when a present Reasoning value falls outside the
    vocabulary. Placeholder prose is skipped, and Model is never
    vocabulary-checked because identifiers are harness-specific.
  • aps next adds a Model: … | Reasoning: … line with the effective
    values, omitted entirely when neither is set.
  • aps export carries model and reasoning on modules and work items,
    null when unset.

Verification

  • cargo test (197 pass), cargo fmt --check, cargo clippy --locked --all-targets -- -D warnings clean.
  • ./test/run.sh passes, including a new test over test/fixtures/routing/
    covering inheritance, item-level override, W023 on both the table column and
    the item field, the next output, and export.
  • ./test/cli-parity.sh reports bash = Rust = PowerShell across all 11
    fixtures; test/ps-parity.ps1 passes. Both ran against a fetched pwsh.
  • aps lint plans and markdownlint clean.

Design note

Reasoning has four levels; harnesses map max onto their own top tier
(xhigh, max, and so on). Making Model a validated enum was rejected
because a model list rots faster than the spec does.

🤖 Generated with Claude Code

…odules

Work items take optional `- **Model:**` (free-form identifier) and
`- **Reasoning:**` (low | medium | high | max) fields, with `Model` and
`Reasoning` module metadata-table columns as inheritable defaults. Item
fields override the module column, mirroring the `Packages:` pattern.
The fields are optional but preferred: templates, aps-rules, the planning
skill reference, and the prompts steer authors to fill them in, and no
existing plan gains a warning by omission.

Surfaces, landed in lockstep across Rust, bash, and PowerShell per D-039:

- W023 warns on a `Reasoning` value outside the vocabulary. Placeholder
  prose is skipped; `Model` is never vocabulary-checked because model
  identifiers are harness-specific.
- `aps next` prints `Model: … | Reasoning: …` when either hint resolves.
- `aps export` carries `model` / `reasoning` on modules and work items.

test/fixtures/routing/ covers inheritance, item-level override, W023 on
both the table column and the item field, and the next/export output;
it is registered with the cross-CLI parity harness.

Plans: SPEC-002 Complete, decision D-047 in the spec module and index.
@joshuaboys
joshuaboys merged commit 6c19caa into main Sep 14, 2026
11 checks passed
@joshuaboys
joshuaboys deleted the work/spec-002 branch September 16, 2026 06:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant