feat: add an AXI-compliant CLI-first agent skill/workflow

[P8L1]

Why

AXI consistently uses less tokens than anything else. Refer to AXI docs

What Changes

Add a first-class, version-matched AXI-style Agent Skill for ProjectAtlas and make its recommended workflow CLI-first on hosts that support shell execution.

The skill should teach the agent a small, deterministic funnel instead of exposing or explaining the entire ProjectAtlas surface up front:

1. Resolve/bind the current project.
2. Request one compact task-oriented session brief.
3. Follow the returned next-step selector into the smallest relevant summary/search/relation/outline operation.
4. Request an exact source slice only when source evidence is required.
5. Refresh/re-index only when ProjectAtlas reports that the index may be stale.
6. Fall back to MCP only when the host cannot use the CLI or a required capability is not available through the AXI surface.

Where useful, introduce CLI commands/flags that combine currently separate agent operations so the result of one command contains both the requested data and a bounded next-step suggestion.

The CLI contract should follow AXI principles:

• compact TOON output by default;
• minimal default fields;
• bounded/truncated large content with an explicit full-output escape hatch;
• pre-computed state such as project/index freshness and result counts;
• explicit zero-result states;
• structured, non-interactive errors and stable exit codes;
• content-first no-argument/home output;
• contextual help[]/next-step command suggestions;
• concise and consistent --help.

The existing Codex plugin skill should be updated/reused rather than creating a second competing skill if that is the cleanest ownership model.

Capabilities

• Agent Skill / host integration

  • Version-matched AXI-style ProjectAtlas skill.
  • Prefer CLI execution when available.
  • Preserve MCP as a fallback/compatibility transport.

• Task-oriented repository entry point

  • CLI equivalent of the compact atlas_session_brief workflow.
  • Return project identity, freshness/index state, ranked task-relevant candidates, blockers, and one concrete next command in one bounded response.

• Narrow navigation

  • CLI access to bounded summaries, symbol/relation search, outlines, health findings, and exact source slices.
  • Stable selectors returned by one command should be accepted directly by the next command.

• AXI output contract

  • TOON by default.
  • Minimal schemas and explicit counts.
  • Deterministic truncation with a documented --full or equivalent escape hatch.
  • Definitive empty states.
  • Structured errors and stable exit codes.
  • help[] next-step suggestions.

• Observability

  • Distinguish CLI/AXI usage from MCP usage in telemetry so the improvement can be benchmarked rather than assumed.

Architecture Diagrams

Architecture views

Update the existing architecture view only if transport/host integration ownership changes. Do not create a duplicate architecture document solely for the skill.

Release Scope

Target the next appropriate minor release after the OpenSpec change is accepted.

Expected implementation surface:

• existing ProjectAtlas skill / Codex plugin;
• plugin/runtime installer metadata;
• CLI command/output layer required for the AXI workflow;
• agent-integration documentation;
• CLI output-contract tests;
• plugin/install smoke tests;
• telemetry attribution for CLI-vs-MCP comparison.

The initial release does not need to remove, deprecate, or redesign the MCP server. This should be additive and backwards compatible.

Affected surface

Agent workflow

Agent workflow

task starts
-> ProjectAtlas skill is available/loaded
-> resolve current project locally
-> one compact AXI session brief
-> agent receives:
project + freshness + ranked candidates + blockers + next command
-> follow returned selector
-> summary/search/relation/outline as needed
-> narrow again if necessary
-> exact source slice
-> edit/test

Acceptance criteria

• A version-matched ProjectAtlas Agent Skill is shipped through the supported plugin/install path.
• On shell-capable hosts, the skill prefers the ProjectAtlas CLI/AXI path for normal repository navigation.
• MCP remains functional as a fallback and existing MCP workflows do not regress.
• One CLI call can produce the compact task-oriented session brief needed at the start of a repository task.
• The session brief includes project identity, index/freshness state, bounded ranked candidates or an explicit zero-result state, blockers when present, and concrete next-step guidance.
• Follow-up commands accept stable selectors returned by prior commands.
• Default machine-readable output is compact TOON and avoids unnecessary fields.
• Potentially large fields are bounded/truncated by default with an explicit full-output escape hatch.
• Empty results are explicit and distinguishable from command failure.
• Errors are structured, commands are non-interactive, and exit codes are deterministic.
• Unknown commands/flags fail loudly.
• No-argument/home behavior exposes useful current project/index state rather than only generic help.
• Successful outputs include bounded contextual next-step suggestions.
• CLI/AXI and MCP usage can be distinguished in telemetry/benchmarking.
• Tests cover output shape, truncation, empty states, errors, selector chaining, plugin packaging, and MCP fallback.
• A representative benchmark compares AXI/CLI vs current MCP workflow using task success, tokens, tool turns, and wall-clock duration.
• Documentation explains the CLI-first funnel and when MCP fallback is appropriate.

Non-Goals

• Do not remove or deprecate the MCP server in this change, unless AXI proves to perform better.
• Do not require network access, hosted indexing, provider credentials, or an external service.
• Do not make agents re-index the repository at the start of every task.
• Do not expose the entire CLI schema/help surface in every model turn.
• Do not return whole files or unbounded repository data by default.
• Do not add interactive prompts to agent-facing commands.
• Do not create a second divergent ProjectAtlas skill when the existing version-matched skill can be evolved.
• Do not claim a fixed token/cost improvement without a ProjectAtlas-specific benchmark.
• Do not optimize token count at the expense of correctness, freshness, or deterministic behavior.

Pre-Mortem

Likely failure modes:

• The new skill merely wraps the current MCP workflow, so schema/tool-discovery overhead remains.

  • Define and test a genuinely CLI-first happy path with MCP used only as fallback.

• The CLI becomes a 1:1 mirror of every MCP tool, increasing command discovery and skill size.

  • Design a small task-oriented AXI surface around the repository-navigation funnel.

• Compact output removes information the agent needs and causes extra recovery calls.

  • Benchmark minimal default fields and add pre-computed state/selectors where they eliminate round trips.

• Outputs become too large and erase the expected token savings.

  • Enforce deterministic bounds/truncation and test worst-case payload sizes.

• CLI and MCP semantics drift.

  • Share service/query logic underneath both transports and add parity tests.

• The skill becomes stale relative to the installed binary.

  • Keep the skill version-matched and add packaging/install smoke tests.

• Agents repeatedly call --help or guess commands.

  • Add content-first home output and contextual help[] next-step templates.

• Agents re-index on every task.

  • Surface freshness explicitly and instruct refresh only when stale.

• CLI subprocess startup makes the workflow slower than MCP on some workloads.

  • Measure wall-clock performance and introduce combined operations where justified.

• Performance claims are inferred from AXI's unrelated benchmark workloads.

  • Run a ProjectAtlas-specific A/B benchmark before documenting savings claims.

OpenSpec plan and task checklist

OpenSpec change: to be assigned

OpenSpec Tasks

• Define the AXI/CLI-first agent workflow and transport fallback policy.
• Inventory the existing CLI, MCP, Codex plugin, and skill surfaces.
• Specify the minimal task-oriented AXI command/output contract.
• Implement or adapt the compact CLI session-brief entry point.
• Implement selector-chained narrow navigation and exact-slice operations required by the skill.
• Add compact TOON defaults, bounds/truncation, counts, explicit empty states, structured errors, exit codes, content-first home output, and contextual next-step guidance.
• Update the existing version-matched skill/plugin to prefer CLI when available.
• Add CLI/MCP semantic parity tests.
• Add skill/plugin packaging and installer smoke tests.
• Add telemetry attribution for AXI/CLI vs MCP paths.
• Build a representative repository-navigation benchmark and record the MCP baseline.
• Run AXI/CLI vs MCP comparisons for success, token usage, turns, and duration.
• Update agent-integration and architecture documentation as required.
• Verify no network/provider credentials are required by the default AXI path.
• Complete release checks without regressing existing MCP integrations.

Privacy check

• I removed secrets, tokens, private repository names, and private filesystem paths from this request.

[P8L1]

(If the axi does perform a lot better than MCP, deprecate or remove MCP)

[styler-ai]

Product review retained the useful requirements—compact task entry, stable selector chaining, definitive empty states, structured failures, and an empirical CLI/MCP comparison—but did not find evidence for making MCP fallback-only or removing it. ProjectAtlas depends on MCP as a first-class typed, freshness-aware agent interface today.

Those valid requirements are now consolidated into #310, which will compare version-matched MCP-first, CLI-first, and mixed packaged workflows before any compatibility decision. Closing this standalone proposal as consolidated rather than adopting its pre-decided transport hierarchy.