Agile-Board

A delivery pipeline for changing code that already exists, driven by 13 slash commands in Claude Code.

Spec Kit is built for large greenfield phases — starting from a blank page. Agile-Board is for the other 90% of the work: small-to-medium tasks on a living system that must not regress. That inversion drives the whole design.

| | Spec Kit | Agile-Board | |---|---|---| | For | Large greenfield phases | Small/medium changes to existing code | | Starts from | A blank page | A system that must not break | | Key step | Specification | Knowledge of existing code + blast radius | | Risk it manages | Building the wrong thing | Breaking the working thing |

Install

Same command on Windows, macOS and Linux:

npx agile-board-pipeline install         # into the current folder
npx agile-board-pipeline install --user  # into ~/.claude — available in every project

Requires Node 18+. Existing files are backed up as .bak unless you pass --force.

Windows (PowerShell):

.\install.ps1 -ProjectPath C:\path\to\your-repo
.\install.ps1 -User

macOS / Linux:

./install.sh /path/to/your-repo
./install.sh --user

Agile-Board stays out of your repo. The commands, the skills and all working notes are gitignored. Exactly one thing is committed: Agile-Board-Summaries/ — one short human-readable summary per branch, written for reviewers.

Colleagues install it themselves (npx agile-board-pipeline install) and run the three setup commands on their own clone.

Configure once per project

Run /agile-board-git first — it can pull the project down for you, so the other two have something real to describe.

| Order | Command | Creates | Holds | |---|---|---|---| | 1 | /agile-board-git | Agile-Board/GIT.md | Host, repo, default branch, merge method | | 2 | /agile-board-setup | Agile-Board/SETUP.md | Task-ref prefixes + verification gates | | 3 | /agile-board-constitution | Agile-Board/CONSTITUTION.md | The project's non-negotiable rules | | 4 | /agile-board-wiki | Agile-Board/WIKI/ | Per-module map — optional, never blocks |

Nothing else runs until all three exist — the pipeline refuses rather than guessing, because guessed task prefixes produce branches and commits that don't match your board.

Re-run any of them to update. All three stay local (gitignored) — each teammate runs them on their own clone.

Starting from an empty folder

The tidiest way to begin:

mkdir my-project ; cd my-project
# install (see above), then in Claude Code:
/agile-board-git       # pick your repo → it pulls the code down here
/agile-board-setup
/agile-board-constitution
/agile-board-wiki      # optional — map the modules you'll work in
/agile-board           # first task

/agile-board-git uses git init + fetch + checkout rather than git clone — clone refuses to run in a folder that already contains the installed .claude/, so this is the sequence that actually works.

/agile-board-constitution will then offer to draft the constitution from the repo's own AGENTS.md / CLAUDE.md / CONTRIBUTING.md — usually much better than starting blank, since the rules already exist and are just scattered.

Not for brand-new projects

Agile-Board is for changing code that already exists. Its core steps — knowledge of the current code, blast radius, regression guards, rollback — have nothing to work with on a blank page. Starting a project from nothing? Use Spec Kit, then come back here for the maintenance work that follows.

Every command checks for a git repository first and says so plainly rather than failing with a raw git error.

Run a task

/agile-board       ref + title + detailed description → clarify → branch   ⏸ GATE 1
/agile-pre         01-plan-before-knowledge.md   what I must learn         ⏸ GATE 2
/agile-knowledge   02-knowledge.md + BLAST RADIUS                          ⏸ GATE 3
/agile-post        03-plan-after-knowledge.md    the real plan             ⏸ GATE 4
/agile-task        04-task.md + acceptance criteria                        ⏸ GATE 5
/agile-check       consistency check → EXECUTE?                            ⏸ GATE 6
/agile-implement   code + verification gates                               ⏸ GATE 7
/agile-review      review loop → 06-test.md → 07-rollback.md          ⏸ GATES 8–10
/agile-MR          squash, rebase, push, open the merge request            ⏸ GATE 11
/agile-close       after merge: pull, prune, delete branch

Each command ends by naming the recommended next one, so you never have to remember the order. Each is resumable — run them days apart, in fresh sessions.

/agile-knowladge also works, as an alias, if that's what your fingers type.

/agile-board-wiki builds Agile-Board/WIKI/ — a per-module map of what lives where, the house patterns, and the gotchas, so a cold agent starts oriented instead of blind. It refreshes as tasks close. It is strictly a map: it says where to look, never what the code does, and every finding is still verified against the code. Optional — tasks work without it.

How it avoids missing things

The knowledge phase is where quality is won or lost, so it doesn't rely on the agent asking the right questions that day:

• A 10-item coverage checklist answered on every task — callers, callees, house pattern, tests that pin behaviour, the cross-cutting story on the existing path (authorization, rate limit, audit, error shape), failure & restart, data, config, limits, and whether a real person can operate what's being built. The classic miss is item 5: the new path silently skips protections the old path had.
• Mechanical tracing — call sites enumerated by grep and counted, not recalled.
• Contract capture — what the code promises today, written down before it changes. You can't preserve a contract nobody stated.
• Requirement → evidence table — every requirement maps to a finding, or is marked UNANSWERED.
• Surgical scope — the files that must change, and the files that must not.
• An assumption ledger — every assumption CONFIRMED, DESTROYED or UNVERIFIED. An UNVERIFIED one the plan depends on blocks the plan until it's verified, asked about, or explicitly accepted. Listing a risk and proceeding is how an honest gap becomes a hidden one.
• A completeness critic — a fresh-context pass that reads the request and the findings as a stranger and asks only "what's missing?" It's the only step aimed at what nobody thought to ask.
• A question to you — "what depends on this that I can't see in the code?" Client integrations, scheduled jobs, manual processes, business constraints.

How it avoids being confidently wrong

• Approach questions are asked after the code is read, never at intake. Being asked "which mechanism?" before anyone has opened the codebase forces an answer you have no basis for — and every later step is built on it.
• The review runs from a fresh context that sees the diff, the rules and the original request — never the plan or the reasoning that produced the code. An agent that watched itself decide will conclude the decision was sound.
• Red-team before executing — one deliberate pass asking what would make this approach wrong? A design error caught there costs a paragraph.
• Staleness check — if the base branch moved in the files you touch since the knowledge was gathered, those findings get re-verified before any code is written.
• Plan-drift check — files touched that weren't planned, and planned files left untouched, both surface at a gate rather than in production.
• Acceptance criteria are evidenced, each marked met / partial / not-met before the merge request. "Done" stops being a feeling.

Does it actually work? — the scorecard

Every summary ends with four numbers: findings raised, findings that were real, gaps the critic caught, and bugs you found in manual testing that the pipeline missed.

That last one is the only honest measure — the others count what the tool said, not what it missed. If it stays high, the review is blind to a category, and you'll know which one instead of guessing.

The eleven gates

At every gate Claude stops and waits. It summarizes the document in plain language — what it concludes, what surprised it, what it couldn't verify — and you choose: approve & continue / revise / skip ahead / abort.

Two rules keep gates from becoming rubber stamps:

• Summarize, don't just announce. "I wrote the knowledge doc" gives you nothing to approve. You get what you'd need in order to disagree.
• One answer covers one gate. Approving the plan is not approving the implementation. Approving the MR is never approving the merge.

Nothing touches source code before GATE 6. Everything before that is documents, undone by deleting a file.

The review loop

run review → append Cycle N to 05-review-findings.md
  ⏸ apply fixes?   → all / selected / skip → exit
  apply → re-run verification gates
  ⏸ review again?  → yes → loop / skip → exit
auto-exit when a cycle has no High or Medium findings
hard stop at cycle 4 — if High/Medium keep appearing, the approach is wrong

The review reads the diff, not the plan — because the reasoning that produced a bug is exactly what makes the bug look correct on re-reading.

Every finding ends as Fixed, Skipped by user, or Acknowledged — not fixing. A skipped review is recorded as skipped. You can skip anything; you just can't end up with a folder that looks rigorous when it wasn't.

What gets produced

Agile-Board-Summaries/         ← COMMITTED — the only path that ships
  <TASK-REF>.md                one short summary per branch, for reviewers

Agile-Board/                   ← gitignored, all of it
  SETUP.md CONSTITUTION.md GIT.md
  FINDINGS-LEDGER.md            confirmed findings, cumulative across tasks
  <TASK-REF>/
    00-request.md               what was asked, verbatim + clarifications
    01-plan-before-knowledge.md what I must learn before planning
    02-knowledge.md             what I learned + BLAST RADIUS
    03-plan-after-knowledge.md  the real plan, grounded in code
    04-task.md                  ordered steps + acceptance criteria
    05-review-findings.md       append-only review cycles
    06-test.md                  manual test script + expected results
    07-rollback.md              how to undo this

Why almost everything is gitignored: the pipeline squashes to one commit per task. Committing the tooling plus hundreds of lines of notes beside a small diff makes the merge request harder to review and carries that noise downstream.

The branch summary is what ships. Agile-Board-Summaries/<TASK-REF>.md is created when the branch is and rewritten after every step, so it always reads as a current description rather than a diary: why the change was needed, what changed, how it works, why this approach over the alternative, what it affects, how it was verified, deploy notes, and what to watch. One screen, ~60 lines max.

Because the config is local too, teammates don't inherit SETUP.md / CONSTITUTION.md / GIT.md — each person runs the three setup commands on their own clone.

Three sizes, so small tasks stay inside the tool

Not every task earns eight documents. A pipeline too heavy for a twelve-line config fix doesn't get used on twelve-line config fixes — it gets bypassed, and then so does the next one. /agile-board picks the path and tells you which:

| Path | The job | Human stops | |---|---|---| | QUICK | A value, not a behaviour — one file, config/constant/version, revertible in one command | 3 | | LIGHT | One file, real logic, small obvious blast radius | 6 | | FULL | New behaviour, several files, shared code, schema/API | 11 |

The floor never moves: blast radius with evidence, the verification gates, a stop before code, a stop before the MR, a separate stop before the merge, the summary, and recorded skips. If a task turns out bigger than it looked, it gets promoted mid-flight and you're told — never carried on cheaply.

It resumes without remembering

A task spans days; sessions end mid-step. The agent that picks it up has no memory of the one that stopped — so the diff is treated as the truth and the recorded step statuses as a claim. Steps marked done but missing from the diff get redone; steps marked pending but already present get verified, not repeated. Both cases are reported to you rather than quietly reconciled, and documents carry a completion stamp so a file that a dead session got three paragraphs into isn't mistaken for a finished phase.

The rules learn from the findings

Every confirmed review finding is logged to Agile-Board/FINDINGS-LEDGER.md with a category. When the same category shows up on a third different task, that stopped being a finding — it's a rule the constitution is missing, and catching it a fourth time costs three more reviews and three more rounds of rework.

At that point /agile-close proposes an amendment, with the three occurrences as evidence and a rule phrased so a reviewer can check a diff against it. You adopt, reword, decline or defer; a decline is recorded and never raised again. It's the one part of this tool that gets better the longer you use it.

Honest limits

A clean review means the code reads as correct — not that the feature works. It cannot catch behaviour under real production data, integration breakage with third-party services, or performance under load. That's what 06-test.md and a real deployment are for.

The skip options are the quality risk. Skipping occasionally under deadline pressure is fine; skipping habitually turns this into an impressive-looking paper trail around unreviewed code. That's exactly why skips get written down.

What's in the package

bin/cli.js           the npx installer (cross-platform)
.claude/commands/    13 slash commands (+ 1 spelling alias)
.claude/skills/
  agile-board/       the pipeline: SKILL.md + 12 references + doc templates
  agile-review/      the adversarial review protocol
templates/           starting points for SETUP.md, CONSTITUTION.md, GIT.md
install.ps1          Windows installer (no-npm fallback)
install.sh           macOS / Linux installer (no-npm fallback)

License

Apache 2.0 — use it, modify it, build on it commercially.

Two conditions worth knowing: keep the copyright notice and NOTICE file, and if you modify files and redistribute them, say so. The license grants no rights to the name — fork the code freely, but give your fork its own name.

Contributing

Issues and pull requests welcome at github.com/emadbrasil/agile-board.

If you use this on a project and something in the pipeline gets in your way, that's worth an issue — the failure mode this design most fears is ceremony heavy enough that people quietly stop following it.