Aep Launch

Launch

Spawn an autonomous workspace agent to implement a feature. Creates a git worktree on a fresh feature branch, bootstraps an implementation agent through the executor abstraction (aep-executor) — which picks the right mode for the current host — and optionally sets up a separate evaluator agent for quality assurance.

Native-first: This skill does not hardwire claude + tmux + cmux. It

delegates spawning and presentation to aep-executor. Read

.claude/skills/aep-executor/references/backends.md before spawning. On

Claude Code the launch mode is native-bg-subagent (default — Agent tool

run_in_background, no team) or claude-bg (native background sessions,

where claude --bg exists); on Codex it is codex-subagent or

codex-exec; legacy (tmux + optional cmux) runs only when explicitly

pinned or on generic hosts. Every mode uses the same AEP-created worktree.

(claude-team was removed — silent agent-teams spawn failure; see

aep-executor/references/backends.md.)

Where this fits:

/aep-onboard → /aep-scaffold → [ /aep-design → /aep-launch → /aep-build → /aep-wrap ]
                                    ▲ you are here

Session: Main session, automated Input: OpenSpec change name (from /aep-design or /aep-dispatch for well-specified stories) Output: Running workspace agent with bootstrapped build + optional evaluator

---

Guardrails Before Launch

1. Verify working copy is clean

git status --porcelain

If any files are modified or staged — ABORT. Commit them first (git add <files> && git commit -m "...") or stash them with git stash.

2. Verify dispatch commit is pushed to remote

# Resolve $BASE (integration branch) — see git-ref "Integration Branch" (override → develop → main)
BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
[ -z "$BASE" ] && { git show-ref --verify --quiet refs/heads/develop \
  || git show-ref --verify --quiet refs/remotes/origin/develop; } && BASE=develop
BASE=${BASE:-main}

git fetch origin
git log --oneline origin/"$BASE".."$BASE"

If any unpushed commits appear — ABORT. The dispatch commit (YAML updates + OpenSpec changes) must be on the remote before launching workspaces. Without this, workspace branches base off a $BASE that doesn't include the dispatch commit, and the OpenSpec files won't be visible inside the worktree.

Push if needed: git push origin "$BASE"

3. Verify calibration context for .5 layer stories

If the story belongs to a .5 layer (0.5, 1.5, 2.5) or has calibration_type set:

# Check for calibration artifact (new path first, then legacy)
type="${calibration_type:-visual-design}"
[ -f "calibration/${type}.yaml" ] || [ -f design-context.yaml ] && echo "calibration context exists" || echo "MISSING"

If the calibration artifact does not exist — ABORT. The user must run /aep-calibrate <type> first. Agents dispatched without calibration context will reproduce the same generic output that created the need for alignment in the first place.

4. Verify Object Map for UI-facing stories

If the story is UI-facing (has object_model_refs, calibration_type in {visual-design, ux-flow}, or a non-null activity whose module is kind: ui):

# Find the object-map that COVERS this story (capability-agnostic — works whether or
# not story.capability is set), then require status: approved.
MAP=$(grep -rl 'story: <STORY-ID>' product/maps/*/object-map.yaml 2>/dev/null | head -1)
{ [ -n "$MAP" ] && grep -q 'status: approved' "$MAP"; } \
  && echo "object map approved: $MAP" || echo "MISSING"

If no approved Object Map covers the story (missing, `draft`, or `stale`) — ABORT. The user must run /aep-model first. A UI-facing agent launched without the noun-first Object Map will invent ad-hoc, one-step-one-screen structure — exactly what the Object Map exists to prevent.

5. Clean up orphan worktree/branch from prior failed launches

Git worktree, unlike jj's jj workspace forget, does not auto-clean if a previous /aep-launch died mid-flight. Two failure modes can block re-launch — both are silent and confusing on first encounter. Run these idempotent checks before git worktree add:

# Resolve $BASE (integration branch) — see git-ref "Integration Branch" (override → develop → main)
BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
[ -z "$BASE" ] && { git show-ref --verify --quiet refs/heads/develop \
  || git show-ref --verify --quiet refs/remotes/origin/develop; } && BASE=develop
BASE=${BASE:-main}

# Check 1: orphan branch with no unmerged work → safe to delete
if git show-ref --verify --quiet refs/heads/feat/<name>; then
  ahead=$(git rev-list --count "$BASE"..feat/<name> 2>/dev/null || echo 0)
  if [ "$ahead" = "0" ]; then
    echo "Removing orphan branch feat/<name> (no commits ahead of $BASE)"
    git branch -D feat/<name>
  else
    echo "ABORT: feat/<name> has $ahead unmerged commit(s). Investigate before re-launching."
    echo "  - If the work is salvageable: git checkout feat/<name> && finish manually"
    echo "  - If the work is abandoned:   git branch -D feat/<name> && retry /aep-launch"
    exit 1
  fi
fi

# Check 2: orphan worktree registration → prune
if [ -d ".git/worktrees/<name>" ] && [ ! -d ".feature-workspaces/<name>" ]; then
  echo "Pruning orphan worktree registration for <name>"
  git worktree prune
fi

The branch deletion is gated on ahead == 0 so live workspaces are never affected — if the orphan branch has unmerged commits, abort and let the user investigate. The worktree prune is gated on the working directory being missing, so it only fires after a manual rm -rf of the worktree dir.

Orphan with a live worktree? If .feature-workspaces/<name> exists with

committed/in-progress work but no live agent (state says active, agent list

says gone), do not delete anything — follow the orphan re-adoption

protocol in aep-executor/references/backends.md: re-spawn a worker into the

existing worktree with a recovery bootstrap.

---

Step 1: Detect the Launch Mode

Run the detection recipe from .claude/skills/aep-executor/references/backends.md and announce the selection, e.g.:

• "Claude Code → native-bg-subagent: in-process background subagent (Agent

tool, run_in_background, no team); steer with SendMessage(to: agentId) / feedback.md; watch with TaskOutput."

• "Claude Code + claude --bg present, OS-bound need → claude-bg: native

background session; watch with claude attach <id>."

• "Codex main thread → codex-subagent: native worker (aep-builder role);

steer with send_input; threads visible in the app / /agent."

• "Pinned tmux → legacy: tmux session (+ cmux tab if available)."

If the user said "…with workflow" and the host is Claude Code, select workflow and follow the dynamic-workflow recipe in the executor reference instead of the steps below.

Step 2: Create the Worktree (common to all modes)

Invariant — one launch = one worktree = one subagent = one story. Each

/aep-launch creates exactly one worktree and spawns exactly one worker (one

native-bg-subagent on Claude Code) to build exactly one story. Do not put

multiple stories into a single launch and do not spawn a second worker into a

worktree that already has a live one. (The autopilot enforces the upstream half

of this: max ONE launch per tick — see aep-autopilot tick protocol Step

⑥.) The one exception is a compile_mode: grouped_change story group, which is

deliberately compiled into a single change/worktree/worker — see Step 4.

Important: Workspaces must live outside .claude/ — Claude Code

treats everything under .claude/ as sensitive and blocks file writes with

permission prompts, even with --dangerously-skip-permissions.

# Resolve $BASE (integration branch) — see git-ref "Integration Branch" (override → develop → main)
BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
[ -z "$BASE" ] && { git show-ref --verify --quiet refs/heads/develop \
  || git show-ref --verify --quiet refs/remotes/origin/develop; } && BASE=develop
BASE=${BASE:-main}

# Create the git worktree on a fresh feature branch (outside .claude/)
mkdir -p .feature-workspaces
git worktree add -b feat/<name> .feature-workspaces/<name> "$BASE"

Replace <name> with a short feature name (e.g., add-auth). The branch will be feat/add-auth.

Note: Add .feature-workspaces/ to your project's .gitignore — worktree directories are ephemeral and should not be tracked.

Disk note: Each worktree shares .git/objects with the main repo (no history duplication), but the working tree itself is duplicated. Budget ~working-tree-size per active workspace.

Step 3: Compose the Bootstrap Prompt

The bootstrap is the same text in every mode; only the delivery differs.

Skill naming: AEP skills are canonically registered with the aep- prefix (/aep-build, /aep-wrap, …). If your project installed them under different names, check .claude/skills/ and adjust the command in the bootstrap accordingly.

Inject Prior Lessons (if available)

Before composing the bootstrap, check for relevant lessons from previous builds:

ls lessons-learned/*.md 2>/dev/null
ls lessons-learned/process/*.md 2>/dev/null

If relevant lessons exist (matching the story's module or activity), append a ## Prior Lessons section to the bootstrap prompt with a summary of relevant entries. Cap at 2000 tokens to avoid context bloat. Also include any relevant process lessons from lessons-learned/process/*.md (these apply to all builds, not just module-specific ones).

# NOTE: /aep-build is the canonical name; adjust if your project registered the build skill differently
PROMPT="/aep-build execute implementation for openspec change <change-name>. Read the worktree-onboarding reference in the build skill's references/worktree-onboarding.md for full setup instructions. Design phases are pre-completed on the integration branch.

## Prior Lessons
<relevant lessons summary, if any — omit this section if no lessons exist>
"

Step 4: Spawn — per mode

The bootstrap is the spawn prompt for every native mode; only legacy has a separate send step. Full recipes live in the executor reference files — this is the dispatch:

**Post-spawn verification is mandatory — do NOT return "running" from a spawn

until the liveness probe passes.** After spawning, run the

Post-Spawn Liveness Probe

(bash .claude/skills/aep-executor/scripts/spawn-liveness-probe.sh <name> <agent_id>):

the worker process/agent must exist and the worktree must show activity

(status.json written or non-empty git diff) within N seconds. On failure,

tear down the dead spawn (and TeamDelete any team that got created) and

auto-fall-back to `native-bg-subagent` into the same worktree — never leave

a silently-dead worktree for the autopilot to flag 30+ minutes later. "Roster

says active" is not liveness.

Mode: native-bg-subagent (aep-executor/references/claude-native.md) — Claude Code default

Pre-flight: if any agent-teams team is active, TeamDelete it first (a live team re-routes teamless background spawns through the broken agent-teams backend). Then spawn with the Agent tool: run_in_background: true, no `team_name`, prompt = worktree contract (absolute path + "operate exclusively there") + $PROMPT + the human-gate instructions. A working spawn returns a bare-hex `agentId` with a JSONL output_file (not an @<team> id) — record it as agent_id. Then run the liveness probe above.

Mode: claude-bg (aep-executor/references/claude-native.md) — only if claude --bg exists

cd .feature-workspaces/<name> && claude --bg --dangerously-skip-permissions "$PROMPT"
cd - >/dev/null   # record the printed session id as agent_id; then run the liveness probe

On Claude Code ≥ 2.1.x the claude --bg flag is absent (BG_AVAILABLE=no) —

detection won't select this mode; native-bg-subagent is used instead.

Mode: codex-subagent (aep-executor/references/codex-native.md)

spawn_agent(agent_type: "aep-builder", message: "<abs worktree path> (branch feat/<name>). $PROMPT"). Record the agent id. Ensure .codex/agents/aep-builder.toml is committed in the repo (see the role TOML in the reference; /aep-onboard installs it).

Mode: codex-exec (aep-executor/references/codex-native.md)

Background codex exec --cd .feature-workspaces/<name> ... "$PROMPT"; record the exec session id as agent_id (steerable later via codex exec resume).

Mode: legacy (aep-executor/references/tmux-session.md)

tmux new-session in the worktree → readiness wait → send-keys -l "$PROMPT"

• Enter → then (cmux hosts only) attach the review tab as a sibling pane —

the full recipe, ordering caveats included, is in the reference.

Step 5: Present

Tell the user where to watch/steer, per mode:

---

Optional: Evaluator Mode (Full Mode)

For complex features, a separate evaluator agent independently reviews the generator's work. This is the single most impactful improvement for agent output quality.

Key design decision: The evaluator is not spawned at launch time. It is spawned by the

generator at Phase 5, after implementation is complete. Anthropic's research shows evaluation

should be sequential — build first, then evaluate — not concurrent.

>

Source: Harness Design for Long-Running Application Development — Anthropic Engineering

Why Separate Evaluation

When asked to evaluate their own work, agents consistently rate it positively — even when quality is mediocre. Separating generation from evaluation (inspired by GANs) dramatically improves output quality:

• The generator focuses on building features
• The evaluator focuses on finding problems
• Separation makes it easy to calibrate the evaluator toward skepticism

When to Use

Rule of thumb: If the feature has 3+ tasks in tasks.md or touches UI, use an evaluator.

Brainstorm Evaluation Criteria (at launch time)

Before the generator starts, brainstorm project-specific scoring criteria with the user. The criteria are written to .dev-workflow/evaluator-criteria.md so they're ready when the generator reaches Phase 5.

a. Read the OpenSpec change

cat openspec/changes/<change-name>/proposal.md
cat openspec/changes/<change-name>/aep-design.md
ls openspec/changes/<change-name>/specs/
cat openspec/changes/<change-name>/tasks.md

b. Identify the feature type

c. Propose dimensions

Read the dimension presets in the gen-eval utility skill at .claude/skills/aep-gen-eval/references/scoring-framework.md (Dimension Presets section). Based on the feature type, propose:

• Which default dimensions to keep (Completeness, Correctness, UX, Security, Code Quality)
• Which to drop or de-weight
• Which to add (Originality, Accessibility, API Design, Performance, Data Integrity, etc.)
• Which to weight heavily — these are where the model tends to fall short

d. Ask the user

Present the proposed dimensions and ask:

1. Which dimensions matter most for this specific feature? 2. What does "good" look like — any concrete quality bars? 3. Where have you seen mediocre output from the model before on similar work? 4. Any hard failure conditions beyond the defaults?

e. Generate project-specific criteria

Write .dev-workflow/evaluator-criteria.md (per-workspace, not the default reference) with:

• The agreed-upon dimensions with weights
• Scale definitions tailored to this feature
• Hard failure thresholds reflecting what the user cares about
• Few-shot examples adapted from the defaults in .claude/skills/aep-gen-eval/references/scoring-framework.md

Skip brainstorming? If the user wants to move fast, fall back to the default criteria at .claude/skills/aep-gen-eval/references/scoring-framework.md. But note that task-specific calibration significantly improves evaluator judgment.

How the Evaluator Loop Works (Phase 5)

The generator self-orchestrates the evaluation loop at Phase 5. You do not need to spawn the evaluator manually. /aep-build Phase 5 picks the matching spawn via executor.spawn_evaluator():

The full loop is documented in the build skill's Phase 5. In summary:

1. Generator writes eval-request.md → spawns evaluator (worktree-bound) 2. Evaluator evaluates → writes eval-response-<N>.md 3. Generator reads response → fixes issues 4. Repeat until pass (max 5 rounds)

Evaluator Bootstrap Prompt Template

The generator sends this when spawning the evaluator (for reference — the build skill handles this automatically):

You are an EVALUATOR agent. Begin evaluation immediately.

Read these files:
1. .dev-workflow/evaluator-criteria.md (scoring calibration)
2. .dev-workflow/signals/eval-request.md (what to evaluate)
3. All files in openspec/changes/<change-name>/
4. .dev-workflow/contracts.md (if exists)
5. .dev-workflow/feature-verification.json (if exists)

Then:
1. Review code changes via `git diff "$(git config --get aep.integration-branch 2>/dev/null || (git show-ref --verify --quiet refs/remotes/origin/develop && echo develop || echo main))"...HEAD`
2. Test the running application if possible
3. Score each dimension per your criteria
4. Write structured feedback to .dev-workflow/signals/eval-response-<N>.md

CRITICAL: Score honestly. Do not rationalize problems away.
Apply hard failure thresholds strictly.
Never modify verification_steps in feature-verification.json.

---

Monitoring Workspace Progress

The main session can check workspace progress without interrupting the agent:

# Check current phase and progress
cat .feature-workspaces/<name>/.dev-workflow/signals/status.json

# Check if ready for human review / blocked on a human decision
ls .feature-workspaces/<name>/.dev-workflow/signals/ready-for-review.flag 2>/dev/null
ls .feature-workspaces/<name>/.dev-workflow/signals/needs-human.md 2>/dev/null

# Send mid-flight feedback (every mode reads this at phase boundaries)
cat >> .feature-workspaces/<name>/.dev-workflow/signals/feedback.md << 'EOF'

## <date> <time>
Priority: high
<feedback here>
EOF

If needs-human.md appears (or status.json shows "blocked_on": "human"), the worker is waiting on a decision — answer it through the mode's transport (see the Human-Gate Protocol in aep-executor/references/backends.md).

---

Managing Parallel Sessions

The main session stays on the integration branch ($BASE) and can:

• Launch multiple workspace workers (one per feature)
• See them all: TaskList (native-bg-subagent), claude agents --json

(claude-bg), the thread list / list_agents (codex-subagent), tmux ls (legacy)

• Switch into any worker: TaskOutput <agentId> / claude attach <id> / open

its thread / tmux attach -t <name>

• Handle /aep-wrap after each PR merges

Under codex-exec, workflow, and headless there is no live surface —

progress is read from signals (+ the /workflows view for workflow mode).

Human decisions are still covered: workers gate-and-park (record

needs-human.md, end cleanly), you answer here in the main session, and the

story resumes in its worktree with the answer.

Each worktree gets its own working tree on its own feat/<name> branch. They share .git/objects so history isn't duplicated, but each working tree adds its own checkout-size to disk.

---

Next Step

The workspace agent is now running autonomously. It follows the build skill to implement, test, and merge the feature.

When the PR merges, run the wrap skill:

/aep-wrap

Inter-Agent Signals Specification

The .dev-workflow/signals/ directory provides file-based communication between the workspace agent and the main session. This follows Anthropic's pattern of agents communicating through files rather than chat.

Anthropic's harness design research uses file-based communication between agents — one agent writes a file, another reads and responds by creating a new file or updating in place. This avoids the ambiguity of chat-based coordination and maintains structured context.

Source: Harness Design for Long-Running Application Development

---

Directory Structure

.dev-workflow/signals/
├── status.json              # Workspace agent writes — current phase and progress
├── feedback.md              # Main session writes — mid-flight feedback
├── ready-for-review.flag    # Workspace agent creates — signals human eval needed
├── needs-human.md           # Workspace agent appends — human-gate record (decision needed)
├── eval-request.md          # Generator writes — requests evaluator review
└── eval-response-<N>.md     # Evaluator writes — evaluation results per round

---

Signal Files

status.json — Progress Signal

Written by: Workspace agent (generator) Read by: Main session Updated: At the start of each phase and on blockers

{
  "phase": 4,
  "phase_name": "implementing",
  "task_current": "Add user login form",
  "task_index": 2,
  "task_total": 5,
  "started_at": "2026-03-25T10:00:00Z",
  "blockers": [],
  "completion_pct": 40,
  "last_updated": "2026-03-25T11:30:00Z"
}

Fields:

Concurrency protocol: These story-tracking fields replace direct writes to product-context.yaml. The main session (via /aep-wrap and /aep-dispatch signal sync) reads these fields and updates the YAML. Workspace agents must never write to product-context.yaml.

Update points:

• Phase 0: After initialization completes
• Phase 4: At start of each task and on completion
• Phase 5–8: At start and completion of each phase
• Phase 9–12: At each sub-step (push, PR create, merge)
• On blockers: Add to blockers array immediately

feedback.md — Main Session Feedback

Written by: Main session (user or main agent) Read by: Workspace agent Format: Append-only markdown

# Feedback

## 2026-03-25 11:45

Priority: high
Focus on the auth flow first — the settings page can wait until a follow-up PR.

## 2026-03-25 14:20

Priority: low
The button colors look off on dark mode. Not blocking.

Rules:

• Main session appends new entries with timestamp and priority
• Workspace agent checks for new feedback at the start of each phase
• High-priority feedback should be addressed before continuing
• Low-priority feedback can be deferred to Phase 11.5

ready-for-review.flag — Review Signal

Created by: Workspace agent Read by: Main session Format: Empty file or single-line description

The workspace agent creates this file when it reaches Phase 11.5 (human evaluation) to signal that the feature is ready for human testing.

# Workspace agent creates:
echo "Feature ready for testing at http://localhost:3000" > .dev-workflow/signals/ready-for-review.flag

The main session can watch for this file:

# Main session polls (or uses filesystem watcher):
cat .feature-workspaces/<name>/.dev-workflow/signals/ready-for-review.flag

needs-human.md — Human-Gate Record

Written by: Workspace agent (append-only) Read by: Main session / autopilot (which surfaces it as an escalation) Created: Whenever the worker hits a decision only the human can make

## 2026-06-10T14:30:00Z — Phase 5 (eval round 4)

**Question:** Eval keeps failing Security on the token storage approach. Options: (a) httpOnly cookie, (b) encrypted localStorage. Spec is silent.
**Context:** Both pass functional criteria; the choice affects the API contract.
resolved: human chose (a) httpOnly cookie — 2026-06-10T15:02:00Z

Rules:

• Pair every entry with "blocked_on": "human" in status.json; clear it and

append a resolved: line after acting on the answer.

• The file is the host-agnostic record; the question is answered

hub-and-spoke in the main session and relayed per launch mode (bg subagent SendMessage(to: agentId), session resume, send_input, codex exec resume, nudge) — see the Human-Gate Protocol in aep-executor/references/backends.md.

• Gate-and-park (native-bg-subagent / workflow / headless / codex-exec / claude-bg): after

recording the gate the worker commits WIP and ends its run cleanly; the orchestrator later resumes a worker into the same worktree with the answer. A parked worker's exited process is expected — not a crash.

• Orchestrators treat a gated workspace as **waiting, not stuck and not

failed**.

eval-request.md — Evaluation Request

Written by: Generator agent Read by: Evaluator agent Created: When generator completes Phase 4 and is ready for evaluation

# Evaluation Request

**Round:** 1
**Date:** 2026-03-25
**Requested by:** generator

## What to evaluate

- All tasks committed on the feature branch
- Dev server running on port 3000 (web) / 3001 (server)

## Changes since last round

- [First evaluation — all changes are new]

## Known issues

- [Any issues the generator is already aware of]

## Files changed

[Output of git diff --stat "$BASE"...HEAD (integration branch; see git-ref)]

eval-response-<N>.md — Evaluation Response

Written by: Evaluator agent Read by: Generator agent Format: Follows the structure defined in evaluator-criteria.md

See the "Evaluation Protocol" section in evaluator-criteria.md for the response format.

---

Reading Signals from Main Session

The main session can check workspace progress without interrupting the agent:

# Check current phase and progress
cat .feature-workspaces/<name>/.dev-workflow/signals/status.json | jq .

# Check if ready for review
ls .feature-workspaces/<name>/.dev-workflow/signals/ready-for-review.flag 2>/dev/null

# Send feedback
cat >> .feature-workspaces/<name>/.dev-workflow/signals/feedback.md << 'EOF'

## 2026-03-25 14:00
Priority: high
The API response format changed — check the latest main for updates.
EOF

---

Signal Polling

Agents should check for signal files at phase boundaries, not continuously:

• Generator checks feedback.md at the start of each new phase
• Evaluator checks eval-request.md after completing its bootstrap (initial read of specs/contracts) and after writing each eval-response
• Main session checks status.json and ready-for-review.flag when the user wants a progress update

There is no filesystem watcher or continuous polling. Agents read signal files at natural transition points in the workflow.

If a signal file doesn't exist yet, skip it and continue — it will be checked again at the next phase boundary.

---

Lifecycle

1. Phase 0: Create .dev-workflow/signals/ directory, initialize status.json 2. Each phase: Update status.json at start and end 3. Phase 4: Update task_current, task_index as tasks progress 4. Phase 5: Generator creates eval-request.md if evaluator is running 5. Phase 5: Evaluator writes eval-response-<N>.md 6. Phase 10: Set story_status: "in_review" and pr_url in status.json 7. Phase 11.5: Create ready-for-review.flag 8. Phase 12: Set story_status: "completed", completed_at, cost_usd in status.json 9. On failure: Set story_status: "failed" and populate failure_log in status.json 10. On blockers: Update status.json blockers immediately 11. On feedback: Check feedback.md at start of each phase

Main session reads these signals via /aep-dispatch (signal sync step) and /aep-wrap (post-merge step) to update product-context.yaml. Workspace agents never write to the YAML directly.