AKM CLI and product surface recommendations
Release plan from the CLI review and the review of release/0.11.0 at 4b44628eb. Checked items are implemented on this branch; the first released version remains to be recorded in the migration guide.
The first additive doctor entry points are also implemented: doctor mirrors health, and doctor metrics, info, log, and judge reuse their existing handlers. Improve-run reporting and the remaining doctor consolidation are still planned.
0.10.x is the target for every compatible fix and additive replacement, including usage metrics; 0.11 removes the deprecated surface and makes incompatible default/result changes. Keep existing commands, flags, config keys, output contracts, and input interpretation working throughout 0.10.x. Introduce replacement behavior through new explicit inputs first; do not hide a breaking change inside an addition. STABILITY.md records the scheduled removals, and the migration guide records first supporting versions.
Doctor boundary: All reporting, health, metrics, and developer diagnostics belong under akm doctor in 0.11, with focused subcommands for distinct jobs. This power-user surface can evolve faster than the normal CLI; ordinary operation results, lifecycle status, and previews such as --dry-run remain with their commands.
Learning boundary: In both 0.10.x and 0.11, simplify improve and related automation/learning interfaces without changing their internals, effective defaults, or behavior. Preserve process selection/order, prompts, model requests, eligibility, judgment, acceptance, writes, publication, and evaluation history; CLI/config changes must feed the existing implementations equivalent inputs. This supersedes the earlier proposals to replace the strategy engine, make improvement proposal-only, unify autonomy policies, or change what setup --learning off disables.
Compatible changes and preparation
- [x] [0.10.x] Remove the tag requirement triggered by
remember --source,--description, or--expires. Independent metadata should not force users to invent an unrelated tag. - [x] [0.10.x] Allow
show --max-tokensto bound a whole asset or exact fragment without requiring--context lead. A content budget should work independently of the presentation mode. - [x] [0.10.x] Add consistent duration-based
--timeoutsupport, such as30sor2m, alongside existing millisecond flags. Users should not need different timeout conventions or manual unit conversion across commands. - [x] [0.10.x / 0.11] Preserve duration shortcuts, including
3Mfor three 30-day months and3mfor three minutes, and give every--timeoutflag one grammar (bare milliseconds, orms,s,m,h,d); the asset-file and--since/--expiresgrammar is unified with it in 0.11. Removing millisecond-only flags must not remove the convenient time notation or change its existing meaning. - [x] [0.10.x] Introduce
akm run <ref>alongsideagent <ref>,command run <ref>/command <ref>,task run, andworkflow run, preserving type-specific inputs and lifecycle behavior. Consumers can adopt one execution entry point before the old commands disappear in 0.11. - [ ] [0.10.x] Introduce
akm doctorwith the existing health checks and task scheduler diagnostics, retaininghealthandtask doctortemporarily. Users should have one diagnostic entry point outside the normal working commands. - [ ] [0.10.x] Add
doctor metricsfor metrics and improve-run usage, routing, and cost reporting, retaining the existing reporting commands temporarily. Power-user reporting should live together under the diagnostic namespace. - [ ] [0.10.x] Add project-scoped asset usage rankings to
doctor metrics, retainingsearch --by-usagetemporarily. Usage analysis belongs with diagnostics instead of changing search into an operation that ignores its query. - [x] [0.10.x] Add
doctor judgeanddoctor promptusing the existing judge and prompt-inspection implementations, retaining their old entry points temporarily. Developers can keep useful inspection tools without exposing them as normal product operations. - [ ] [0.10.x] Add
doctor info,doctor log, anddoctor explain <ref>for installation information, diagnostic events, and task/workflow execution-plan inspection. A consistent diagnostic family makes advanced investigation discoverable without adding more top-level commands. - [ ] [0.10.x] Add scheduler reconciliation/rebind/owned-orphan maintenance under
doctor scheduler syncand task history underdoctor log, retaining every old task command. Administrators can move to the replacement surface before 0.11 removes the old entry points. - [x] [0.10.x, release version pending] Extend
importwith asset-ref copying and explicit typed-task import, preserving clone's asset/companion-file behavior and existing document imports. Implemented asimport <ref> --asset-refandimport <file> --type task; legacy commands remain unchanged. - [x] [0.10.x] Add repeatable search
--include key=valuewith the scoped semantics below, retaining both old inclusion flags and their existing behavior. Callers can adopt precise inclusion without changing established searches during a patch release. - [x] [0.10.x] Add show
--outlineand--leadalongside--detail briefand--context lead, retaining the old modes and character budget. The simpler read interface can be adopted before its predecessors are removed. - [x] [0.10.x] Add
curate --max-tokensas an explicit way to request bounded packed context, retaining--packand the existing default result. The new budget control can ship before 0.11 changes curate's default. - [ ] [0.10.x] Add the clearer session-extraction source selector alongside its old
--typespelling and make explicitupgrade --channelselection consistent across CLI and plugins. Consumers can migrate away from overloaded or duplicate selectors before removal. - [x] [0.10.x] Add the shared
--configfile override while preserving existing location resolution for callers that do not use it. First ships in 0.10.261119.AKM_CONFIG_FILEis the environment companion; use the root prefix for dynamic task/workflow inputs. No data/state/cache migration. - [ ] [0.10.x] Add experimental config aliases for retained research controls, keeping old keys and flags accepted with unchanged effective values and precedence. Research configurations can migrate without changing the engines or waiting for a breaking release.
- [ ] [0.10.x] Add equivalent bulk-proposal entry points only where existing handlers preserve selection, judgment, and side effects, retaining old controls. A simpler review interface can be exercised before redundant entry points are removed.
- [ ] [0.10.x] Publish deprecation notices and migrate owned plugins, bundles, scripts, examples, and evaluator adapters after replacements ship. A documented overlap period is useful only if consumers actually adopt the replacements.
- [ ] [0.10.x] Run agent ratification with fresh agents in separate minimal-instruction, guided, and plugin conditions, and repeat it on the 0.11 candidate. Task completion, recovery, and unnecessary calls provide stronger usability evidence than command tests alone.
- [ ] [0.10.x] Complete the outstanding workflow qualification covering mid-run bundle updates, cross-bundle scripts and secrets, and intact URL propagation through env. These scenarios establish whether the retained workflow capabilities work under realistic changes and dependencies.
- [ ] [0.10.x] Audit affected plugins, Desktop, evaluators, bundles, scripts, and persisted consumers before implementing the cuts. Replacement interfaces need to cover real consumers without preserving unnecessary complexity indefinitely.
- [ ] [0.10.x] Classify each learning control as proven product use, demonstrated research use, or removal, recording its consumer and effective value. This separates useful controls from experimental sprawl without disturbing the evaluation baseline.
- [ ] [0.10.x] Prepare a concrete stable/experimental/remove decision for every retained surface, including defaults and experimental exit criteria. The release needs a bounded product promise rather than an indefinite collection of evolving features.
- [x] [0.10.x] Mark every retiring command Deprecated in the
STABILITY.mdcommand index, with its 0.11 removal and replacement or removal action; also list retired flags, config paths, and behavior changes. Users should see the warning where they check a command's stability, while its existing interface still works. - [x] [0.10.x] Publish the first draft of the 0.10.x-to-0.11.0 migration guide with surface changes, behavior changes, and an action for each affected consumer. Users should be able to prepare scripts, plugins, and installations before upgrading.
- [x] [0.10.x] Mark unresolved migration details with named
TODO(0.11:...)entries for the 0.11 developers. The release team needs explicit completion work rather than guessed replacement flags or undocumented behavior.
CLI cuts and refactors
- [ ] [0.11] Remove the standalone
judgeand any remainingimprove judgeentry point in favor ofdoctor judge. Internal model evaluation belongs in the power-user diagnostic surface. - [ ] [0.11] Remove
improve --show-promptin favor ofdoctor prompt. Prompt inspection should remain available without enlarging the normal improvement interface. - [ ] [0.11] Remove top-level
healthin favor of baredoctor, with reporting and comparison controls underdoctor metrics. Routine diagnosis gets a simple entry point while advanced analysis remains encapsulated under the same namespace. - [ ] [0.11] Remove top-level
metricsin favor ofdoctor metrics. Usage, outcome, and cost analysis should not compete for space in the normal CLI. - [ ] [0.11] Remove
task doctorafter its diagnostics are available throughdoctor. A second diagnostic entry point adds discovery cost without a separate user job. - [ ] [0.10.x add; 0.11 remove] Replace
improve reportwithdoctor metrics, preserving run/window selection and usage, routing, and cost data. Improvement reporting belongs with the other diagnostic reports. - [ ] [0.11] Put every reporting command, mode, and human report table under doctor, including improve's automatic post-run usage table, while preserving recorded data and structured operation results. A consistent reporting boundary keeps normal command output focused without changing learning internals or evaluation evidence.
- [ ] [0.11] Move top-level
infoandlogtodoctor infoanddoctor log. Installation inspection and diagnostic event analysis belong beside the other power-user tools. - [ ] [0.11] Replace
task explainandworkflow planwithdoctor explain <ref>, retaining ordinary mutation previews such as--dry-runon their commands. Detailed execution inspection belongs under doctor while checking an operation before applying it remains part of normal use. - [x] [0.10.x] Give new
doctorsubcommands an explicit evolving contract, preserving error/exit conventions, credential redaction, and specific machine fields promised to consumers. The compatibility boundary must be clear from the first release of the replacement. - [ ] [0.11] Keep JSON and text as general output formats, remove YAML, and limit Markdown to reports and JSONL to operations where streaming is useful. Each supported format should solve a concrete consumption problem instead of multiplying every command's presentation variants.
- [ ] [0.11] Remove global
--outputin favor of stdout and shell redirection. File delivery does not need a parallel CLI mechanism for every renderer. - [ ] [0.11] Remove global
--detailand replace its useful behaviors with explicit per-command controls for limits, context budgets, and outlines. Users should understand what a control changes without learning command-specific meanings of brief, normal, and full. - [ ] [0.10.x audit/aliases; 0.11 removal] Retire
remember --autoand--enrich, first providing experimental configuration for demonstrated research uses of the same enrichment path. Reducing capture options does not justify moving enrichment into a different learning process. - [ ] [0.11] Remove
remember --show-similarand use retrieval for similarity checks. Saving and searching are already distinct operations and do not need a combined capture mode. - [ ] [0.10.x aliases; 0.11 old-path removal] Move custom strategy definitions and research-only process tuning under
experimental, keeping the existing strategy engine and selection behavior. Ordinary users should not need pipeline internals, while evaluations still need to isolate and tune processes. - [ ] [0.11] Move
improve --require-feedback-signalinto experimental configuration only after preserving its per-run scope, precedence, and exact eligibility behavior for existing callers. Removing a research switch must not silently enable additional maintenance work. - [ ] [0.11] Remove
improve --json-to-stdoutonce the ordinary JSON output exposes the run data evaluators consume, preserving persisted results and telemetry. A redundant output switch can disappear without depriving research of its evidence. - [ ] [0.11] Simplify bulk proposal controls only where the existing drain/accept handlers can retain identical selection, judgment, and side effects; retain explicit-ID accept/reject. Similar-looking commands are not interchangeable when they apply different approval rules.
- [ ] [0.11] Remove
upgrade --nextand use--channelto select a coordinated CLI-and-plugin release channel. Two prerelease selectors with different plugin behavior make upgrades difficult to predict. - [ ] [0.11] Remove
agent <ref>,command run <ref>/command <ref>,task run, andworkflow runafterakm run <ref>has shipped in 0.10.x. The compatibility period lets consumers migrate before execution is consolidated under one command. - [ ] [0.11] Remove the no-ref interactive agent launcher. Starting another agent CLI without using an AKM asset provides little AKM-specific value.
- [ ] [0.11] Make
curatereturn bounded packed context by default, preserve refs and selection reasons, and replace the optional--packmode with a normal token-budget control. Curate should deliver usable context while search handles candidate discovery. - [ ] [0.11] Remove
search --by-usageafter its usage-ranking functionality is available throughdoctor metrics. Search should consistently interpret its query rather than silently switch jobs. - [ ] [0.11] Remove
task addand import validated task definition files, leaving new tasks disabled untiltask enableand preserving activation when updating existing tasks. Tasks are assets and do not need a parallel CLI authoring system; this replaces the earlier proposal to keep a reducedtask add. - [ ] [0.11] Remove
task syncafter its maintenance capabilities ship underdoctor scheduler syncin 0.10.x. Host scheduler repair belongs with administration, and bare doctor must not mutate scheduler entries. - [ ] [0.11] Remove
task prune, folding required cleanup of owned orphan scheduler entries into the migration/reconciliation path. A separate pruning command duplicates scheduler maintenance; unrelated installations' entries must remain untouched. - [ ] [0.11] Remove
task historyafter its task/ref, bundle, time-window, and limit selection ships indoctor log; usedoctor metricsfor aggregates. Per-run investigation should share the diagnostic surface without losing task identity or execution evidence. - [ ] [0.11] Leave
task enable,task disable, and the scheduler'stask dispatchentry point as the task family after moving execution and diagnostics. These are distinct scheduling operations, while generic search/show already discover and inspect task assets. - [ ] [0.11] Remove
cloneafterimportaccepts its asset refs and preserves asset type, companion files, provenance, and destination behavior in 0.10.x. Users should choose the source to bring in rather than decide between two copying commands. - [ ] [0.10.x additions; 0.11 incompatible cleanup] Unify import's common destination/name/overwrite controls and retain
--bundleversus unmanaged--dest; require an explicit new input form when typed import would reinterpret an existing document input. The 0.10.x additions are implemented as--asset-refand--type task, with shared--name/--force/--bundleand asset-only--dest; incompatible cleanup remains for 0.11. - [ ] [0.11] Remove
search --include-proposedand--include-sessionsafter repeatable--include key=valueships in 0.10.x, initially supportingquality=proposedandtype=<excluded-type>. One inclusion control can restore normally hidden categories without adding a boolean for every category. - [x] [0.10.x] Make the new
--includerelax only the named default exclusions while retaining query matching, source/project boundaries, explicit filters, and type selection. An inclusion option should expand eligible categories without becoming an unrestricted OR that bypasses the caller's constraints. - [ ] [0.11] Make
lintexit nonzero for errors and remove--fail-on-flagged. A validation command should signal failed validation without an additional opt-in flag. - [ ] [0.11] Remove
--timeout-msafter duration-based--timeoutis supported throughout. Keeping two equivalent timeout interfaces would preserve the inconsistency the replacement is meant to remove. - [ ] [0.10.x new interfaces; 0.11 legacy tightening] Reject invalid values and incompatible flag combinations instead of silently substituting behavior, retaining existing documented compatibility during 0.10.x. New interfaces can be strict immediately without unexpectedly breaking old scripts in a patch release.
- [ ] [0.11] Rename session extraction's source-selector
--type, keeping it distinct from the execution--harnessselector.--typeshould consistently mean asset type rather than sometimes identifying the source of session logs.
Show argument review
All declared show arguments and shared flags were checked in the current 0.10 tree and the reviewed 0.11 snapshot. Proposed names below are migration targets, not installed syntax.
| Argument | Recommendation and reason |
|---|---|
<ref>[#fragment] |
[0.10.x / 0.11] Keep one ref, returning its full body or exact selected section by default. A read should not need a verbosity preset to return the requested content. |
--context exact|lead |
[0.10.x add; 0.11 remove old mode] Add --lead for the document introduction on a Markdown fragment; exact remains the default. A single optional behavior does not need a two-value mode. |
--max-tokens |
[0.10.x fix; retain in 0.11] Apply the budget independently to whole documents, exact fragments, and lead-plus-fragment reads; disclose estimation and truncation. Context size is a useful control regardless of presentation. |
--max-chars |
[0.11] Remove in favor of the token budget. Two mutually exclusive size units add little value to an agent-facing read command. |
--detail brief |
[0.10.x add; 0.11 remove old mode] Add --outline, returning heading titles/slugs without the body. Finding a section is a concrete operation, not a verbosity level. |
Other --detail modes, including 0.10's agent projection |
[0.11] Remove in favor of one consistent result with content, ref, and useful metadata. Scripts and agents should not need different result shapes for the same read. |
--project |
[0.10.x / 0.11] Retain explicit usage attribution, including none, and clarify that it does not filter or change content. Wrappers reading outside a project's working directory still need correct attribution. |
--format |
[0.11] Retain JSON and text only, with the same content-selection behavior. Structured consumption and direct reading cover show's normal uses. |
--output |
[0.11] Remove; use shell redirection. Writing stdout to a file does not need another show option. |
Shared --config |
[0.10.x add; retain in 0.11] Offer the normal installation/config selector without changing existing path resolution when omitted. Explicit reads must still resolve against the intended installation. |
--quiet / -q, --verbose |
[0.10.x retain; 0.11 conflict error] Keep shared stderr controls and reject simultaneous use in 0.11. Diagnostics should neither change the returned content nor compete with each other. |
--help / -h |
[0.10.x] Add concise whole-asset, fragment, outline, and bounded-read examples as replacements land. These examples explain the complete content-selection surface before migration. |
- [ ] [0.10.x new flags; 0.11 old-mode cleanup] Reject unsupported combinations of the new show controls, including lead without a Markdown fragment and outline with content-only controls. A successful read must honor the requested selection without adding raw/debug variants to show.
Learning configuration cleanup
- [ ] [0.10.x / 0.11] Keep ordinary controls for enablement, scope, budgets, model/connection selection, retention, and sync/push behavior on the supported surface where they have demonstrated use. Operating an installation should not require experimental tuning or lose controls over cost and publication.
- [ ] [0.10.x aliases; 0.11 old-path removal] Retain research-used process isolation, quality-gate toggles, reflect defect filters, and extraction/session-indexing controls under experimental configuration. The current reflect, distill, extract, and bakeoff evaluators use these controls to distinguish treatments.
- [ ] [0.10.x audit/aliases; 0.11 removal] Audit per-process runner overrides and remaining thresholds, chunk sizes, filters, and maintenance knobs individually; move demonstrated research controls under
experimentaland remove controls without demonstrated product or research value. Moving every old knob wholesale would preserve the sprawl under a different heading. - [ ] [0.11] Remove a configuration control only when doing so leaves the existing process implementation and effective research settings intact. Deleting a schema field must not discard a working override or become an excuse to simplify the underlying algorithm.
- [ ] [0.10.x] Treat new experimental aliases as optional overrides of unchanged defaults, preserving the existing
experimental.improveAutonomygate separately. Relocation must not turn currently enabled learning processes off or enable autonomous writes. - [ ] [0.10.x] Translate old and new settings at the configuration boundary, preserving values, precedence, false/zero/empty overrides, and conflict diagnostics; remove old-key support only in 0.11. The same experiment should reach the same engine inputs after migration without an internal refactor.
- [ ] [0.10.x rollout; 0.11 cleanup] Update help, examples, config templates, and schema descriptions together, showing replacements and deprecations as they land. Hiding flags from help alone does not produce a smaller supported surface.
- [ ] [0.10.x, repeat on 0.11] Verify migrated effective plans, model requests, side effects, and recorded evidence with deterministic fixtures/replays, updating evaluator adapters without changing cases or scoring. Interface compatibility should be established without introducing a new treatment into the research.
Command and argument usage metrics
- [x] [0.10.x] Capture every CLI invocation by default at the shared entry point, including nested commands, help/version, invalid arguments, startup failures, and cancellations, without sampling. Starting before the removals supplies a baseline of actual command attempts.
- [x] [0.10.x] Record command paths and every supplied argument's identity, positional role, repeated occurrences, negation, and canonical spelling while distinguishing explicit input from defaults. This reveals which flags and combinations callers actually choose instead of counting parser-injected defaults as demand.
- [x] [0.10.x] Record the resolved asset type for
runand separate AKM options from asset inputs and arguments after--. A unified entry point must still reveal which execution capabilities are used without attributing child-program flags to AKM. - [x] [0.10.x] Attach invocation identity, timestamp, CLI version, local instance identity, known caller/source, duration, exit status, and structured outcome/error category. Version comparisons, adoption breadth, and failure rates distinguish useful features from repeatedly attempted or brittle ones.
- [x] [0.10.x] Retain safe argument values such as declared enums and booleans, recording presence/type or redaction markers for secrets, free text, paths, URLs, and opaque payloads. Feature analysis needs argument usage without turning metrics into a second store of prompts, credentials, or command content.
- [x] [0.10.x collection/retention; 0.11 preservation] Store usage locally with additive metrics storage, retain release-comparable aggregates after detailed records expire, and preserve them through the 0.11 storage migration. Future release decisions require durable evidence and a clear distinction between unused and unobserved surfaces.
- [x] [0.10.x] Add command/argument counts, combinations, per-instance adoption, errors, and duration summaries to
doctor metrics, with version/source/window filters and a stable JSON export for lab aggregation. One report should show what is used, where it is used, and where callers encounter friction. - [x] [0.10.x / 0.11] Keep user/agent, scheduled, improvement-internal, audit/evaluation, and unknown traffic distinguishable, with command metrics separate from learning feedback and ranking inputs. Background repetition and measurement activity must not masquerade as product demand or alter the learning processes.
- [x] [0.10.x, repeat on 0.11] Verify exactly-once invocation counting, redaction, early-exit coverage, concurrent writes, rollup/export deduplication, and bounded overhead through the real CLI entry point. Collection failures must preserve command behavior and appear as coverage gaps rather than successful executions or evidence of zero usage.
Implementation: doctor metrics usage and the local cli_usage_* tables of
metrics.db are available in the working tree; first published version is pending. Resolved run dispatch
wiring is tracked with the additive run implementation. The
CLI reference documents the schema,
retention, export deduplication and observation limits.
Release fixes and completion
- [ ] [0.11] Track qualified bundle/task identity through task reservation and dispatch. A running task in one bundle must not suppress a same-named task in another bundle.
- [ ] [0.11] Preserve legacy-ref usage history or block destructive indexing until migration completes after a manual package upgrade. Missing a migration step should not silently erase historical evidence.
- [ ] [0.11] Reconcile learning changes already on the branch against the research baseline, including removed
improve.stateGcand relocated inference settings. An existing branch change is not evidence that dropping a control preserves behavior. - [ ] [0.11] Rehearse upgrades with matching plugins, custom config paths, and existing OS scheduler entries. Unit-level compatibility does not prove that an installed CLI, its plugins, and scheduled jobs still operate on the same installation.
- [ ] [0.11] Detect incompatible active workflow runs before upgrade and provide a clear drain, finish, or restart procedure. Abandoning a frozen run and starting fresh can repeat work or side effects.
- [ ] [0.11] Stabilize the qualified task and workflow core and explicitly retain-as-experimental or remove each remaining questionable capability, including child workflows. Users need precise supported capabilities rather than blanket uncertainty around an entire feature family.
- [ ] [0.11] Publish the stable 0.11 core contract and the separate evolving doctor boundary, with matching help, examples, schemas, and stability documentation. Users should know which flags, result fields, and defaults they can depend on and where diagnostic churn is expected.
- [ ] [0.11] Resolve every migration-guide marker against the final implementation and record the first supporting versions, exact replacements, and verified upgrade behavior. The draft must become actionable release documentation before 0.11.0 ships.
- [ ] [0.11] Run the platform, packaged-artifact, and upgrade gates on the exact release candidate. The latest merge's green fast checks do not cover the deferred release-specific validations.
- [ ] [0.11] Freeze feature scope after these cuts and decisions, limiting remaining release work to correctness, compatibility, and usability fixes. A bounded stabilization period makes the release easier to validate and gives the supported surface time to settle.