@accord-dev/accord 0.8.1 → 0.9.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.
Files changed (3) hide show
  1. package/README.md +21 -15
  2. package/dist/cli.js +9468 -6884
  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.8.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.
11
+ Released: `@accord-dev/accord@0.9.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.8.1 <command>
40
+ npx --yes @accord-dev/accord@0.9.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.8.1
46
+ npm i -g @accord-dev/accord@0.9.1
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.8.1 init
56
+ npx --yes @accord-dev/accord@0.9.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.8.1 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` (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/`.
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:`, and the optional `/accord-audit` (see Daily use). 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, one that lets only the `accord-verifier` subagent write `verification.md`, 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.8.1`).
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.9.1`).
80
80
 
81
81
  ### 4. Make the accord check a merge gate
82
82
 
@@ -99,6 +99,7 @@ Work starts from `/accord` or one of its own commands inside the agent session:
99
99
  | `/accord-continue <id>` | Resume a ticket at the stage and step it reached. |
100
100
  | `/accord-pickup <id>` | Claim an unclaimed ticket and start it. |
101
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-audit` | Optional. Report what a machine can see about your conventions (linter and its rules, formatter, type checking, tests, languages, folders, PR template, commit rule), each gap with its fix, and draft conventions from the code, line by line, only on your yes. Nothing runs it for you. |
102
103
  | `/accord-upgrade` | Move the repository to a newer accord release (see [Version pin](#8-version-pin-and-upgrading)). |
103
104
 
104
105
  Lanes:
@@ -130,44 +131,49 @@ In Claude Code, the pane shows the dashboard beside the chat.
130
131
  After you change `runtimes:`, write the copies again and commit what it prints:
131
132
 
132
133
  ```sh
133
- npx --yes @accord-dev/accord@0.8.1 skills sync
134
+ npx --yes @accord-dev/accord@0.9.1 skills sync
134
135
  ```
135
136
 
136
137
  `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.
137
138
 
138
139
  ### 7. CLI commands for people and CI
139
140
 
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.1` in place of `accord`. Run `accord --help` for the full list, and `accord <command> --help` for each one.
141
+ 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.9.1` in place of `accord`. Run `accord --help` for the full list, and `accord <command> --help` for each one.
141
142
 
142
143
  | Command | What it does |
143
144
  |---|---|
144
145
  | `accord lint [--json]` | Report every finding in the accord folder. |
145
146
  | `accord gate ready <id>` | Report whether the ticket passes the Ready gate. |
146
147
  | `accord gate plan <id>` | Report whether the ticket passes the plan gate. |
147
- | `accord gate done <id>` | Report whether the ticket passes the Done gate. |
148
+ | `accord gate done <id>` | Report whether the ticket passes the Done gate. A slop hit of the ticket's diff (the `## Slop` list of `accord review-package`) must be fixed or named by a `slop:<kind> <path>:<line> — <reason>` line in the last `## Round` of `review.md`, else `gate.slop-unresolved` refuses; only for tickets claimed at or after the release that ships it. |
148
149
  | `accord status [--json] [--all]` | Print one row per ticket; `--all` includes archived tickets. |
149
150
  | `accord dashboard [--json]` | Print the ranked dashboard sections for you. |
150
151
  | `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. |
151
152
  | `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`. |
152
153
  | `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. |
153
154
  | `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. |
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. |
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. |
155
+ | `accord commit check <file>` | Judge the first line of a commit message file against `commits.message` in `accord/config.yml` (the `conventional` preset or your own pattern): exit 0 when it passes or no rule is set, exit 1 naming the rule and a message that passes, exit 2 when the file cannot be read or the pattern is not in force. Merge commits and `Revert "..."` subjects are exempt where `accord task-done` and `accord gate done` apply the rule: it covers commits on a ticket branch, for a ticket claimed at or after the release that added it. |
156
+ | `accord commit message <id>` | Run `commits.message.command`, your script that builds the message (a Jira key, say), only after `accord trust` allowed it, with `ACCORD_TICKET`, `ACCORD_TICKET_FILE`, `ACCORD_BASE_REF` and `ACCORD_ROOT` in its environment (`ACCORD_TICKET_FILE` is the ticket file's absolute path with forward slashes; `ACCORD_ROOT` is the checkout root as the platform writes it): its first output line is the subject and the rest the body. The message goes to a file under `.git`, printed as `message-file: <path>` for `git commit -F`, and is then judged like `accord commit check`. |
157
+ | `accord audit` | Report what a machine can see about the repository's conventions and about accord's own setup: `fact: <name>: <value>` lines (`languages`, `layout`, `linter`, `linter-rules`, `formatter`, `typecheck`, `tests`, `pr-template`, `commit-rule`, `conventions`, `npm-latest`, `rendered-files`, `new-key`, `team-audit`), then `gap: <id>: <text> - fix: <fix>` lines: conventions (`conventions-empty`, `conventions-thin`, `no-linter`, `no-formatter`, `typecheck-loose`, `no-pr-template`, `commit-rule-unset`, `subject-breaks-rule`), setup (`pin-mismatch`, `pin-behind-latest`, `config-invalid`, `workflow-missing`, `workflow-pin`, `workflow-timeout`, `render-missing`, `render-edited`, `render-orphan`, `render-retired`, `hook-missing`, `hook-edited`, `hook-doubled`, `script-untrusted`, `script-trust-stale`, `security-file`) and the team's own script (`team-audit`, from `audit.command`, run only after `accord trust audit.command@<digest>`), then `gaps: <n>`. The latest release is read from npm, and an unreachable registry prints `npm-latest: no observation`, never that the version is current. It exits 0 whenever it ran, calls no model, writes nothing in the repository (it never edits the security file, a trust allow or config.yml), and no gate runs it. It runs under a version pin mismatch and reports it as a `pin-mismatch` gap. |
158
+ | `accord conventions write <file>` | Append the convention lines the owner accepted in `/accord-audit` (each `- <convention> — enforced by: <rule id or prose>`, at most 300 characters) to `accord/product/conventions.md` as the default branch has it, commit them with the `conventions` subject on a new branch `conventions/<date>` in a temporary worktree and push it, printing `branch:`, `base:` and `title:`. A line already in the file is skipped and named; a line it cannot read, or a branch origin already has, is exit 2. The checkout is not touched and nothing is merged. |
159
+ | `accord pr <id>` | Write the title and the body file of a ticket's pull request, for the step that opens it (`gh pr create --title "<title>" --body-file <path>`; accord never calls `gh` itself). It prints `title: <id>: <title>`, `body-file: <path>` (`<git dir>/accord-pr-<id>.md`, one per worktree, never tracked), then `template: <path>`, `script: pr.command` or `template: none`, then one `remaining: <heading>` line per template section the ticket could not fill, for you to write. The body is the repository's PR template with every heading kept and the ticket's id, title, Intent, acceptance criteria and test evidence filled in: `pr.template` in `accord/config.yml` names one tracked file; else a single `pull_request_template` in `.github/`, the root or `docs/` (any case, `_` or `-`); else the first `.md` file of the first `PULL_REQUEST_TEMPLATE/` folder, printed as `template: <path> (first of N; set pr.template to choose)`. `pr.command` is your own script that replaces the template: it runs only after `accord trust`, with `ACCORD_TICKET`, `ACCORD_TICKET_FILE`, `ACCORD_BASE_REF` and `ACCORD_ROOT` in its environment (`ACCORD_TICKET_FILE` is the ticket file's absolute path with forward slashes; `ACCORD_ROOT` is the checkout root as the platform writes it); its first output line is the title and the rest the body; a non-zero exit, a timeout (60 s), more than 1 MiB of output or an empty first line stops with its stderr, with no fallback to the template. With neither, the body is one `- <subject>` line per commit of the branch (an epic's Intent). A title with a double quote, a backtick, `$`, a backslash, a control character or a line break is refused, because the skills pass it inside a quoted argument. |
160
+ | `accord trust [<script>@<digest>...] [--revoke]` | With no script named, show each script `accord/config.yml` declares (`tracker.command` under the `script` adapter, `git.sync`, `build.regenerate`, which `accord worktree task merge` prints for the build stage to run only once it is allowed, `commits.message.command`, which builds a commit message, and `pr.command`, which builds a pull request's title and body): 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>`, `accord trust tracker.command@<digest>`, `accord trust commits.message.command@<digest>` or `accord trust pr.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. |
161
+ | `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 and a `## Slop` section: the commented-out code, empty catch blocks, `any`-style types, new dependencies, grown files and new files nothing names (TypeScript and JavaScript, C#, Python, HTML and CSS, plus a team's patterns from `accord/product/slop.md`) that the ticket's whole diff adds, one `slop:<kind> <path>:<line>` each. `--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. |
156
162
  | `accord skills sync` | Write every skill the config declares into `.claude/skills/` and `.agents/skills/`. |
157
163
  | `accord worktree open <id>` | Find or prepare the ticket's worktree. |
158
164
  | `accord worktree clean` | Remove worktrees and branches of tickets done on the default branch. |
159
165
 
160
166
  ### 8. Version pin and upgrading
161
167
 
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.1:
168
+ `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.9.1:
163
169
 
164
170
  ```sh
165
- npx --yes @accord-dev/accord@0.8.1 <command>
171
+ npx --yes @accord-dev/accord@0.9.1 <command>
166
172
  ```
167
173
 
168
- There is no flag or environment variable that skips the check. Only `--version`, `--help` and `upgrade` run regardless.
174
+ There is no flag or environment variable that skips the check. Only `--version`, `--help`, `upgrade` and `audit` run regardless: `upgrade` because it runs as the newer version, and `audit` because it only reports (it reports the mismatch as a `pin-mismatch` gap and writes nothing in the repository).
169
175
 
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.1 upgrade` once by hand.
176
+ `/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.9.1 upgrade` once by hand.
171
177
 
172
178
  Exit codes:
173
179