🧠 myAI — your AI's memory, and you own it

A self-owned, git-versioned AI memory + multi-agent framework. Plug any agent into your OWN portable brain so it boots already knowing your projects, decisions, and context.

myAI (npm i -g ai-management, CLI: myai) is a self-owned, git-versioned AI memory layer and a multi-agent development framework in one package. Plug any agent — Claude Code, Cursor, Gemini, Codex, opencode — into your own portable brain so it boots already knowing your projects, your decisions, and where you left off, instead of starting from a blank slate every session. It is local-first (runs in Docker on your machine), MCP-native (Model Context Protocol tools any agent can call), and ships an autonomous runner, RAG semantic search, a live operations dashboard, and one-command app blueprints. No SaaS account. No vendor lock-in. Your memory lives in a private git repo that you push, clone, and back up like any other.

🤔 Why myAI

Every AI coding session, your agent learns things — decisions made, gotchas hit, what shipped, what's next. Then the chat closes and it all dies. Worse:

• Agent context dies each session. Tomorrow's session starts from zero and you re-explain everything.
• Memory is locked in a vendor's cloud. Switch tools or lose your subscription and your context evaporates.
• Every new agent starts blank. Claude doesn't know what Cursor learned; Gemini doesn't know what Codex decided.

myAI is the answer. One portable brain that you own, served to every agent through a small local gateway. Sessions become git commits, wrap up is a merge, main is the single truth every agent boots from. A returning agent gets a ~300-token catch-up diff instead of re-reading everything. Bring your own credentials, run it all on your own machine, and take your context anywhere. Honest positioning: most "memory" tools are complementary — run myAI next to whichever you already use (see the comparison hub).

✨ Feature highlights

| | Pillar | What it gives you | |---|--------|-------------------| | 🧠 | The Brain | Git-versioned agent memory you own — sessions = commits, wrap up = merge | | 🔌 | Plug any agent | One command wires Claude / Cursor / Windsurf / Codex / Gemini / opencode into your context | | 💻 | The myai CLI | One binary wrapping install → run → scan → scaffold → brain → backup | | 📊 | Dashboard | A live Next.js ops console at localhost:3210 — agents, tasks, plans, memory | | 📱 | Remote management | Drive any repo from your phone; hand off seamlessly to desktop | | 🤖 | Autonomous Runner | Off-hours worker drains a task queue on test and surfaces work for review | | 🔌 | MCP servers | Model Context Protocol tools: library docs, browser, containers, your API | | 🔎 | RAG & memory search | Semantic search across everything you've done — local vectors, your data | | 🤝 | Multi-agent handoff | Hand off between agents/devices; the file system is the shared memory | | 🐳 | Local Docker stack | Gateway + dashboard + Mongo, memory-capped, single-tenant loopback | | 🚀 | Quick-to-production | make prod provisions branching + CI + Vercel/Render/Atlas | | ⭐ | Blueprint | Describe an app in one sentence → full-stack scaffold | | 💡 | Jam | Collaborative ideation mode — brainstorm before you build | | 🏗️ | Architecture | Parallel dispatch lanes, file ownership, state coordination | | 📚 | Skills | Repeatable playbooks that auto-trigger on your prompt | | 🎭 | Agents | Specialist subagents (frontend, API, DB, DevOps, security, QA…) | | 🪝 | Hooks | Session Usage Guard + lifecycle hooks — never lose context again | | 🔑 | Keywords | Type agent mode, ship it, wrap up, yolo god — full workflows |

📑 Table of contents

• Quickstart (5 minutes)
• Add myAI to any repo — one command
• Pillars
  • 🧠 The Brain
  • 🔌 Plug any agent
  • 💻 The myai CLI
  • 📊 Dashboard
  • 📱 Remote management
  • 🤖 Autonomous Runner
  • 🔌 MCP servers
  • 🔎 RAG & memory search
  • 🤝 Multi-agent handoff
  • 🐳 Local Docker stack
  • 🚀 Quick-to-production (make prod)
  • ⭐ Blueprint (idea → app)
  • 💡 Jam (ideation)
  • 🏗️ Architecture
  • 📚 Skills
  • 🎭 The specialist agents
  • 🪝 Hooks & the Usage Guard
  • 🔑 Keywords
• 🔬 Under the hood (deep dive)
• 🛠️ For framework operators / self-hosters
• 📚 Docs, comparisons & hands-on guides
• 🔗 Connect Hub
• 🔧 Maintenance & contributing

⚡ Quickstart — download → running in 5 minutes

Self-hosted, single operator, your own Anthropic key. No SaaS account, no lock-in. Prerequisites: Docker Desktop (running), Node 20+, git. Optionally the Claude CLI logged in (claude) instead of an API key.

# 0. npm preflight — a root-owned npm prefix (Homebrew/OS-bundled Node) fails
#    the next line with a raw EACCES. Check + redirect to ~/.local if needed:
p="$(npm config get prefix)"; [ -w "$p" ] || { npm config set prefix "$HOME/.local"; export PATH="$HOME/.local/bin:$PATH"; }

# 1. Install the CLI (one binary: `myai`, aliased `ai-manage`)
npm i -g ai-management

# 2. Preflight — checks docker, node, compose, ports, your key
myai doctor

# 3. Initialize the framework into a repo (this one, or any path)
#    The guided wizard asks 3 things: API key · profile · scan dir.
#    It writes them to AI/.env. Press Enter to skip any answer.
myai init .

# 4. Bring the self-contained stack up (gateway + dashboard + mongo)
#    Waits for health, then prints the dashboard URL.
myai up
#    → Dashboard   http://localhost:3210
#    → Gateway MCP http://localhost:3100/mcp

# 5. Register the repos you want to manage (RAG + directory)
myai scan ~/code --register

# 6. (optional) Generate a brand-new full-stack app from one sentence
myai new-app ~/code/my-idea

Open http://localhost:3210/welcome — with MYAI_EDITION=independent (the wizard's default profile) the page greets you with the local quickstart and one-tap links into the running dashboard. Queue a task from Work → Queue; the off-hours runner builds it and surfaces it in Needs Review for your ship it.

Bring-your-own credentials. Set ANTHROPIC_API_KEY during myai init (or any time in AI/.env), or skip it and let the runner use your logged-in Claude CLI. No keys ship in the package. Re-run myai init . --no-wizard for a non-interactive scaffold (CI/scripts).

Tear down / scripted runs: myai down (add --volumes to drop the mongo data). myai init <path> --wizard forces the wizard even when piped.

🌱 Add myAI to any repo — one command (greenfield)

The end-user path. No AI/ folder, no boilerplate — the package is the framework.

# 0. npm preflight — check + redirect to ~/.local if the prefix isn't writable
p="$(npm config get prefix)"; [ -w "$p" ] || { npm config set prefix "$HOME/.local"; export PATH="$HOME/.local/bin:$PATH"; }

# 1. Install the framework as a global module (once per machine)
npm i -g ai-management

# 2. Initialize any git repo — this is all it takes
cd /path/to/your/repo
myai init

Greenfield myai init (the default for any end-user repo) drops exactly two artifacts and nothing else:

• CLAUDE.md — a ~30-line kernel (committed). Points identity at your brain, points the framework at the installed module (myai root), lists the boot protocol. No policy bodies, no secrets — the only committed framework file.
• .myai-local — a gitignored per-repo pointer (namespace id, gateway hint, cached identity blurb for degraded boot). The .gitignore rule is appended automatically; the pointer is never committed.

Agents, skills, hooks, rule bodies, and the PreToolUse safety rails (no push to main, no secret commits, Docker-only npm) all resolve at runtime from the installed module — a kernel-only repo behaves identically to a scaffolded one. First-ever myai init also bootstraps your brain (~/.myai/brain, one per user) and can wire a private remote so later machines auto-clone it.

Then open the repo in your agent and type agent mode — it boots from the brain via context_boot. Re-running myai init is always a safe no-op (never clobbers a user-edited CLAUDE.md).

Verify a kernel-only repo is healthy:

myai root/scripts/lint_myai_init.sh /path/to/your/repo   # exit 0 = GREEN
./scripts/health_check.sh /path/to/your/repo             # kernel-only repo → all checks pass

Migrating an already-scaffolded repo (one with a committed AI/ folder)? That is a different, reversible track — see documentation/MYAI_MIGRATION_GUIDE.md. Use myai init --managed to force the legacy AI/-scaffold for operator/fleet repos.

🧠 The Brain — own your AI's memory

This is the heart of myAI: git-versioned agent memory that you own.

Every session your agent learns things — decisions made, gotchas hit, what shipped, what's next. Normally that dies when the chat closes. The Brain keeps it — in a private git repo you own.

• Sessions are commits. wrap up is a merge. main is the single truth every agent boots from. A returning agent gets a ~300-token brain_delta catch-up diff instead of re-reading everything.
• It lives at ~/.myai/brain, separate from your code, one per person. Push it to a private remote, clone it on any machine, myai backup / myai restore it. No SaaS lock-in.
• Reading needs no server. merge auto-distills each namespace's boot artifacts as plain files — brief.md (~150-token boot brief), working.md (~2k working context), rollup.md (one line per atom). git pull → read files works offline.
• Conflict-free by design. Memory is append-only "atoms" — one immutable file each, filenames embed a content hash — so parallel agents on different devices merge without conflict. Re-writing an identical atom is a no-op (dedup by hash); changed content is a NEW atom; history is never edited.
• Stash crosses devices. myai brain stash freezes in-flight context straight to main (not a local ref like git stash), so ANY later session on ANY device can pop it after a plain pull.

Why it matters

Your context is the most valuable thing you build with an AI — and today it's trapped in someone else's cloud, gone the moment a chat closes or a subscription lapses. The Brain makes it a portable, versioned asset you carry between machines, tools, and even AI vendors. Switch from Claude to Cursor to Gemini and they all boot from the same memory.

How to use it

The brain is a real private git repo, driven by myai brain <verb>:

init | status | write | stash | pop | branch | checkout | merge |
log | diff | blame | revert | session start/merge | distill

stash freezes context on main so any later session on any device can pop it; merge auto-distills the ~150-token boot briefs as plain files. Add --remote git@yourhost:you/brain.git on init to sync it between machines — it's just git.

Prove it in 5 minutes — no Docker, no gateway, no API key required. The scripted walkthrough (init → work → stash → pop from a second agent → merge → diff, against a throwaway brain that never touches your real one) ships in the npm package: TRY_BRAIN.md.

Keyword muscle memory over the gateway's brain_* MCP tools: brain status, brain commit, brain stash / brain pop, brain branch / brain checkout, brain merge (what wrap up calls), brain log, brain diff, brain delta (what agent mode -min boots with), brain blame, brain revert.

🔌 Plug any agent into your context

myai runs a small LOCAL gateway that exposes your brain, memory, tasks, and repos as tools any agent can call. On its first handshake the agent calls context_boot and answers "who am I working with?" from YOUR context — not a blank slate.

One command wires it up:

myai plug            # lists every supported agent + its one-liner
myai plug claude     # (or cursor / windsurf / codex / gemini / opencode)
myai plug proof      # live continuity round-trip with NO agent installed

Two tiers, so any agent connects:

• Cooperating (MCP) tier — claude | cursor | windsurf | codex | gemini | opencode. These auto-boot on the initialize handshake + a context_boot recall round-trip, pointed at the local gateway with the local token. Merge, never clobber; idempotent.
• Wrap-it tier — ollama | chatgpt | print. A context bundle is prepended for a blank agent that can't speak MCP.

Why it matters

Plugging an agent in means it opens already knowing you. Semantic search across everything you've done (memory_search / recall_session) surfaces the right past decision on demand — local vectors, your data. And reading needs no cloud: briefs distill to plain files, so git pull → read works offline. Your context becomes a shared substrate that every tool in your kit draws from.

Non-Claude proof

Real, verified connect configs live in examples/agents/ — a Gemini CLI + opencode connect config and a raw Ollama shim (context_boot → system preamble), verified live against the gateway. Under the hood, myai plug routes to myai connect-agent (MCP tier) or myai shim (wrap-it tier).

💻 The myai CLI

The framework ships an npm CLI — ai-management — that wraps the most-used operations behind a single binary (myai, aliased ai-manage). It is a thin dispatcher: each subcommand shells into the existing scripts/*.sh (or docker compose), so the bash playbooks remain the single source of truth.

myai --help          # list all commands
myai doctor          # preflight checks (node, docker, compose, scripts, git)
                     #   --json → {checks:[{label,status,detail}],ok} for CI/scripts
myai init <path>     # initialize the framework into a project   → scripts/myai_init.sh
                     #   DEFAULT = greenfield: drops only a ~30-line kernel CLAUDE.md
                     #   + gitignored .myai-local (no AI/ folder — framework resolves
                     #   from the installed module). --managed forces the legacy AI/
                     #   scaffold (operator/fleet repos; master auto-detected).
                     #   --greenfield to force greenfield. --force overwrites a
                     #   user-edited (non-kernel) CLAUDE.md. Guided first-run wizard on
                     #   a TTY; --no-wizard to skip, --wizard to force.
myai root            # print the installed module path            → scripts/myai_root.sh
                     #   ≈ $(npm root -g)/ai-management. Kernel-only repos
                     #   resolve agents/skills/hooks/rules from here.
myai up              # self-contained stack live on localhost     → scripts/myai_up.sh
                     #   gateway + dashboard + mongo, single-tenant loopback (no auth
                     #   friction), waits for health, prints the dashboard URL.
                     #   Flags: --build, --full, --runner, --no-wait, --timeout <s>
myai down            # stop the stack cleanly (--volumes drops data) → scripts/myai_down.sh
myai status          # inspect the running stack                  → scripts/myai_status.sh
                     #   gateway/dashboard /health, docker compose ps, task-queue counts
                     #   (pending/working/review/blocked/done via the local-token gateway).
                     #   Flags: --json (machine-readable), --repo <name>. Exit 0 = healthy,
                     #   so it doubles as a poll target for scripts.
myai logs [service]  # tail stack logs (docker compose logs -f)   → scripts/myai_logs.sh
                     #   all services or one of gateway | dashboard | mongo.
                     #   Flags: --no-follow (print + exit), --tail <n> (default 100)
myai queue [verb]    # inspect/control the runner task queue       → scripts/myai_queue.sh
                     #   CLI mirror of the dashboard /work orchestration view.
                     #   `queue` / `queue list` [--repo][--status][--priority][--all][--json]
                     #   (done hidden by default); `queue cancel <taskId>` [--reason][--force]
                     #   marks it blocked (reversible — requeue via tasks_update
                     #   {status:pending}); `queue reprioritize <taskId> <P0|P1|P2|P3>`.
myai scan <path>     # spider git repos → register + seed awareness → scripts/myai_scan.sh
                     #   walks <path>, finds every git repo (skips node_modules/vendored),
                     #   upserts each into the gateway app-directory (repos_card) + seeds RAG
                     #   awareness (memory_store), prints a summary table. Idempotent.
                     #   Flags: --register (add to managed_repos.txt), --max-depth <n>,
                     #          --no-rag, --no-cards, --dry-run, --json
myai demo            # seed realistic sample data                 → scripts/myai_demo.sh
                     #   6 tasks (all statuses) · 2 disabled schedules · a 5-day plan ·
                     #   3 repo cards · 3 memory vectors · 8 budget rows — so the
                     #   first-run dashboard is alive, not a wall of empty panels.
                     #   Idempotent; every row is demo-tagged and fully removable.
                     #   Flags: --clean (remove all demo rows), --force (re-seed)
myai new-app <path>  # scaffold a full-stack blueprint app        → scripts/myai_new_app.sh
                     #   → scripts/init_blueprint.sh (offline, unchanged)
myai new-app "<idea>" # headless idea→app via agentFlow, then self-registers the
                     #   produced repo (repos_upsert) — any whitespace in the
                     #   argument (or --idea "<text>") switches to this mode;
                     #   flags: --name, --group, --no-trigger, --timeout, --json
myai connect <path>  # install the Connect Hub module             → scripts/init_connect.sh
myai plug [agent]    # plug ANY agent into your brain — ONE front door → scripts/myai_plug.sh
                     #   `myai plug` lists every agent + its one-liner; `myai plug <agent>`
                     #   routes to the right tier and forwards extra flags; `myai plug proof`
                     #   runs the live continuity round-trip with NO agent installed.
                     #   Cooperating (MCP) tier: claude|cursor|windsurf|codex|gemini|opencode
                     #   — auto-boot on the `initialize` handshake + `context_boot` recall.
                     #   Wrap-it tier: ollama|chatgpt|print — bundle prepended for a blank
                     #   agent. Under the hood → myai connect-agent / myai shim (below).
myai connect-agent   # cooperating (MCP) tier of `myai plug`        → scripts/myai_connect_agent.sh
                     #   prints/installs MCP config for Claude Code (./.mcp.json), Cursor,
                     #   Windsurf, Codex CLI — pointed at the local gateway with the local
                     #   token — then verifies the hookup live: `initialize` (betaC
                     #   auto-boot rides in on instructions) + a `context_boot` round-trip
                     #   ("who am I working with?" → operator context). Merge, never
                     #   clobber; idempotent. Args: claude|cursor|windsurf|codex|all.
                     #   Flags: --install (write config), --verify (check only), --no-verify
                     #   Non-Claude proof: examples/agents/ — Gemini CLI + opencode
                     #   connect configs and a raw Ollama shim (context_boot → system
                     #   preamble), verified live against the gateway.
myai schedule ...    # queue an autonomous task for the runner    → scripts/schedule_task.sh
myai login           # authenticate against a HOSTED gateway      → scripts/myai_login.sh
                     #   validates a per-tenant API key (myai_live_… / myai_test_…) via
                     #   GET /api/auth/whoami before persisting anything — non-secret
                     #   identity (gatewayUrl/tenantId/org/plan) goes to ~/.myai/config,
                     #   the raw key to ~/.myai/credentials (chmod 600). Distinct from
                     #   `myai config` (raw key setting, no validation) and tenant-key
                     #   rotation (operator CRUD). Flags: --key <apiKey> (or $MYAI_API_KEY,
                     #   or an interactive hidden prompt), --gateway-url <url>, --json.
myai whoami          # show the active org/tenant/plan/quota       → scripts/myai_whoami.sh
                     #   round-trips to the gateway every time (never trusts cached
                     #   identity) so quota numbers are live. Requires `myai login` first.
                     #   Flags: --gateway-url <url>, --json.
myai runner <verb>   # manage the local off-hours runner schedule → scripts/myai_runner.sh
                     #   install [--every-minutes N|--every-hours N] | uninstall | start |
                     #   stop | status (+ next-fire) | logs [-f] [-n N] — launchd (mac) /
                     #   systemd or cron (linux). Distinct from `myai status`/`myai logs`
                     #   (gateway health) — this controls the local worker.
myai brain <verb>    # git-versioned agent memory                 → scripts/myai_brain.sh
                     #   the brain is a real private git repo SEPARATE from code git:
                     #   sessions = commits, wrap up = merge, `main` = the truth every
                     #   agent boots from. Verbs: init | status | write | stash | pop |
                     #   branch | checkout | merge | log | diff | blame | revert |
                     #   session start/merge | distill. `stash` freezes context on main
                     #   so ANY later session on ANY device can `pop` it; `merge`
                     #   auto-distills ~150-token boot briefs as plain files (reading
                     #   needs no server — git pull → read files). 5-minute scripted
                     #   walkthrough: TRY_BRAIN.md (ships in the npm package).
myai memory ...      # portable memory bundle                     → scripts/myai_memory.sh
                     #   export [dir] pulls the corpus (state/handoff/pattern source
                     #   texts) as JSON manifest + markdown; import <dir> re-embeds on
                     #   this gateway with dedup-by-hash.
myai context ...     # FULL portable context bundle                → scripts/myai_context.sh
                     #   export [dir] tars memory corpus + vectors (embeddings) + brain
                     #   atoms + ~/.myai config into ONE versioned, checksummed,
                     #   secret-redacted myai-context-<host>-<ts>.tar.gz; import <arc>
                     #   verifies integrity (CHECKSUMS.sha256) then re-imports — memory
                     #   always (idempotent), brain/config opt-in. import-external <src>
                     #   ingests FROM ChatGPT/Claude export, Obsidian, markdown, or a raw
                     #   vector store (re-embed + dedup-by-hash, tenant-scoped) — the
                     #   bring-your-existing-context on-ramp. Own + download your whole
                     #   context. Superset of memory + backup.
myai backup [dir]    # snapshot brain + config to a dated archive  → scripts/myai_backup.sh
                     #   tars the WHOLE git-versioned brain repo (history intact) plus
                     #   the ~/.myai config files (config, brain.path) into one
                     #   myai-backup-<host>-<ts>.tar.gz. --out <file> for an exact path,
                     #   --quiet to print only the path. No gateway/network needed.
myai restore <arc>   # restore a backup archive                    → scripts/myai_restore.sh
                     #   unpacks brain → THIS machine's resolved brain dir (or --to <dir>)
                     #   + config → ~/.myai. Machine-agnostic (paths re-resolved, brain.path
                     #   repointed). Refuses to clobber a non-empty target without --force
                     #   (existing state moved to .bak-<ts>, never deleted); --dry-run previews.

Docker-only / no host build: the CLI has zero required runtime dependencies. It uses commander for help + parsing when installed, and falls back to a built-in parser otherwise — so myai --help and myai doctor work even before npm install runs. Smoke check: ./scripts/smoke-cli.sh (validates --help, --version, doctor, and npm pack).

📊 Dashboard — your live operations console

myai up brings up a Next.js 15 operations console at http://localhost:3210. It's the human window into everything the framework is doing — no CLI required.

| Path | Page | |------|------| | / | Status home — gateway health, counts, recent activity | | /agents | Browse all 62 agents | | /skills | Browse all 136 skills with trigger search | | /hooks | Registered hooks + event bindings | | /rules | Governance rules (AI_RULES, routing, design) | | /repos | your managed repos — health grid by workspace | | /sessions | Active + historical gateway sessions | | /sona | SONA analytics (confidence, usage, categories) | | /patterns | SONA pattern browser | | /api/health | Dashboard-side health check | | /api/agents/:name | Agent detail (proxies gateway) | | /api/skills/:name | Skill detail (proxies gateway) |

Plus the operations views the runner and scheduler drive:

• /plan — every repo's 10-day plan table (Day · Fires UTC→Sydney · Focus · Status).
• /schedule — Scheduled Runs (with Repo column) above the priority-ordered Up Next queue + Needs Review.
• /directory — one-point app pointer (localhost/app/api/Vercel/DNS URLs + Mongo + last status); self-updated by each repo on wrap up.
• /budgets — cost/budget dashboard when budget guards are enabled (see below).
• /fleet — cross-repo orchestration snapshot; the Fleet Morning Console.

Seed it with realistic sample data so the first run isn't empty: myai demo (idempotent, --clean to remove).

Production URL: https://ai-management-one.vercel.app/

📱 Remote management — drive the fleet from your phone

Work on any repo from your phone, then continue seamlessly from your desktop — and vice versa. Every repo is fully self-contained with state, agents, skills, and documentation, so opening any repo on any device gives you full context immediately.

The remote-fleet tooling lets you see who's live where and open phone-drivable sessions:

| Keyword | What it does | |---------|--------------| | remote status | Which repos have live claude sessions + profile (anti-duplication view). Runs ./AI/scripts/remote_fleet.sh status. | | remote start [all\|core\|repo…\|--last-start] | Open a phone-drivable claude-museum session per repo (iTerm tab, duplicate-guarded, --max RAM cap; records what it launched). | | remote stop [repo…\|--last-start] | Kill museum sessions only — never interactive shells. |

Anchor rule: the master-AI session is NEVER stopped — it's the phone's doorway to remote start the fleet back (override: --include-anchor). stop --last-start undoes only the last start's launches; start --last-start reopens exactly that recorded set (record never rewritten, so the pair toggles the same set). Repo set: config/remote_fleet.txt.

Telegram is wired too — telegram setup / telegram start connect a bot channel to the gateway. See the full CLI-Mobile workflow under operator docs for the branch-sync mechanics.

🤖 Autonomous Runner — work that ships while you sleep

There is one standard way to schedule autonomous work in any repo: create tasks in the gateway queue, which the launchd CLI runner (every few hours, free Fable window, claude-tech, subscription-billed, 0 API tokens) works on a test branch and flips to Needs Review for your ship it. Never use gateway cron schedules or Claude Code cloud routines for per-repo work — they fragment the view and/or bill tokens.

⏰ Off-hours policy: autonomous runs fire only when you're not in interactive sessions — weekdays 6pm–9am Sydney, and all weekend. The runner no-ops during weekday 9am–6pm (override a one-off with --force). Plan fire times on /plan are clamped into this band (default 8pm Sydney). Tunable via WORK_HOURS_START/WORK_HOURS_END.

Why it matters

Queue the work you'd rather not babysit, walk away, and come back to branches built and waiting for review. Zero API cost when routed through your logged-in CLI subscription, and everything lands on test first — nothing autonomous ever touches main.

The keyword to type in ANY repo

schedule plan

Runs the mythos-grade planning protocol (planning only — builds nothing):

1. Writes AI/plan/MYTHOS_IMPROVEMENT_PLAN.md — an ambitious, opinionated improvement & feature plan: tooling, tracking, service & integration, functionality, UX/web design, user journey, practical use cases.
2. Posts a 10-day schedule via the gateway plan_set MCP tool → renders as a table on the dashboard /plan page (Day · Fires UTC→Sydney · Focus · Status), one focus per day (fires ≈9am Sydney).
3. Schedules the work — creates session-sized tasks (./AI/scripts/schedule_task.sh, --model claude-fable-5) the CLI runner executes across the next 10 days.

Other scheduling keywords

| Keyword | What it does | |---------|--------------| | schedule plan | Full mythos plan + 10-day dashboard schedule + queued tasks (above). The one to type in any repo. | | schedule <description> / schedule task | Queue a single autonomous task for this repo (schedule_task.sh). | | schedule list / what's scheduled | Show this repo's queue (schedule_task.sh --list; --list-all for the fleet). |

Installing the runner on a machine (per-machine worker)

The CLI runner is a per-machine worker — the shared queue lives in the gateway, but each Mac/Linux box that should work it needs the schedule installed once. One entry point on every platform:

./scripts/setup_cli_runner_schedule.sh                    # install — fires every 10 minutes
./scripts/setup_cli_runner_schedule.sh --every-minutes 5  # custom cadence
./scripts/setup_cli_runner_schedule.sh --status           # timer state + last session log
./scripts/setup_cli_runner_schedule.sh --uninstall        # remove

• macOS → a launchd user agent (com.myai.cli-task-runner). Keep the box awake on AC power: sudo pmset -c sleep 0.
• Linux / VPS → the entry point auto-routes (same flags) to scripts/setup_cli_runner_linux.sh: a systemd user timer (myai-cli-runner.timer) when the user manager is reachable, otherwise a crontab entry with a managed marker (WSL1, minimal containers, non-systemd distros). Force a backend with --systemd / --cron. On a headless box run loginctl enable-linger $USER once so the timer survives logout — the installer reminds you when lingering is off.
• Windows → best-effort tier, two paths (full guide: documentation/WINDOWS_RUNNER.md). Recommended: WSL2 — inside WSL2 the entry point routes to the Linux/systemd installer unchanged; add a myai-wsl-keepalive logon task so the WSL VM (and its timer) stays up. Experimental: native Task Scheduler — scripts/setup_cli_runner_windows.ps1 registers a schtasks job (myai-cli-task-runner, same 10-min cadence, mirrored -Status/-Uninstall verbs) that fires the runner via Git Bash through a hidden-window wrapper; runs only while logged on and isn't CI-tested. Running the bash entry point from Git Bash prints these options and exits.

The cadence installer only controls when fires happen; the slot/backoff semantics (up to MAX_CONCURRENT = 5 parallel tasks, 30-minute backoff when all slots are busy, weekday 6pm–9am + weekend off-hours guard) live in cli_task_runner.sh and are identical on both platforms. Silence a machine that should never be a worker: touch ~/.ai-cli-runner/.no-runner.

You can also manage the runner from the CLI directly: myai runner install | uninstall | start | stop | status | logs.

Full protocol reference: documentation/KEYWORDS_REFERENCE.md → Scheduling. Helper scripts: scripts/schedule_task.sh, scripts/repo_card.sh.

🔌 MCP servers — plug in tools

MCP (Model Context Protocol) servers extend Claude Code — and any MCP-capable agent — with specialised tools: library docs, browser automation, container management, component browsing, and more. Configs are auto-managed and propagated to all managed repos via update_all.sh.

Installed (No API Key Required)

Base — All Projects

These are installed in every managed repo via templates/mcp.json → .mcp.json.

| Server | Package | Purpose | Tools | |--------|---------|---------|-------| | Context7 | @upstash/context7-mcp | Version-specific library docs in-context (Next.js, React, Mongoose, Tailwind, etc.) | resolve, get-library-docs | | shadcn/ui | @jpisnice/shadcn-ui-mcp-server | Browse, search, install shadcn components directly from Claude Code | browse, search, install | | Playwright | @playwright/mcp | E2E browser testing — navigate pages, click elements, fill forms, assert content, take screenshots. Use for testing Vercel preview URLs before merging PRs | navigate, click, fill, screenshot, expect, +20 more | | Dropbox | https://mcp.dropbox.com/mcp (remote) | Read, search, create files in Dropbox — OAuth auto-handled | list, search, read, create | | GitHub | @modelcontextprotocol/server-github | Repo, issue, PR, branch, release management against the repo's origin remote. Needs GITHUB_PERSONAL_ACCESS_TOKEN env (one-time: export GITHUB_PERSONAL_ACCESS_TOKEN=$(gh auth token)) | create_issue, create_pull_request, list_commits, search_repositories, +20 more | | Vercel | https://mcp.vercel.com (remote) | Deployment status, env vars, log streaming — OAuth-scoped per Vercel account, sees all your projects | list_deployments, get_deployment, list_env_vars, read_logs, +more | | myai | Local gateway (localhost:3100) | MCP interface to the myAI gateway (when Docker is running) | Varies by gateway version |

Back-compat note: this server's .mcp.json key was renamed from ai-framework to myai (task-887c7fcb, 2026-07-24) to match the repo/package/CLI name. Existing installs pick up the new key on next myai init/myai mcp sync or a fresh .mcp.json propagation; if Claude Code shows the server as disconnected after pulling this change, restart Claude Code so it re-reads .mcp.json. Tool calls are unaffected — only the connection label changed, not brain_*/other tool names.

Conditional — Auto-Detected by update_all.sh

These are merged into .mcp.json only when the project matches the detection condition.

| Server | Package | Condition | Purpose | Tools | |--------|---------|-----------|---------|-------| | Chrome DevTools | @anthropic-ai/chrome-devtools-mcp-server | Has next.config.*, vercel.json, or src/app/layout.tsx | Browser console logs, network requests, screenshots, performance profiling | console, network, screenshot, evaluate | | Docker | docker-mcp | Has docker-compose.yml | Container logs, exec into containers, manage containers. Uses {folderName}-* naming convention per AI_RULES | sandbox_exec, run_js, mcp-exec, mcp-find, search_npm_packages | | OpenAPI | openapi-mcp-server | Has src/app/api/, src/routes/, or routes/ | Exposes API endpoints as MCP tools from OpenAPI spec. Claude can discover and call your API directly | Auto-generated from OpenAPI paths |

User-Level — Installed per Machine

These are installed via Claude Code plugins or browser extensions, not managed by update_all.sh.

| Server | Source | Purpose | Tools | |--------|--------|---------|-------| | Claude in Chrome | Chrome browser extension | Full browser automation — navigate, click, fill forms, read pages, record GIFs, execute JavaScript, read console/network | navigate, read_page, form_input, javascript_tool, gif_creator, tabs_create_mcp, read_console_messages, read_network_requests, +10 more | | Google Drive | Claude Code OAuth integration | Read and access Google Drive files | authenticate, complete_authentication |

Planned (API Key Required)

Add these by setting the API key in each project's .env. Once available, add to templates/mcp.json (all repos) or project-specific .mcp.json.

| Server | Package | Purpose | Priority | |--------|---------|---------|----------| | Brave Search | @anthropic-ai/brave-search-mcp-server | Web search from Claude sessions | High | | Figma | @anthropic-ai/figma-mcp-server | Read designs, components, variables | High | | Sentry | @sentry/mcp-server | Error tracking, issue management | High | | MongoDB Atlas | @anthropic-ai/mongodb-mcp-server | Direct Atlas queries and management | Medium | | Upstash | @upstash/mcp-server | Serverless Redis, Kafka, QStash | Low | | Notion | @anthropic-ai/notion-mcp-server | Pages, databases, blocks access | Low | | Slack | @anthropic-ai/slack-mcp-server | Channel messaging, workflows | Low |

Full details and setup instructions: plan/MCP_SERVERS.md

How MCP Configs Are Managed

templates/mcp.json          ← Base config (myai, Context7, shadcn, Playwright, Dropbox, GitHub, Vercel) → all repos
templates/mcp-web.json      ← Chrome DevTools overlay → merged if Next.js/Vercel detected
templates/mcp-docker.json   ← Docker overlay → merged if docker-compose.yml detected

Propagation flow:

1. Edit templates in this master repo
2. Run ./scripts/update_all.sh
3. Script copies base to <repo>/.mcp.json, then merges overlays based on detection
4. Uses jq (preferred) or python3 fallback for JSON merging
5. Claude Code reads .mcp.json on session start — servers are available immediately

Adding a new MCP server to all repos:

1. Add the server block to templates/mcp.json
2. Run ./scripts/update_all.sh
3. All your managed repos get it on next sync

Adding per-project only:

1. Edit <project>/.mcp.json directly
2. update_all.sh won't overwrite project-specific additions (it merges, not replaces)

On agent mode — MCP Awareness

When agent mode runs in any repo, it reports which MCP servers are active by reading .mcp.json. This ensures the agent knows what tools are available before dispatching work.

🔎 RAG & memory search

Semantic search across everything you've ever done — local vectors, your data, no cloud round-trip. When you myai scan ~/code --register, the framework embeds each repo's state, handoff, and archive into the gateway's central vector store. From then on, any agent can pull the right past decision on demand instead of you re-explaining it.

Two search surfaces, exposed as both REST endpoints and MCP tools:

| Tool | What it does | |------|--------------| | memory_search | Semantic search across all repos' vectors | | recall_session | Semantic recall over the session corpus (state + handoff + archive); ranked blocks, since/repo filters | | memory_store | Embed + store a chunk (dedupes by content hash) | | memory_context | Pre-built context block (handoff + state + patterns) | | memory_stats | Vector counts per repo / source | | memory_reindex | Re-embed a repo's corpus into the central store |

REST equivalents live on the gateway's :3200 surface (POST /api/memory/search, POST /api/vectors/search, GET /api/vectors/stats, POST /api/vectors/index) — see Gateway Routes.

When the RAG_RECALL=1 flag is set and the session-start hook reports RAG RECALL: ON, agent mode prefers semantic recall_session over plain grep for looking up older sessions. Managed repos use the master gateway over the network — they don't run their own vector store, so all embeddings flow through one place. wrap up calls memory_reindex to keep the corpus current.

You can also carry your corpus between machines or import an existing one: myai memory export/import (corpus only) and myai context export/import (full bundle incl. vectors + brain), plus myai context import-external to ingest FROM a ChatGPT/Claude export, Obsidian, markdown, or a raw vector store — the bring-your-existing-context on-ramp.

🤝 Multi-agent handoff

The file system is the shared memory, so handing off between agents, sessions, and devices is always safe. Switch from Claude to Gemini mid-project, pick up tomorrow on a different machine, or recover instantly when an agent hits a rate limit — the next agent reads the state and continues from exactly where the last one stopped.

When to hand off

• End of day — save state so tomorrow's agent (same or different) picks up cleanly
• Credit exhaustion — agent hits token/API limit mid-session, switch to another
• Specialist swap — e.g. Gemini for document writing, Claude for code generation
• Any time — the file system is the shared memory, so handoff is always safe

Save state — tell the current agent

handoff

Or the full version:

Save state and prepare for handoff. Update AI/state/STATE.md with current progress and blockers. Write AI/state/AI_AGENT_HANDOFF.md with clear instructions for the next agent including what's done, what's in progress, and what to do next.

Pickup — start the next agent

If the agent has an instruction file (CLAUDE.md, GEMINI.md, etc.), just type:

agent mode

If the agent is new and doesn't have its instruction file yet, use:

Read AI/state/STATE.md and AI/state/AI_AGENT_HANDOFF.md to sync state. Read AI/documentation/AI_RULES.md for tech mandates and AI/documentation/MULTI_AGENT_ROUTING.md for routing. Report what's done, in progress, and next priority. Update STATE.md after every task.

Mid-session credit exhaustion

The problem: AI agents (especially Claude) hit API rate limits mid-session with zero warning. The session dies, context is lost, no handoff is saved. You wait hours.

The solution: Session Usage Guard automatically detects approaching limits and forces a clean handoff before the session dies. See Hooks & the Session Usage Guard below for full details.

Manual handoff (if usage guard hasn't triggered yet):

1. Tell it: wrap up (saves state + handoff)
2. Open the next agent (e.g. switch from Claude to Gemini)
3. Tell it: agent mode (reads state and continues)

The handoff files capture exactly where you left off — the new agent picks up from the same point.

The "Start Work" prompt (everyday multi-agent mode)

Use this prompt every time you open an AI agent in a project that has the AI/ framework. It synchronizes state, activates all 64 specialist subagents, and dispatches work in parallel lanes automatically.

You are operating in multi-agent mode with 64 specialist subagents available.

**Step 1 — Synchronize state:**
Read the following files in order:
1. `AI/state/STATE.md` — current project progress, blockers, and last stopping point
2. `AI/state/AI_AGENT_HANDOFF.md` — specific instructions from the previous session
3. `AI/documentation/AI_RULES.md` — global tech mandates (Docker, Next.js, MongoDB, Render, Vercel, GitHub Actions)
4. `AI/documentation/MULTI_AGENT_ROUTING.md` — routing reference for all specialists

**Step 2 — Assess and report:**
Based on STATE.md, tell me:
- What was completed last session
- What is currently in progress or blocked
- What the next priority is

**Step 3 — Dispatch specialists in parallel:**
Based on the current project state and next priority, identify which parallel lanes apply and dispatch the relevant specialists simultaneously:
- Lane A (Frontend): `frontend-specialist` + `ui-ux-specialist`
- Lane B (Backend): `api-specialist` + `database-specialist`
- Lane C (Infrastructure): `devops-specialist` + `security-specialist`
- Lane D (Async, always): `documentation-specialist` + `solution-architect` + `project-manager`
- Cross-lane: `tech-lead` (reviews) + `qa-specialist` (tests)

Only sequence work when a specialist's output is a required input for another. Parallel is the default.

**Step 4 — Log and maintain state:**
After every completed task, autonomously update `AI/state/STATE.md` and log actions to `AI/logs/claude_log.md` (or `AI/logs/gemini.md` / `AI/logs/copilot.md`). Do not wait for me to ask.

Lightweight version (for quick sessions or follow-up prompts)

Read AI/state/STATE.md and AI/state/AI_AGENT_HANDOFF.md to sync state. Check AI/documentation/MULTI_AGENT_ROUTING.md and dispatch the relevant specialist agents in parallel for the next priority. Update STATE.md after every task without being asked.

agent mode -a — auto-mode flag

Run agent mode -a (or --auto) instead of agent mode to combine the full startup with autonomous-execution mode in one keyword. The agent does standard agent mode (project identity, git sync, multi-machine check, state read, status report, lane dispatch) and then automatically activates YOLO god as the final step.

From that point: no questions, no permission prompts, just maximum-velocity execution against the priorities reported in the status step. All YOLO safety rails preserved (no push to main, no secret commits, no destructive ops without explicit ask, 4h hard cap).

Same effect as typing agent mode then yolo god separately — just one keyword.

🐳 Local Docker stack

myai up brings up a self-contained, single-tenant stack on localhost — gateway + dashboard + Mongo — waits for health, and prints the dashboard URL. No auth friction (loopback-scoped), no external services. Everything runs on your machine; your data never leaves it.

The stack is memory-capped so it stays light and predictable — see Docker Memory Limits for defaults (~2 GB reserved, ~390 MB in practice) and how to tune per machine. Four localhost surfaces come up together:

| Port | Protocol | Audience | Purpose | |------|----------|----------|---------| | :3100 | JSON-RPC (HTTP) | LLM agents (Claude Code, Cursor, etc.) | MCP tool server | | :3200 | HTTP REST JSON | Humans, dashboards, CI scripts | REST API | | :3201 | WebSocket | Browsers, streaming UIs, Telegram bot | Real-time channel | | :3210 | HTTPS/HTTP | Humans | Next.js operations dashboard |

Manage it all from the CLI: myai up / myai down (--volumes drops data) / myai status / myai logs [service]. Full route/endpoint reference is in Under the hood → Gateway Routes.

🚀 Quick-to-production — make prod

The make prod keyword automates production provisioning for any project with the AI framework. Describe nothing extra — it detects your stack, provisions only what's missing, and wires branching + CI + hosting in one shot.

How It Works

You: "make prod"

Step 0 — Check existing config (ALWAYS first):
  ├── .vercel/project.json exists?  → Already on Vercel
  ├── render.yaml exists?           → Already on Render
  ├── mongodb+srv:// in env?        → Already on Atlas
  ├── test branch exists?           → Already has branching
  └── If all configured → verify health → done (no re-provisioning)

Step 1 — Set up branching strategy:
  ├── Create test branch from main
  ├── Copy CI workflows (.github/workflows/ci.yml + merge-gate.yml)
  ├── Set branch protection (main: PR + CI, test: CI)
  └── Add vercel.json for dual-branch deploys

Step 2 — Detect project type & provision:
  ├── next.config.ts found          → Vercel deployment
  ├── express/fastify in deps       → Render deployment
  └── Mongoose models / MONGODB_URI → MongoDB Atlas

Step 3 — Provision only what's missing:
  ├── Vercel: link project, set env vars (Production + Preview), deploy
  ├── Atlas: create DB user, build connection string
  ├── Render: create web service, set env vars
  └── Generate .vercelignore / render.yaml

Step 4 — Verify:
  ├── Push test commit to test branch → CI passes
  ├── Vercel preview URL loads
  ├── curl /api/health → {"status":"ok","db":"connected"}
  └── Update state files with production + preview URLs

Usage

# In any project with the AI framework:
# Just type "make prod" to your AI agent

# Or run the script directly:
./scripts/make_prod.sh /path/to/project [project-name]

What Gets Created

| Service | Config File | Env Vars Set | |---------|-------------|-------------| | Vercel | .vercel/project.json, .vercelignore | MONGODB_URI, JWT_SECRET, NODE_ENV | | MongoDB Atlas | Connection string in env | MONGODB_URI | | Render | render.yaml | MONGODB_URI, JWT_SECRET, NODE_ENV, PORT |

Key Behaviour

• Idempotent: Running make prod on an already-deployed project just verifies health — it won't re-provision or overwrite existing config
• Partial setup: If Vercel is configured but Atlas isn't, only Atlas gets provisioned
• Git auto-deploy: If Vercel has git integration, deploying is just git push

Branching Strategy — Production Safety

No wrong code reaches production. Every repo uses two always-building branches:

| Branch | Purpose | Auto-deploys to | Protection | |--------|---------|-----------------|------------| | main | Production | Vercel prod URL | PR required, CI must pass | | test | Staging | Vercel preview URL | CI must pass, direct push OK |

1. Push to test     →  git push origin test
2. CI runs          →  lint, type-check, test (automatic)
3. Preview deploys  →  Vercel generates preview URL (automatic)
4. User tests       →  AI asks user to verify preview URL
5. Create PR        →  gh pr create --base main --head test
6. AI reviews PR    →  code review + merge gate check
7. Merge            →  gh pr merge --merge
8. Prod deploys     →  Vercel auto-deploys to production (automatic)
9. Notify           →  AI confirms "Production deployment complete"

Emergency hotfix:

git checkout -b hotfix/critical-fix main
# fix...commit...push
gh pr create --base main --head hotfix/critical-fix
# After merge: sync test branch
git checkout test && git merge main && git push origin test

CI pipeline (per repo) — every push to main or test runs:

• Lint — ESLint
• Type-check — TypeScript compiler
• Test — Vitest/Jest with MongoDB service
• Deploy Check — full production build (PRs to main only)
• Merge Gate — only test or hotfix/* branches can PR to main

Files added per repo:

| File | Purpose | |------|---------| | .github/workflows/ci.yml | CI pipeline | | .github/workflows/merge-gate.yml | Enforce test→main flow | | vercel.json | Enable dual-branch deploys |

Also available: make preview (set up the test→preview pipeline for a specific repo).

⭐ Blueprint — from idea to app in 4 steps

Zero config. Zero boilerplate. Just describe what you want to build.

The Powerhouse Blueprint gives you the full engineering stack — 62 AI agents, 136 skills, CI/CD, database, error monitoring, design system — all pre-wired and ready. You don't pick agents, you don't configure tools, you don't set up pipelines. You just talk about your app.

The 4 Steps

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  STEP 1   Open this repo in Claude                              │
│           cd ~/path/to/ai_management && claude                  │
│                                                                 │
│  STEP 2   Run the blueprint command                             │
│           init blueprint ~/path/to/<your-app-name>              │
│                                                                 │
│  STEP 3   Open the new app in Claude                            │
│           cd ~/path/to/<your-app-name> && claude               │
│           then type: agent mode                                 │
│                                                                 │
│  STEP 4   Describe your app                                     │
│           "Build a task management app with team collaboration"  │
│           "Build an e-commerce platform with Stripe payments"    │
│           "Build a real-time chat app with AI moderation"        │
│                                                                 │
│  That's it. The AI builds it.                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

What happens behind the scenes

You don't need to know any of this — it just works. But here's what the blueprint wires up for you automatically:

| Layer | What you get | You configure | |-------|-------------|---------------| | AI Brain | 62 specialist agents, 136 skills, MCP servers, hooks, SONA pattern memory | Nothing — auto-routed by your prompt | | App Stack | Next.js 15 (App Router) + TypeScript strict + Tailwind v4 + shadcn/ui | Nothing — ready to build on | | Database | MongoDB in Docker (local) + Atlas-ready for prod | Just swap MONGODB_URI for production | | AI Integration | @anthropic-ai/sdk with prompt caching, sample AI feature | Nothing — imported and ready | | Error Monitoring | Sentry browser + server + edge (graceful when DSN absent) | Add Sentry DSN when ready | | CI/CD | 4 GitHub Actions: lint, merge gate, Claude review, Copilot review | Nothing — runs on push | | Design System | Tailwind v4 + shadcn/ui + Google Stitch MCP for AI-driven UI | Nothing — just describe your UI | | Dev Environment | ./dev script (up / stop / reset / logs / shell / test / tsc) | Nothing — Docker handles it all | | Deployment | Vercel-ready + BLUEPRINT_HOOKUP.md for 5-min production wireup | Follow the hookup guide | | Keywords | agent mode (+ -a for auto-mode), ship it, wrap up, yolo god, check bugs, office mode | Just type them |

Why this matters

Traditional setup: create repo → install deps → configure TypeScript → set up Tailwind → add shadcn → configure ESLint → write Dockerfile → set up docker-compose → create CI workflows → configure Sentry → set up database → write CLAUDE.md → configure MCP servers → set up agents → then start building. That's hours of boilerplate.

With the blueprint: 4 steps, then you're building your app. The AI already knows how to route your requests to the right specialist, which tools to use, and how to ship your code safely through CI.

Alternative paths

One-command scaffold:

myai new-app ~/code/my-idea

GitHub Template (skip step 1+2):

gh repo create knofler/<name> --template knofler/todo-blueprint --private --clone
cd <name> && cp .env.example .env.local && ./dev

Script with GitHub + Vercel flags:

./scripts/init_blueprint.sh ~/path/to/<name> \
    --gh-create knofler/<name> --gh-private --vercel

Canonical reference: plan/POWERHOUSE_BLUEPRINT.md Template repo: knofler/todo-blueprint

💡 Jam — ideate before you build

Not every session should start with code. Type jam (or jam <idea>) and the agent flips from executor to thought-partner: it explores the idea with you, pushes back, weighs options and tradeoffs, and asks the sharpening questions — a real conversation, not a multiple-choice interrogation.

• It's the one explicit exception to zero-prompt/YOLO mode — in a jam, questions and dialogue are the work. No code, edits, or commits happen during the jam.
• Persistent mode — it holds until you say build it or jam done.
• On convergence it writes a brief to AI/plan/jam/<slug>.md and registers it as a plan (visible on the dashboard /plan), then hands you a decision point: schedule it (queue for the runner, or agent mode to build now, or init blueprint for a new app), more jam (keep refining), or park it.

Why it matters: the cheapest place to fix a bad idea is before a single line is written. Jam gives you a structured brainstorm that ends in a real, registered plan — so the thinking isn't lost.

Full protocol: documentation/KEYWORDS_REFERENCE.md → "Jam".

🏗️ Architecture — how agents coordinate

The framework uses parallel dispatch lanes so multiple specialists work simultaneously without blocking each other. All coordination happens through shared state files — no direct agent-to-agent messaging needed.

Directing a specific agent

Each agent is a specialist with a defined domain. You can activate one by describing a task in its area, or by explicitly naming it.

Claude Code (auto-discovered from .claude/agents/):

# Implicit — Claude Code routes automatically based on keywords:
"Design the MongoDB schema for the users collection"
→ Activates: database-specialist

# Explicit — name the agent directly:
"As the security-specialist, audit the authentication flow in src/middleware/auth.ts"

Gemini / Copilot (manual role adoption):

"Adopt the role defined in AI/agents/api-specialist.md for this session.
Now implement the /api/v1/users endpoint with validation and error handling."

Multi-agent in one prompt (dispatch several at once):

"Dispatch these specialists in parallel:
- frontend-specialist: Create the dashboard page at src/app/dashboard/page.tsx
- api-specialist: Implement GET /api/v1/dashboard/stats
- database-specialist: Add an aggregation pipeline for dashboard metrics"

Invoking a skill manually

Skills are repeatable playbooks that produce consistent, standards-compliant output. Each skill has trigger keywords — use them naturally in your prompt, or invoke by name.

By trigger keyword (Claude Code auto-matches):

"Write a Dockerfile for the API service"
→ Triggers: dockerfile-create skill

"Set up rate limiting on the auth endpoints"
→ Triggers: rate-limit-setup skill

"Create the schema for the orders collection"
→ Triggers: schema-design skill

By explicit name:

"Run the api-contract skill for the payments service"
"Execute the test-strategy skill for this project"
"Use the owasp-audit skill to review our security posture"

Gemini / Copilot (reference the skill file directly):

"Follow the playbook in AI/skills/schema-design/SKILL.md to design the products collection schema."

How agents coordinate & break down work

1. Task Arrives

You describe a feature (e.g., "Build a user registration system with email verification").

2. Parallel Dispatch

The framework identifies which specialists are needed and assigns them to lanes:

Lane A (Frontend):    frontend-specialist → registration form + verification page
                      ui-ux-specialist    → form design, validation UX, accessibility

Lane B (Backend):     api-specialist      → POST /api/auth/register, GET /api/auth/verify
                      database-specialist → User schema, email verification tokens

Lane C (Infra):       devops-specialist   → environment variables for email service
                      security-specialist → password hashing, token expiry, rate limiting

Lane D (Async):       documentation-specialist → API docs, README update
                      solution-architect       → ADR for auth approach
                      product-manager          → acceptance criteria
                      tech-ba                  → requirements traceability

Cross-Lane:           tech-lead      → reviews all outputs for consistency
                      qa-specialist  → writes unit, integration, and E2E tests

3. Sequencing Rules

Lanes run in parallel, but within a lane, work sequences when one specialist's output feeds another:

• database-specialist designs the schema → api-specialist implements endpoints using that schema
• api-specialist finalizes the API contract → frontend-specialist integrates against it
• All implementation done → qa-specialist writes tests → tech-lead reviews

Rule: Only sequence when a specialist's output is a required input for another. Parallel is always the default.

4. State Coordination

All agents read and write to the same state files — this is how they stay in sync without direct communication:

| File | Purpose | Who Writes | |------|---------|-----------| | AI/state/STATE.md | Current progress, blockers, next steps | All agents, after every task | | AI/state/AI_AGENT_HANDOFF.md | Context for the next agent/session | Outgoing agent at session end | | AI/logs/claude_log.md | Timestamped action log | Claude agents | | AI/logs/gemini.md | Timestamped action log | Gemini agents | | AI/logs/copilot.md | Timestamped action log | Copilot agents |

Protocol:

1. Session start: Read STATE.md + AI_AGENT_HANDOFF.md to sync
2. After every task: Update STATE.md autonomously (don't wait to be asked)
3. Session end: Update STATE.md + write AI_AGENT_HANDOFF.md + log to agent log

5. File Ownership

Each lane owns specific directories to avoid merge conflicts:

Lane A owns: src/app/, src/components/, src/styles/
Lane B owns: src/routes/, src/models/, src/services/, src/middleware/
Lane C owns: docker-compose.yml, Dockerfile, .github/, render.yaml
Lane D owns: AI/, README.md, docs/
Cross-lane:  tests/, src/types/ (shared contracts)

Worked Example: "Add a search feature"

You: "Add full-text search to the products catalog"

Step 1 — Dispatch parallel:
  database-specialist → MongoDB text index + aggregation pipeline  (Lane B)
  solution-architect  → ADR: text search vs Atlas Search vs Algolia (Lane D)
  product-manager     → acceptance criteria for search UX            (Lane D)

Step 2 — After schema ready, sequence:
  api-specialist      → GET /api/v1/products/search endpoint         (Lane B)

Step 3 — After API ready, parallel:
  frontend-specialist → search bar component + results page          (Lane A)
  ui-ux-specialist    → search UX: debounce, loading states, empty   (Lane A)
  documentation-specialist → API docs for search endpoint            (Lane D)

Step 4 — After implementation, parallel:
  qa-specialist       → unit tests + integration tests + E2E         (Cross)
  security-specialist → input sanitization, query injection review   (Lane C)
  tech-lead           → cross-lane coherence review                  (Cross)

Step 5 — All update STATE.md with their completed work.

How it's delivered to projects

When you run ./scripts/init_ai.sh [project], everything gets copied automatically:

[target-project]/
├── AI/
│   ├── .claude/
│   │   ├── agents/ → ../agents/   ← Symlink, Claude Code auto-discovers
│   │   └── skills/ → ../skills/   ← Symlink, Claude Code auto-discovers
│   ├── agents/                     ← 62 agent definit