@accord-dev/accord 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +158 -13
- package/dist/cli.js +7364 -501
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,31 +2,176 @@
|
|
|
2
2
|
|
|
3
3
|
# accord
|
|
4
4
|
|
|
5
|
-
A
|
|
5
|
+
A contract for AI-assisted software delivery.
|
|
6
6
|
|
|
7
|
-
Accord
|
|
7
|
+
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.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
Released: `@accord-dev/accord@0.3.0` on npm. See [docs/design.md](https://github.com/ngothanhluan/accord/blob/main/docs/design.md) for the design and the reasoning behind it.
|
|
10
12
|
|
|
11
13
|
## The problem
|
|
12
14
|
|
|
13
|
-
AI coding agents produce features that pass their own tests and still miss what the user meant. The largest measured cause is
|
|
15
|
+
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.
|
|
14
16
|
|
|
15
17
|
## What it is
|
|
16
18
|
|
|
17
|
-
- A folder convention
|
|
18
|
-
- Plain-text formats a
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
19
|
+
- 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" }`.
|
|
20
|
+
- 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.
|
|
21
|
+
- 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.
|
|
22
|
+
- A workflow shipped as skill files, one definition each, rendered for every coding agent you list: Claude Code, Codex, Cursor and Copilot.
|
|
23
|
+
- Lanes sized to the work, each ticket worked in its own git worktree. See [Usage](#usage).
|
|
24
|
+
- 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.
|
|
25
|
+
- Trackers, design tools and a future multi-repo hub are adapters, never requirements. The default tracker is `none`.
|
|
23
26
|
|
|
24
27
|
## What it is not
|
|
25
28
|
|
|
26
|
-
- Not another spec-generation CLI. It sits
|
|
29
|
+
- Not another spec-generation CLI. It sits beside whatever agent you already work through, and does not replace it.
|
|
27
30
|
- Not a ticket system. Your tracker stays your tracker.
|
|
28
|
-
- Not a database. Git is the only source of truth
|
|
31
|
+
- Not a database. Git is the only source of truth: the contract is files in your repository, versioned with the code it describes.
|
|
32
|
+
|
|
33
|
+
## Usage
|
|
34
|
+
|
|
35
|
+
### 1. Requirements
|
|
36
|
+
|
|
37
|
+
Node 22.12 or newer. Run accord through npx with an exact version, so nothing needs installing:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npx --yes @accord-dev/accord@0.3.0 <command>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Or install it globally and run `accord <command>`:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
npm i -g @accord-dev/accord@0.3.0
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The global install must be the same version the repository pins (see [Version pin](#7-version-pin-and-upgrading)).
|
|
50
|
+
|
|
51
|
+
### 2. Initialise a repository
|
|
52
|
+
|
|
53
|
+
In the repository root:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
npx --yes @accord-dev/accord@0.3.0 init
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`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:
|
|
60
|
+
|
|
61
|
+
- `accord/config.yml`, pinned to the running version, with `runtimes: [claude, codex]` and a comment on every key.
|
|
62
|
+
- `accord/product/glossary.md`, `accord/product/business-rules.md` and `accord/product/conventions.md`, from templates.
|
|
63
|
+
- `.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.
|
|
64
|
+
- 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/`.
|
|
65
|
+
- 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.
|
|
66
|
+
- A short accord block appended to `AGENTS.md` and `CLAUDE.md`, or those files created.
|
|
67
|
+
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
### 3. Commit what init wrote
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
git status # check the list holds only what init printed
|
|
74
|
+
git add accord .github .claude .agents AGENTS.md CLAUDE.md # leave out any of these init did not print
|
|
75
|
+
git commit -m "accord init"
|
|
76
|
+
git push
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
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/accord@0.3.0`).
|
|
80
|
+
|
|
81
|
+
### 4. Daily use in your coding agent
|
|
82
|
+
|
|
83
|
+
All work starts from the `/accord` skill inside the agent session:
|
|
84
|
+
|
|
85
|
+
| Command | What it does |
|
|
86
|
+
|---|---|
|
|
87
|
+
| `/accord` | The dashboard: your tickets, the team's, and what is ready to pick up, with the actions that apply. |
|
|
88
|
+
| `/accord <request>` | New work. Accord proposes a lane with its reason; you may override it. |
|
|
89
|
+
| `/accord continue <id>` | Resume a ticket at the stage and step it reached. |
|
|
90
|
+
| `/accord pick-up <id>` | Claim an unclaimed ticket and start it. |
|
|
91
|
+
| `/accord upgrade` | Move the repository to a newer accord release (see [Version pin](#7-version-pin-and-upgrading)). |
|
|
92
|
+
|
|
93
|
+
Lanes:
|
|
94
|
+
|
|
95
|
+
- 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.
|
|
96
|
+
- M, a feature (one story). It passes through six stages, each a skill you can also call directly:
|
|
97
|
+
1. intent (`accord-intent`): an interview that writes the intent, acceptance criteria, vetoes and decisions.
|
|
98
|
+
2. approach (`accord-approach`): the lightest approach that works, argued against by a critic, approved by the owner.
|
|
99
|
+
3. plan (`accord-plan`): a task-by-task plan checked by `accord gate plan`.
|
|
100
|
+
4. build (`accord-build`): one fresh executor per task, each recorded with `accord task-done`.
|
|
101
|
+
5. review (`accord-review`): reviewers until no Must is open and every Should is fixed.
|
|
102
|
+
6. verify (`accord-verify`): a fresh verifier checks each criterion, writes `verification.md`, and `accord gate done` runs once the owner approves.
|
|
103
|
+
|
|
104
|
+
`accord-debug` finds a root cause before any fix when something fails for a reason nobody has shown.
|
|
105
|
+
- L (an epic) and P (a project) are not built yet. Accord proposes splitting such work into lane M tickets linked by `depends_on`.
|
|
106
|
+
|
|
107
|
+
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.
|
|
108
|
+
|
|
109
|
+
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.
|
|
110
|
+
|
|
111
|
+
In Claude Code, the pane shows the dashboard beside the chat.
|
|
112
|
+
|
|
113
|
+
### 5. Other runtimes
|
|
114
|
+
|
|
115
|
+
`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.
|
|
116
|
+
|
|
117
|
+
After you change `runtimes:`, write the copies again and commit what it prints:
|
|
118
|
+
|
|
119
|
+
```sh
|
|
120
|
+
npx --yes @accord-dev/accord@0.3.0 skills sync
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
`skills sync` never deletes. When you remove a runtime, it lists the copies it no longer writes, and you delete them yourself.
|
|
124
|
+
|
|
125
|
+
### 6. CLI commands for people and CI
|
|
126
|
+
|
|
127
|
+
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/accord@0.3.0` in place of `accord`. Run `accord --help` for the full list, and `accord <command> --help` for each one.
|
|
128
|
+
|
|
129
|
+
| Command | What it does |
|
|
130
|
+
|---|---|
|
|
131
|
+
| `accord lint [--json]` | Report every finding in the accord folder. |
|
|
132
|
+
| `accord gate ready <id>` | Report whether the ticket passes the Ready gate. |
|
|
133
|
+
| `accord gate plan <id>` | Report whether the ticket passes the plan gate. |
|
|
134
|
+
| `accord gate done <id>` | Report whether the ticket passes the Done gate. |
|
|
135
|
+
| `accord status [--json] [--all]` | Print one row per ticket; `--all` includes archived tickets. |
|
|
136
|
+
| `accord dashboard [--json]` | Print the ranked dashboard sections for you. |
|
|
137
|
+
| `accord show <id> [--json]` | Print one ticket: its intent and each criterion with its state. |
|
|
138
|
+
| `accord new ticket [id]` | Write `accord/tickets/<id>.md` from the template. |
|
|
139
|
+
| `accord skills sync` | Write every skill the config declares into `.claude/skills/` and `.agents/skills/`. |
|
|
140
|
+
| `accord worktree open <id>` | Find or prepare the ticket's worktree. |
|
|
141
|
+
| `accord worktree clean` | Remove worktrees and branches of tickets done on the default branch. |
|
|
142
|
+
|
|
143
|
+
### 7. Version pin and upgrading
|
|
144
|
+
|
|
145
|
+
`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` hook only warns, so the prompt goes on), and names the command to run instead, with the pinned version in place of 0.3.0:
|
|
146
|
+
|
|
147
|
+
```sh
|
|
148
|
+
npx --yes @accord-dev/accord@0.3.0 <command>
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
There is no flag or environment variable that skips the check. Only `--version`, `--help` and `upgrade` run regardless.
|
|
152
|
+
|
|
153
|
+
`/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/accord@0.3.0 upgrade` once by hand.
|
|
154
|
+
|
|
155
|
+
Exit codes:
|
|
156
|
+
|
|
157
|
+
| Code | Meaning |
|
|
158
|
+
|---|---|
|
|
159
|
+
| 0 | Gate passed, or lint clean (warnings allowed). |
|
|
160
|
+
| 1 | Gate failed, or lint found errors. The reasons are printed. |
|
|
161
|
+
| 2 | Usage or environment error: bad arguments, no accord folder, unreadable config, version mismatch. |
|
|
162
|
+
|
|
163
|
+
### 8. Running main from a clone
|
|
164
|
+
|
|
165
|
+
To work on accord itself:
|
|
166
|
+
|
|
167
|
+
```sh
|
|
168
|
+
npm install
|
|
169
|
+
npm run build
|
|
170
|
+
npm rebuild @accord-dev/accord
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
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.
|
|
29
174
|
|
|
30
175
|
## License
|
|
31
176
|
|
|
32
|
-
MIT
|
|
177
|
+
MIT. See [LICENSE](https://github.com/ngothanhluan/accord/blob/main/LICENSE).
|