| name | aep-onboard |
| description | Installs, verifies, and explains Agentic Engineering Patterns (AEP). Use for first-time AEP or plugin mentions, environment setup, tool checks, project plugin configuration, or an overview; use /aep-scaffold to create a project. |
Onboard
Set up your environment for agentic TypeScript development and get oriented to how AEP thinks. Phase 0 points you to the mental-model tour; Phases 1–5 install the plugin, verify tools, and configure recommended plugins. Run once on first setup — returning users re-verifying their environment can skip Phase 0 and start at Phase 1.
Phase 0 — Orient Yourself (first-timers only)
Returning user? If you've run /aep-onboard before and are just re-verifying your environment, skip to Phase 1.
AEP is not a command runner — it's a workflow that separates thinking (what to build, decided with the AI on the control plane) from doing (agents building to precise specs on the execution plane), communicating only through structured artifacts (product-context.yaml, signal files in .dev-workflow/signals/) rather than shared code context. Installing the tools without that model leaves you staring at a blank terminal unsure which skill to run first.
Read the installed orientation guide — the self-contained 10-minute first-hour tour: the three mental models (control vs execution plane, the Jeff Patton story map, the two-session main/workspace model), what every skill does, and the four concrete paths (new product / existing project / single feature / hands-free).
Done when: you've read orientation.md and can name which of the four paths in "Next Steps — Pick Your Path" (below) matches your situation. Then continue to Phase 1.
Phase 1 — Install the Plugin
Install the AEP skills with the skills CLI at project level, once per agent your project uses. Pin to the latest release and commit the installed files so the version is frozen for your team:
npx skills add memorysaver/agentic-engineering-patterns@<latest-tag> -a claude-code --skill '*' -y
This installs every AEP skill (the aep-* names) plus a skills-lock.json manifest — commit both. The lockfile is the project pin; upgrade it intentionally by rerunning the same command with the desired tag, then review and commit the resulting skill and lockfile diff.
Optional add-ons — always ask the user
AEP pairs with two project-level skills from memorysaver/skills. Ask the user whether they want each, and install only what they choose (newest tag at https://github.com/memorysaver/skills/releases/latest, once per agent):
- Behavioral guidelines in
AGENTS.md? → install project-behavior, then run it to scaffold/extend AGENTS.md.
- A project memory system (committed lessons + recall)? → install
project-memory (and memory-forge), run project-memory to bootstrap project-memory/, then add a concise ## Memory & Learning Loop section to AGENTS.md that layers these onto AEP's native lessons loop instead of duplicating it. AEP already captures (/aep-build → .dev-workflow/lessons.md), archives (/aep-wrap → lessons-learned/), and recalls (/aep-launch); the supplement adds: project-memory recall at /aep-dispatch + persisting the archived lesson at /aep-wrap (qmd semantic recall), and memory-forge distilling settled lessons (≥7 days, ≥3 accrued) into skills at /aep-reflect / pre-PR.
npx skills add memorysaver/skills@<latest-tag> -a claude-code \
--skill project-behavior --skill project-memory --skill memory-forge -y
Note: This installs the AEP skills themselves. Recommended third-party Claude Code plugins are configured at the project level in Phase 4 via .claude/settings.json; browser automation is added only after its local smoke test passes.
Phase 2 — Verify Required Tools
Each tool below earns its place in the agentic workflow — git provides version control and worktrees (one isolated working tree per parallel agent), bun runs the TypeScript monorepo, openspec powers spec-driven development, an executor (claude or codex) runs the implementation agents, and gh publishes PRs. tmux is optional: launches are native-first (see /aep-executor); tmux only hosts the pinned legacy mode and the generic-host fallback.
Run this check:
command -v claude >/dev/null 2>&1 || command -v codex >/dev/null 2>&1 \
&& echo "executor: OK" || echo "executor: MISSING (install claude or codex)"
for cmd in bun git gh openspec; do
printf "%-15s" "$cmd:"
which $cmd >/dev/null 2>&1 && echo "OK ($(which $cmd))" || echo "MISSING"
done
printf "%-15s" "tmux:"
which tmux >/dev/null 2>&1 && echo "OK ($(which tmux))" || echo "MISSING (optional — only the legacy launch mode needs it)"
Install any missing tools:
| Tool | Purpose | Install |
|---|
git | Version control + worktrees | xcode-select --install (macOS) |
bun | Package manager & runtime | curl -fsSL https://bun.sh/install | bash |
claude | Executor: Claude Code CLI | npm install -g @anthropic-ai/claude-code |
codex | Executor: OpenAI Codex CLI | npm install -g @openai/codex (alt to claude) |
gh | GitHub CLI for PRs | brew install gh |
openspec | Spec-driven development (Node >= 20.19) | npm install -g @fission-ai/openspec@latest |
tmux | Terminal multiplexer (optional — legacy mode) | brew install tmux |
All required tools (executor + bun/git/gh/openspec) must show OK
before proceeding. You need at least one executor (claude or codex) — not
both. tmux may be MISSING; that's fine — launches are native-first.
Native-first launches: the executor abstraction picks the host's native mode automatically (Claude Code background subagents/sessions, or Codex native subagents/exec workers) with live monitoring and steering, no tmux required — which is why tmux may show MISSING. See /aep-executor.
Note on parallelism: Each parallel feature agent runs in its own git worktree at .feature-workspaces/<name>/ on its own feat/<name> branch. Worktrees share the underlying .git/objects (no history duplication) but each adds one full working-tree copy on disk — budget accordingly when running many agents in parallel.
Phase 3 — Verify Optional Tools
for cmd in cmux agent-browser portless; do
printf "%-15s" "$cmd:"
which $cmd >/dev/null 2>&1 && echo "OK ($(which $cmd))" || echo "MISSING (optional)"
done
| Tool | Purpose | Install |
|---|
cmux | Clickable tab multiplexer for watching legacy-mode tmux sessions — optional; only used when tmux is pinned | bun add -g cmux |
agent-browser | Browser automation testing | Claude Code plugin: agent-browser@agent-browser |
portless | Port management (.localhost) | bun add -g portless |
cmux is a convenience, not a requirement. It only adds clickable tabs for
watching legacy-mode tmux sessions (when aep.executor-backend tmux is
pinned). Without it, pinned workspaces still run in tmux with the full
monitor + mid-flight-feedback loop — attach with tmux attach -t <name>.
Skills auto-detect cmux and never abort when it's absent. See /aep-executor.
These are optional — the workflow works without them but is enhanced by them. On macOS, do not enable agent-browser until a one-command smoke test can launch a page without crashing Chrome:
agent-browser navigate about:blank
If macOS shows a Google Chrome crash report with _RegisterApplication, TransformProcessType, or abort() called, leave agent-browser disabled and use non-browser checks (curl, unit tests, screenshots from the user, or the host agent's browser tool) until the local Chrome/agent-browser combination is healthy.
Phase 4 — Configure Project Plugins
Configure recommended plugins at the project level. These are not cosmetic — superpowers provides the planning/TDD skills that /aep-design assumes exist, mgrep powers deeper search, frontend-design is assumed by visual calibration work, code-review is used by /aep-build, and the hooks enforce the concurrency protocol that keeps parallel workspace agents from corrupting product-context.yaml. Plugin roles are summarized in references/plugins.md.
What to write
Read .claude/settings.json if it exists, then merge references/settings-template.json into it (create the file from the template if it's missing). The template carries three keys — extraKnownMarketplaces, enabledPlugins, and the two concurrency-protocol hooks.
Verify the two hooks landed:
jq '[.hooks.PreToolUse[].matcher]' .claude/settings.json
Concurrency protocol hooks: they block a workspace agent from editing, writing, or committing product-context.yaml and redirect it to signal files. This is defense-in-depth — the skill instructions also direct agents to use signals, but the hook catches model drift. Only the main session (/aep-wrap, /aep-dispatch, /aep-reflect) updates the YAML.
Optional browser automation
Add agent-browser only after the Phase 3 smoke test succeeds — it launches a local Chrome that some macOS/Chrome combinations crash during application registration. Merge this extra block into .claude/settings.json:
{
"extraKnownMarketplaces": {
"agent-browser": {
"source": { "source": "github", "repo": "vercel-labs/agent-browser" }
}
},
"enabledPlugins": {
"agent-browser@agent-browser": true
}
}
Merging rules
- Merge new entries into existing keys — preserve any other settings (
permissions, env, etc.); do not overwrite them.
- If
hooks.PreToolUse already exists, append these hook entries rather than replacing existing hooks.
- If the file doesn't exist, create it from the template (all three keys).
Phase 5 — Verify Environment
echo "=== Core Tools ==="
command -v claude >/dev/null 2>&1 || command -v codex >/dev/null 2>&1 \
&& echo "executor: OK" || echo "executor: MISSING (claude or codex)"
for cmd in bun git gh openspec; do
printf "%-15s" "$cmd:"
which $cmd >/dev/null 2>&1 && echo "OK" || echo "MISSING"
done
echo ""
echo "=== Optional Tools ==="
for cmd in tmux cmux agent-browser portless; do
printf "%-15s" "$cmd:"
which $cmd >/dev/null 2>&1 && echo "OK" || echo "MISSING (optional)"
done
echo ""
echo "=== Git Repo ==="
[ -d .git ] && echo "git repo: OK" || echo "Not a git repo — run: git init"
git worktree list 2>/dev/null | head -5
If all core tools show OK, the environment is ready.
Integration branch (single- vs two-branch mode)
AEP integrates all feature work into one integration branch ($BASE across the skills). Resolve $BASE per /aep-git-ref → "Integration Branch" (config override first, then auto-detect — the standard main/develop cases need no configuration) and report which mode this repo is in: develop → two-branch (main is promote-only production); otherwise single-branch on main.
For a non-standard integration branch name (not main/develop, e.g. staging or integration), set the repo-local override once — see the same /aep-git-ref section for the config command and why the standard cases stay unpinned (so a repo can grow from single- to two-branch mode with no reconfiguration).
Enable the native launch modes (recommended)
/aep-launch and /aep-autopilot pick the launch mode automatically — native first, tmux only when pinned. Claude Code needs no setup (background subagents by default, falling back to background sessions). To unlock the best Codex mode, commit the two AEP role files (aep-builder.toml, aep-evaluator.toml) into the project's .codex/agents/ — the TOML templates and the full launch-mode explainer live in /aep-executor (references/codex-native.md). Prefer the legacy tmux+cmux workflow instead? Pin it: git config aep.executor-backend tmux.
Next Steps — Pick Your Path
Your next move depends on your situation. Pick the path that matches what you're trying to do. Full context for each path (including why each step is in the order it's in) is in the installed orientation guide.
Path A — New product from scratch
You have an idea and a fresh repo.
/aep-envision → /aep-map → /aep-validate → /aep-scaffold → /aep-autopilot
/aep-envision validates the opportunity and extracts the activity backbone. /aep-map decomposes it into a system map + story graph + agent topology. /aep-validate runs gen/eval checks. /aep-scaffold creates the monorepo + OpenSpec. /aep-autopilot (optional) takes over hands-free — or drive it manually with /aep-dispatch → /aep-design → /aep-launch → /aep-build → /aep-wrap.
Path B — Onboarding an existing project
You have a codebase and want to add AEP workflows to it.
/aep-scaffold → /aep-dispatch → /aep-design → /aep-launch → /aep-build → /aep-wrap
/aep-scaffold adds agentic infrastructure (OpenSpec, workspace hooks, E2E skeleton) to existing code. Then start a feature cycle with /aep-dispatch. Use /aep-envision later if you want to retrofit a product context.
Path C — Single feature, no product context
You just want to ship one feature with AEP workflows.
/aep-design → /aep-launch → /aep-build → /aep-wrap
/aep-design produces an OpenSpec change on the integration branch ($BASE). /aep-launch spawns an isolated git worktree on a feat/<name> branch and boots the agent. /aep-build implements, tests, reviews, and merges. /aep-wrap archives and removes the worktree.
Path D — Hands-free autonomous mode
You have a validated product context and want to go grab coffee.
/aep-autopilot
One command. Pauses only for design escalations or layer gate failures. Run /aep-autopilot directly for its full tick and pause protocol.
Still unsure which path? Use the decision rule in the installed orientation guide.
Guardrails
- Run from the project root — tools and plugins are verified relative to the current environment.
- Re-run anytime — safe to re-run to verify the environment is still complete. Returning users can skip Phase 0 (orientation) and jump to Phase 1.
- Checks only — this skill verifies and installs tools; it does not scaffold projects or modify code.
Learn More
- Installed orientation guide — mental models, skill map, and the four entry paths; always available offline with this skill.
/aep-git-ref — worktree lifecycle, branch naming, commit-per-task pattern, $BASE resolution, and recovery./aep-autopilot — the autonomous tick, monitoring, escalation, and pause protocol.- Public AEP documentation — extended glossary, decisions, and architecture material when network access is available.
