air-workbench

name

air-workbench

description

Open AIR Workbench to discover local Agent Skills, visualize and round-trip a Skill workflow as AIR (Agent Intermediate Representation), review a native Codex or Claude plan, inspect observable execution evidence, or promote a reviewed plan or trace into a Skill draft. Use only when the user explicitly asks for AIR Workbench, the legacy Workflow Studio, Skill-to-graph or graph-to-Skill conversion, visual workflow editing, plan approval, observable tracing, or plan/trace promotion. Do not trigger for ordinary Skill execution, general planning, or routine Codex/Claude requests.

AIR Workbench

Keep SKILL.md as the native executable and distributable artifact. AIR is the portable, editable interchange view:

SKILL.md ⇄ AIR workflow ⇄ visual graph

Resolve all script paths relative to this Skill directory. Do not install a global command:

node scripts/air.mjs --help

AIR is a project-defined format, not an IANA or standards-body format. agents/air-workbench/ is the current physical package path, renamed from agents/workflow-studio/; “Workflow Studio” identifies only scripts/workflow-studio.mjs, its compatibility commands, and legacy artifacts.

1. Open the current AIR Workbench editor

Start AIR Workbench without an input to discover installed and project-local Skills automatically:

node scripts/air.mjs workbench

The catalog scans standard project, user, system, repository, and authoritative enabled Codex plugin Skill roots with finite read-only bounds and exposes only opaque item IDs through the local API. Explicit enabled configuration and valid remote-install markers are authority; cache presence alone is ignored. It opens the first discovered Skill, or an empty document when none is available. The four-region shell keeps Resources, the React Flow canvas, Properties / Run setup, and Problems / Evidence / Source / Diff in one workspace. Use the Resources filter, Quick Open (Command/Ctrl+P), and manual Refresh resources as needed. Never accept a browser-supplied path, root, glob, URL, or output destination.

The local catalog/OpenAPI contract is version 1.1.0; AIR artifacts and /air/v1 remain unchanged. Skill content edits rotate opaque IDs. Use only an explicit replaces_id produced by a complete, mutually unique server-private same-source relation to offer Keep/Cancel/Reload. It covers only the immediately preceding successful generation and is not a route alias. Omit it for unchanged, split, merge, swap, incomplete, unreadable, or truncated scans; never match by public name, hash, source label, or path.

Open a specific Skill or AIR artifact by supplying one input:

node scripts/air.mjs workbench /path/to/skill/SKILL.md
node scripts/air.mjs workbench /path/to/workflow.air.json

Discovery is enabled at launch. It is snapshot-based: do not claim a watcher, live follow, provider signal, or managed run. Modified documents are isolated in memory, and a resource switch requires Keep, Discard, or Cancel instead of silently replacing edits.

Default binding is loopback. An explicit --host 0.0.0.0 is informed consent to expose the same token-protected, read-only catalog over plaintext HTTP to reachable IPv4 networks:

node scripts/air.mjs workbench \
  --host 0.0.0.0

Tell the user to replace 0.0.0.0 in the printed URL with http://<LAN-IP>:PORT/?token=TOKEN, preserving the port and token. Use a trusted network/firewall, keep the token URL private, and stop the process after review. Do not describe 0.0.0.0 as local-user-only.

2. Inspect metadata-only Codex and Claude sessions

The default Resources catalog includes bounded Codex rollout streams and Claude main/subagent streams. Selecting a session creates an in-memory, read-only AIR trace snapshot. Its graph and Evidence timeline contain observed record envelopes plus separately inferred temporal order. hidden_reasoning_recovered is always false.

All public surfaces omit raw prompts, messages, reasoning, commands and arguments, results, stdout/stderr, attachments, file content, environment and credentials, branches, filesystem paths, and provider identifiers. Use only opaque server-instance session/snapshot IDs. The artifact must retain the metadata-only privacy manifest and omission counts. Require every published catalog row to have a unique opaque session ID that resolves to exactly one server-private source authority. Never reissue a public snapshot ID during one server registry lifetime, even after its private continuation handle expires.

Refresh resources takes another bounded catalog snapshot and, for the selected session, requests continuation from the last server-owned cursor. Incomplete trailing JSONL remains uncommitted until a later manual refresh. If a continuation source was truncated, replaced, rotated, or rewritten, report the source change instead of joining histories. Even when no prior snapshot handle is supplied, verify the server-owned last-published bounded continuity high-water before reusing an epoch or event IDs. Revalidate that high-water at every later publication cut and do not lower it when a fresh capture accepts a shorter prefix; start a new epoch with disjoint event IDs after a mismatch. Provider lifecycle evidence is asymmetric; unknown is correct when no authoritative evidence exists.

Session graphs are evidence, not editable workflows. Do not enable step/edge editing, plan setup, Markdown export, source, or diff for them, and never expose raw provider JSONL to the browser.

3. Choose the AIR representation

• .air.json is the complete AIR 1 artifact for workflow, plan, and trace.
• .air.md is the lossless workflow-only Markdown carrier defined by the AIR codec. Lossless does not mean byte-identical: the carrier is the source bytes as an exact prefix plus an appended inert air:v1 metadata comment, so it is always larger than the source. Never tell a user that air convert returns their original bytes. The byte-preserving render is workflow-studio export on an unedited import.
• .air.md contains valid Agent Skill Markdown, but Codex and Claude do not discover it merely from that extension. To activate or distribute it as a native Skill, place the reviewed bytes at <skill-directory>/SKILL.md — after confirming with the user which of the two outputs they want there.
• Plans and traces use .air.json; Markdown reports of them are non-lossless views, not AIR carriers.

Use the AIR CLI to import, validate, or convert without overwriting an existing output:

node scripts/air.mjs import /path/to/skill/SKILL.md \
  --out /path/to/workflow.air.json
node scripts/air.mjs validate /path/to/workflow.air.json
node scripts/air.mjs convert /path/to/workflow.air.json \
  --out /path/to/workflow.air.md

4. Migrate legacy artifacts explicitly

AIR Workbench reads Workflow IR 1.0, exact workflow-studio:v1 Skill metadata, plain SKILL.md, and saved legacy workflow/plan/trace artifacts. It does not silently rewrite them.

Migration is deterministic, no-overwrite, and new-output-only. A migrated legacy plan loses executable approval because AIR binds different bytes; any old approval is historical, non-authorizing provenance. Require a fresh AIR approval before any future AIR-native execution path.

node scripts/air.mjs migrate /path/to/legacy.json \
  --to air/1 \
  --out /path/to/migrated.air.json

5. Review and edit a workflow

Keep the graph canvas, semantic outline, selection inspector, source, and diff in one review context:

• select a step or dependency on the React Flow canvas or keyboard-operable outline;
• edit step titles/bodies and supported dependency properties;
• add, reorder, or delete steps and connect/reconnect dependencies;
• use bounded undo/redo for semantic graph edits; and
• review source and the full diff before downloading an artifact or Markdown draft.

Canvas positions, viewport, focus, and selection are presentation state and must never enter AIR, legacy Workflow IR, plan hashes, approvals, or promoted Skills. Mount the interactive canvas only at or below 1,000 nodes and 1,000 edges. Above either limit, use the bounded first-100-rows-per-kind fallback while preserving validation, diagnostics, source truth, and downloads.

For a real repository smoke test:

node scripts/workflow-studio.mjs import \
  ../background-implementer/SKILL.md \
  --out /tmp/background-implementer.workflow.json
node scripts/workflow-studio.mjs studio \
  /tmp/background-implementer.workflow.json

An unchanged Skill round-trip must preserve its source bytes exactly. Unsupported or ambiguous Markdown remains opaque rather than being guessed.

6. Use the legacy native-run compatibility path

The established Workflow IR 1.0 native-run commands remain available unchanged while AIR-native plan/run support is developed:

node scripts/workflow-studio.mjs plan /path/to/workflow.json \
  --agent codex \
  --cwd /path/to/workspace \
  --prompt-file /path/to/prompt.txt \
  --safety read-only \
  --out /path/to/plan.json
node scripts/workflow-studio.mjs approve /path/to/plan.json \
  --out /path/to/approved-plan.json
node scripts/workflow-studio.mjs run /path/to/approved-plan.json \
  --trace /path/to/trace.json

Use --agent claude for Claude Code. Default to read-only; workspace-write requires a separate explicit choice. Browser review is not CLI authorization. Any prompt, graph, agent, working-directory, safety, or command change requires new approval.

The browser's Run setup prepares and downloads a reviewed plan; it is not a Run control and does not grant native approval. Before a native run, state that the graph is supplied to the selected CLI but is not enforced node by node. A trace includes observable provider events and explicitly inferred sequence, not hidden reasoning or causal truth. Missing CLIs fail explicitly; never install, silently fall back, add bypass flags, or accept arbitrary passthrough arguments.

7. Promote a reviewed legacy plan or trace

Promotion always writes a new Skill draft and never overwrites a source:

node scripts/workflow-studio.mjs promote /path/to/plan-or-trace.json \
  --name reviewed-workflow \
  --description "Run the reviewed workflow." \
  --out /path/to/reviewed-workflow

Review generated instructions and provenance warnings. Trace-derived steps describe observed history, not guaranteed future behavior.

Compatibility and limits

• AIR 1 uses format: "air", air_version: "1.0.0", the https://open330.github.io/air/ project origin, and canonical /air/v1 read-only discovery routes.
• /api/artifact, Workflow IR 1.0, workflow-studio:v1, and scripts/workflow-studio.mjs remain explicit compatibility boundaries.
• The server has no browser file-write, Skill-install, or agent-run endpoint.
• Native execution remains delegated to installed Codex and Claude CLIs; AIR Workbench is not a managed node-by-node orchestrator.
• The default Resources catalog discovers bounded Skills plus metadata-only Codex rollout and Claude main/subagent sessions. Session snapshots and timelines are read-only and refresh manually; there is no watcher or live follow.
• The installed runtime uses checked-in same-origin assets and needs no npm, CDN, registry, telemetry, remote service, or global executable.
• Import coverage is partial and shape-based. Only the recognized document shapes become steps; anything else imports to zero nodes and zero edges with a workflow.none warning, which is a normal result and not an error. The bottom rung chains ordinary ## sections in document order and marks the result heuristic confidence with inferred edge provenance — say so instead of presenting an inferred order as the author's declared sequence. README.md lists the rungs and their confidence.rule_id values.
• This Skill is not part of the core install profile. Install it explicitly with agt skill install -g --from jiunbae/agent-skills/agents/air-workbench or ./install.sh agents/air-workbench.

See README.md and spec/AIR-1.0.0.md for the complete contract, safety model, build instructions, and compatibility matrix.