accord

A contract for AI-assisted software delivery.

Accord adds a small, fixed folder to your repository. Before an agent writes code, that folder records what a feature is for, what it must do, how it must look, and how you will know it is done. Afterwards the work is verified against those same acceptance criteria. A CLI checks the contract deterministically, so an agent cannot skip it.

BA, designer, developer and reviewer are four stages a ticket passes through, not four job titles. One person can pass through all four, or four people on a team can divide them. No gate reads who anyone is, so the same rules hold either way.

Released: @accord-dev/[email protected] on npm. See docs/design.md for the design and the reasoning behind it.

The problem

AI coding agents produce features that pass their own tests and still miss what the user meant. The largest measured cause is an agent ignoring instructions it already had, not a missing spec. The second is a spec that never captured intent, and verification done without acceptance criteria to check against. Accord addresses both. Whoever holds the intent captures it and the acceptance criteria up front, and a Done gate checks the result against those criteria, independently of the agent that built it.

What it is

• A folder convention. A fixed accord/ folder at the repository root holds config.yml, product/ (glossary, business rules, conventions), tickets/<id>.md (epics, stories and bugs are all tickets; a story names its epic with parent:), tickets/<id>/ (the ticket's records, such as tickets/<id>/verification.md), and assets/<id>/ (designer-owned prototypes). Tracker links are a tracker: map keyed by adapter, for example tracker: { github-issues: "1234" }.
• Plain-text formats that a person and a model can both read and a linter can check: EARS for requirements, Gherkin for acceptance criteria, and YAML frontmatter with a JSON schema.
• Gates. Ready passes before work starts. Done passes only when a fresh agent context, not the one that wrote the code, has verified the work against the acceptance criteria and the test evidence matches.
• A workflow shipped as skill files, one definition each, rendered for every coding agent you list: Claude Code, Codex, Cursor and Copilot.
• Lanes sized to the work, each ticket worked in its own git worktree. See Usage.
• Tests as evidence, never as a claim. accord task-done and accord gate done read only the JUnit report that tests.report names in config.yml. The CLI never runs a test command itself.
• Trackers, design tools and a future multi-repo hub are adapters, never requirements. The default tracker is none.

What it is not

• Not another spec-generation CLI. It sits beside whatever agent you already work through, and does not replace it.
• Not a ticket system. Your tracker stays your tracker.
• Not a database. Git is the only source of truth: the contract is files in your repository, versioned with the code it describes.

Usage

1. Requirements

Node 22.12 or newer. Run accord through npx with an exact version, so nothing needs installing:

npx --yes @accord-dev/[email protected] <command>

Or install it globally and run accord <command>:

npm i -g @accord-dev/[email protected]

The global install must be the same version the repository pins (see Version pin).

2. Initialise a repository

In the repository root:

npx --yes @accord-dev/[email protected] init

init asks nothing and takes no options. It never overwrites accord/config.yml, the product files or the workflow when they exist. The skill, agent and pane copies are accord's own and are rewritten to this version, and the hooks are merged into existing settings. Each path is printed as created, skipped, appended, updated, unchanged or overwrote local edits. It writes:

• accord/config.yml, pinned to the running version, with runtimes: [claude, codex] and a comment on every key.
• accord/product/glossary.md, accord/product/business-rules.md and accord/product/conventions.md, from templates.
• .github/workflows/accord.yml, a GitHub Actions workflow that runs lint and gate done on the tickets a pull request changes, with the same pinned version.
• The skills: /accord and the stage skills accord-intent, accord-approach, accord-plan, accord-build, accord-review, accord-verify and accord-debug, plus accord-designer for the designer role in roles:. Claude Code reads them from .claude/skills/, Codex from .agents/skills/.
• For Claude Code only: the accord agents in .claude/agents/, the dashboard pane plugin in .claude/accord-panel/, and in .claude/settings.json the session hooks and the keys that enable the pane. Existing settings are kept.
• A short accord block appended to AGENTS.md and CLAUDE.md, or those files created.

Then edit accord/config.yml. Before the first ticket that carries a @test: scenario, remove the # from the commented tests: and report: lines at its end, and set report: to the JUnit report your test runner writes.

3. Commit what init wrote

git status   # check the list holds only what init printed
git add accord .github .claude .agents AGENTS.md CLAUDE.md   # leave out any of these init did not print
git commit -m "accord init"
git push

Teammates get the same skills, hooks and pane by pulling. The skills run a bare accord command. In Claude Code, the session hook tells the agent to run it through npx at the pinned version when accord is not on PATH. In Codex, Cursor and Copilot there is no such hook, so each person installs the pinned version globally (npm i -g @accord-dev/[email protected]).

4. Daily use in your coding agent

All work starts from the /accord skill inside the agent session:

| Command | What it does | |---|---| | /accord | The dashboard: your tickets, the team's, and what is ready to pick up, with the actions that apply. | | /accord <request> | New work. Accord proposes a lane with its reason; you may override it. | | /accord continue <id> | Resume a ticket at the stage and step it reached. | | /accord pick-up <id> | Claim an unclaimed ticket and start it. | | /accord upgrade | Move the repository to a newer accord release (see Version pin). |

Lanes:

• S, a small fix (a bug, a copy change, one flag). The session writes one line for what it understood and one for when it is done, makes the change, runs the affected tests, and runs review rounds with a fresh reviewer until no Must finding is open. Then gate done and a pull request.

• M, a feature (one story). It passes through six stages, each a skill you can also call directly:

  1. intent (accord-intent): an interview that writes the intent, acceptance criteria, vetoes and decisions.
  2. approach (accord-approach): the planner drafts the lightest approach that works, a critic argues against it in rounds accord round <id> --approach counts, and the owner approves it.
  3. plan (accord-plan): a task-by-task plan checked by accord gate plan.
  4. build (accord-build): one fresh executor per task, each recorded with accord task-done.
  5. review (accord-review): reviewers until no Must is open and every Should is fixed.
  6. verify (accord-verify): a fresh verifier checks each criterion, writes verification.md, and accord gate done runs once the owner approves.

  accord-debug finds a root cause before any fix when something fails for a reason nobody has shown.

• L (an epic) and P (a project) are not built yet. Accord proposes splitting such work into lane M tickets linked by depends_on.

A request moves from S to M when it changes a public interface or schema, touches a listed sensitive area or auth, money or data deletion, has more than one plausible reading that one question cannot settle, or is expected to touch more than 5 files or more than 3 code areas, tests and generated copies not counted. A scout reads the code before any lane is proposed, a lane S ticket records the files it expects to touch, and accord gate done fails it when it touches others. A lane only rises, except that a lane M ticket whose intent is not yet approved may move to lane S in place, keeping its id, branch and worktree.

Each ticket is worked in its own git worktree, the sibling folder <repository folder>-<id in lower case>, prepared by the setup commands listed in config.yml. accord worktree open <id> prints the folder and the /accord continue <id> line to type in a session opened there. Tickets done on the remote main branch have their worktree and branches removed by accord worktree clean, which /accord runs.

In Claude Code, the pane shows the dashboard beside the chat.

5. Other runtimes

runtimes: in accord/config.yml decides which skill folders accord writes. claude writes .claude/skills/ and also the agents, the pane and the hooks; codex writes .agents/skills/. Cursor and Copilot read both folders, so the default runtimes: [claude, codex] already serves all four tools, and listing cursor or copilot adds nothing.

After you change runtimes:, write the copies again and commit what it prints:

npx --yes @accord-dev/[email protected] skills sync

skills sync deletes no copy you may still use. When you remove a runtime, it lists the copies it no longer writes, and you delete them yourself. The one file it deletes is .claude/agents/accord-architect.md, an agent accord no longer has, and only while its marker shows nobody edited it: it prints removed for it, and lists an edited copy with the others.

6. CLI commands for people and CI

The skills call the CLI for you. These are the commands most useful to run by hand or in CI. Bare accord needs the global install at the pinned version; without it, put npx --yes @accord-dev/[email protected] in place of accord. Run accord --help for the full list, and accord <command> --help for each one.

| Command | What it does | |---|---| | accord lint [--json] | Report every finding in the accord folder. | | accord gate ready <id> | Report whether the ticket passes the Ready gate. | | accord gate plan <id> | Report whether the ticket passes the plan gate. | | accord gate done <id> | Report whether the ticket passes the Done gate. | | accord status [--json] [--all] | Print one row per ticket; --all includes archived tickets. | | accord dashboard [--json] | Print the ranked dashboard sections for you. | | accord show <id> [--json] | Print one ticket: its intent and each criterion with its state. | | accord new ticket [id] | Write accord/tickets/<id>.md from the template. | | accord skills sync | Write every skill the config declares into .claude/skills/ and .agents/skills/. | | accord worktree open <id> | Find or prepare the ticket's worktree. | | accord worktree clean | Remove worktrees and branches of tickets done on the default branch. |

7. Version pin and upgrading

accord/config.yml pins an exact version in its accord: key, and the CI workflow and Claude Code hooks use the same one. Every command that reads the repository refuses with exit 2 when the running version differs (on a version mismatch the prompt-expansion and pre-tool-use hooks only warn, so the prompt or the agent dispatch goes on), and names the command to run instead, with the pinned version in place of 0.4.0:

npx --yes @accord-dev/[email protected] <command>

There is no flag or environment variable that skips the check. Only --version, --help and upgrade run regardless.

/accord says when a newer release is out. /accord upgrade runs upgrade as the newer version, which pushes a branch upgrade/<version> from the remote default branch with one commit that moves the pin and regenerates the skill files. Your checkout is not touched; merge the pull request to upgrade. A repository still pinned to 0.1.0 runs npx --yes @accord-dev/[email protected] upgrade once by hand.

Exit codes:

| Code | Meaning | |---|---| | 0 | Gate passed, or lint clean (warnings allowed). | | 1 | Gate failed, or lint found errors. The reasons are printed. | | 2 | Usage or environment error: bad arguments, no accord folder, unreadable config, version mismatch. |

8. Running main from a clone

To work on accord itself:

npm install
npm run build
npm rebuild @accord-dev/accord

The last step links the accord command that the skills call. After pulling a version bump, run npm run build again, or the workspace CLI reports the old version and every command refuses on the pin.

License

MIT. See LICENSE.