ADE / Guide / Training
Quick training · two 15-minute tracks

Learn ADE and the agent hub by doing

Two short, hands-on tracks. Each step has the exact command or click and what you should see. Shortcuts show macOS first, then Linux.

Track 1 · ADEInstall, set up a project, plan → approve → shard → build → verify, sub-terminals, the stage board. Track 2 · Agent hubMake a hub, the first session, focus terminals, the brain, the journal, auto sync and the briefing.
Track 1 · about 15 minutes

ADE: one project, from plan to a verified story

You need macOS or Linux, git, and Claude Code (npm install -g @anthropic-ai/claude-code).

Track 1 at a glanceEleven steps: install, a practice project, project setup, start an agent, then plan, approve, shard, build and verify, then the stage board and a sub-terminal.1Install2Project3Setup4Agent5Plan6Approve7Shard8Build9Verify10Stage board11Sub-terminalSteps 5 to 9 are the flow: Plan → Approve → Shard → Build → Verify

  1. Install ADE

    curl -fsSL https://ade.ardata.tech/install.sh | bash

    It picks the build for your machine, checks it against the release's SHA256SUMS and installs without sudo. Run it again later to upgrade. You can also use the download page.

    Installing ADEThe install script picks the build for this machine, checks it against the release's SHA256SUMS, and installs without sudo: into /Applications on macOS or ~/.local/bin on Linux.curl -fsSL …/install.sh | bashPicks the build for this machine.dmg on macOS · AppImage on LinuxChecks it against SHA256SUMSfrom the release, before installingmacOS/ApplicationsLinux~/.local/binNo sudo · run it again later to upgrade
    You should seeADE in /Applications on macOS, or the AppImage in ~/.local/bin on Linux.

  2. Make a tiny practice project

    mkdir -p ~/Project/hello-ade && cd ~/Project/hello-ade && git init

    Launch ADE. It opens with one terminal in your home folder and a short tour. Then cd ~/Project/hello-ade in that terminal.

    A practice projectIn ADE's first terminal, cd into the new hello-ade repo; the file browser and fleet view follow the terminal there.$ cd ~/Project/hello-adein ADE's first terminalFile browserfollows the terminalFleet viewfollows the terminal~/Project/hello-ade/an empty git repo (git init)
    You should seethe file browser and fleet view follow the terminal into hello-ade.

  3. Let project setup run

    The first time a terminal enters a project ADE has no record of, it sets it up for agents, adding only files that are missing. Opened from the New tab dialog, it first asks BMAD v6 (default) or BMAD v4; set up any other way, it gets v6. You can also run Project: Set up BMAD, methodology and agents from the command palette (⌘P / Ctrl+Shift+P).

    What project setup addsProject setup adds only missing files: the eight role agents in .claude/agents, BMAD v6 skills in .claude/skills, the _bmad folder, the rules in .ade/rules.md, the .ade/methodology choice, and CLAUDE.md, which loads the rules.hello-ade/.claude/agents/the eight roles.claude/skills/BMAD v6 skills_bmad/config, ade-runtime.mjs.ade/rules.mdthe rules.ade/methodologyv6 or v4CLAUDE.mdloads the rulesproduct-managerarchitectdesignerscrum-masterdeveloperqadevopsadversarial-reviewer
    You should seea toast, then .claude/agents/ with eight roles (product manager, architect, designer, scrum master, developer, QA, DevOps, adversarial reviewer), BMAD v6 skills in .claude/skills/, _bmad/, and the rules in .ade/rules.md, loaded from CLAUDE.md.

  4. Start an agent

    Type claude, or press ⌘⇧A / Ctrl+Alt+Shift+A for the agent picker. For longer prompts, open the scratchpad with ⌘J / Ctrl+Shift+J and send with ⌘↵ / Ctrl+Enter.

    Three ways to start an agentType claude, open the agent picker with Command-Shift-A, or write a longer prompt in the scratchpad with Command-J and send it with Command-Enter. Each starts Claude Code in the project with the eight roles available as sub-agents.Type itclaudeAgent picker⌘⇧AScratchpad⌘J, send ⌘↵Claude Code in hello-adethe eight roles available as sub-agentsLinux: Ctrl+Alt+Shift+A · Ctrl+Shift+J · Ctrl+Enter
    You should seeClaude Code running in the project, with the eight roles available as sub-agents.

  5. Plan: ask the planning roles

    The work flows in five steps:

    Plan→Approve→Shard→Build→Verify

    Ask by name, for example:

    Use the product-manager agent to write a PRD for a CLI that adds two numbers.
Then use the architect agent to write the architecture, with one verification command.
    Planning roles and their documentsYou ask the product-manager agent for docs/prd.md and the architect agent for docs/architecture.md, which names the one verification command. On v6, BMAD skills write under _bmad-output.You ask by nameproduct-managerarchitectdocs/prd.mdwhat to builddocs/architecture.mdnames the verify commandOn v6, BMAD skills write under _bmad-output/
    You should seedocs/prd.md and docs/architecture.md, which names the one verification command (for example npm test) under "Verification command". On v6, BMAD skills write their documents under _bmad-output/; where the two differ, the BMAD location is the one to use.

  6. Approve, after the skeptic

    Have the adversarial-reviewer look at the PRD and the architecture.

    Fix what it blocks on, then approve the plan yourself. Approval fixes the verification command; changing it later needs your approval again.

    Approval after the skepticThe adversarial reviewer reads the PRD and architecture and reports findings by severity. Fix what it blocks on and repeat, then approve the plan yourself, which fixes the verification command and adds a dated line to .ade/session.md.PRD + architectureadversarial-reviewerfindings by severityblocks?fix itYou approvefixes the verification command.ade/session.mda dated journal line
    You should seea review with findings by severity, and after you approve, a dated line in the journal .ade/session.md.

  7. Shard into stories

    Use the scrum-master agent to shard the plan into stories.
    Sharding into storiesThe scrum-master agent slices the approved plan into small, independently testable stories, one file each in docs/stories, with a journal line per story.Approved planscrum-masterdocs/stories/Story 1Story 2Story 3small, independently testable · a journal line each
    You should seesmall, independently testable stories in docs/stories/, one file each, and a journal line per story.

  8. Build one story, test-first

    Use the developer agent to build story 1, test-first.

    The developer writes the failing test, then the code, runs the verification command and reports its real output. It does not mark the story Done. Several developers can run in parallel, each in its own git worktree.

    Test-first buildThe developer writes a failing test, writes the code, runs the verification command and reports its real output; it never marks the story Done. Several developers can work at once, each in its own git worktree.1 Write the failing testred2 Write the code3 Run the verification commandgreen4 Report the real outputit does not mark the story DoneSeveral at once: each developer in its own git worktreedeveloperworktree Adeveloperworktree B
    You should seea new test, the code, and the command's output in the agent's report.

  9. Verify: the only path to Done

    Use the qa agent to verify story 1.
    The verification gateThe qa agent runs the verification command on the story. If it passes, the story is Done, with the real output recorded in its Verification section and a journal line. If it fails, the story is not Done. No agent certifies its own work.Story 1qaruns the verification commandpasses?Not Doneno agent certifiesits own workDoneoutput recorded · journal line
    You should seethe real output recorded in the story's Verification section and a journal line. A story is Done only when the verification command passes; no agent certifies its own work.

  10. Watch it on the stage board

    Open it with ⌘⇧Y / Ctrl+Alt+Shift+Y (View: Toggle stage board). On a v6 project it maps BMAD's four phases (Analysis, Planning, Implementation, Validation) and refreshes as agents write files. You can Approve a draft and Dispatch an approved story to a developer agent in a new tab.

    The stage boardCommand-Shift-Y opens the stage board. On a v6 project it maps BMAD's four phases, Analysis, Planning, Implementation and Validation, and refreshes as agents write files. Approve a draft, Dispatch an approved story to a developer, and a story that says it is done without a passing QA gate shows as claimed.AnalysisPlanningImplementationValidationproduct briefprd.mdarchitecture.mdstory 2Approvestory 1Dispatchstory 1 · Donestory 3 · claimed⌘⇧Y / Ctrl+Alt+Shift+Y · refreshes as agents write files
    You should seeyour documents listed by phase; a story that says it is done without a passing QA gate shows as claimed.

  11. Run a side shell with a sub-terminal

    Right-click the tab and choose New Sub-terminal. Switch between a tab's sub-terminals with ⌘[ and ⌘] (Ctrl+Shift+[ and Ctrl+Shift+] on Linux). Closing one that is still running something asks first.

    Sub-terminalsRight-click a tab and choose New Sub-terminal to get a second shell in the same tab and folder. Switch between them with Command-[ and Command-] (Ctrl+Shift+[ and ] on Linux). Closing one that is still running something asks first.hello-aderight-click →New Sub-terminalagent: claudeside: npm test⌘[ ⌘]Still running? Closing asks firstLinux: Ctrl+Shift+[ and Ctrl+Shift+]
    You should seea second shell in the same tab and folder, for a test watcher or a dev server beside the agent.

Check yourself

  • Where do the eight role agents live, and what file holds the rules? (.claude/agents/, .ade/rules.md)
  • Which document names the verification command, and who can change it? (docs/architecture.md; only with your approval)
  • Who marks a story Done? (Nobody by assertion: only a passing verification command, recorded by QA or you.)
  • How do you open the stage board and switch sub-terminals?

Go deeper: Project setup, Agents & fleet, Keyboard shortcuts.

Track 2 · about 15 minutes

Agent hub: a persona that remembers one client's work

The ai-agent-hub-template is private for now; this track assumes you have access. You need macOS, git, gh, Claude Code, and gitleaks for auto sync. Ollama is optional.

Track 2 at a glanceTen steps: pick a persona, make the hub, commit hub.conf, link and check this Mac, the first session, then the daily loop of focus terminal, brain, journal and sync, and finally the scheduled jobs.1Persona2Make hub3Commit4Link, check5Session6Focus term.7Brain8Journal9Sync10ScheduleSteps 6 to 9 are the daily loop: work, search, write it down, sync

  1. Pick a persona

    gh repo create my-acme-sre --private --template alvin-reyes/ai-agent-hub-template --clone
cd my-acme-sre
bin/init --list
    Picking a personaCreate the hub from the template, then bin/init --list shows the thirteen personas. The example uses DevOps / SRE.gh repo create my-acme-sre --template …bin/init --listStaff Software EngineerDevOps / SREData EngineerML / AI EngineerFrontend EngineerMobile EngineerQA / Test EngineerSecurity EngineerSolutions ArchitectTech LeadEngineering ManagerTechnical Product ManagerFractional CTO13 personas · the example uses DevOps / SRE
    You should seethe personas: staff software engineer, DevOps/SRE, data, ML/AI, frontend, mobile, QA, security, solutions architect, tech lead, engineering manager, technical product manager, fractional CTO.

  2. Make the hub

    bin/init --persona devops-sre --client "Acme Corp" --owner "Sam Lee" \
  --repo acme/infra=~/code/infra --briefing 08:00

    Without GitHub, add --dest ~/Project/acme-sre to copy the template to a new folder first.

    bin/init makes the hubbin/init takes the persona, client, owner, repo and briefing time, and writes hub.conf (names and locations, never secrets), the persona in CLAUDE.md, and one folder per work area: ops/environments, ops/ci-cd, ops/monitoring and ops/security.--persona devops-sre--client "Acme Corp"--owner "Sam Lee"--repo acme/infra--briefing 08:00bin/inithub.confCLAUDE.mdops/environmentsops/ci-cdops/monitoringops/securityhub.conf holds names and locations, never secrets
    You should seehub.conf (names and locations, never secrets), the persona in CLAUDE.md, and one folder per work area, such as ops/environments.

  3. Commit hub.conf once, by hand

    git add -A && git commit -m "Initialize the hub" && git push -u origin main

    bin/init commits nothing and bin/sync leaves hub.conf out, so this is the one commit you make yourself. push -u also sets the upstream auto sync needs.

    The one commit you make by handCommit hub.conf yourself and push with -u: bin/init commits nothing, bin/sync leaves hub.conf out, and -u sets the upstream auto sync needs.hub.confgit add -A && git commitgit push -u origin mainThe hub on GitHubbin/init commits nothingbin/sync leaves it out-u sets the upstreamauto sync needsthe one commit you make
    You should seethe hub on GitHub, with hub.conf in it.

  4. Link it to Claude, and check this Mac

    bin/setup && bin/doctor
    Linking and checking this Macbin/setup links Claude's auto-memory for the hub, its folders and their checkouts into the repo and sets the git hooks path. bin/doctor reports OK or MISSING per tool, login, repo, box and secret name, and never prints a secret.bin/setupbin/doctorLinksClaude's auto-memory forthe hub, every folder andtheir checkoutsSets the git hooks pathtoolsOKloginsOKreposOKthe boxMISSINGsecret namesOKbin/doctor never prints a secret
    You should seeOK or MISSING per tool, login, repo, box and secret name. bin/doctor never prints a secret.

  5. First session in the hub

    claude
    The first sessionStarting claude in the hub runs the SessionStart hook, bin/context, which reads each folder's STATE.md, so the session starts with what is live, open and waiting.$ claudeSessionStart hookbin/contextops/environmentsSTATE.mdops/ci-cdSTATE.mdops/monitoringSTATE.mdThe session starts withwhat is live, open and waiting
    You should seethe session start with what is live, open and waiting, from each folder's STATE.md.

  6. Open a focus terminal

    bin/work ops/environments
bin/work --model opus --prompt "Check the last pipeline run" ops/ci-cd

    Each folder opens in its own Terminal, in the folder's repo checkout, with its named agent and hooks. --model sets the session's model; --agent-model sets the folder's specialist agents.

    A focus terminalbin/work opens the folder in a new Terminal, in its repo checkout, with its named agent, its hooks and the model you choose; other terminals hear what it changed on their next prompt.bin/work --model opus ops/environmentsTerminal · ops/environmentscheckout~/code/infraagentops-environmentsmodelopushooksthe folder'sOther terminalshear its changes on their next prompt
    You should seea new Terminal window. Other terminals hear what it changed on their next prompt.

  7. Search the brain

    ollama pull nomic-embed-text     # once per Mac, optional
bin/brain index
bin/brain search "what did the client decide about SMS"
    The brainbin/brain index reads the hub's Markdown (STATE, memory, the journal, notes and any brain paths) into .local/brain.db: SQLite FTS5 keywords plus local Ollama vectors. bin/brain search ranks both and returns file, line, heading and a snippet. It stays on this Mac; without Ollama it works keyword only.STATE.mdmemory/journal/notes, docs--brain-pathbin/brain index.local/brain.dbFTS5 keywordsOllama vectorsbin/brain search "what did the client decide…"1 file:line · heading · snippet2 file:line · heading · snippet3 file:line · heading · snippeton this Mac only · keyword only without Ollama
    You should seefile, line, heading and a snippet for each match: SQLite keywords plus local Ollama vectors, on this Mac only. Without Ollama it still works, keyword only.

  8. Write to the journal

    bin/journal ops/environments "Rotated the staging certificate"
    The journalbin/journal appends a dated entry to journal/<UTC date>.md. Other sessions see it as a change notice on their next prompt, bin/context shows recent entries, and the brain indexes it.bin/journal ops/environments "Rotated…"journal/<UTC date>.md## 10:42 UTC · ops/environmentsRotated the staging certificateOther sessionsa change notice on their next promptbin/contextshows the recent entriesThe brainindexes it at session end
    You should seea dated entry in journal/<UTC date>.md, the timeline every agent and hook shares.

  9. Sync, with the secret scan

    bin/sync           # review first
bin/sync --yes     # commit and push the hub's files

    Auto sync (bin/sync --auto) also runs at every focus session's end. It refuses to run without gitleaks, scans every commit to push, retries a rejected push once with a rebase, and never force-pushes or touches the client's code.

    Sync with the secret scanbin/sync commits the hub's files and pushes them. Auto sync refuses to run without gitleaks; the pre-commit hook scans each commit, and the commits to push are scanned again. A rejected push is rebased once and retried. It never force-pushes and never pushes repos/, the client's code.Hub files changedgitleaks installed?Commit (pre-commit scan)Scan commits to pushgit pushRefusedloggedSecret foundnothing pushedRejected?rebase once, retryThe hub on GitHubnever force-pushedNever pushes repos/, the client's code
    You should seethe hub's changes pushed. Auto sync logs one line per run in ~/.agent-hub/<name>/logs/sync.log.

  10. Turn on the scheduled jobs

    bin/schedule install
bin/schedule status
    The scheduled jobsbin/schedule install loads three launchd jobs: the weekday morning briefing at the set time (read-only, on Haiku, into the journal and a notification), bin/monitor every 30 minutes, and bin/sync --auto every 30 minutes.briefingmonitorsync06:0008:0010:0012:00Weekday 08:00 (--briefing): the briefingread-only, on Haiku · journal + notificationbin/monitorevery 30 minutesbin/sync --autoevery 30 minutesbin/schedule install · bin/schedule status
    You should seethree launchd jobs: the weekday morning briefing (read-only, on Haiku, into the journal and a notification), bin/monitor every 30 minutes, and bin/sync --auto every 30 minutes.

Check yourself

  • Which file must you commit by hand, and why? (hub.conf; nothing else commits it)
  • How do you open a focus terminal on one folder with a different model?
  • Where does the brain live, and does it ever leave the Mac? (.local/brain.db, gitignored; no)
  • What does auto sync refuse to do? (Run without gitleaks, force-push, or push the client's code)

Go deeper: the full agent hub guide, with flow diagrams and every setting.