Skip to content
Skills Library
AI & agents · Automation

aep-executor

/aep-executor

Spawns and steers workspace agents across Claude Code and Codex backends. Use for backend choice, launch mode, or host detection; other skills call it.

Licence
MIT
Last repository change
18.09.2026

Assessment and security

85/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 18.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/detect-backend.sh, scripts/spawn-liveness-probe.sh

What it does and when to use it

Spawns and steers workspace agents across Claude Code and Codex backends. Use for backend choice, launch mode, or host detection; other skills call it.

Original author description

Spawns and steers workspace agents across Claude Code and Codex backends. Use for backend choice, launch mode, or host detection; other skills call it.

How it works

  1. How Other Skills Use This
  2. The Operation Contract
  3. The Modes (summary)
  4. Reference Files
  5. Standalone Usage
  6. Rationale
  7. Next Step
Original SKILL.md headings · 132 lines, 998 words
SKILL.md preview
---
name: aep-executor
description: >-
  Spawns and steers workspace agents across Claude Code and Codex backends.
  Use for backend choice, launch mode, or host detection; other skills call
  it.
---

# Executor Abstraction

A reusable abstraction for **running implementation work in an isolated
workspace**, independent of which agent host (Claude Code, Codex) or which
mechanism is available. Lifecycle skills speak one vocabulary of operations;
this skill maps each operation to a concrete recipe per mode. It is consumed as
a library by `/aep-launch`, `/aep-build`, and `/aep-autopilot`, and can be
invoked standalone to dry-run detection (see [Standalone Usage](#standalone-usage)).

**Native-first:** Claude Code launches use a native in-process background subagent
(`native-bg-subagent`, the default) or — where the `claude --bg` flag exists —
native background sessions (`claude-bg`); Codex launches use native subagents
(`codex-subagent`) or headless exec workers (`codex-exec`). tmux+cmux is the
**`legacy`** mode — selected only by explicit pin
(`git config aep.executor-backend tmux`) or on generic hosts. Every mode runs its
worker in an AEP-created git worktree at `.feature-workspaces/<ws>`.

---

## How Other Skills Use This

| Skill                | What it uses                                          | Operations                                     |
| -------------------- | ----------------------------------------------------- | ---------------------------------------------- |
| `/aep-launch`        | Start the implementation agent + expose it for review | `detect`, `spawn`, `present`                   |
| `/aep-build` Phase 5 | Spawn the evaluator in the right execution context    | `detect`, `spawn_evaluator`                    |
| `/aep-build`         | Raise a human decision mid-build                      | `gate`                                         |
| `/aep-autopilot`     | Run the periodic tick check cheaply; steer workspaces | `detect`, `check`, `nudge`, `liveness`, `gate` |
| `/aep-wrap`          | Tear down the worker + worktree after merge           | `teardown`                                     |
| `/aep-dispatch`      | Resolve the handoff mode; route "…with workflow" runs | `detect`                                       |

---

## The Operation Contract

Every consumer speaks these verbs. The recipe files supply the implementation
per mode.

| Op                          | Purpose                                                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detect()`                  | Resolve host + native capabilities + pin, select a mode                                                                                                     |
| `spawn(ws, branch, prompt)` | Start an implementation agent bound to the AEP worktree                                                                                                     |
| `spawn_evaluator(ws, role)` | Start an evaluator agent (worktree-bound) in the mode's eval context; accepts an optional tier-derived **effort hint** (see backends.md)                    |
| `nudge(ws, msg)`            | Send a mid-flight instruction _(steerable modes; pull-based under claude-bg)_                                                                               |
| `liveness(ws)`              | Is the agent actively working? _(mode-specific signal + git-diff corroboration)_                                                                            |
| `gate(ws)`                  | Surface a worker's human decision: `needs-human.md` + the mode's transport, answered hub-and-spoke through the main agent (block-in-place or gate-and-park) |
| `check(prompt, schema)`     | Run a read-only analysis prompt in a **cheap, context-isolated** agent; return its JSON result — keeps a long-lived orchestrator session's context small    |
| `monitor(ws)`               | Read `.dev-workflow/signals/status.json` — **host-independent, never changes**                                                                              |
| `present(ws)`               | Human review surface (`TaskOutput` / `claude attach` / Codex thread / cmux tab / signals)                                                                   |
| `teardown(ws)`              | Worker + worktree cleanup                                                                                                                                   |

> **`monitor()` is already abstract.** Progress is reported through signal files
> at phase boundaries regardless of the executor. Native push channels
> (SendMessage, send_input) are an acceleration layer — the signal files remain
> the durable, host-agnostic source of truth.

---

## The Modes (summary)

| Mode                   | Lifetime      | Selected when                                                          |
| ---------------------- | ------------- | ---------------------------------------------------------------------- |
| **native-bg-subagent** | session-bound | **Claude Code default** + long-lived orchestrator                      |
| **claude-bg**          | OS-bound      | Claude Code, `claude --bg` present (cron driver / OS-bound need)       |
| **codex-subagent**     | session-bound | Codex with a living main thread (desktop app or interactive CLI)       |
| **codex-exec**         | OS-bound      | Codex + cron driver, or hard isolation demanded                        |
| **legacy**             | OS-bound      | explicit pin (`aep.executor-backend tmux`), or generic host w/ tmux    |
| **workflow**           | session-bound | explicit opt-in ("…with workflow") + Claude Code (see `/aep-workflow`) |
| **headless**           | session-bound | last resort                                                            |

Read `references/backends.md` for each mode's mechanism, the detection recipe,
the full selection order, the driver × backend compatibility matrix, the
human-gate protocol, and orphan re-adoption.

---

## Reference Files

| File                                                                   | Contents                                                                                                    | When to read                                                                                                            |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [`references/backends.md`](references/backends.md)                     | Mode matrix, detection, selection order, driver compatibility, gate protocol, orphan re-adoption, `check()` | Always, before spawning or steering                                                                                     |
| [`references/claude-native.md`](references/claude-native.md)           | `native-bg-subagent` (default) + `claude-bg` recipes, `--bg` availability note                              | When the selected mode is a Claude native one                                                                           |
| [`references/codex-native.md`](references/codex-native.md)             | `codex-subagent` + `codex-exec` recipes, `aep-builder`/`aep-evaluator` role TOMLs, desktop app mapping      | When the selected mode is a Codex one                                                                                   |
| [`references/tmux-session.md`](references/tmux-session.md)             | `legacy` recipes (tmux spawn/nudge/liveness, cmux tab ladder)                                               | When `legacy` is pinned or selected                                                                                     |
| [`references/dogfood-validation.md`](references/dogfood-validation.md) | `dogfood_method()` host × mode detection, `e2e_tool()`, `target_url()` resolution                           | When running dogfood validation (consumed by `/aep-build`, `/aep-launch`, `/aep-watch`, the autopilot post-merge guard) |

The skill also ships two probes, so the exact bash lives in one place instead of
being retyped from a reference:

- `scripts/detect-backend.sh [--lifetime long|ephemeral] [--opt-in workflow|tmux] [--json]`
  — host, executor commands, native capabilities, pin, presentation surface, and
  the selected `MODE`. `eval "$(bash scripts/detect-backend.sh)"` to use it.
- `scripts/spawn-liveness-probe.sh <name> <agent_id>` — the post-spawn liveness
  probe every spawner runs (`references/backends.md` § Post-Spawn Liveness Probe).

---

## Standalone Usage

Invoked directly, this skill reports what would happen:

1. Run `bash scripts/detect-backend.sh` (add `--lifetime ephemeral` when this
   invocation is a cron/launchd one-shot — the script cannot probe that).
2. Report each field it prints, and say **why** that `MODE` won: which earlier
   rule in the selection order did not match.
3. If the user asked "why not workflow / why not tmux", explain the opt-in/pin
   gates.

This does not spawn anything — it is a dry-run of `detect()`.

---

## Rationale

Why native modes come first and tmux is a pinned `legacy` mode, why AEP owns the
worktree, why session-bound vs OS-bound is a first-class axis, why human gates are
hub-and-spoke, and why autopilot drives only steerable modes are recorded in
`docs/decisions/native-first-executor.md`,
`docs/decisions/host-agnostic-executor.md`, and
`docs/decisions/remove-claude-team.md`.

---

## Next Step

After detecting/spawning, control returns to the calling skill:

- `/aep-launch` → the bootstrap was the spawn prompt (native modes) or sent over
  tmux (legacy), then `/aep-build` runs in the workspace
- `/aep-autopilot` → resumes its tick loop
- `/aep-dispatch` → completes the handoff
Files in this package (9)
  • SKILL.md 10 KB
  • references/action-list.schema.json 2 KB
  • references/backends.md 28 KB
  • references/claude-native.md 10 KB
  • references/codex-native.md 10 KB
  • references/dogfood-validation.md 15 KB
  • references/tmux-session.md 6 KB
  • scripts/detect-backend.sh 6 KB
  • scripts/spawn-liveness-probe.sh 2 KB

Versions

The database has no other skills named aep-executor.

Database snapshot: 13.11.2026 · package version b5a0eb10ddf8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100codex-first-executor
    Fork Overlay:Codex-first 外部执行器策略。按任务特征路由到 Claude 或 Codex,Codex-first(非品牌路由)。使用时机:需要决定是否将当前任务派发给 Codex 时加载此 skill。
  • 95aep-dispatch
    Picks one ready story and hands it to /aep-design or /aep-launch. Use for "what's next" or "dispatch"; running continuously is /aep-autopilot.
  • 85aep-workflow
    Authors a re-runnable multi-agent harness for one task too large or uncertain for a single context. Use for "dynamic workflow" or "orchestrate subagents".
  • 95executor-capability-gate
    Fork Overlay:外部模型调用前置检查门控。调用 Codex/Gemini 之前运行五项检查,防止调用失败浪费时间。使用时机:任何调用外部模型(Codex [C]、Gemini [G])之前自动运行。
  • 90Codex Framework
    Reference knowledge for OpenAI Codex CLI compatibility — how Codex discovers AGENTS.md instructions and .agents/skills so a Forge (Claude Code) project can interoperate with Codex without duplicating agent definitions. Use when a user asks to "add Codex support", make the repo…
  • 100turbo
    Enable, disable, or inspect Session Cartographer Turbo Mode, the optional shared warm recall backend for Claude Code and Codex. Use when the user asks about Turbo Mode, faster recall, or the global recall backend.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.