@accord-dev/accord 0.4.0 → 0.4.1
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 +20 -17
- package/dist/cli.js +16057 -13225
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ Accord adds a small, fixed folder to your repository. Before an agent writes cod
|
|
|
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
10
|
|
|
11
|
-
Released: `@accord-dev/accord@0.4.
|
|
11
|
+
Released: `@accord-dev/accord@0.4.1` on npm. See [docs/design.md](https://github.com/ngothanhluan/accord/blob/main/docs/design.md) for the design and the reasoning behind it.
|
|
12
12
|
|
|
13
13
|
## The problem
|
|
14
14
|
|
|
@@ -37,13 +37,13 @@ AI coding agents produce features that pass their own tests and still miss what
|
|
|
37
37
|
Node 22.12 or newer. Run accord through npx with an exact version, so nothing needs installing:
|
|
38
38
|
|
|
39
39
|
```sh
|
|
40
|
-
npx --yes @accord-dev/accord@0.4.
|
|
40
|
+
npx --yes @accord-dev/accord@0.4.1 <command>
|
|
41
41
|
```
|
|
42
42
|
|
|
43
43
|
Or install it globally and run `accord <command>`:
|
|
44
44
|
|
|
45
45
|
```sh
|
|
46
|
-
npm i -g @accord-dev/accord@0.4.
|
|
46
|
+
npm i -g @accord-dev/accord@0.4.1
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
The global install must be the same version the repository pins (see [Version pin](#7-version-pin-and-upgrading)).
|
|
@@ -53,7 +53,7 @@ The global install must be the same version the repository pins (see [Version pi
|
|
|
53
53
|
In the repository root:
|
|
54
54
|
|
|
55
55
|
```sh
|
|
56
|
-
npx --yes @accord-dev/accord@0.4.
|
|
56
|
+
npx --yes @accord-dev/accord@0.4.1 init
|
|
57
57
|
```
|
|
58
58
|
|
|
59
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:
|
|
@@ -61,7 +61,7 @@ npx --yes @accord-dev/accord@0.4.0 init
|
|
|
61
61
|
- `accord/config.yml`, pinned to the running version, with `runtimes: [claude, codex]` and a comment on every key.
|
|
62
62
|
- `accord/product/glossary.md`, `accord/product/business-rules.md` and `accord/product/conventions.md`, from templates.
|
|
63
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
|
|
64
|
+
- The skills: `/accord` and the stage skills `accord-intent` (which holds the discuss stage), `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
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
66
|
- A short accord block appended to `AGENTS.md` and `CLAUDE.md`, or those files created.
|
|
67
67
|
|
|
@@ -76,7 +76,7 @@ git commit -m "accord init"
|
|
|
76
76
|
git push
|
|
77
77
|
```
|
|
78
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.4.
|
|
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.4.1`).
|
|
80
80
|
|
|
81
81
|
### 4. Daily use in your coding agent
|
|
82
82
|
|
|
@@ -94,17 +94,18 @@ Lanes:
|
|
|
94
94
|
|
|
95
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
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 planner drafts the lightest approach that works, a critic argues against it in rounds `accord round <id> --approach` counts, and the owner approves
|
|
99
|
-
3. plan (`accord-plan`): a task-by-task plan checked by `accord gate plan
|
|
97
|
+
1. intent (`accord-intent`): an interview that writes the intent, acceptance criteria, vetoes and decisions, then the discuss stage: it asks the owner every gray area one at a time, with a recommended default and what each choice costs, and writes each answer as a Decision.
|
|
98
|
+
2. approach (`accord-approach`): the planner drafts the lightest approach that works, a critic argues against it in at most two rounds `accord round <id> --approach` counts, and the owner approves the whole ticket once, from `accord show <id> --approval --short`.
|
|
99
|
+
3. plan (`accord-plan`): a task-by-task plan that lists tasks, criteria, files, interfaces and dependencies, checked by `accord gate plan`, and one plan checker checks it in at most three rounds.
|
|
100
100
|
4. build (`accord-build`): one fresh executor per task, each recorded with `accord task-done`.
|
|
101
101
|
5. review (`accord-review`): reviewers until no Must is open and every Should is fixed.
|
|
102
102
|
6. verify (`accord-verify`): a fresh verifier checks each criterion, writes `verification.md`, and `accord gate done` runs once the owner approves.
|
|
103
103
|
|
|
104
104
|
`accord-debug` finds a root cause before any fix when something fails for a reason nobody has shown.
|
|
105
|
+
- R, research: a question accord cannot answer from the code, with no change asked. `accord new ticket <id> --lane R` writes a ticket with a question, a timebox and a token budget the owner sets, quoted under `## Decisions`. The session researches within them, checks `accord budget <id>` between steps and stops to ask the owner past either, and ends in a record under `accord/research/`, written on its branch after the claim, that the ticket lists under `research:`; an older record listed there is evidence, not the result. There is no approach, plan, critic, review or verification; `accord gate done` refuses a branch that changes the shipped packages.
|
|
105
106
|
- 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
|
|
|
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, 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.
|
|
108
|
+
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; `accord scout check` checks the citations and logged searches of its report and prints the lane numbers, and the report is saved as `accord/tickets/<id>/scout.md`, which `accord approve` requires of a lane M ticket, judged by the same check at the commit that last changed it, unless the file holds a `skipped: <reason>` line. 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.
|
|
108
109
|
|
|
109
110
|
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
|
|
|
@@ -117,14 +118,14 @@ In Claude Code, the pane shows the dashboard beside the chat.
|
|
|
117
118
|
After you change `runtimes:`, write the copies again and commit what it prints:
|
|
118
119
|
|
|
119
120
|
```sh
|
|
120
|
-
npx --yes @accord-dev/accord@0.4.
|
|
121
|
+
npx --yes @accord-dev/accord@0.4.1 skills sync
|
|
121
122
|
```
|
|
122
123
|
|
|
123
124
|
`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.
|
|
124
125
|
|
|
125
126
|
### 6. CLI commands for people and CI
|
|
126
127
|
|
|
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.4.
|
|
128
|
+
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.4.1` in place of `accord`. Run `accord --help` for the full list, and `accord <command> --help` for each one.
|
|
128
129
|
|
|
129
130
|
| Command | What it does |
|
|
130
131
|
|---|---|
|
|
@@ -134,23 +135,25 @@ The skills call the CLI for you. These are the commands most useful to run by ha
|
|
|
134
135
|
| `accord gate done <id>` | Report whether the ticket passes the Done gate. |
|
|
135
136
|
| `accord status [--json] [--all]` | Print one row per ticket; `--all` includes archived tickets. |
|
|
136
137
|
| `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
|
|
138
|
+
| `accord show <id> [--json | --approval [--short]]` | Print one ticket: its intent and each criterion with its state. `--approval` prints what the owner approves, and `--short` the shorter view the owner's yes is asked from. |
|
|
139
|
+
| `accord scout check <file> [--ticket <id>]` | Check a scout report's citations and logged searches against the files git tracks, and print its lane numbers. `--ticket` leaves that ticket's own files and listed research records out of every search, as for a saved `scout.md`. |
|
|
140
|
+
| `accord new ticket [id] [--lane <lane>]` | Write `accord/tickets/<id>.md` from the template, or from the lane's template under `--lane` (S, M, L, P, or R for research). |
|
|
141
|
+
| `accord budget <id>` | Report whether a lane R ticket is within its timebox and token budget since its claim commit (exit 1 means stop and ask the owner), and print the `Spent:` line its research record states. Tokens read `not measured` when the checkout's own transcripts do not cover the time since the claim. |
|
|
139
142
|
| `accord skills sync` | Write every skill the config declares into `.claude/skills/` and `.agents/skills/`. |
|
|
140
143
|
| `accord worktree open <id>` | Find or prepare the ticket's worktree. |
|
|
141
144
|
| `accord worktree clean` | Remove worktrees and branches of tickets done on the default branch. |
|
|
142
145
|
|
|
143
146
|
### 7. Version pin and upgrading
|
|
144
147
|
|
|
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` 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.
|
|
148
|
+
`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.1:
|
|
146
149
|
|
|
147
150
|
```sh
|
|
148
|
-
npx --yes @accord-dev/accord@0.4.
|
|
151
|
+
npx --yes @accord-dev/accord@0.4.1 <command>
|
|
149
152
|
```
|
|
150
153
|
|
|
151
154
|
There is no flag or environment variable that skips the check. Only `--version`, `--help` and `upgrade` run regardless.
|
|
152
155
|
|
|
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.4.
|
|
156
|
+
`/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.4.1 upgrade` once by hand.
|
|
154
157
|
|
|
155
158
|
Exit codes:
|
|
156
159
|
|