0.9.2 Agent, Command, Task, Workflow, and Model Resolution Plan

Historical implementation plan. WP0-WP8 are implementation-complete for the 0.9.2 release cut. Current public contracts live in Tasks and Workflow Schema. The sequencing and staged checkpoint text below is preserved as historical evidence, not current product status.

Status: In progress; WP5 runtime lowering convergence is implemented, with WP6 task v3 and WP7 durable workflow IR work still outstanding

Decision date: 2026-08-18

Target branch: release/0.9.2

GitHub tracker: #801

Normative design: Agent, Command, Engine, and Model Resolution

Implementation checkpoint (2026-08-19): The reviewed WP5/#809 integration uses the active WP2/WP3 model-map and common-cascade resolver before runtime lowering. Canonical command and non-interactive agent dispatch, the existing task-v2 prompt arm, improve/proposal model-work adapters, current frozen workflow unit and judge dispatch, index passes, and the shared structured-LLM seam now enter the common resolved-request/lowerer path. This is runtime lowering convergence, not completion of the task-v3 source format (WP6) or the WP7 source-to-frozen durable workflow IR and resume-persistence design. Current workflow lowering notices are live diagnostics, not journaled result/evidence data. Full GitHub Actions execution remains out of scope.

1. Outcome

AKM 0.9.2 delivers one coherent execution model for direct command runs, scheduled tasks, and frozen workflows. The same source assets and configuration must resolve to the same command content, persona, engine, model, tools, and ordinary runtime settings regardless of entry point.

The release also establishes GitHub-compatible task and workflow seams without claiming full GitHub Actions execution. Existing AKM Markdown workflows remain first-class. Native Claude and OpenCode files remain authoritative and are translated at runtime; AKM does not synchronize or write them.

2. Definition of done

0.9.2 is complete only when all of the following are true:

1. akm command run is the only stored-command execution surface.
2. Direct command runs, task runs, and workflow freeze call one resolver and produce equivalent resolved requests for equivalent inputs.
3. Commands and agents are read through their bundle adapters. Raw native file bytes and frontmatter are never accidentally dispatched as user prompt content.
4. All registered agent harness profiles and direct LLM engines consume the same resolved/lowered request contract.
5. Task v3 uses the approved GitHub-step-compatible shape. V2 is rejected by normal execution and handled by an explicit fail-closed migrator.
6. AKM Markdown workflows and GitHub-shaped YAML compile into the same versioned internal IR and freeze the same dispatch-significant state.
7. Installed and user models.json layers resolve aliases deterministically, with user values overlaying installed defaults by alias and field.
8. Unsupported native template syntax, GitHub triggers, and adapter constructs fail or emit notices according to the normative design; nothing is silently ignored, guessed, synchronized, or partially expanded.
9. Contract, unit, integration, migration, and release checks pass.

3. Decisions fixed for this milestone

4. Architecture and data flow

Every entry point must converge before engine dispatch:

source adapter
  -> typed agent/command/task/workflow source
  -> invocation adapter
  -> common cascade resolver
  -> model alias expansion
  -> authorization check
  -> versioned resolved request / workflow IR
  -> engine-specific optimistic lowering
  -> harness, LLM provider, shell, or workflow scheduler

For direct commands and scheduled tasks, resolution occurs when execution starts. For workflows, the same resolver runs during plan creation and the complete resolved result is frozen. Resume consumes the frozen representation; it does not re-read current assets or config.

No entry point may independently rebuild command arguments, choose a model, interpret tools, or construct agent prompts after this convergence point.

5. Implementation work packages

WP0 - Characterization and contract fixtures

Before changing behavior:

• capture current direct-agent, command, task, workflow-freeze, model-alias, and harness-lowering behavior;
• add representative AKM, Claude, and OpenCode command/agent fixtures;
• add task-v2 fixtures for every deterministic migration case and each deliberately blocked case;
• add equivalent Markdown and GitHub-shaped YAML workflow fixtures; and
• define a normalized resolved-request projection used only by tests to prove cross-entry-point equivalence.

This package prevents cleanup from accidentally enshrining a 0.9.1 seam as the new contract.

WP1 - Shared source and resolved-execution types

Introduce one internal source representation for:

• adapter-rendered command content and metadata;
• resolved persona content and metadata;
• exact source ref, bundle, adapter, file identity, and content hash;
• command argument input before and after substitution; and
• ordinary unresolved execution defaults.

Introduce one resolved request containing the dispatch-significant result:

• final persona and command content;
• selected engine and exact or aliased model input;
• resolved inference settings;
• selected tools and authorization result;
• timeout, workspace, environment, and other shared runtime settings;
• source identities/hashes; and
• structured lowering notices.

The type must not embed a static engine capability matrix. Unsupported-field handling belongs to lowering adapters.

WP2 - Model map files and alias expansion

• Ship an immutable default models.json as a package/build asset.
• Read an optional models.json from the normal AKM config directory.
• Validate both files with one versioned schema.
• Overlay user values over installed values by alias and nested field.
• Keep engine-specific config overrides nearer than both files.
• Support simple exact-model strings and structured inference profiles.
• Recognize only aliases present in the merged registry. Pass unknown values through as exact model identifiers; fail when a known alias lacks a mapping for the selected engine.
• Provide an explicit CLI operation to copy installed defaults into the user config directory. It must not overwrite an existing user file without an explicit confirmation flag.
• Include the installed file in npm, standalone binary, Bun/Node, and Docker packaging tests.

Do not store authoritative defaults in the cache and do not add reusable mapping-pack installation in 0.9.2.

WP3 - Common cascade resolver and authorization boundary

• Implement the far-to-near cascade once.
• Preserve omitted versus explicit values, including explicit false, 0, empty allowed collections, and null where the schema assigns meaning.
• Expand a structured model alias as defaults at the layer that selected it, then apply explicit sibling and nearer fields.
• Resolve tool selection using nearest-explicit-wins.
• Perform machine/user authorization after selection and before dispatch.
• Return an explicit policy failure rather than silently adding or removing tools.
• Produce stable, machine-readable provenance for each resolved field so --verbose, dry-run, health, and tests can explain why a value won.

WP4 - Command execution surface

• Add canonical akm command run <ref> dispatch.
• Keep stored-command execution out of akm agent; do not add a compatibility alias beside the canonical command surface.
• Load commands and selected agents through bundle adapters.
• Implement only one-pass $ARGUMENTS replacement.
• Detect unsupported native template constructs before engine dispatch.
• Support a built-in command action for anonymous inline command content.
• Require exactly one of with.ref and with.content; accept with.arguments as the exact portable argument string.
• Preserve a persona on engines without a native system-prompt channel by composing the specified deterministic persona block and emitting a lowering notice.

No code path may fall back to asking a harness to resolve an AKM command name.

WP5 - Engine lowering convergence

• Route direct agent/command execution, improve/proposal agent execution, tasks, and workflow steps through the resolved-request boundary.
• Ensure configured model and inference settings reach every harness.
• Update each registered execution profile to lower the fields it understands and report untranslated fields.
• Dispatch optimistically after lowering; provider/harness rejection remains a runtime failure.
• Remove pre-dispatch failures based only on hard-coded guesses about engine capabilities.
• Keep operator authorization and invalid configuration as hard pre-dispatch failures.

The conformance matrix must cover OpenCode, OpenCode SDK, Claude, Codex, Gemini, Aider, Copilot, Pi, Amazon Q, OpenHands, and direct LLM connections without adding native file-format adapters for those extra harnesses.

Implemented checkpoint (2026-08-19): Engine lowering is an implementation registry derived from the harness registry, plus a direct-LLM lowerer; it is not a model/provider capability table. The common cascade resolves model-map aliases to exact model IDs and inference before lowering. Lowerers consume that exact selection, report translated and untranslated paths with stable, secret-free structured notices, and dispatch optimistically. Symbolic LLM and SDK-fallback credentials remain symbolic until the final runner dispatch. Already-frozen runner material uses the config-free lowering entry point, so it does not re-read config, aliases, environment variables, or credentials. The current task-v2 and workflow-engine adapters exercise this runtime seam; their WP6/WP7 replacement schemas and durable freeze/resume representation are not claimed by WP5.

WP6 - Task v3, adapters, migration, and scheduling

Define and publish a strict v3 schema with:

• exactly one executable uses or run selection;
• GitHub-compatible name, with, env, shell, and working-directory fields where applicable;
• AKM-only scheduling and resolver overrides under akm for step-shaped tasks; and
• deterministic recognition of AKM refs versus GitHub action refs.

Add adapters for:

1. step plus akm.schedule;
2. step plus GitHub-style on; and
3. complete on plus jobs documents.

A complete on plus jobs document becomes one workflow asset with an internal scheduler binding. It must not create a duplicate public task ref.

The scheduler adapter supports time schedules and manual dispatch. It rejects locally unsupported GitHub service-event triggers with source-located diagnostics and never installs a watcher or polling daemon.

The v2 migrator must:

• offer a no-write preview using the same planner as execution;
• back up each file immediately before replacement;
• map v2 prompt content to anonymous command content;
• map workflow refs and deterministic command strings to the v3 target;
• stop on argv arrays or other shell-ambiguous constructs;
• preserve schedules, enabled state, params, timeouts, redaction metadata, and resolver overrides when their translation is exact;
• validate the resulting v3 document before replacing the source; and
• report every changed, skipped, and blocked file.

Normal task execution rejects v2 with a direct migration hint.

WP7 - Multi-format workflow compile and freeze

• Preserve the current AKM Markdown adapter as a first-class source format.
• Add the GitHub-shaped YAML adapter for the approved 0.9.2 subset.
• Compile both through one versioned IR builder.
• Shape portable nodes around jobs, needs, steps, uses, run, with, and env where doing so does not change AKM semantics.
• Carry adapter-owned extensions explicitly rather than placing opaque native metadata into the common source model.
• Resolve command, persona, engine, model, tools, and source snapshots before persisting a run plan.
• Make resume consume only frozen dispatch inputs.
• Reject unsupported GitHub expressions, contexts, actions, events, or runner behavior explicitly in 0.9.2.

Full GitHub Actions/workflow execution and remote action acquisition are not part of this work package.

WP8 - Documentation, diagnostics, and release gates

• Update CLI, configuration, task, workflow, model, migration, and adapter references.
• Add a task-v2-to-v3 migration guide with before/after examples and blocked argv-array examples.
• Document every supported 0.9.2 workflow subset and every explicit 0.9.3 boundary.
• Add health checks for unreadable/invalid user models.json, missing known alias mappings, and unavailable explicitly selected engines.
• Ensure dry-run and verbose output show resolved field provenance and lowering notices without exposing secrets.
• Run bun run check, build/package regression suites, and ./tests/release-check.sh before the release candidate.

6. Sequencing and dependencies

WP0 characterization
  -> WP1 shared types
      -> WP2 model maps
      -> WP3 resolver/authorization
          -> WP4 command surface
          -> WP5 engine convergence
          -> WP6 task v3 and migration
          -> WP7 workflow compile/freeze
              -> WP8 release gates

WP2 may proceed alongside the source-type portion of WP1 once its schema contract is pinned. WP6 and WP7 may proceed in parallel only after WP3's resolved-request contract is stable. Engine-specific work in WP5 can be split by harness after the common lowering interface and conformance fixture exist.

7. GitHub milestone tracking

The milestone parent is #801. Closing carryover defects does not complete this plan; every work package has its own issue and must link its implementation commits and verification evidence.

The milestone also contains parallel architecture, security, infrastructure, and product-correctness work. These issues do not substitute for a work package:

Release readiness requires WP0-WP8 to be complete, the security issues to be resolved or covered by an explicit documented release decision, gated suites to pass against the release-candidate SHA, and improve --dry-run to be trustworthy for the dogfood period. Architecture cleanup may remain off the critical path only when it does not block those outcomes.

8. Required contract tests

At minimum, the suite must prove:

1. Equivalent direct, task, and workflow inputs produce byte-equivalent normalized resolved requests.
2. Every cascade layer wins only over farther layers, including tools.
3. Operator tool denial is explicit and independent of bundle provenance.
4. Native command frontmatter is metadata, not prompt content.
5. $ARGUMENTS expands exactly once and unsupported templates never dispatch.
6. Installed model defaults, partial user overlays, structured profiles, engine overrides, known-unmapped aliases, and exact unknown identifiers behave as specified.
7. Every registered engine profile receives the selected exact model and emits notices for intentionally untranslated settings.
8. All three scheduling source shapes produce the expected scheduler binding; unsupported service triggers produce no registration side effect.
9. Task migration preview performs no writes and matches the later execution plan; ambiguous cases remain untouched.
10. Equivalent Markdown and YAML workflows freeze equivalent portable IR.
11. Resume does not observe subsequent edits to commands, agents, config, or model maps.
12. Native Claude/OpenCode bundles remain byte-for-byte unchanged throughout indexing and execution.

9. Explicitly out of scope

• Portable positional or named command arguments
• Expressions, loops, or recursive command-template expansion
• Nested or separately journaled child workflows
• Explicit native-session reuse
• New native agent/command formats beyond AKM, Claude, and OpenCode
• Reusable/distributed model mapping packs
• Full GitHub expression, context, runner, action, and event semantics
• Fetching or executing arbitrary remote GitHub actions
• Publishing the future GitHub Action package
• Generating, exporting, projecting, or synchronizing native/GitHub files

These may become 0.9.3 work, but 0.9.2 must leave clean adapter and IR seams for them without claiming support early.

10. Release evidence

The 0.9.2 release PR and parent tracker #801 must include:

• a work-package checklist linked to implementation commits or issues;
• schema and migration examples;
• the cross-entry-point resolver conformance report;
• the all-engine lowering conformance report;
• the task migration dry-run and execution parity report;
• workflow Markdown/YAML IR equivalence evidence;
• package-content evidence for the installed models.json;
• the full release-check result; and
• manual dogfood notes from direct commands, at least one scheduled task, and a resumed workflow.