# apt-plan adapter — Aperant Conductor

This adapter is **only loaded** when the planner runs under the Aperant
Conductor (a master-orchestrator agent inside the Aperant desktop / web
app). Native invocations of `/apt:plan` (from plain Claude Code, Gemini
CLI, OpenCode, or Codex) IGNORE this file entirely — the framework
behavior in `SKILL.md` is the source of truth for them.

## When to load this adapter

Detect Conductor context by env var:

```bash
[ -n "$APERANT_TERMINAL_ID" ]
```

The Conductor injects `APERANT_TERMINAL_ID` into every PTY it spawns.
If the var is unset, you are NOT under the Conductor — stop reading.

## What changes under the Conductor

The planner's filesystem outputs (`spec.md`, `implementation_plan.json`)
are unchanged. The ADDITION is one extra step after Section 8 (Persist
State) of `SKILL.md`:

### Plan-Ready Signal (framework-owned, no action required)

The `artifact.ready{kind:'plan'}` signal is emitted **automatically** by
the framework's `apt-tools commit` postcondition. When the planner
commits `spec.md` + `implementation_plan.json` via the standard:

```bash
node packages/framework/bin/apt-tools.mjs commit "plan: ..." \
  --files spec.md implementation_plan.json
```

…and the process is running under a Conductor PTY (env
`APERANT_TERMINAL_ID` is set), `apt-tools commit` auto-emits a fully-
formed `artifact.ready` envelope to `.aperant/events/{today}.jsonl`.
The envelope carries the `task_id`, plan path, sha256 hash, and the
auto-stamped `terminal_id`.

This replaces the earlier markdown-discipline emit step. The earlier
step was correctly skipped on QUICK / SIMPLE classified tasks (Fast
Path Guarantee, ID-05) — moving the emit to a
framework postcondition makes it work uniformly across QUICK, STANDARD,
DEEP, and COMPLEX without violating the Fast Path Guarantee.

**Planner authors don't need to do anything.** As long as you call
`apt-tools commit` to land your plan artifacts, the Conductor will
see `artifact.ready` and the drawer's PlanReadyCard will auto-promote.

If the planner does NOT use `apt-tools commit` (it lands the plan via
raw `git commit` or `git add`), the auto-emit will not fire. In that
case the Conductor falls back to filesystem polling of the task dir
(slightly higher latency, same outcome).

### Plan-review handshake (Step 6 + 7 of Conductor v2)

After emitting `artifact.ready{kind:'plan'}` the planner SHOULD pause at
an idle prompt and listen for ONE of three Conductor-driven inputs:

- `proceed\r` — the human (via the PlanReadyCard's **Approve** button)
  approves the plan. Continue to `/apt:execute` as you would in the
  normal flow.
- `abort\r` — the human rejected. Abandon this plan; do not start
  execution. Optionally exit the session cleanly.
- `[Conductor realignment] <note>\r` — the human pressed **Realign**.
  Treat the `<note>` as additional planning context: re-open spec.md /
  implementation_plan.json, address the note's gaps, commit a new
  revision, and emit a fresh `artifact.ready{kind:'plan'}` (with the
  same task_id but a NEW request_id — the drawer keys cards on
  request_id, so re-using it would suppress the new card). The
  realignment loop can repeat; after attempt_n >= 3 the Conductor may
  decide to respawn the terminal entirely.

These exact strings are pinned by the Conductor's `ConductorContextHost`
handlers (`packages/ui/src/sections/conductor/ConductorContextHost.tsx`).
Native CLI invocations of `/apt:plan` (no `APERANT_TERMINAL_ID`) skip
this handshake and follow the normal report → `/apt:execute` flow.

## Why this lives in an adapter (not in SKILL.md)

The Aperant Framework is consumed by multiple CLIs (Claude Code, Gemini,
OpenCode, Codex) and by the Aperant app itself. The vast majority of
`/apt:plan` invocations come from native CLIs — those should not see
or execute Conductor-specific machinery. By isolating the Conductor's
event-emit obligations to this adapter, the public skill stays minimal
and the framework remains CLI-agnostic. The pattern mirrors
`appendices/` (reasoning-stance loaders) but with a different semantic:
**runtime-context loader** — load when the runtime environment matches.

## Adding more adapters

Future runtime contexts (e.g. a hypothetical CI runner, another
orchestrator) can add `adapters/{context}.md` files using the same
pattern: detect via env or filesystem signal, document the additional
obligations, and add a one-line conditional reference in `SKILL.md`.
