Skip to main content
Glama

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/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). 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 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. 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 tools
add_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.

briefA
Read-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_docsA
Read-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_readyA
Read-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.

collectionsB
Read-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.

fieldsA
Read-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.

getB
Read-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.

graphA
Read-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.

listC
Read-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.

milestonesA
Read-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_questionA
Read-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.

questionsA
Read-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.

readyB
Read-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.

tagsA
Read-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.

validateA
Read-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.

versionA
Read-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

    B3.4/5.0

    Scored across 35 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers