| name | aep-onboard |
| description | Full environment onboarding and first-hour orientation for Agentic Engineering Patterns (AEP). Use when setting up a new machine, joining the project, installing the plugin, or when the user says "get started", "onboard", "setup environment", "install prerequisites", "what is this plugin", "help me understand AEP", "I'm new to agentic engineering", "introduce me to this workflow", or wants to prepare their dev environment AND learn the mental model. Always use this first when a user mentions AEP, agentic-engineering-patterns, or this plugin for the first time. |
Onboard
Set up your environment for agentic TypeScript development AND get oriented to how AEP thinks. Phase 0 gives you the 5-minute mental model; Phases 1–5 install the plugin, verify tools, and configure recommended plugins. Run once on first setup — returning users running for environment verification can skip Phase 0 and jump straight to Phase 1.
Phase 0 — Orient Yourself (5 minutes, first-timers only)
Returning user? If you've run /aep-onboard before and you're just re-verifying your environment, skip to Phase 1.
Before installing tools, get the mental model. AEP is not a "command runner" — it's a workflow that separates thinking (what to build) from doing (building it). Installing the tools without understanding this will leave you staring at a blank terminal wondering which of 17 skills to run first.
The three mental models you need:
-
Control plane vs execution plane. You + AI make high-leverage decisions on the control plane (goals, decomposition, architecture, priorities). Agents receive precise specs and build on the execution plane. They never share code context directly — only structured artifacts like product-context.yaml and signal files. See README.md "The Mental Model".
-
The story map. Your product is organized as a Jeff Patton story map — a grid with activities (columns, user journey left→right), layers (rows, enrichment top→down), waves (parallel batches within a layer), and release lines (what's shippable). Layer 0 is the walking skeleton — the thinnest end-to-end path. See README.md "The Story Map".
-
Two-session model. The main session runs on your integration branch (main in single-branch mode, or develop in two-branch mode — see Phase 5) where you + AI plan (/aep-envision, /aep-map, /aep-dispatch, /aep-design, /aep-wrap, /aep-reflect). The workspace session runs autonomously in an isolated git worktree on a feat/<name> branch where one agent implements a feature (/aep-build). They communicate only through signal files in .dev-workflow/signals/. See skills/product-context/README.md.
v2 split-mode (good to know): Some projects store product context in two files — product/index.yaml (stable intent: opportunity, personas, capabilities, constraints) + product-context.yaml (mutable state: architecture, stories, cost, changelog). All skills auto-detect which mode a project uses. If you see only product-context.yaml, that's v1 single-file mode and it works exactly the same way. See docs/aep-v2-improvement-guideline.md.
Next step: for the full 10-minute first-hour guide — including a table of all 17 skills, four concrete paths (new product / existing project / single feature / hands-free), and a glossary shortlist — read docs/orientation.md. Then come back 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. For the full pinning + formatter guidance, see Installing Skills.
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 (Claude Code native background subagents / background sessions, Codex subagents — 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 (native-bg-subagent) or
background sessions (claude-bg); Codex native subagents (codex-subagent) or
exec workers (codex-exec). All include live monitoring and steering without
tmux. See aep-executor and the "Enable the native launch modes" step in
Phase 5.
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 plugins are not optional cosmetics — 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.
What to write
Read .claude/settings.json if it exists. Merge the following keys into it (or create the file if missing):
{
"extraKnownMarketplaces": {
"claude-plugins-official": {
"source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
},
"superpowers-marketplace": {
"source": { "source": "github", "repo": "obra/superpowers-marketplace" }
},
"Mixedbread-Grep": {
"source": { "source": "github", "repo": "mixedbread-ai/mgrep" }
}
},
"enabledPlugins": {
"superpowers@superpowers-marketplace": true,
"frontend-design@claude-plugins-official": true,
"code-review@claude-plugins-official": true,
"mgrep@Mixedbread-Grep": true,
"skill-creator@claude-plugins-official": true
},
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path // \"\"' | { read -r f; case \"$f\" in *product-context.yaml) if [[ \"$PWD\" == */.feature-workspaces/* ]]; then echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"CONCURRENCY PROTOCOL: Workspace sessions must not write to product-context.yaml. Write to .dev-workflow/signals/status.json instead. Only the main session (via /aep-wrap, /aep-dispatch, /aep-reflect) updates the YAML.\"}}'; fi ;; esac; }",
"statusMessage": "Checking concurrency protocol..."
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command // \"\"' | { read -r cmd; if [[ \"$PWD\" == */.feature-workspaces/* ]] && echo \"$cmd\" | grep -qE 'git\\s+(add|commit).*product-context\\.yaml'; then echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"CONCURRENCY PROTOCOL: Workspace sessions must not commit product-context.yaml. Write to .dev-workflow/signals/status.json instead.\"}}'; fi; }",
"statusMessage": "Checking concurrency protocol..."
}
]
}
]
}
}
Concurrency protocol hooks: The hooks section enforces the rule that only the main session writes to product-context.yaml. When a workspace agent attempts to edit, write, or commit product-context.yaml, the hook blocks the action and explains how to use signals instead. This is defense-in-depth — the skill instructions also direct agents to use signals, but the hook catches any model drift.
Optional browser automation
Only add agent-browser after the Phase 3 smoke test succeeds. It launches a local Chrome process, and some macOS/Chrome combinations crash during application registration before the test can run.
{
"extraKnownMarketplaces": {
"agent-browser": {
"source": { "source": "github", "repo": "vercel-labs/agent-browser" }
}
},
"enabledPlugins": {
"agent-browser@agent-browser": true
}
}
Plugin reference
| Plugin | Marketplace | Purpose |
|---|
superpowers | superpowers-marketplace | Planning, debugging, TDD, code review workflows |
agent-browser | agent-browser | Optional browser automation for testing |
frontend-design | claude-plugins-official | High-quality UI generation |
code-review | claude-plugins-official | PR code review |
mgrep | Mixedbread-Grep | Semantic search (local + web) |
skill-creator | claude-plugins-official | Create and test new skills |
Merging rules
- If
.claude/settings.json already has these keys, merge new entries — do not overwrite other keys
- Preserve any existing settings (permissions, env, etc.)
- If
.claude/settings.json already has a hooks.PreToolUse array, append these hook entries — do not replace existing hooks
- If the file doesn't exist, create it with all three keys (
extraKnownMarketplaces, enabledPlugins, hooks)
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). The standard cases are auto-detected — you do not configure anything. Report which mode this repo is in:
if git show-ref --verify --quiet refs/heads/develop \
|| git show-ref --verify --quiet refs/remotes/origin/develop; then
echo "Integration branch: develop (two-branch mode — main is promote-only production)"
else
echo "Integration branch: main (single-branch mode)"
fi
- single-branch mode (no
develop): AEP integrates into main. The default; matches a brand-new repo — don't create develop just for AEP.
- two-branch mode (
develop exists): AEP integrates into develop (staging); production main is promote-only and AEP never touches it. Promotion develop → main is your CI/CD or PR step — exactly like deployment, which AEP leaves to you.
- No pinning, no reconfiguration. Because the standard cases are auto-detected, a project grows from single- to two-branch mode simply by creating
develop — every skill picks it up automatically on the next run. Do not run git config aep.integration-branch main; pinning the default would suppress that upgrade.
- Non-standard name only: if your integration branch is neither
main nor develop (e.g. staging, integration), set the override once: git config aep.integration-branch <name>. It lives in .git/config, shared across all worktrees. See git-ref → "Integration Branch".
Enable the native launch modes (recommended)
/aep-launch and /aep-autopilot pick the launch mode automatically (see
aep-executor): native first, tmux only when pinned. The native modes need no
flag; one one-time setup step unlocks the best Codex mode:
Claude Code — background subagents (native-bg-subagent mode). This is the
Claude Code default — the Agent tool with run_in_background: true, no
team_name, spawned with no active team. No flag or settings change is
required (agent teams has been removed). If the host can't run a background
subagent, launches fall back to claude-bg (native background sessions, GA) —
fully functional, with pull-based steering.
Codex — custom agent roles (codex-subagent mode). Commit the two AEP
role files into the project's .codex/agents/ so both the desktop app and the
CLI discover them (the TOML contents are in
aep-executor/references/codex-native.md):
mkdir -p .codex/agents
git add .codex/agents && git commit -m "chore: add AEP codex agent roles"
Prefer the old tmux+cmux workflow? 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 docs/orientation.md section 4, "The Four Paths".
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. Deep dive: docs/workflow/autonomous-loop.md.
Still unsure which path? See the decision tree in docs/skills-quick-reference.md.
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 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
Pointers for going deeper. None of these are required reading — check what's relevant when you need it.
Mental models & concepts
Skills decision guide
Autonomous mode
v2 upgrades
Git + worktree conventions
