aep-onboard

オンボーディング

エージェント型 TypeScript 開発の環境をセットアップし、AEP の考え方を理解しましょう。フェーズ 0 では考え方のガイドを紹介し、フェーズ 1〜5 では AEP をインストールしてツールを確認し、AEP のプロジェクト向けガードレールを設定します。初回セットアップ時に一度実行してください。環境を再確認するリピーターは、フェーズ 0 を省略してフェーズ 1 から開始できます。

---

フェーズ 0 — 全体像を把握する（初回のみ）

以前に利用したことがありますか？ /aep-onboard を実行したことがあり、環境を再確認するだけの場合は、フェーズ 1 に進んでください。

AEP はコマンドランナーではありません。AEP は、（AI とともに コントロールプレーン で決定する、何を作るかという）思考 と、（実行プレーン でエージェントが厳密な仕様に基づいて構築する）実行 を分離したワークフローです。共有コードコンテキストではなく、構造化されたアーティファクト（product-context.yaml、.dev-workflow/signals/ 内のシグナルファイル）のみを介して連携します。この考え方を理解せずにツールをインストールすると、どのスキルを最初に実行すればよいかわからず、空白のターミナルを前に途方に暮れることになります。

インストール済みのオリエンテーションガイド をお読みください。これは、初めての1時間を案内する、自己完結した10分間のツアーです。3つの考え方のモデル（コントロールプレーンと実行プレーン、Jeff Patton のストーリーマップ、2セッションのメイン／ワークスペースモデル）、各スキルの役割、4つの具体的な進め方（新規プロダクト／既存プロジェクト／単一機能／ハンズフリー）を説明しています。

完了条件： orientation.md を読み、「次のステップ — 進め方を選ぶ」（以下）にある4つの進め方のうち、自分の状況に合うものを挙げられること。その後、フェーズ 1 に進みます。

---

フェーズ 1 — プラグインをインストールする

skills CLI を使って、AEP v4.1.0 をプロジェクトレベルでインストールします。プロジェクトで使うエージェントごとに一度実行してください。バージョンをチーム内で固定できるよう、インストールしたファイルをコミットします。

# Run the command for each agent runtime this project uses.
npx -y [email protected] add memorysaver/[email protected] -a claude-code --skill '*' -y
npx -y [email protected] add memorysaver/[email protected] -a codex        --skill '*' -y

これにより、すべての AEP スキル（aep-* という名前）と skills-lock.json マニフェストがインストールされます。両方をコミットしてください。各エージェントランタイムには、それぞれ独自のコピーが作成されます。すでに共有シンボリックリンクの構成がある場合も、そのまま使用できます。コミットされたスキルの内容が、プロジェクトに永続的に固定されるバージョンです。意図的にアップグレードするには、希望するタグを指定して同じコマンドを再実行し、生成されたスキルとロックファイルの差分を確認してコミットします。

フェーズ 1 では AEP のみをインストールします。AEP のプロジェクト記録は自己完結しています。/aep-build は教訓を .dev-workflow/lessons.md に記録し、/aep-wrap はそれらを lessons-learned/ にアーカイブし、/aep-launch はそれらを呼び出します。利用可能な場合、ホストのメモリはこの記録を補強するものです。オプションのサードパーティー連携は references/plugins.md に記載されており、ユーザーが求めた場合にのみ追加します。

---

フェーズ 1.5 — エージェント指示ファイルを組み込む

指示ファイルは AEP とともにバージョン管理されています。このスキルには、templates/ 以下に 3 つのテンプレートが含まれています。AGENTS.md.tmpl（汎用的な作業上の取り決め、固定リリースと /aep-easy-explain レジスターを含む ## AEP Workflow セクション、および project-convention/ を参照する ## Project Context）、CLAUDE.md.tmpl（@AGENTS.md）、project-convention/README.md.tmpl（規約のインデックス：AEP でプロジェクトを運用する方法、docs/ の振り分け表、AEP が管理するディレクトリ、規約の追加方法）です。AGENTS.md の 1 行目はマーカー `` です。/aep-scaffold の監査でこれが読み取られ、references/migrations.md ではこれを基準にアップグレード手順が定められています。

• AGENTS.md がまだない場合： 3 つのテンプレートをそのまま配置し（リポジトリのルートに project-convention/README.md を配置）、インストールとともにコミットします。
• 既存の AGENTS.md がある場合： そのマーカーを読み取り、references/migrations.md のすべてのセクションを、マーカーが示すリリースから固定リリースまで順に適用します。プロジェクト固有の内容は project-convention/<topic>.md に移し、トピックごとにファイルを 1 つ作成して README からリンクします。プロジェクト固有の内容を AGENTS.md に残してはいけません。手書きの CLAUDE.md は、@AGENTS.md にする前に手作業で AGENTS.md に統合します。
• Codex 専用のリポジトリの場合： CLAUDE.md はスキップします。

確認： head -1 AGENTS.md で固定リリースのマーカーが表示されること。Claude Code がインストールされている場合は、head -1 CLAUDE.md で @AGENTS.md が表示されること。project-convention/README.md が存在すること。

---

フェーズ 2 — 必須ツールの確認

以下のツールはそれぞれ、エージェント型ワークフローで重要な役割を果たします。git はバージョン管理とワークツリー（並列実行する各エージェントに1つずつ、隔離された作業ツリー）を提供し、Node/npm は固定バージョンのインストーラーと OpenSpec を実行し、bun は TypeScript モノレポを実行し、openspec は仕様駆動開発を支え、エグゼキューター（claude または codex）は実装エージェントを実行し、gh は PR を公開します。Claude Code のプロジェクトでは、AEP の並行処理フック用に jq も必要です。tmux は任意です。起動はネイティブ方式を優先します（/aep-executor を参照）。tmux は固定バージョンのレガシーモードと汎用ホストのフォールバックでのみ使用されます。

次のチェックを実行します。

# Required: at least one executor (claude OR codex)
command -v claude >/dev/null 2>&1 || command -v codex >/dev/null 2>&1 \
  && echo "executor:      OK" || echo "executor:      MISSING (install claude or codex)"

# Required: everything else
for cmd in node npm bun git gh openspec; do
  printf "%-15s" "$cmd:"
  command -v "$cmd" >/dev/null 2>&1 && echo "OK ($(command -v "$cmd"))" || echo "MISSING"
done
node -e 'const [M,m]=process.versions.node.split(".").map(Number); process.exit(M>20||(M===20&&m>=19)?0:1)' \
  && echo "node version:   OK (>=20.19)" || echo "node version:   TOO OLD (need >=20.19)"

# Required only when Claude Code skills are installed: concurrency hooks parse tool input with jq
if [ -e .claude/skills/aep-onboard/SKILL.md ]; then
  printf "%-15s" "jq:"
  command -v jq >/dev/null 2>&1 && echo "OK ($(command -v jq))" || echo "MISSING (required for Claude hooks)"
fi

# Optional (legacy/pinned-tmux mode only): tmux
printf "%-15s" "tmux:"
command -v tmux >/dev/null 2>&1 && echo "OK ($(command -v tmux))" || echo "MISSING (optional — only the legacy launch mode needs it)"

不足しているツールをインストールします。

ツール	用途	インストール
node/npm	固定バージョンのスキルインストーラー + OpenSpec ランタイム	プラットフォームで推奨されるバージョン管理ツールで Node >= 20.19
git	バージョン管理 + ワークツリー	xcode-select --install（macOS）
bun	パッケージマネージャーおよびランタイム	curl -fsSL https://bun.sh/install | bash
claude	エグゼキューター：Claude Code CLI	npm install -g @anthropic-ai/claude-code
codex	エグゼキューター：OpenAI Codex CLI	npm install -g @openai/codex (claude の代替)
gh	PR 用 GitHub CLI	brew install gh
openspec	仕様駆動開発	npm install -g @fission-ai/openspec@latest
jq	Claude Code の並行処理フック用 JSON 解析	brew install jq / apt-get install jq (Claude のみ)
tmux	ターミナルマルチプレクサー（任意 — レガシーモード）	brew install tmux

必須ツール（Node >=20.19、npm、エグゼキューター、bun/git/gh/openspec、および Claude をインストールする場合は jq）がすべて OK と表示されてから、次に進んでください。必要なエグゼキューターは少なくとも1つ（claude または codex）です。両方は必要ありません。tmux は MISSING と表示されても問題ありません。起動はネイティブ方式を優先します。

並列実行について： 並列実行する各機能エージェントは、それぞれ独自の feat/<name> ブランチ上にある .feature-workspaces/<name>/ の独自の git worktree で実行されます。ワークツリーは共通の .git/objects を共有するため（履歴は重複しません）が、それぞれディスク上に作業ツリー全体のコピーを1つ追加します。多数のエージェントを並列実行する場合は、それに応じて容量を確保してください。

---

フェーズ 3 — オプションのツールを確認する

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

ツール	目的	インストール
cmux	レガシーモードの tmux セッションを監視するためのクリック可能なタブマルチプレクサー — 任意。tmux が固定されている場合のみ使用	bun add -g cmux
agent-browser	ブラウザー自動化テスト	Claude Code プラグイン：agent-browser@agent-browser
portless	ポート管理（.localhost）	bun add -g portless

cmux は利便性のためのツールです。 なくても、固定された tmux ワークスペースは モニターと実行中フィードバックのループ全体で動作します — tmux attach -t <name> で接続してください。 /aep-executor を参照してください。

これらは任意です — ワークフローはなくても動作しますが、あるとより便利です。macOS では、1 コマンドのスモークテストで Chrome をクラッシュさせずにページを起動できるようになったら、agent-browser を有効にしてください。

agent-browser navigate about:blank

macOS で _RegisterApplication、TransformProcessType、または abort() called を含む Google Chrome のクラッシュレポートが表示された場合は、agent-browser を無効のままにし、ローカルの Chrome／agent-browser の組み合わせが正常に動作するようになるまでは、ブラウザーを使わない確認方法（curl、ユニットテスト、ユーザーから提供されたスクリーンショット、またはホストエージェントのブラウザーツール）を使用してください。

---

フェーズ 4 — AEP プロジェクトのガードレールを設定する（Claude Code のみ）

このプロジェクトに .claude/skills/aep-* のインストールがない場合は、このフェーズをスキップしてください。Codex はインストール済みの AEP の指示とネイティブのエージェントロールを通じてワークフローを適用するため、.claude/settings.json は必要ありません。

Claude Code プロジェクトでは、AEP の 2 つの並行処理フックをインストールしてください。これらのフックにより、並列ワークスペースエージェントが product-context.yaml を破損するのを防ぎます。サードパーティ製のオプションのプラグインは基本オンボーディングの対象外です。AEP のコアワークフローとフォールバック手順は、それらがなくても動作します。

書き込む内容

.claude/settings.json が存在する場合は読み込み、references/settings-template.json の hooks.PreToolUse エントリーをマージしてください（ファイルがない場合はテンプレートから作成します）。既存の設定とフックはすべて保持してください。

確認：2 つのフックが追加されていることを確認してください。

jq '[.hooks.PreToolUse[].matcher]' .claude/settings.json
# expect an array containing both "Edit|Write" and "Bash"

並行処理プロトコルのフック： ワークスペースエージェントによる product-context.yaml の編集、書き込み、コミットをブロックし、シグナルファイルを使うように誘導します。これは多層防御です — スキルの指示でもエージェントにシグナルの使用を指示しますが、このフックはモデルの指示逸脱を検知します。YAML を更新するのはメインセッション（/aep-wrap、/aep-dispatch、/aep-reflect）のみです。

マージのルール

• 既存のキーに新しいエントリーをマージし、ほかの設定（permissions、env など）は保持してください。
• hooks.PreToolUse がすでに存在する場合は、既存のフックを置き換えず、これらのフックエントリーを追加してください。
• ファイルが存在しない場合は、フックのみのテンプレートから作成してください。

---

フェーズ 5 — 環境を確認する

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 node npm bun git gh openspec; do
  printf "%-15s" "$cmd:"
  command -v "$cmd" >/dev/null 2>&1 && echo "OK" || echo "MISSING"
done
node -e 'const [M,m]=process.versions.node.split(".").map(Number); process.exit(M>20||(M===20&&m>=19)?0:1)' \
  && echo "node version:   OK (>=20.19)" || echo "node version:   TOO OLD (need >=20.19)"
if [ -e .claude/skills/aep-onboard/SKILL.md ]; then
  printf "%-15s" "jq:"
  command -v jq >/dev/null 2>&1 && echo "OK" || echo "MISSING (required for Claude hooks)"
fi
echo ""
echo "=== Optional Tools ==="
for cmd in tmux cmux agent-browser portless; do
  printf "%-15s" "$cmd:"
  command -v "$cmd" >/dev/null 2>&1 && echo "OK" || echo "MISSING (optional)"
done
echo ""
echo "=== Git Repo ==="
git rev-parse --is-inside-work-tree >/dev/null 2>&1 && echo "git repo: OK" || echo "Not a git repo — run: git init"
git worktree list 2>/dev/null | head -5

すべてのコアツールが OK と表示されれば、環境の準備は完了です。

統合ブランチ（単一ブランチモードと2ブランチモード）

AEP は、すべての機能開発を1つの統合ブランチ（各スキルでの $BASE）に統合します。/aep-git-ref →「統合ブランチ」に従って $BASE を解決し（まず設定による上書きを確認し、次に自動検出します。標準的な main／develop のケースでは設定不要です）、このリポジトリがどちらのモードかを報告してください。develop の場合は2ブランチモード（main は本番環境への昇格専用）で、それ以外は main を使う単一ブランチモードです。

標準以外の統合ブランチ名（main／develop 以外。例：staging や integration）を使う場合は、リポジトリローカルの上書き設定を一度だけ行ってください。設定コマンドと、標準ケースでは設定を固定しない理由（再設定なしでリポジトリを単一ブランチモードから2ブランチモードに移行できるようにするため）については、同じ /aep-git-ref のセクションを参照してください。

ネイティブの起動モードを有効にする（推奨）

/aep-launch と /aep-autopilot は起動モードを自動で選択します。まずネイティブモードを使い、tmux が固定指定されている場合にのみ tmux を使います。Claude Code にはセットアップ不要です（デフォルトでバックグラウンドサブエージェントを使い、利用できない場合はバックグラウンドセッションにフォールバックします）。Codex で最適なモードを利用するには、2つの AEP ロールファイル（aep-builder.toml、aep-evaluator.toml）をプロジェクトの .codex/agents/ にコミットしてください。TOML テンプレートと起動モードの詳しい説明は /aep-executor（references/codex-native.md）にあります。従来の tmux+cmux ワークフローを使いたい場合は、次のように固定してください：git config aep.executor-backend tmux。

---

次のステップ — 進め方を選ぶ

次に行うことは状況によって異なります。目的に合った進め方を選んでください。各進め方の詳しい背景（各ステップがその順序になっている理由を含む）は、インストール済みのオリエンテーションガイドにあります。

パス A — 新しいプロダクトをゼロから作る

アイデアがあり、新しいリポジトリを用意しています。

/aep-envision  →  /aep-map  →  /aep-validate  →  /aep-scaffold  →  /aep-autopilot

/aep-autopilot は任意です。同じループを /aep-dispatch → /aep-design → /aep-launch → /aep-build → /aep-wrap で手動実行することもできます。

パス B — 既存プロジェクトへの導入

コードベースがあり、AEP ワークフローを追加したいと考えています。

/aep-scaffold  →  /aep-dispatch  →  /aep-design  →  /aep-launch  →  /aep-build  →  /aep-wrap

/aep-scaffold は既存のコードにエージェント基盤（OpenSpec、ワークスペースフック、E2E の骨組み）を追加します。/aep-envision を使うと、後からプロダクトのコンテキストを追加できます。

パス C — プロダクトのコンテキストなしで、単一の機能を開発する

AEP ワークフローを使って、1つの機能だけをリリースしたい場合です。

/aep-design  →  /aep-launch  →  /aep-build  →  /aep-wrap

/aep-design は統合ブランチ（$BASE）に OpenSpec の変更を作成します。残りの作業は feat/<name> の分離されたワークツリーで実行され、/aep-wrap がそれをアーカイブして削除します。

パス D — 人手を介さない自律モード

プロダクトのコンテキストが検証済みで、コーヒーを飲みに行きたい場合です。

/aep-autopilot

コマンドは1つだけです。設計に関するエスカレーション、またはレイヤーゲートの失敗があった場合にのみ一時停止します。ティックと一時停止のプロトコル全体については、/aep-autopilot を直接実行してください。

どの進め方を選ぶか迷っていますか？ インストール済みのオリエンテーションガイドにある判断基準を使ってください。

---

ガードレール

• プロジェクトのルートから実行してください — ツールとプラグインは、現在の環境を基準に検証されます。
• いつでも再実行できます — 環境が引き続き完全であることを確認するため、安全に再実行できます。以前から利用しているユーザーはフェーズ 0（オリエンテーション）を省略し、フェーズ 1 から始められます。
• 確認のみです — このスキルはツールを検証してインストールします。プロジェクトの骨組みを作成したり、コードを変更したりはしません。

---

詳細情報

• インストール済みのオリエンテーションガイド — メンタルモデル、スキルマップ、4つの開始パスを掲載しています。このスキルがあれば、常にオフラインで利用できます。
• /aep-git-ref — ワークツリーのライフサイクル、ブランチの命名、タスクごとのコミットパターン、$BASE の解決、復旧について説明します。
• /aep-autopilot — 自律ティック、監視、エスカレーション、一時停止のプロトコルについて説明します。
• AEP の公開ドキュメント — ネットワークに接続できる場合に参照できる、用語集、判断事項、アーキテクチャ資料です。