Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/da0101/agentboard

Two-command AI agent context kit. Drops a .platform/ skeleton + activation prompt into any project — the LLM scans your code, interviews you, and fills the context pack. No stack pre-picking.
https://github.com/da0101/agentboard

Last synced: 19 days ago
JSON representation

Two-command AI agent context kit. Drops a .platform/ skeleton + activation prompt into any project — the LLM scans your code, interviews you, and fills the context pack. No stack pre-picking.

Awesome Lists containing this project

README 

          
# 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.



```bash

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 ` 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



```bash

cd /path/to/project

agentboard init

```



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



```text

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 ` 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/.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:]` 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 (16 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

- `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 ` prints one role file (and activates it manually). To add your own, create `.platform/roles/.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



```text

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



```bash

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  [repo-id ...] [--repo ]

agentboard new-stream  --domain  [--domain  ...] [--type feature] [--agent codex] [--repo repo-primary] [--repo  ...]

agentboard resolve 

agentboard role list

agentboard role show 

agentboard handoff [stream-slug] [--budget ]

agentboard checkpoint  --what "..." --next "..." [--provider 
] [--type ] [--diff]

agentboard close 

agentboard close  --confirm

agentboard brief [--all]

agentboard watch [--interval ] [--once] [--install] [--uninstall] [--status]

agentboard install-hooks [--force] [--dry-run] [--aliases]

agentboard progress  [--base ] [--note ""] [--dry-run]

agentboard status

agentboard add-repo 

agentboard usage log --provider  --input  --output  [--model ] [--stream ] [--repo ] [--type ] [--note ]

agentboard usage summary

agentboard usage history

agentboard usage stream 

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 `); 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 ...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



---



## 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](/Users/danilulmashev/Documents/GitHub/agentboard/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:



```bash

agentboard update

agentboard migrate

agentboard migrate --apply

agentboard brief-upgrade  --apply

agentboard doctor

```



Use `brief-upgrade ` 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](/Users/danilulmashev/Documents/GitHub/agentboard/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



```bash

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:



```bash

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

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

```



---



## License



MIT