brindley
Brindley is an MCP server for planning work as Markdown "initiatives" in a git repo — settling open questions with an AI agent, tracking dependencies and status, and handing off to implementation.
Collections: mark folders as collections (
create_collection,update_collection,rename_collection), configure statuses, types, tags, scoring dimensions, ignore globs and status folders (ignore); list them with counts (collections).Initiatives: create tickets (auto-numbered across worktrees/branches/history), edit fields and body sections (
create,update,batch_update), inspect one (get) or query many (list,fields,ready,check_ready).Design conversations: surface unresolved questions (
questions,next_question), add, split or settle them into a Decisions section (add_question,split_question,resolve_question).Dependencies & milestones: add/remove blocking and related links with cycle detection (
set_dependencies), visualise the graph as adjacency lists plus Mermaid (graph,milestones).Lifecycle: enforce status transitions (draft → designed → in-progress → done), abandon/supersede with reasons (
set_status), close with a required docs-impact note (complete).Maintenance: lint structure and links (
validate,check_docs), auto-repair obvious findings (fix), renumber collisions, repad widths, move files into status folders, and regenerate README tables/Mermaid (renumber,repad,tidy,regenerate_readmes).Reporting: generate a self-contained one-page HTML progress report from collections and git history (
report); inventory tags and their theme docs (tags).Workflow plumbing: fetch the design-review/implement/spike/triage briefs as text (
brief), switch the server to another git worktree for the session (use_worktree), and read the computed server version (version).
Manages planning initiatives as files in a git repository, using branches, tags, worktrees, and history for numbering, dependency/readiness checks, reporting, and switching the server between worktrees.
Reads and writes Markdown initiative files and collection READMEs, including front-matter, open questions, dependencies, acceptance criteria, generated tables, and Mermaid dependency graphs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@brindley create a new initiative for adding OAuth login"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 — getting started, concepts, the workflow, why "Brindley"?
Quick start
For Claude Code, install the plugin once and it works in every repo (Node 20+ and git):
claude plugin install brindley --marketplace duckAsteroid/brindleyIt 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). Without the plugin
(claude mcp add -s user brindley -- npx -y brindley@latest) and for other MCP clients (opencode,
…), see getting started.
Related MCP server: MCP GitHub Project Manager
Developing Brindley
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 siteThe 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. Release from an up-to-date,
clean main with npm run release -- "<highlights>" (--dry-run to see the version first): it
commits the next version into the Claude Code plugin (plugin/), tags it (annotated with the
highlights; a plain tag without them) and pushes main and the tag together. The steps can also be
run by hand: npm run release:prepare, then
git tag -a v1.0.0 -m "<highlights>" && git push origin main v1.0.0. The tag starts the
Release workflow, which 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 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 (the file format) and MCP-SERVER.md
(the server). Documentation pages live in site/ and publish to GitHub Pages on push.
Licence
MIT © 2026 Chris Senior
Available Tools
35 toolsadd_questionA
Add an open question — one decision per question: pose several as separate questions (warns when the text looks like more than one). It is labelled with the next free label (returned as id); don't write one yourself. A blocking question moves a designed initiative back to draft. Use implementation=true for questions deliberately left to the implementer.
Inputs: ref (required), text (required), collection, implementation.
batch_updateA
Apply update-style changes to many initiatives (tickets/issues) in one call — e.g. recording statuses across an adopted folder. Each entry is a ref plus any of status, reason, type, owner, tags, status_note, docs, dimensions; status: "from-text" takes the status from the initiative's Status: line or ## Status section. Every entry is checked first: if any fails, nothing is written and every failure is returned. dry_run: true shows what each file would get. A milestone this reaches, or stops being reached, is reported under milestones.
Inputs: entries (required), dry_run.
briefARead-only
The brief for one of Brindley's workflows — the text of the prompt of the same name, for agents and skills that cannot fetch MCP prompts: design-review (work through an initiative's open questions with the user), implement (hand-off brief for implementing one initiative), spike (build and measure a spike) or triage (review the initiatives). ref is required except for triage, which takes an optional collection. Follow the brief it returns.
Inputs: workflow (required), ref, collection.
check_docsARead-only
Lint project docs for history phrasing, design debate and links into initiatives (docs must describe only what the code is). Defaults to docs changed vs HEAD.
Inputs: paths.
check_readyARead-only
Is this initiative (ticket/issue) complete and ready to work on? Runs the preflight the implement and spike briefs start with: status, dependencies, blocking open questions, acceptance criteria (or ## Measures for a spike), validation errors. ready: false means stop and report, don't start.
Inputs: ref (required), collection.
collectionsBRead-only
Every collection with its details, counts by initiative status, and number ready.
Inputs: no named parameters.
completeA
Mark an initiative (ticket/issue) done — "close" it. docs_impact is required: the project doc paths updated in this change, or "none: ". Reports which initiatives became ready, and any milestone it reaches (milestones).
Inputs: ref (required), collection, docs_impact.
createB
Create a new initiative (ticket/issue). The number is coined automatically by scanning the working tree, other worktrees, branches and history. A folder path that isn't a collection yet is marked as one. A milestone this reaches, or stops being reached, is reported under milestones.
Inputs: title (required), collection (required), why, goal, +5 more.
create_collectionA
Mark a folder as a collection: adds brindley: 1 and the given details to its README.md front-matter, creating the folder and README if needed. Works on a folder that already holds numbered initiative files. The first collection in a repo also returns the agent-instructions snippet for AGENTS.md / CLAUDE.md.
Inputs: path (required), docs, link, name, +13 more.
fieldsARead-only
Every front-matter field an initiative (ticket/issue) can have in a collection, and the values each accepts: statuses and their aliases, types, tags, scoring dimensions (in ranking order, with any default and whether required), and the free-text fields — with the tool that sets each. Give a collection or an initiative ref; with neither, every collection.
Inputs: ref, collection.
fixA
Repair the validate findings that have one obvious fix, editing text in place (never renaming or moving a file): a broken link whose filename matches exactly one initiative in its collection, depends_on / related front-matter (turned into links under ## Dependencies / ## Related), and open questions without a label (given the labels they are reported with). Anything ambiguous is listed in unfixed. Dry run by default: returns each edit (file, line, before, after); pass dry_run: false to write. Padding is fixed by repad, numbers by renumber.
Inputs: dry_run, collection.
getBRead-only
Full detail of one initiative (ticket/issue), including its dependency report (each dependency classified satisfied / blocking / external / missing), dependants, open questions and acceptance criteria.
Inputs: ref (required), collection.
graphARead-only
Dependency graph as an adjacency list plus Mermaid: a collection's active work, one initiative's neighbourhood, or a tag (theme) across collections.
Inputs: ref, tag, show, arrows, +7 more.
ignoreA
Add or remove a collection's ignore: patterns — numbered files that are not initiatives (companion notes, reviews). .gitignore semantics, relative to the collection folder: # comments, ! re-includes, leading / anchors, trailing / = folder, no / = any depth. Use dry_run to preview which files a change would ignore. Ignored numbers are still never reused.
Inputs: collection (required), add, remove, dry_run.
listCRead-only
List initiatives (a.k.a. tickets or issues) across the repo, or in one collection, optionally filtered.
Inputs: tag, type, owner, ready, +4 more.
milestonesARead-only
Every milestone (a doc with milestone: <slug> front-matter) and where it stands: reached, not reached or unspecified; done against counted members; what is still to do (initiatives and included milestones); unconfirmed external members; and when it was reached, from git history. Give milestone (a slug) for just one, with its members.
Inputs: milestone.
next_questionARead-only
The next unresolved blocking question in one initiative (the first labelled after after, if given), with its label (id) and the count remaining. Drives the design-review conversation.
Inputs: ref (required), after, collection.
questionsARead-only
Unresolved open questions, grouped by initiative. Abandoned and superseded initiatives are left out — dropping the work settles them — unless asked for by ref.
Inputs: ref, collection, include_implementation.
readyBRead-only
Initiatives (tickets/issues) that are designed with nothing blocking — what an agent can pick up now — in suggested order (prerequisites first).
Inputs: type, collection.
regenerate_readmesA
Rebuild the generated README blocks (tables + Mermaid). check=true only reports what is stale (for CI).
Inputs: check, collection.
rename_collectionA
Move a collection to a new folder, rewriting every relative link into it from anywhere in the repo and out of it from inside. If its name comes from its folder (no name: in its README), the name changes too and "#" references by the old name, path or automatic alias are rewritten; explicit aliases are kept. Refuses a destination that exists or is inside another collection, and a new name another collection uses. dry_run: true returns the plan.
Inputs: to (required), collection (required), dry_run.
renumberA
Give an initiative a new number — fixing a number collision after a merge. Renames its file and asset folder (keeping the slug, padded to the collection's width) and rewrites every link and "#" reference to it across the repo. to defaults to the next number, coined as create does. For one file of a duplicate-number pair, pass ref as its path. dry_run: true returns the plan without writing.
Inputs: ref (required), to, dry_run, collection.
repadA
Pad every initiative number in a collection to one width (01-, 001-) — the given width, or the width most of its files use — renaming the files and their asset folders and rewriting every link to them across the repo. Dry run by default: returns each rename and link rewrite; pass dry_run: false to apply. Refuses a width too small for the highest number.
Inputs: collection (required), width, dry_run.
reportA
Write a one-page progress report for people outside the team — a self-contained HTML file (default build/brindley-report.html) — from the collections and their git history: headline figures, work complete against scope over time, what was delivered, added and taken out this period, workstreams, and what needs attention. Returns the file's path and the figures. Changes no initiative.
Inputs: out, mode, since, until, +4 more.
resolve_questionA
Resolve an open question, named by its label (id, e.g. "Q3") or match. Default mode "remove": delete it and record the decision under its label in record_in (default "Decisions", e.g. "Agreed direction"). Mode "tick": keep it as "- [x] Q3 … — answer".
Inputs: ref (required), answer (required), id, mode, +3 more.
set_dependenciesA
Add or remove dependency links. Dependencies are the links under an initiative's ## Dependencies heading (blocking); ## Related links are non-blocking. Adds a bullet with a relative link (and optional why); removes the bullet(s) linking to the target — bullets only: a link inside a paragraph is left in place and reported with its line, to edit by hand. Refuses unknown initiatives and cycles.
Inputs: ref (required), add, why, remove, +3 more.
set_statusA
Change an initiative's (ticket's/issue's) status, enforcing the lifecycle: designed needs no blocking open questions; in-progress needs ready; done goes through complete. Abandoning needs a reason; abandoned, superseded and deferred work gets a callout under its title saying so, which is removed when it is reopened. A milestone this reaches, or stops being reached, is reported under milestones.
Inputs: ref (required), status (required), force, branch, +4 more.
split_questionA
Split an open question that poses several decisions into one question per decision, in its place and order, in one write. Each part is text or { text, implementation?, answer? }: parts inherit the question's (implementation) marker unless they set their own, and a part with an answer is settled as it is written — recorded in record_in (default "Decisions"), or kept ticked with mode "tick", as resolve_question does. Parts are labelled under the question's label (Q3 → Q3.1, Q3.2), and Q3 stops existing. Returns the parts left open with their labels.
Inputs: ref (required), into (required), id, mode, +3 more.
tagsARead-only
Every tag in use plus declared-but-unused ones, with descriptions, counts by status, and the theme overview doc if one exists (a doc whose front-matter says theme: <tag>).
Inputs: no named parameters.
tidyA
For a collection that declares folders: (status → folder), move every initiative to where its status belongs — its folder, or the top of the collection — with its asset folder, rewriting every link to them. Dry run by default: returns each move and link rewrite; pass dry_run: false to apply. Status changes keep things in step after that; tidy is for files already out of place.
Inputs: collection (required), dry_run.
updateA
Edit an initiative's (ticket's/issue's) front-matter fields or H1, or replace a named body section — including on a done initiative, which is how settled work is refined (no status change needed). status records the status an initiative already has when its front-matter has none (no lifecycle checks); to change a recorded status, use set_status. Cannot change its number or filename. A milestone this reaches, or stops being reached, is reported under milestones.
Inputs: ref (required), docs, tags, type, +9 more.
update_collectionC
Edit a collection README's details, including its status (active | done | abandoned).
Inputs: collection (required), docs, link, tags, +13 more.
use_worktreeA
Switch this server to another git worktree of the same repository, for the rest of this session: every later call reads and writes that checkout. Call it right after creating the worktree you will implement in, so initiative edits land in that branch's commit. With no path (or the original checkout's path), switch back — do that after merging, before removing the worktree. Returns the checkout now in use.
Inputs: path.
validateARead-only
Check initiatives and collection structure: missing or unknown statuses, status vs folder vs body-prose disagreements, files not in their collection's status folder, duplicate numbers, dangling references, cycles, broken links (with where a moved file now lives), stale READMEs. Returns errors and warnings with file and line.
Inputs: docs, rules, collection.
versionARead-only
The Brindley server's version (computed from git tags + Conventional Commits) and build commit.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Git collaboration for AI agents and people: tasks, hand-offs, reviews, teams, shared memory.
Shared project docs, task planning and GitHub evidence for people and their AI agents.
Issue tracker for coding agents: a real backlog, plus a risk-ranked review of every change.
Project management for humans and AI agents: goals, metrics, projects, and issues.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to register, self-assign and coordinate tasks, track progress, review work, and manage GitHub Projects v2 with AI-powered PRD generation, sprint planning, issue triage, and PRD-to-issues pipelines backed entirely by GitHub-native storage.272 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents and human managers to orchestrate GitHub-based project work by self-assigning tasks, coordinating swarms, tracking token budgets, generating PRDs, planning sprints, triaging issues, and materializing tasks as GitHub issues, milestones, and project views.272 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents and teams to turn GitHub Projects v2 into an autonomous task substrate for registering, claiming, tracking, reviewing, and completing work, while also supporting AI-powered PRD generation, sprint planning, issue triage, roadmap creation, GitHub Actions/releases/branches, and MCP resources/prompts.272 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to self-assign and coordinate tasks, track progress and token budgets, and automate GitHub project workflows such as PRD-to-issues pipelines, sprint planning, triage, reviews, and releases.272 npmMIT