Agentboard

Shared work-state and project-truth for multi-provider AI workflows. Agentboard gives Claude Code, Codex CLI, and Gemini CLI a common .platform/ pack so each provider loads the same project truth, tracks the same workstreams, and can pick up work another provider started.

cd /path/to/your/project
agentboard init
# then open the project in your AI CLI and say:
# > activate this project

Agentboard scaffolds a .platform/ pack plus root entry files, then hands off to the LLM to scan the actual codebase, ask a few targeted questions, and write project-specific context. No stack picker. No static React/Django/Vite templates pretending to know your repo. The LLM reads the repo and decides.

Status: actively evolving from a proven internal setup used across multi-repo product work. The kit is stack-agnostic; the project-specific intelligence is generated during activation.

---

How it actually works

Agentboard does not move chat history, tool-call state, or in-session memory between providers — nothing does, and pretending otherwise would be dishonest. What Agentboard ships is:

1. A shared project-truth format — .platform/ holds architecture, decisions, domains, conventions, and a live work-stream registry. Plain markdown, readable by any LLM.
2. Provider-neutral entry files — CLAUDE.md, AGENTS.md, and GEMINI.md at the repo root point each CLI at the same .platform/ pack. Claude Code, Codex CLI, and Gemini CLI each auto-load their own entry file on session start.
3. A deterministic handoff packet — agentboard handoff <stream> prints the minimum load order (brief → stream → domains → repos) plus the git branch hint, so the next provider can resume without a full re-brief.
4. A persistent work layer — streams registered in work/ACTIVE.md survive context compaction, session death, and provider switches. What doesn't survive: the chat. What does: the work state.

Result: start a stream in Claude Code, resume it in Codex CLI, finish it in Gemini CLI — each session loads the same files in the same order, with the same stream metadata, and with git as the cross-session edit log.

---

The problem

Every new AI session starts half-blind:

• The agent re-discovers decisions you already made
• The agent loads the wrong files and misses cross-layer constraints
• Parallel sessions collide because there is no shared task registry
• Useful context disappears when the session ends

Agentboard solves that by shipping a reusable process layer and leaving project truth to be written from your codebase during activation.

---

What Agentboard actually is

Agentboard is not just a prompt stub. It gives a project:

• Root entry files: CLAUDE.md, AGENTS.md, GEMINI.md
• A shared .platform/ reference pack
• Workflow skills installed for multiple providers
• Workstream tracking that survives context loss
• Domain-first context files so agents load the right slice of the system
• Optional hub mode for multi-repo platforms

The design split is deliberate:

• Generic, shipped verbatim: workflow rules, onboarding path, sync script, work tracking protocol, repo templates, hooks
• Project-specific, written during activation: architecture, decisions, repos, domain files, conventions, current priorities

When NOT to use Agentboard

Agentboard earns its keep when context has to survive across providers (Claude Code + Codex + Gemini on the same work) or across repos (a hub coordinating several codebases). That's where shared stream files, handoffs, and the memory pack do something no single tool does. If you're a solo developer using only Claude Code on a single repo, there's real overlap with what you already get natively — CLAUDE.md, auto-memory, and built-in session resumption cover much of the same ground, and the checkpoint/log-reason discipline may feel like ceremony. It still buys you structured workstream history and a portable context pack if you later add a second provider or repo, but if that's not on your horizon, native memory alone may be enough.

---

Quick start

Single repo

cd /path/to/project
agentboard init

Then open the repo in Claude Code, Codex CLI, or Gemini CLI and say:

activate this project

Multi-repo platform hub

If you run agentboard init in an empty parent folder or a folder that only contains sibling repos, Agentboard can switch to hub mode.

In hub mode:

1. .platform/ lives in the hub folder
2. .platform/repos.md lists the sibling repos
3. agentboard add-repo <path> scaffolds thin entry files into each sibling repo
4. activation scans the sibling repos, not the hub folder itself

---

CI and merge protection

Agentboard now ships a GitHub Actions merge-gate workflow in .github/workflows/ci.yml.

It runs on:

• pull requests targeting develop
• pull requests targeting main
• direct pushes to develop
• direct pushes to main

The workflow runs:

• unit-tests → bash tests/unit.sh
• integration-tests → bash tests/integration.sh
• ci-gate → final required gate that depends on both jobs

Important: GitHub Actions alone does not block merges. To actually prevent merges when tests fail, you must configure GitHub branch protection or rulesets for both develop and main and mark these checks as required:

• unit-tests
• integration-tests
• ci-gate

Recommended rules for both branches:

• require a pull request before merging
• require status checks to pass before merging
• require branches to be up to date before merging
• include administrators if you want the rule to apply to everyone

If you later add a deploy workflow, make it depend on the same green checks or only allow deploys from protected branches.

---

What agentboard init does

init is intentionally small and generic. It does not make stack-specific decisions.

It:

1. Asks 2 questions: project name and one-line description
2. Copies the .platform/ skeleton
3. Writes root entry stubs if they do not already exist
4. Preserves existing CLAUDE.md, AGENTS.md, and GEMINI.md
5. Installs shared skills into .claude/skills/ and .agents/skills/
6. Installs .claude/settings.json if absent, so Claude Code can enforce closure hooks

If a root entry file already exists, init does not overwrite it. Activation later prepends the Agentboard section and preserves the original content below.

---

What activation does

When you say activate this project, the root entry file tells the agent to read .platform/ACTIVATE.md or .platform/ACTIVATE-HUB.md and follow the activation protocol.

The activation flow is:

1. Scan the repo or sibling repos: tree, manifests, README, env examples, git history, source entry points
2. Interview the user with 5-8 targeted questions
3. Fill the project truth into the .platform/ pack
4. Install or merge the steady-state root entry files without deleting user content
5. Sync AGENTS.md and GEMINI.md from CLAUDE.md where safe
6. Confirm what was written and what still needs review

The agent writes project-specific files from what it actually finds, including:

• .platform/STATUS.md
• .platform/architecture.md
• .platform/memory/decisions.md
• .platform/repos.md
• .platform/domains/*.md
• .platform/conventions/*.md
• .platform/work/BRIEF.md when there is an active focus area

---

Domain-first context

A key design choice is that feature context is domain-first, not repo-first.

Instead of forcing every agent to read:

• backend.md
• frontend.md
• widget.md

for one feature, activation creates focused files like:

• .platform/domains/auth.md
• .platform/domains/orders.md
• .platform/domains/billing.md

Each domain file is cross-layer. It can cover backend, frontend, widget, and API contract for that concern in one place. Repo-wide docs still exist, but they are for conventions and navigation, not feature briefings.

This keeps context small and makes multi-agent work much more reliable.

---

Active work model

Agentboard ships a persistent work layer under .platform/work/:

• BRIEF.md — what the current active feature is, why it matters, what context to load
• ACTIVE.md — registry of live workstreams
• TEMPLATE.md — template for a new workstream
• archive/ — completed workstreams

Streams and domains are meant to carry lightweight metadata so tooling can validate state without turning .platform/ into a database.

The workflow expects non-trivial work to be registered before execution:

1. check work/ACTIVE.md
2. ensure a domain file exists
3. create work/<stream>.md
4. add the stream to ACTIVE.md
5. update BRIEF.md

This is what makes work resumable after context compaction or handoff to another agent.

---

Skills

agentboard init installs a shared skill pack for all providers:

• ab-triage
• ab-workflow
• ab-research
• ab-pm
• ab-architect
• ab-test-writer
• ab-security
• ab-qa
• ab-review
• ab-debug

Install behavior is additive:

• Claude Code gets .claude/skills/
• Codex CLI and Gemini workflows get .agents/skills/
• existing skills with the same name are kept during init

Each skill has a SKILL.md and uses progressive disclosure: the name and description are visible at session start, and the full protocol loads on demand.

Role profiles

Skills cover process stages; role profiles cover who is doing the work. agentboard init also installs .platform/roles/ — a routing index plus one file per role. At the start of a session the agent matches the user's plain-English request against the index (by meaning, not keywords — "make me app for gym" works), adopts the matching role, and announces it with a [role:<slug>] label so you always know which hat it's wearing. No match → it works as a plain pair programmer, no ceremony. Naming a role in chat always overrides the automatic routing.

The shipped roles (17 total):

• product-manager — shapes what to build: requirements, priorities, "is this worth it"
• tech-advisor — research and comparison: "X vs Y", "which database", "how does Z work for us"
• startup-mvp — builds a new product from scratch, scope-ruthless
• feature-builder — adds a feature to an existing product: "add checkout", "build notifications"
• backend-architect — server-side design: APIs, data models, scaling
• frontend-engineer — UI/UX implementation: components, screens, accessibility
• debugger — finds and fixes bugs with root-cause discipline
• perf-engineer — speed, memory, and scalability work
• qa-engineer — test plans, coverage, edge-case hunting, "is this ready to ship"
• security-engineer — security review: auth, permissions, handling user data safely
• code-auditor — honest assessment of existing code; reads, doesn't rewrite
• code-cleanup-engineer — cleans up existing code safely: duplication, dead code, oversized files, comments, housekeeping
• refactor-architect — makes messy working code clean without adding features
• devops-engineer — deploy, CI/CD, containers, monitoring, "the server is down"
• data-analyst — answers from data: metrics, queries, reports, "why are users churning"
• tech-writer — documentation: READMEs, API references, guides, onboarding docs
• pair-programmer — the default for everything else

ab role list prints the routing table; ab role show <slug> prints one role file (and activates it manually). To add your own, create .platform/roles/<slug>.md following any shipped role's structure and add a row to INDEX.md. Don't edit the shipped role files in place — agentboard update refreshes them.

---

What ships in the kit

your-project/
├── CLAUDE.md
├── AGENTS.md
├── GEMINI.md
├── .claude/
│   ├── settings.json
│   └── skills/            (ab-* skill pack)
├── .agents/
│   └── skills/
└── .platform/
    ├── ACTIVATE.md / ACTIVATE-HUB.md
    ├── ONBOARDING.md
    ├── workflow.md
    ├── STATUS.md
    ├── architecture.md
    ├── repos.md
    ├── agents/            (commands.md, context-organization.md, skill-labels.md, …)
    ├── roles/             (role profiles: INDEX.md + one file per role)
    ├── memory/
    │   ├── decisions.md
    │   ├── log.md
    │   ├── learnings.md
    │   ├── gotchas.md
    │   ├── playbook.md
    │   ├── open-questions.md
    │   └── BACKLOG.md
    ├── domains/
    │   └── TEMPLATE.md
    ├── work/
    │   ├── BRIEF.md
    │   ├── ACTIVE.md
    │   ├── TEMPLATE.md
    │   └── archive/
    ├── scripts/
    │   ├── sync-context.sh
    │   └── hooks/
    └── templates/
        └── repo/

After activation, the agent also creates project-specific directories and files such as:

• .platform/conventions/*.md
• .platform/domains/*.md
• .platform/domains/TEMPLATE.md
• per-repo deep references in hub mode

So the shipped scaffold is the operational shell; activation fills in the project-specific content.

---

Commands

agentboard install
agentboard init
agentboard update [--dry-run]
agentboard sync [--apply|--list]
agentboard bootstrap [--apply-domains]
agentboard migrate [--apply]
agentboard brief-upgrade [stream-slug] [--apply]
agentboard doctor
agentboard new-domain <slug> [repo-id ...] [--repo <repo-id>]
agentboard new-stream <slug> --domain <domain-slug> [--domain <domain-slug> ...] [--type feature] [--agent codex] [--repo repo-primary] [--repo <repo-id> ...]
agentboard resolve <stream-slug|stream-id|domain-slug|domain-id|repo-id>
agentboard role list
agentboard role show <slug>
agentboard handoff [stream-slug] [--budget <N|Nk>]
agentboard checkpoint <slug> --what "..." --next "..." [--provider <p>] [--type <t>] [--diff]
agentboard close <slug>
agentboard close <slug> --confirm
agentboard brief [--all]
agentboard watch [--interval <n>] [--once] [--install] [--uninstall] [--status]
agentboard install-hooks [--force] [--dry-run] [--aliases]
agentboard progress <stream-slug> [--base <branch>] [--note "<text>"] [--dry-run]
agentboard status
agentboard add-repo <path>
agentboard usage log --provider <name> --input <N> --output <N> [--model <M>] [--stream <S>] [--repo <R>] [--type <T>] [--note <text>]
agentboard usage summary
agentboard usage history
agentboard usage stream <stream-slug>
agentboard usage dashboard [--today|--week|--month]
agentboard usage optimize
agentboard usage learn [--apply]
agentboard version
agentboard help

Command notes

• install creates a symlink for agentboard in your user bin directory and prints the PATH snippet to add if needed
• init scaffolds the kit into the current directory
• update refreshes shipped process files and skill protocols without touching project-specific docs
• sync keeps AGENTS.md and GEMINI.md aligned with CLAUDE.md
• bootstrap discovers repo layout, fills repos.md, scaffolds missing deep-reference files, infers broad repo roles plus optional stack hints, ingests local project artifacts into repo refs, suggests starter domains from repo structure, suggests stream commands from git branch state and dirty worktree semantics, and syncs hub repo paths into sync-context.sh; use --apply-domains to create the inferred domain stubs
• migrate upgrades legacy pre-frontmatter stream/domain files to metadata v1 when Agentboard can infer the missing fields safely
• brief-upgrade rewrites a legacy multi-stream work/BRIEF.md into the newer single-stream format for one chosen stream
• doctor validates active .platform/ state, stream/domain metadata, domain references, and repo IDs against the repo registry
• new-domain bootstraps a domain file with metadata and can assign multiple repo IDs up front
• new-stream bootstraps a stream file, registers it in work/ACTIVE.md, and seeds work/BRIEF.md when the brief is still a placeholder; repeat --domain and --repo when the stream spans multiple areas or repos
• resolve turns a canonical stream/domain/repo reference into the exact file or repo record to load
• role lists the available role profiles (list) or prints one role file for manual activation (show <slug>); the routing table lives in .platform/roles/INDEX.md
• handoff prints the minimum file load order, repo scope, and current-state summary another LLM needs to resume a stream without a full re-brief; --budget drops secondary domains when token count is tight
• checkpoint saves a compact "where we are" snapshot into the stream file before a context clear, provider switch, or session end; overwrites ## Resume state and prepends a trimmed ## Progress log entry
• close runs in two steps: first call prints the harvest checklist (distill gotchas/decisions/learnings into .platform/memory/); second call with --confirm archives the stream and logs closure
• brief prints the compact session-start briefing: active streams, recent gotchas, open questions, top usage pattern; run this at the start of every session
• watch background poller that auto-checkpoints the active stream whenever tracked files change via git status; --install registers a per-project scheduler (launchd on macOS, systemd on Linux); --aliases on install-hooks wires codex/gemini CLI through the project wrappers globally
• install-hooks installs the full hook stack: Claude Code PreToolUse bash-guard, git pre-commit closure gate, git post-commit activity log, and Codex/Gemini provider wrappers; --aliases writes shell functions to ~/.zshrc/~/.bashrc so codex and gemini auto-route through the project wrappers
• progress appends a git-diff summary (git diff --stat <base>...HEAD) to the stream's ## Progress log section, stamped with timestamp and branch; use this instead of hand-typing what changed
• status prints .platform/STATUS.md
• add-repo scaffolds entry files into a sibling repo in hub mode and refuses to overwrite existing root entry files
• usage log records a token segment to ~/.agentboard/usage.db; usage summary/history/stream/dashboard/learn aggregate and visualise the data — see CHEATSHEET.md for the full reference
• usage optimize surfaces optimization insights from the same database: most expensive task types and streams, provider efficiency comparison, largest individual segments, and streams that need finer checkpointing

---

VS Code extension

A sidebar extension ships in extensions/vscode/. It gives you 5 live panels without leaving your editor:

Panel	What it shows
HUD	Model, branch, token pressure, CI status, cost, risk flags, open PRs
Streams	Active streams + next actions from .platform/work/ACTIVE.md
Catalog	Installed skills, roles, and CLI commands with counts
Sessions	Live agent sessions (role, stream, status, started)
Worktrees	Active git worktrees per stream

Install:

cd extensions/vscode
npm install && npm run compile
npx @vscode/vsce package
code --install-extension agentboard-0.1.0.vsix

Sessions and Worktrees panels require the control plane (ab start). All other panels work with no daemon.

Control plane

ab start launches a Node.js daemon on 127.0.0.1:7842 that tracks agent sessions, manages git worktrees, and routes task delegation:

ab start                                    # start daemon
ab sessions                                 # list active sessions
ab delegate "add rate limiting to the API"  # match task → role → prompt
ab worktree new feature-auth                # create git worktree for a stream
ab stop                                     # stop daemon

The daemon writes agentboard.hud-status.json on every state change — the VS Code extension picks it up instantly.

---

Updating existing installs

As Agentboard evolves, agentboard update lets a project pull in newer process files without clobbering project truth.

For older projects that still use the legacy framework shape, use the dedicated migration flow in MIGRATION_GUIDE.md.

It updates things like:

• workflow.md
• ONBOARDING.md
• ACTIVATE*.md
• .platform/agents/*.md
• shipped convention templates if the kit includes them
• scripts/sync-context.sh
• shipped skills

It does not overwrite project-authored operational state such as:

• architecture.md
• decisions.md
• repos.md
• STATUS.md
• log.md
• work/*
• domains/*

Migrating older projects

If a project already has an older .platform/ layout, the current upgrade path is:

agentboard update
agentboard migrate
agentboard migrate --apply
agentboard brief-upgrade <stream-slug> --apply
agentboard doctor

Use brief-upgrade <stream-slug> without --apply first if you want to preview the rewritten BRIEF before writing it.

The full step-by-step guide lives in MIGRATION_GUIDE.md.

---

Single repo vs hub mode

Single repo

• .platform/ lives beside the app code
• activation scans the current repo
• CLAUDE.md, AGENTS.md, and GEMINI.md live at the repo root

Hub mode

• the hub folder holds .platform/ and shared cross-repo truth
• sibling repos get thin entry stubs
• activation scans all listed sibling repos
• per-repo deep references can point agents back into the shared platform pack

Hub mode is useful when your system is split across backend, frontend, mobile, widget, or infra repos but you still want one shared context brain.

---

Why no stack pre-picking

Traditional scaffolding asks: React or Vue? Django or FastAPI? Postgres or MongoDB?

Agentboard does not, for three reasons:

1. The stack is already visible in the repo
2. Static stack templates go stale quickly
3. The LLM can write rules for the actual project, not generic best practice

The point of the kit is to scaffold the structure and let activation generate the truth.

---

Install

git clone https://github.com/[you]/agentboard ~/code/agentboard
~/code/agentboard/bin/agentboard install

By default, agentboard install symlinks into your user bin directory such as ~/.local/bin/agentboard and tells you what to add to your shell config if that directory is not already on your PATH.

You can also preview or override the target:

~/code/agentboard/bin/agentboard install --dry-run
~/code/agentboard/bin/agentboard install --dir ~/bin

---

License

MIT