A practical cheat sheet for working with the Brain + AI Workflow + Archon stack. Bookmark this and open it whenever you're not sure what command to run.
Before any session — on every Mac restart, every login — these are humming via launchd. You never start them, you never check them. They just exist:
| Service | Role |
|---|---|
ai.roipros.archon.dev | Archon workflow engine on localhost:3090 |
ai.roipros.cloudflared.archon | Cloudflare tunnel: archon.roipros.com → localhost:3090 (for GitHub webhooks) |
ai.roipros.brain.refresh | Daily 02:00 brain re-indexing |
ai.roipros.brain.slackbot | Brain Slack bot (DM access from your phone) |
ai.roipros.brain.research-watch | WatchPaths on ~/Documents/research-inbox/ — runs brain refresh --tag research on every batch of new/modified files (30 s debounce, 60 s throttle) |
| (part of Archon) | Archon Slack bot — Second-Brain workspace, @-mentionable in channels |
| Claude Code MCP | Auto-connects to the brain on every session start — no setup needed per session |
Check with launchctl list | grep ai.roipros. All four agents should show a PID and status 0. If one is missing, launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<the-plist> brings it back. Logs live at ~/.archon/archon.log and ~/.cloudflared/archon.err.
Most sessions fall into one of these three buckets. Pick the matching scenario, then drop into the daily loop.
You're starting something from scratch. Empty folder, no git history, no .claude/ yet. One-time setup before you can use the workflow.
A project you've already initialized with /init-workflow at some point. Fresh Claude Code session, ready to work.
Your iOS app, currently still on BMAD. Two paths: keep using BMAD for now, or do the Phase 8 brownfield migration when ready.
From your terminal:
# 1. Make the directory and enter it
mkdir ~/Documents/AI-Projects/my-new-thing
cd ~/Documents/AI-Projects/my-new-thing
# 2. (Optional but recommended) initialize git and create a private GitHub repo
git init
gh repo create my-new-thing --private --source=. --remote=origin
# 3. Open Claude Code in this directory
claudeNow inside the Claude Code session, run these commands in order:
/init-workflow — symlinks .claude/commands, .claude/agents, .claude/skills from your workflow repo and copies the CLAUDE.md template. Takes ~5 seconds. Confirms with you before overwriting anything that already exists.CLAUDE.md — fill in the project's tech stack, dev commands, and conventions. The template has placeholders; just replace them. This is what the AI reads to understand the project's rules./create-prd — greenfield only. Skip if you already know what you're building. Walks you through a conversation to produce .agents/PRD.md, which future /plan-feature calls reference for context./brain-onboard — registers the project with the federated brain. It'll prompt for tag (use the directory name), sensitivity (confidential is the safer default; shareable if you want Slack DM access from your phone), type (usually mixed or code), and description./prime — final step before working. Loads the project's CLAUDE.md and reference docs into the AI's context so it's oriented for this session.You're now ready for the daily loop.
If you want to be able to @archon fix this on GitHub issues for this repo, wire the GitHub webhook per reference/archon-v2-setup-guide.md § 5 in your workflow repo. ~5 minutes, one-time per repo. Not required to start working — you can always trigger Archon manually via /archon/fix-issue N.
For any project that's already been /init-workflow'd:
cd ~/Documents/AI-Projects/the-project
claudeInside the session:
/primeThat's it. One command. The setup happened once at init time; you never repeat it. /prime re-orients the assistant for this specific session by reading the project's CLAUDE.md and reference docs.
If you want the brain to surface relevant cross-project context up front, you can also ask something like:
"Before we start, check the brain for anything relevant to [whatever you're about to work on]"The assistant will use the brain MCP automatically.
VOX is currently still on BMAD. Two real options here:
Open VOX exactly as you always have. Nothing changes until you commit to migrating. This is fine — the new workflow is waiting whenever you're ready.
When you're ready (probably not today; settle into the workflow on a smaller project first), follow reference/brownfield-onboarding.md in your workflow repo. The compressed version:
cp -r ~/Documents/AI-Projects/vox ~/Documents/AI-Projects/vox-cleancd vox-clean. Delete BMAD artifacts: .bmad* folders, story files, sharded PRD/architecture docs. Preserve any genuinely useful decision records — port them to docs/decisions/ as plain markdown.vox-clean. Run /init-workflow to wire in the workflow.CLAUDE.md for VOX specifics: Swift, SwiftUI, Xcode, iOS 18+, TestFlight build commands, your architectural conventions./brain-onboard — VOX is already in the federation as the vox tag pointing at the original directory. Either update ~/.graphify/federation.yaml to point at vox-clean, or add a new vox-v2 tag temporarily and keep both indexed while you transition./prime and verify the AI sees the clean structure (no leftover BMAD references in its understanding).@archon fix this on iOS bugs.vox → vox.bmad-backup, rename vox-clean → vox. Update brain federation path to match.Budget 2-4 hours of focused time for the migration. Keep the .bmad-backup copy around for at least a few weeks until you're sure nothing was lost.
Once a project is initialized and primed, the typical work session looks like this:
| Step | Command | What it does |
|---|---|---|
| 1 | /prime | Start of session, always. Loads project context. |
| 2 | /plan-feature "<what you want to build>" | Produce a deep implementation plan with context references, file paths, validation commands, acceptance criteria. Saves to .agents/plans/. |
| 3 | /execute .agents/plans/<plan-file>.md | Implement the plan task-by-task. Archon-aware: creates tasks in Archon, moves them through todo → doing → review. |
| 4 | /code-review | Manual-style code review against your project's standards in CLAUDE.md. |
| 5 | /validate | Run tests, type checks, linters, formatters. |
| 6 | /code-review-fix | Address findings from /code-review if any. |
| 7 | /commit | Stage and commit with a structured message. |
Not every session goes through all seven steps. For small tweaks, you might skip planning entirely. For complex features, you might iterate steps 2-6 several times before committing.
When you want Archon to take a task end-to-end without supervision:
| From where | Command | When |
|---|---|---|
| Inside Claude Code | /archon/fix-issue 42 |
You have a GitHub issue and want a draft PR back |
| Inside Claude Code | /archon/pr-review 17 |
Smart review of an existing PR |
| Inside Claude Code | /archon/feature-dev "<description>" |
Greenfield feature with autonomous PR delivery |
| Inside Claude Code | /archon/create-issue "<problem>" |
Have Archon classify a problem and file a clean issue |
| GitHub web/mobile | Comment @archon fix this |
From your phone, on any issue (requires the webhook wired for that repo) |
| Slack DM | Message the Archon bot | From anywhere with Slack open |
Archon opens PRs as drafts by default. Nothing auto-merges. Review and approve before merging. Each run takes 5-15 minutes for typical fixes.
You don't typically invoke the brain explicitly — the assistant uses the MCP automatically when a question might span projects. But you can prompt for it deliberately:
shareable corpora.brain query "<your question>" for a Haiku-summarized prose answer with citations. Or brain query "..." --raw for the raw graph results./save-research inside claude.ai after a research run; the report lands in ~/Documents/research-inbox/ and is queryable from /brain within a minute. See the section below.Other useful brain commands from terminal:
brain status # what's indexed, node/edge counts
brain refresh --tag <tag> # force re-index of one corpus
brain dump <path> # onboard a new corpus
brain path <source> <target> # find connection between two conceptsWhen you run Deep Research on claude.ai and want the report to stick around as queryable, cross-project knowledge alongside your code corpora, save it to the research inbox. The federated brain picks it up automatically.
The research-inbox folder at ~/Documents/research-inbox/ is a federated brain corpus (tag research, sensitivity confidential). A launchd WatchPaths agent watches it; whenever a file is created or modified, it debounces for ~30 seconds (to settle batched writes), then runs brain refresh --tag research. Graphify extracts nodes and edges, merges them into ~/.graphify/global-graph.json, and replays bridges. End-to-end latency is roughly 45–60 seconds from save to queryable.
/save-research [topic-slug] in that same conversation. The skill writes a single markdown file with frontmatter (title, date, sources) and the full report body to ~/Documents/research-inbox/<YYYY-MM-DD>_<topic-slug>.md. Name collisions get suffixed -2, -3, etc.brain status — the research row's node count bumps after each save.tail -5 ~/.graphify/research-watch.log — look for the trailing exit 0 line./brain <something from the report> in Claude Code, or brain query "..." from terminal.The research inbox mixes personal, business, employer, and hobby topics, so the corpus is tagged confidential. /brain (local CLI and Claude Code MCP) returns research hits freely. Slack DM does not — the SLACK_DM egress filter blocks confidential-tier content, so research never leaks to your phone via the Brain bot.
If a research question is one-off and you don't need to remember it later, just ask Claude directly without saving. The pipeline is for output you want to be findable months from now, especially as bridges across other projects.
| Situation | What to do |
|---|---|
| Brand-new project, never set up | /init-workflow → edit CLAUDE.md → /brain-onboard → /prime |
| Existing project, fresh session | /prime |
| VOX, today (BMAD-era) | Use BMAD as before — new workflow not active yet |
| VOX, after Phase 8 migration | /prime like any other project |
| Plan a feature | /plan-feature "what you want" |
| Implement an existing plan | /execute .agents/plans/<file>.md |
| Review your own changes | /code-review → fix findings → /validate → /commit |
| Hand a bug off to Archon | /archon/fix-issue N or @archon fix this on the GitHub issue |
| Review a PR via Archon | /archon/pr-review N |
| Query across all your projects | Just ask the AI naturally — brain MCP auto-engages |
| Save research from claude.ai | /save-research [topic-slug] in the claude.ai conversation |
| Query latest research | /brain <question> (Claude Code) or brain query "<question>" (terminal) |
| Ask the brain from your phone | Slack DM to the Brain bot in Second-Brain |
| Something seems off with Archon | Check launchctl list | grep ai.roipros + tail ~/.archon/archon.log |
/prime starts every session. The Brain auto-helps when you ask cross-project questions. Use the slash-command loop (/plan-feature → /execute → /code-review → /commit) when you're driving. Use /archon/* commands or @archon mentions when you want to delegate. That's the whole system.