# APE — Aidan’s Phase Engine

APE runs coding tasks through planning, tests, implementation, review, and shipping.
It saves progress outside the chat, so a task can continue in another session.

APE coordinates the host's native agents. Its runtime decides the next stage and
checks the evidence before accepting a worker's result. This helps catch unsupported
claims; it does not guarantee that a test, review, or code change is correct.

## Current status

Version **2.25.8** is approved for release with a documented owner exception.
The tested candidate passed all 18 CI jobs and completed the mechanical, fast,
full, and protected-land Codex workflows. The full workflow required recovery
after two host stream interruptions and an expired, unspawned test ticket;
this is not an uninterrupted schema-v5 first-pass certificate. Runtime and
plugin package bytes are preserved from the tested candidate. See the
[release notes](docs/releases/2.25.8.md) and
[evidence and limits](docs/prevention-release-status.md).

Codex CLI is the primary host. The Claude Code package is included, but
Claude live operation is unverified. Codex IDE integrations and ChatGPT web,
mobile, and cloud runtimes are not supported.
Codex is the sole required live release-certification host; a Claude subscription
or API account is not required to use APE with Codex or publish its release.

Installing APE does not start a run. You choose when it can work and ship.

## Install

Node.js 22.12.0 or newer is required.

### Codex CLI

Use the pinned Codex CLI **0.153.4**. Install the plugin and enable the native V2
worker tools in the Codex home you use for APE:

```bash
codex plugin marketplace add AAWWCC/ape
codex plugin add ape@ape
codex features enable multi_agent_v2
```

The feature command updates that Codex home's `config.toml`. Restart Codex, then
use `codex features list` in the same launch environment to verify that
`multi_agent_v2` is `true`. The older `multi_agent` setting alone does not ensure
the worker interface APE requires. See [host compatibility](docs/compatibility.md)
for the equivalent configuration and launch option.

### Claude Code

Run inside Claude Code:

```text
/plugin marketplace add AAWWCC/ape
/plugin install ape@ape
/reload-plugins
```

Both packages run locally through Node.js. APE stores project state under
`.ape/runtime/`; it does not send that state to an APE-operated service.
The coding host and configured tools still use their own services and permissions.

### Compatibility

[`compatibility.json`](compatibility.json) defines the supported host versions
and platforms. See [host compatibility](docs/compatibility.md) before changing a
CLI version. CI checks packages on Linux, macOS, and Windows.

## Use

Start by setting up the project's test commands. Configuration changes are
proposed for your approval:

```text
/ape:config init
/ape:config doctor
```

Then start a task, check its progress, or continue it later:

```text
/ape:run Add optimistic locking to invoice updates
/ape:status
/ape:resume
```

Use APE for work that needs tests, review, or continuity across sessions.
For a tiny edit or a quick question, an ordinary coding session may be simpler.

| Skill | What it does |
| --- | --- |
| `run` | Start a build, investigation, or shipping run. |
| `status` | Show progress, pending work, and blocks. |
| `resume` | Continue an interrupted run. |
| `history` | Inspect past runs and their results. |
| `config` | Set up commands, models, and shipping. |
| `override` | Request an audited abort, reset, or dispatch expiration. |
| `roadmap` | Manage an optional project roadmap. |

Only read-only `status` may be selected automatically. Invoke the other skills
explicitly. See the [skill reference](docs/skills.md) for details.

## Pipelines

| Mode | Work |
| --- | --- |
| `phase` | Plan, test, implement, review, and ship a change. |
| `debug` | Investigate a problem without editing files. |
| `spike` | Research a question without editing files. |
| `land` | Review and ship existing work without editing it. |

A `phase` run uses one of three lanes:

- **Mechanical:** documentation, generated files, and other non-behavioral changes.
- **Fast:** small behavioral changes without high-risk triggers.
- **Full:** larger or sensitive changes, such as authentication, migrations, or public APIs.

Choose `auto` to let APE classify the lane. A run can move to a stricter lane,
but not a lighter one.

Behavioral changes normally start with failing tests, written by a separate
test worker. Use `green-maintenance` for tests that should already pass, such as
a regression net or deflake. Non-behavioral work does not need fabricated failing
tests. See [pipeline rules](docs/pipeline.md) for scope limits and stage order.

## Gates and shipping

Before dispatching workers, APE checks the proposed scope, repository state,
commands, required capabilities, and later pipeline stages. Missing paths need
approval; they are not silently added.

Workers must return validated results called **receipts**. APE also checks file
scope, tree identity, tests, reviews, and the configured gates before shipping.

GitHub is the only shipping provider. Each project needs its own explicit
repository target. By default, green work waits for an audited `ship` action.
With `shipping.auto_merge: true`, a run also needs explicit per-run shipping
approval before APE may push, open a PR, and merge.

APE waits for required checks and proof of the remote merge. A failed local
cleanup does not undo a proven remote success. A blocked run does not authorize
automatic reset, abort, or restoration.

See [configuration](docs/configuration.md) and [pipeline rules](docs/pipeline.md)
for the exact checks and recovery options.

## Development

```bash
npm ci
npm run public:hooks
npm run typecheck
npm run test:agent
npm run bundle
npm run package:plugins
npm run package:check
npm run public:check
```

`npm test` uses six workers. `npm run test:agent -- <paths...>` uses three and is
the preferred profile when other agents may also be testing.

`public:check` scans both packaged plugins and the actual Git worktree inventory,
including new nonignored source files. Tracked docs and tests remain checked even
when ignore rules change. Negative tests construct their explicitly synthetic
protected-looking inputs from fixture components; no source directory is exempt.
Never place real private values in source, including split or encoded forms.

Keep runtime changes, tests, and generated packages easy to review separately.
The Git hooks check commit identities; verify the remote before pushing.
A rebuild does not update an installed plugin. Reinstallation, pushes, and
publication are separate actions.

The package and release builders accept `--output-root` for a new or empty directory,
or one containing only recognized APE output. They preserve unfamiliar files and refuse
source directories. A package upgrade that removes an old generated filename may need
a fresh output directory; inspect the retained files before removing them yourself.

For the full checklists, see [Contributing](CONTRIBUTING.md),
[release checks](docs/operational-readiness.md),
[prompt evaluations](evals/README.md), and
[performance baselines](docs/performance-baselines.md).

## Help and license

- [Documentation index](docs/README.md)
- [Report a bug](docs/incident-reporting.md)
- [GitHub Issues](https://github.com/AAWWCC/ape/issues) and [Discussions](https://github.com/AAWWCC/ape/discussions)
- [Security policy](SECURITY.md) for private vulnerability reports

APE is licensed under [MIT](LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md)
for material with separate terms.