@accord-dev/accord 0.7.0 → 0.8.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.
Files changed (3) hide show
  1. package/README.md +20 -18
  2. package/dist/cli.js +3372 -1445
  3. 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.7.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.
11
+ Released: `@accord-dev/accord@0.8.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.
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.7.0 <command>
40
+ npx --yes @accord-dev/accord@0.8.0 <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.7.0
46
+ npm i -g @accord-dev/accord@0.8.0
47
47
  ```
48
48
 
49
49
  The global install must be the same version the repository pins (see [Version pin](#8-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.7.0 init
56
+ npx --yes @accord-dev/accord@0.8.0 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:
@@ -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.7.0`).
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.8.0`).
80
80
 
81
81
  ### 4. Make the accord check a merge gate
82
82
 
@@ -90,15 +90,16 @@ accord changes no GitHub setting, so nothing yet stops a pull request from mergi
90
90
 
91
91
  ### 5. Daily use in your coding agent
92
92
 
93
- All work starts from the `/accord` skill inside the agent session:
93
+ Work starts from `/accord` or one of its own commands inside the agent session:
94
94
 
95
95
  | Command | What it does |
96
96
  |---|---|
97
97
  | `/accord` | The dashboard: your tickets, the team's, and what is ready to pick up, with the actions that apply. |
98
- | `/accord <request>` | New work. Accord proposes a lane with its reason; you may override it. |
99
- | `/accord continue <id>` | Resume a ticket at the stage and step it reached. |
100
- | `/accord pick-up <id>` | Claim an unclaimed ticket and start it. |
101
- | `/accord upgrade` | Move the repository to a newer accord release (see [Version pin](#8-version-pin-and-upgrading)). |
98
+ | `/accord-new <request>` | New work. Accord proposes a lane with its reason; you may override it. |
99
+ | `/accord-continue <id>` | Resume a ticket at the stage and step it reached. |
100
+ | `/accord-pickup <id>` | Claim an unclaimed ticket and start it. |
101
+ | `/accord-queue <idea>` | Note an idea as a draft ticket for later, from any session, without starting it or leaving the ticket you are on. |
102
+ | `/accord-upgrade` | Move the repository to a newer accord release (see [Version pin](#8-version-pin-and-upgrading)). |
102
103
 
103
104
  Lanes:
104
105
 
@@ -113,11 +114,12 @@ Lanes:
113
114
 
114
115
  `accord-debug` finds a root cause before any fix when something fails for a reason nobody has shown.
115
116
  - 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.
116
- - L (an epic) and P (a project) are not built yet. Accord proposes splitting such work into lane M tickets linked by `depends_on`.
117
+ - L, an epic, proposed when a request names three or more parts that would each be a story of its own: `/accord-new` interviews the owner once (why, for whom, the Vetoes, the Decisions), proposes a split into two to ten stories linked by `depends_on`, and on the owner's yes runs `accord new ticket --type epic --lane L --split <file> --queue`, which queues the epic and every story in one pull request. Each story then runs lane M, picked up in its own worktree. The epic itself gets no approach or plan critique.
118
+ - P (a project) is not built yet; accord proposes an epic instead.
117
119
 
118
120
  A request moves from S to M when it changes a public interface or schema, touches a listed sensitive area or auth, money, migration 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.
119
121
 
120
- 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.
122
+ 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.
121
123
 
122
124
  In Claude Code, the pane shows the dashboard beside the chat.
123
125
 
@@ -128,14 +130,14 @@ In Claude Code, the pane shows the dashboard beside the chat.
128
130
  After you change `runtimes:`, write the copies again and commit what it prints:
129
131
 
130
132
  ```sh
131
- npx --yes @accord-dev/accord@0.7.0 skills sync
133
+ npx --yes @accord-dev/accord@0.8.0 skills sync
132
134
  ```
133
135
 
134
136
  `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.
135
137
 
136
138
  ### 7. CLI commands for people and CI
137
139
 
138
- 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.7.0` in place of `accord`. Run `accord --help` for the full list, and `accord <command> --help` for each one.
140
+ 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.8.0` in place of `accord`. Run `accord --help` for the full list, and `accord <command> --help` for each one.
139
141
 
140
142
  | Command | What it does |
141
143
  |---|---|
@@ -147,7 +149,7 @@ The skills call the CLI for you. These are the commands most useful to run by ha
147
149
  | `accord dashboard [--json]` | Print the ranked dashboard sections for you. |
148
150
  | `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. |
149
151
  | `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`. |
150
- | `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). |
152
+ | `accord new ticket [id] [--lane <lane>] [--title <text>] [--queue] [--note <line>] [--related <ids>] [--no-dup-check] [--split <file>]` | Write `accord/tickets/<id>.md` from the template, or from the lane's template under `--lane` (S, M, L, P, or R for research). `--title` sets the title, and a lane S or M ticket or a queued one needs it; before writing, the command prints the most similar tickets and creates nothing until `--related <ids>` or `--related none` is given; `--no-dup-check` lets a script create without that check and says so; `--queue` with up to four `--note <line>` writes a draft on a backlog branch off the default branch instead of the working tree; `--split <file>` writes an epic and its stories in one step. |
151
153
  | `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. |
152
154
  | `accord trust [<script>@<digest>...] [--revoke]` | With no script named, show each script `accord/config.yml` declares (`tracker.command` under the `script` adapter, `git.sync`, and `build.regenerate`, which `accord worktree task merge` prints for the build stage to run only once it is allowed): its command, a digest of what it covers, the files an allow covers and the ones that changed, and allow nothing. `accord trust git.sync@<digest>` or `accord trust tracker.command@<digest>`, with the digest the preview printed, allows that script in this repository, and refuses if the files changed since: a local record inside `.git`, never committed, bound to the command and the files it reaches (the script's whole folder, the package.json script `npm run` runs), so a change to either asks again. accord checks only the files it lists; anything else the command loads is not checked, so whoever allows a script must review the pull request that changed it. `--revoke` withdraws the allows. |
153
155
  | `accord review-package <id> [--base <ref>] [--security [--round <n>]]` | Print the commits, stat and diff a reviewer reads, with the security triggers the diff matched. `--security` prints the security package instead: the checklist, the triggers and only the hunks they match, whole, with their context (a path match is cut at 300 lines, and the cut says how many lines it left out). `--security --round <n>` prints it for the n-th round of `review.md`, over the range `accord round` and `accord gate done` check; a `(final review)` round has none. |
@@ -157,15 +159,15 @@ The skills call the CLI for you. These are the commands most useful to run by ha
157
159
 
158
160
  ### 8. Version pin and upgrading
159
161
 
160
- `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.7.0:
162
+ `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.8.0:
161
163
 
162
164
  ```sh
163
- npx --yes @accord-dev/accord@0.7.0 <command>
165
+ npx --yes @accord-dev/accord@0.8.0 <command>
164
166
  ```
165
167
 
166
168
  There is no flag or environment variable that skips the check. Only `--version`, `--help` and `upgrade` run regardless.
167
169
 
168
- `/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.7.0 upgrade` once by hand.
170
+ `/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.8.0 upgrade` once by hand.
169
171
 
170
172
  Exit codes:
171
173