brindley
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/brindley-logo-dark.svg">
<img alt="Brindley ā Design fully before anyone digs" src="assets/brindley-logo.svg" width="300">
</picture>
Plan work as Markdown in your git repo. Settle every open question with your AI agent, then hand
it over to build ā with an MCP server that keeps it all straight.
**š Documentation: [duckasteroid.github.io/brindley](https://duckasteroid.github.io/brindley/)**
ā [getting started](https://duckasteroid.github.io/brindley/guide/getting-started),
[concepts](https://duckasteroid.github.io/brindley/guide/concepts),
[the workflow](https://duckasteroid.github.io/brindley/guide/workflow),
[why "Brindley"?](https://duckasteroid.github.io/brindley/story)
## Quick start
For Claude Code, install the plugin once and it works in every repo (Node 20+ and git):
```sh
claude plugin install brindley --marketplace duckAsteroid/brindley
```
It brings the MCP server at a pinned version, the workflows as skills (`/brindley:design-review`,
`/brindley:implement`, `/brindley:spike`, `/brindley:triage`) and an implementer agent. Allow its
tools with the permission rule `mcp__plugin_brindley_brindley`.
Then ask your agent to *"make `docs/plans` a collection"*. For the people outside the team,
`npx -y brindley@latest report` writes a one-page progress report from the collections and their
git history ([example](https://duckasteroid.github.io/brindley/guide/reporting)). Without the plugin
(`claude mcp add -s user brindley -- npx -y brindley@latest`) and for other MCP clients (opencode,
ā¦), see [getting started](https://duckasteroid.github.io/brindley/guide/getting-started).
## Developing Brindley
```sh
npm test # unit + MCP-level tests
npm run build # stamps the version, compiles to dist/
npm run version:explain # how the current version is computed
cd site && npm install && npm run dev # the documentation site
```
The version comes from git: the last `vX.Y.Z` tag, bumped by the Conventional Commits since it
(`feat` ā minor, `fix`/`perf` ā patch, `!` ā major), with `-SNAPSHOT` off-tag ā the same rules as
[gradle-versioning](https://github.com/duckAsteroid/gradle-versioning). Release with
`npm run release:prepare`, which commits the next version into the Claude Code plugin (`plugin/`),
then tag and push ā `git tag -a v1.0.0 -m "<highlights>" && git push origin main v1.0.0` ā and the
Release workflow checks the plugin names the tag's version, validates it, tests, publishes to npm
(with provenance) and creates a GitHub Release. Its notes, and the site's
[Releases](https://duckasteroid.github.io/brindley/releases) page, come from
`node scripts/changelog.mjs`: the annotated tag's message as highlights (optional ā a plain tag
gives none), then the `feat`, `fix`, `perf` and breaking commits since the previous release.
Design documents: [FORMAT.md](FORMAT.md) (the file format) and [MCP-SERVER.md](MCP-SERVER.md)
(the server). Documentation pages live in [`site/`](site/) and publish to GitHub Pages on push.
## Licence
[MIT](LICENSE) Ā© 2026 Chris Senior
TDQS
Scored across 35 tools
Most tools target a distinct resource+action: collections, initiatives, questions, dependencies, milestones, tags and docs each get their own verbs, and descriptions pre-empt common confusions (update says 'to change a recorded status, use set_status'; fix says 'padding is fixed by repad, numbers by renumber'). Residual overlap exists in the repair cluster (validate/fix/repad/renumber/tidy), the readiness pair (ready lists workable initiatives vs check_ready gates a single one) and update vs batch_update, but these are distinguishable with care.
There is an implicit split ā bare-noun query tools (collections, tags, milestones, questions, fields, graph, report) and bare-verb mutation tools (create, update, get, complete, fix, tidy, repad, renumber) ā alongside consistent verb_noun tools (set_status, add_question, check_ready, create_collection). This is readable and partly intentional, but it is not one predictable pattern: 'list' lacks a noun while 'collections' has no verb, and create/update sit next to create_collection/update_collection style names.
At 35 tools the surface is heavy for a ticket/initiative server; an agent must scan a long catalogue to find the right verb. Many are individually justified by the git-aware domain, but several clusters (fix/repad/renumber/tidy, validate/check_docs/check_ready) could be consolidated into fewer tools with mode parameters.
Coverage of the stated domain is strong: full initiative lifecycle (create/get/list/update/batch_update/set_status/complete), questions (add/split/resolve/next/list), dependencies and graph, collections management, milestones, tags, validation and repair, docs linting, briefs, reports and worktree switching. Minor gaps: no way to delete/remove an initiative (mitigated by abandoned/superseded statuses), no tool to create milestones or arbitrary docs, and no explicit search beyond list filters.