@accord-dev/accord 0.0.0 → 0.2.0

package/README.md

@@ -2,30 +2,48 @@
 
 # accord
 
-A team contract for AI-assisted software delivery.
+A contract for AI-assisted software delivery.
 
-Accord defines a small, conventional folder inside your repository where a business analyst, designer, and developer write down what a feature is for, what it must do, how it must look, and how you will know it is done, before an AI agent writes a line of code; QA verifies against the same acceptance criteria. A CLI checks that contract deterministically, so an agent cannot skip it.
+Accord defines a small, conventional folder inside your repository where what a feature is for, what it must do, how it must look, and how you will know it is done are written down before an agent writes a line of code, and verified against those same acceptance criteria afterwards. A CLI checks that contract deterministically, so an agent cannot skip it.
 
-**Status: design phase.** Nothing is published yet. See [docs/design.md](docs/design.md) for the current design and the reasoning behind it.
+BA, designer, developer, reviewer are four stages a ticket passes through, not four job titles. One person passes through all four in turn; four people on a team divide them. No gate reads who anyone is, so the same rules hold either way.
+
+**Released:** `@accord-dev/accord@0.2.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.
+
+## Try it
+
+Nothing to install. Node 22.12 or newer, and:
+
+```sh
+npx --yes @accord-dev/accord@0.2.0 --version
+```
+
+That prints the version back. `init` in place of `--version` writes the `accord/` folder, the workflow skills for the runtimes you name, and a CI workflow pinned to the same release, into whatever repository you run it in.
+
+**New in 0.2.0:** the workflow layer described below (lanes, `/accord`, the stage skills, the accord agents in `.claude/agents/`, and three session hooks in `.claude/settings.json`). A repository pinned to 0.1.0 moves with `npx --yes @accord-dev/accord@0.2.0 upgrade`; from 0.2.0 on, `/accord upgrade` does it. To run `main` from a clone: `npm install`, `npm run build`, then `npm rebuild @accord-dev/accord` so the `accord` command exists for the hooks.
 
 ## The problem
 
-AI coding agents produce features that pass their own tests and still miss what the user meant. The largest measured cause is not a missing spec but an agent ignoring instructions it already had. The second is a spec that never captured intent, and QA testing without acceptance criteria. Accord attacks both: intent and acceptance criteria are captured up front by the people who hold them, and a Done gate verifies the result against those criteria independently of the agent that built it.
+AI coding agents produce features that pass their own tests and still miss what the user meant. The largest measured cause is not a missing spec but an agent ignoring instructions it already had. The second is a spec that never captured intent, and verification done without acceptance criteria to verify against. Accord attacks both: intent and acceptance criteria are captured up front by whoever holds them, and a Done gate verifies the result against those criteria independently of the agent that built it.
 
 ## What it is
 
 - A folder convention: a fixed `accord/` folder at the repo root with `config.yml`, `product/` (glossary, business rules), `tickets/<id>.md` (epics, stories, and bugs are all tickets; a story names its epic with `parent:`), `tickets/<id>/verification.md` (the review record), and `assets/<id>/` (designer-owned prototypes). Tracker links are a `tracker:` map keyed by adapter, for example `tracker: { github-issues: "1234" }`.
 - Plain-text formats a human and a model can both read and a linter can check: EARS for requirements, Gherkin for acceptance criteria, YAML frontmatter with a JSON schema, fixed headings per ticket: Intent, Requirements, Acceptance criteria, Open questions, Plan.
-- Two gates: **Ready** before work starts, **Done** before the card goes to QA: a fresh agent context, not the one that wrote the code, writes `tickets/<id>/verification.md`; the developer ticks `verified:` after a self-test; Done passes only when scenario tags, evidence tags, and `verified` match.
-- Role workflows (`ba`, `dev`, `designer`) shipped as skill files for Claude Code, Cursor, Copilot, and Codex; QA verifies on the dev environment and records results in the tracker.
-- A CLI: `init`, `new`, `lint`, `gate`, `status`.
+- Two gates: **Ready** before work starts, **Done** before the work is called finished: a fresh agent context, not the one that wrote the code, writes `tickets/<id>/verification.md`; the developer ticks `verified:` after a self-test; Done passes only when scenario tags, evidence tags, and `verified` match.
+- A workflow, shipped as skill files, one definition each, rendered for every runtime you list. `/accord` is the entry point: with no argument it shows your tickets, the team's, and what is ready to pick up; with a request it proposes a lane and starts. Every ticket runs the same six stages, each a skill you can also call directly: `accord-intent`, `accord-approach`, `accord-plan`, `accord-build`, `accord-review`, `accord-verify`, plus `accord-debug` for a root cause.
+- Lanes sized to the work: **S** for a small fix (done in the session, one review pass, affected tests), **M** for a feature (an owner-approved approach, a checked plan, one fresh executor per task, review to convergence, an evidence report). A ticket opts in with `lane:` in its frontmatter; a ticket without it keeps every 0.1.0 rule.
+- One worktree per ticket. Pick up, Continue and a new lane M ticket first fetch `origin`, so a new ticket branch starts at the remote's latest default branch. A fetch that fails, or gets no answer within 30 seconds, is one line, and the work goes on. Before verify, Continue merges the remote's default branch into a ticket branch that is behind, with a merge commit, then runs the setup commands and pushes it; a conflict is aborted and named. Before its full suite, `accord-verify` runs `accord worktree merge <id>`, which merges the remote's default branch into the ticket branch with a merge commit, never a rebase. A conflict is aborted and named, and verify stops. Pick up, Continue and a new lane M ticket each work in the ticket's own git worktree, the sibling folder `<repository folder>-<id in lower case>`, prepared by the `setup` commands `config.yml` lists, run in order through the shell (they are repository content, trusted as `tests.affected` is). `accord worktree open` prints the folder and the line `/accord continue <id>` to type in a session opened there. In Claude Code the session rooted there holds the ticket until it ends, and a second session is refused. In Cursor, Copilot and Codex the worktree is made, prepared, reused and removed the same way, but a second session is not refused yet. Every `/accord` command (the dashboard, Pick up, Continue, and a new lane M or lane S ticket with `--worktree`) fetches, then removes the worktree, the local branch and the branch on `origin` of each ticket done on the remote main branch, keeping one with uncommitted work, held by another session, or holding a commit after its verified commit; files ignored by `.gitignore`, such as `node_modules`, go with the worktree.
+- New releases. The session start hook and `/accord` say when a newer accord is out than the repository pins; the registry is asked at most once in 24 hours per machine with a 3 second limit, and an unreachable registry adds nothing. `/accord upgrade` runs `upgrade` as the newer version, which pushes a branch `upgrade/<version>` cut from the remote main whose one commit moves the pin in `config.yml`, the CI workflow and the Claude Code hooks and holds the regenerated skill files; your checkout is left alone.
+- Tests as evidence, never as a claim. `accord task-done` and `accord gate done` read only the JUnit report `tests.report` names in `config.yml`, so the `tests.affected` command template you configure there must write that same report; if it writes nothing, every `task-done` refuses the report as older than the commit. The CLI never runs a test command itself.
+- A CLI: `init`, `new`, `lint`, `gate ready|plan|done`, `approve`, `brief`, `task-done`, `review-package`, `tests baseline`, `status`, `next`, `anchor`, `hook`, `skills sync`, `upgrade`, `worktree open|clean|merge`.
 - 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 at the team layer and works alongside whatever agent harness each member already uses.
+- 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; a stateless remote MCP server lets non-technical members work the same tickets from their chat app over the GitHub API.
+- Not a database. Git is the only source of truth: the contract is files in your repository, versioned with the code it describes.
 
 ## License