codex-brain-bootstrap

Auto-configure AGENTS.md and brain/ knowledge docs for a new project. Use when setting up Brain Bootstrap in a new repository. Discovers the codebase, fills in templates, and writes project-specific configuration.

Use before any new feature, component, or behavioral change — when you need to explore requirements and design before writing code. Hard gate — no code until design is approved.

Build the project and verify it compiles cleanly. Use after making changes to confirm nothing is broken before running tests. Reads the build command from brain/build.md.

Activate safety mode — review every destructive command before running. Use before working on production infrastructure, migration scripts, or any task where a typo could be catastrophic.

Generate a user-facing changelog from git commits — categorize, filter noise, translate to user language. Pass a tag or date as argument (e.g. "$changelog v1.0.0" or "$changelog 2026-01-01").

Save session state before context gets full or before ending. Writes current task state, branch, and loaded docs to brain/tasks/todo.md so the next session can resume cleanly.

Remove all git worktrees for merged branches. Accepts --dry-run to preview. Use after merging PRs or for weekly maintenance.

Clean workspace — build artifacts, dependencies, caches, Docker volumes, or temp files. Accepts arguments like build, deps, all, cache, docker, tasks, reinstall.

Semantic vector search over the codebase — find code by meaning, not exact names. Use when you need to locate implementations without knowing exact function/class names. Triggers on "find code", "search codebase", "locate implementation", "what does X do".

Change risk analysis — detect blast radius, risk score, and breaking changes from git diffs. Use before any PR or merge. Triggers on "review PR", "check impact", "blast radius", "what breaks", "safe to merge".

Use when you need structural graph navigation — trace call paths, detect blast radius, find dead code, or query architecture — before reading files. Structural queries only: not for semantic meaning (use cocoindex-code for that).

Load all relevant brain/ knowledge files for a domain area. Use at session start or when switching to a new topic. Accepts a domain keyword like api, database, auth, build, security.

Verify that a new field, enum value, or status code exists consistently across all layers. Use after adding new fields to prevent cross-layer inconsistency (DB → service → API → tests).

Query the database — list schemas, tables, describe a table, or run SQL. Accepts arguments like schemas, tables, describe <table>, or raw SQL.

Root cause analysis for bugs and errors. Use when something is broken and the cause is not obvious. Applies the 5-step investigation method — observe, hypothesize, trace backwards, binary search, prove.

Manage dependencies and fix CVEs — check outdated packages, update a specific package, run security audit, explain why a package is installed, or deduplicate. Read brain/cve-policy.md for the decision tree.

Analyze branch diff against merge-base — stat overview, full diff, file list, commit list, or branch overlap check. Always uses merge-base to exclude main's forward progress.

Docker workflow helpers — list containers, build, run, logs, compose up/down, prune. Non-interactive only.

Git workflow helpers — status, rebase, commit, amend, log, stash, branch management. Includes pre-push checklist. NEVER git push autonomously.

Verify Codex configuration health — AGENTS.md, hooks, config.toml, agents, skills, secrets scan, and MCP reachability. Reports ✅/⚠️/❌ for each check.

Use when you have open GitHub issues that need categorization, duplicate detection, staleness review, or triage comments — runs 3-phase workflow with mandatory user validation before posting. Args: "all" for deep analysis, issue numbers (e.g. "42 57"), "fr" for French, no arg = audit only.

Run the linter and formatter check. Use before opening a PR to ensure code style compliance. Reads lint command from brain/build.md.

Detect and fix stale brain/*.md knowledge docs. Use when brain/architecture.md or build.md references missing files, wrong commands, or outdated patterns. Keeps the knowledge base accurate.

Manage MCP (Model Context Protocol) servers — list configured tools, check status, show invocation format, or add a new server to .codex/config.toml.

Run database or schema migrations — up, down, rollback, status, or create a new migration. Reads brain/build.md for migration commands.

Generate a PR/MR description after the review passes. Use after $review confirms the code is ready to merge. Reads brain/templates.md for the required format.

Plan a non-trivial task before implementing. Use when the task requires 3+ steps, multiple files, or an architectural decision. Writes a checkable plan to brain/tasks/todo.md.

Browser automation — navigate, click, fill, snapshot web pages. Use for UI testing, documentation scraping, OAuth flows, web research. Always snapshot first, screenshot never (unless required).

Use when you have open GitHub PRs that need categorization, overlap detection, risk review, or code review comments — runs 3-phase workflow with mandatory user validation before posting. Args: "all" to review all, PR numbers (e.g. "42 57"), "fr" for French, no arg = audit only.

Use when receiving code review feedback — before implementing suggestions, especially if feedback seems unclear or technically questionable. Verify before implementing.

Generate a comprehensive repo recap (PRs, issues, releases) ready to share with the team. Pass "fr" for French output (default is English).

Isolated codebase exploration that preserves your main context. Use when you need to understand code structure, trace call paths, or gather evidence before making changes. Spawns an explorer subagent.

Resume a previous session from brain/tasks/todo.md. Use at the start of a new session to restore context and continue where you left off.

Full 10-point expert code review. Use before any PR or MR. Checks correctness, cross-layer consistency, transaction safety, test coverage, and security. Spawns reviewer subagent for isolation.

5-step root cause trace for errors deep in execution. Use when the error surface is far from the actual trigger. Trace backwards from the symptom to the origin.

Use when renaming symbols across files, finding all references to a function/class, moving code between files, or inlining variables — LSP-backed atomic multi-file refactoring. Zero manual grep needed.

Start service(s) locally for development. Accepts a service name, all, frontend, or backend. Reads brain/build.md for the actual start commands.

Generate a parallel workstream plan for multi-agent Codex work. Decomposes a feature into independent workstreams, each ownable by a separate Codex instance. Saves to brain/tasks/ACTION_PLAN.md.

Project status dashboard — AGENTS.md budget, unfilled placeholders, lessons file size, hooks executability, jq availability, plugin states. One-glance health report.

Use when executing implementation plans with independent tasks — dispatches fresh subagents per task with two-stage review (spec compliance, then code quality). Use after $plan generates an independent-task plan.