yadflow 4.0.0 → 4.1.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 (9) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +237 -334
  3. package/bin/commands.mjs +1 -0
  4. package/bin/yad.mjs +17 -5
  5. package/cli/capture.mjs +1 -1
  6. package/cli/claims.mjs +1 -1
  7. package/cli/detect.mjs +642 -0
  8. package/cli/errors.mjs +2 -2
  9. package/package.json +6 -5
package/README.md CHANGED
@@ -1,387 +1,290 @@
1
- # Yadflow — keep AI-generated code from shipping ungoverned
1
+ # Yadflow — shared project memory and workflows for teams building with AI
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/yadflow?logo=npm)](https://www.npmjs.com/package/yadflow)
4
4
  [![CI](https://github.com/abdelrahmannasr/yadflow/actions/workflows/ci.yml/badge.svg)](https://github.com/abdelrahmannasr/yadflow/actions/workflows/ci.yml)
5
5
  [![node](https://img.shields.io/node/v/yadflow?logo=node.js)](https://github.com/abdelrahmannasr/yadflow/blob/main/package.json)
6
- [![report](https://img.shields.io/badge/docs-Yadflow%20report-2471a3)](https://abdelrahmannasr.github.io/yadflow/)
7
6
 
8
- **A governance layer for AI-assisted software engineering — a gated development lifecycle where
9
- AI builds and a human clears every gate.**
10
- *AI builds. The hand decides.* (*yad* — **يد**, Arabic for "hand".) On npm and GitHub as `yadflow`.
7
+ Coordinate work, automate repetitive delivery tasks, and keep the decisions behind your software.
8
+ Yadflow connects plans, architecture, code and reviews in a versioned project record. Your team and
9
+ your AI assistants can use that record across sessions and across repositories, with human approval
10
+ where it matters.
11
11
 
12
- > **Not another coding assistant — the governance layer around the one you already use.**
13
- > Yadflow doesn't write your code; it governs how AI-written code ships. Keep Cursor, GitHub Copilot,
14
- > Claude Code, Continue — or hand-written commits. The zero-dependency `yad` CLI and the CI gates
15
- > review the work **no matter who or what produced it.** The workflow skills run today in
16
- > **Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub Copilot, Zencoder and opencode** — see
17
- > [which agent reads which directory](#which-ai-agents-are-supported).
12
+ *Less coordination work. More shared understanding.*
18
13
 
19
- ## The problem
14
+ **[Quickstart](#quickstart)** · **[See it work](#see-it-work)** · **[Documentation](#documentation)**
20
15
 
21
- AI writes code faster than any team can review it. Left ungoverned, that speed turns into risk:
22
- unreviewed AI-generated changes merge straight into the codebase, architectural decisions get made
23
- by autocomplete, and the trail of *why* a change was made disappears. The faster the team ships with
24
- AI, the harder it gets to keep control of quality, architecture, and accountability.
16
+ **What you install.** Yadflow is not another coding assistant. It works with the one you already use.
25
17
 
26
- ## What Yadflow is
18
+ - **The `yad` command-line tool.** It is written in Node and has no dependencies. It sets up a
19
+ project, tells you the next action, runs reviews, and reads the project history.
20
+ - **38 workflow skills.** A skill is a set of instructions that your AI assistant loads for one task,
21
+ such as "write the architecture". The skills run in Claude Code, Codex CLI, Cursor, Gemini CLI,
22
+ GitHub Copilot, Zencoder and opencode.
23
+ - **Plain files in git.** Every plan, decision, approval and link lives as a readable file in a
24
+ repository. There is no database and no server.
25
+ - **Checks in your code repositories.** These run on GitHub Actions or GitLab CI. One check, for
26
+ example, makes each change name the task it belongs to.
27
27
 
28
- Yadflow puts a **human gate on every step** of the lifecycle. Each step does its work, writes its
29
- output to a plain file, and **waits** — it never advances until a human clears its gate (by approving,
30
- or in solo mode, switched with `yad mode`, by merging your own PR) — or, for a Build step the team set to `auto`, on its own after a clean run.
31
- Reviews ride real PR/MRs; all state lives in files you
32
- can read, diff, and edit — no database, nothing hidden. The result is a paper trail for every decision
33
- and a hard wall between "AI proposed" and "we shipped it."
28
+ The name: *yad* (**يد**) is Arabic for "hand". The hand is the person who decides.
34
29
 
35
- It installs with one command (`npx yadflow setup`) and works across one Product + many code repos,
36
- solo or team.
30
+ ## See it work
37
31
 
38
- ## How the workflow looks
32
+ The running example is a small shop. It has a **checkout feature**: customers pay in the mobile app,
33
+ and merchants see a queue of pending orders. Two later pieces of work build on it:
39
34
 
40
- <!-- Source: docs/diagrams/sdlc-overview.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
41
- ![Yadflow SDLC overview — setup, human-gated Shape, per-story Build, automation you switch on](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg)
35
+ 1. **A fix.** Tests never proved that the queue leaves out fulfilled orders, so a fix adds that test.
36
+ 2. **A change.** Merchants want the queue sorted by pickup time.
42
37
 
43
- **Legend:** 🟨 **artifact** (a step writes a file and stops) · 🟧 **gate** (a human review that must
44
- pass) · 🟦 **can run on auto** (a Build step the team may set to advance on its own, with `yad dial`) ·
45
- ⬜ **locked** (the engineer review — always a person).
38
+ The checkout feature and the fix are real records in this repository's [`epics/`](epics) folder.
39
+ The recording below adds the change. It runs real `yad` commands on a new local project, in team
40
+ mode, with made-up people. The one pre-written file is the change's plan, which your AI assistant would
41
+ normally write. That step is labelled on screen.
42
+
43
+ ![Terminal recording: yad history lists the checkout feature and its fix. yad thread shows which version of each document applies. yad epic new starts a linked change that keeps the feature's architecture, contract and UI. yad assign and yad next show the owner and the next action. yad gate refuses to move on before anyone approves; a teammate approves, and the review passes. yad history search and yad thread then show the updated record.](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/media/feature-change.gif)
44
+
45
+ *Recorded from the yadflow source with vhs. To re-record it, see
46
+ [`docs/media/feature-change.tape`](docs/media/feature-change.tape).*
47
+
48
+ ## What it helps with
49
+
50
+ | Benefit | What gives it to you today |
51
+ | --- | --- |
52
+ | **Reusable project context** | Plans, architecture, the shared contract (the agreed interface between repositories, such as API endpoints), stories and reviews are files in one repository. Skills read them before they write. `yad history` lists and searches past work. |
53
+ | **Clear ownership and handoffs** | `yad next` prints the single next action for each piece of work, with its owner. `yad assign` gives a step to one person. `yad claims` shows who is editing which file right now. Owners and claims are advice, not locks. |
54
+ | **Less repetitive delivery work** | Skills draft each document and stop for review. `yad ship` makes the commit and opens the pull request with the template filled in, and suggests reviewers. On Claude Code and Cursor, a hook (a small script the assistant runs after each edit) saves every draft for you. Setup wires the checks into each repository. |
55
+ | **Traceable decisions** | Each approval is tied to the exact contents of the file. If the file changes, the approval no longer counts. Later changes link to the work they change, and `yad thread` shows the whole chain. |
56
+ | **Reviews you control** | Every planning step waits for a person to approve it. Reviews happen in real pull requests (GitHub) or merge requests (GitLab), or locally with no platform. The Review Companion sums up a change and answers questions about it. |
57
+
58
+ ## How it fits together
59
+
60
+ Three words come up everywhere:
61
+
62
+ - **Product repository.** One git repository that holds the project record: plans, decisions,
63
+ approvals and history. It usually has no product code in it.
64
+ - **Code repository.** A repository where the code lives, such as `backend` or `mobile`. Yadflow adds
65
+ checks to it and links each change back to the plan.
66
+ - **Feature thread.** A feature plus every later change and fix that builds on it, linked by a
67
+ `parent` field.
68
+
69
+ Work moves in two parts. **Shape** plans the work in the Product repository. Its steps are the epic,
70
+ the architecture, the UI design, the stories and the test cases. An **epic** is one feature or
71
+ change, and a **story** is one piece of it for one or more repositories. Each planning step stops
72
+ until a person approves it. **Build** makes each story real in each code repository. The steps
73
+ are: spec, implement, checks, ship, and a human code review.
74
+
75
+ <!-- Source: docs/diagrams/work-and-memory.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
76
+ <img src="https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/work-and-memory.svg" width="340" alt="A loop. The project record feeds people and AI assistants, who plan a change. A human review approves it or asks for changes. The approved change is built in the code repositories, then checked and code-reviewed. The merged outcome is recorded, and the next task starts from the updated record.">
77
+
78
+ *How work and the record feed each other. Not every arrow is automatic: people approve, merge and ask
79
+ their assistant for the next step.*
80
+
81
+ The complete map of every step, check and gate is in the
82
+ [full workflow diagram](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg).
83
+ It is large, so open it full size.
46
84
 
47
85
  ## Quickstart
48
86
 
49
- Pick the way in that fits. A **workspace** is the folder that holds the Product (`product/`) and
50
- your code repos side by side:
87
+ **You need:**
88
+
89
+ - Node.js 18 or newer
90
+ - git
91
+ - an AI assistant from the list above
92
+
93
+ The GitHub CLI (`gh`) or GitLab CLI (`glab`) is optional. Without either one, reviews run locally.
94
+
95
+ **1. Install the command and create a project.** Run this in a terminal, in a folder that is not
96
+ inside a git repository:
51
97
 
52
98
  ```bash
53
- npx yadflow new acme # 1a. new product: makes acme/product/, then runs the guided setup
54
- npx yadflow init # 1b. repos you already have: run in the folder that holds them
55
- npx yadflow join <url> # 1c. joining a team: clones the Product and every repo it registers
56
- npx yadflow setup # or run the guided setup inside an existing Product repo
99
+ npm install -g yadflow@latest # installs the yad command
100
+ yad new acme # creates acme/product/ and runs the guided setup
57
101
  ```
58
102
 
59
- `new` creates nothing outside your machine — it prints the `gh`/`glab` line that puts the Product
60
- online. `join` never commits or pushes; it only adds per-machine files. All three leave a small
61
- `.yad-workspace.json` in the workspace, so `yad` finds the Product from any repo it registers.
103
+ Setup asks a few questions: solo or team, one repository or several, GitHub, GitLab or no platform,
104
+ and which assistant folders to install the skills into. Then it creates these:
62
105
 
63
- Then, in your AI IDE, drive the lifecycle by invoking skills by name:
106
+ - `acme/product/` — the Product repository, with the skills and the `.sdlc/` settings
107
+ - `acme/.yad-workspace.json` — this lets `yad` find the Product from inside any code repository the
108
+ Product lists
64
109
 
65
- ```text
66
- run yad-epic # 2. author + gate the "thinking": epic → architecture → UI → stories
67
- run yad-spec … # 3. Build: spec → implement → checks → ship (per story, per repo)
68
- ```
110
+ It creates nothing online. At the end it prints the commands that put the Product on GitHub or GitLab,
111
+ for you to run when you are ready.
69
112
 
70
- Every step stops at a gate until a human approves. New here? **Walk it lesson-by-lesson in the
71
- [guided tutorial](https://abdelrahmannasr.github.io/yadflow/tutorial/)**, or read the
72
- [team guide](TEAM-GUIDE.md).
113
+ ![yad new acme — creates acme/product/ and runs the guided setup, then prints the commands that put the Product online](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/media/setup-wizard.gif)
73
114
 
74
- Running `yad` tells you when a new release is out. To upgrade, run these in the Product:
115
+ **2. Ask for the next action.** Run this in the terminal:
75
116
 
76
117
  ```bash
77
- npm install -g yadflow # 1. install the latest release
78
- yad migrate # 2. preview: which state files this release would rewrite (writes nothing)
79
- yad migrate --apply # 3. rewrite them, keeping a <file>.yad-orig copy of each
80
- yad update # 4. re-sync this project's skills, gate scripts and CI files
81
- yad doctor # 5. confirm everything is healthy
118
+ cd acme/product
119
+ yad next # prints the single next thing to do; run it any time
82
120
  ```
83
121
 
84
- `yad migrate` moves your state files onto the file shape the new release expects. On a minor or patch
85
- release it usually has nothing to do. Coming from 3.x? Read
86
- [upgrading to 4.0](docs/migrations/upgrading-to-4.md) first. See also
87
- [staying up to date](docs/CLI.md#staying-up-to-date).
88
- An update rewrites the files yad manages (gate scripts, CI, PR/MR templates) — but not one **you**
89
- edited: yad records the sha of every file it writes, so an edit to one is reported as `modified` and
90
- left alone. A file it has no record of (an install predating that record) is still replaced, but only
91
- after saving a `.yad-orig` backup
92
- ([managed files](docs/CLI.md#managed-files-what-yad-owns-and-what-you-edited)).
93
-
94
- ## What `npx yadflow setup` installs
95
-
96
- ![yad new acme — makes acme/product/, runs the guided setup wizard (install the yad-* skills, record the Product, wire the gates, stamp the .sdlc config), then prints the commands that put the Product on GitHub or GitLab](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/media/setup-wizard.gif)
97
-
98
- The recording shows `yad new acme`, which runs this wizard inside the new `acme/product/`
99
- ([how to re-record it](https://github.com/abdelrahmannasr/yadflow/blob/main/docs/media/setup-wizard.tape)). The wizard is idempotent and profile-driven (solo/team, greenfield/brownfield, monorepo/separate).
100
- In one pass it produces:
101
-
102
- - **The `yad` CLI** — zero-dependency Node, run via `npx` or a global install. The main groups:
103
-
104
- | Group | Commands |
105
- | --- | --- |
106
- | Start a workspace | `new`, `init`, `join`, `setup` |
107
- | Drive the lifecycle | `next`, `epic new`, `foundation`, `gate`, `skip` / `defer` / `unblock`, `mode`, `dial`, `kill` |
108
- | Drafts and owners | `capture`, `claims`, `fold`, `assign` / `unassign` / `owners` |
109
- | Build | `commit`, `open-pr`, `ship`, `review`, `checkpoint`, `tidy up` |
110
- | Code repos | `repo` (`list`, `clone`, `refresh`, `sync`), `risk-map`, `codeowners` |
111
- | Feature threads | `thread`, `reconcile` |
112
- | Read the record | `history`, `index`, `usage`, `docs` |
113
- | Keep healthy | `doctor`, `check`, `update`, `migrate`, `report` |
114
-
115
- Every command, with its flags: [docs/CLI.md](docs/CLI.md#commands).
116
- - **38 workflow skills** installed into your AI assistant — Claude Code, Codex CLI, Cursor,
117
- Gemini CLI, GitHub Copilot, Zencoder and opencode. See
118
- [which agent reads which directory](#which-ai-agents-are-supported).
119
- - **`.sdlc/` config** — the Product, connected repos, and tool connections
120
- (design, testing, learning), all as plain JSON you can read and diff.
121
- - **CI gates**, wired into every connected repo and the Product as **GitHub Actions or GitLab CI** —
122
- spec-link, contract-check, verified-commits, build/test/lint, the feature-thread gates, the advisory
123
- risk-map check (warns when a code repo's `.sdlc/risk-map` — a risk level per directory, no names — is
124
- stale, says how many approvers a PR asks for — one more when it touches a `high` directory — and names
125
- who has worked in that directory in the last 30 days), and the push-on-main **`yad-update-guard`** (which re-checks any direct-to-default commit — e.g. from
126
- `yad update --push` — with just `verified-commits` + `commit-message`), shipped as CI-agnostic bash
127
- under `checks/`.
128
- - **An agent guardrail** on a verified Product — `hooks/ledger-guard.mjs`, a harness hook that refuses an
129
- agent the CI-owned gate-ledger write at the moment it tries it and names the command that owns the
130
- transition, instead of letting it surface as a CI failure twenty minutes later. Harness-agnostic
131
- (stdin payload, exit 0 allows / 2 denies) and fails open — the CI gate stays the authority. The same
132
- rule guards a person's `git commit` through a `pre-commit` hook `yad check --fix` installs in each clone
133
- (E48); it never overwrites a hook of your own. What to turn on in GitHub or GitLab so the CI checks
134
- actually hold a merge: [Branch protection](docs/branch-protection.md).
135
- - **Background capture** on every Product, in both ledger modes (E43) — `hooks/yad-capture.mjs`, a
136
- harness hook that runs `yad capture` after each agent edit. It snapshots every changed Shape artifact
137
- onto your private `yad/wip/<you>/<epic>` branches, so a draft is never lost and nobody types a git
138
- command. See [Background capture](#background-capture) below.
139
- - **PR/MR templates** and an opt-in CodeRabbit config.
140
-
141
- Your first `yad-epic` seeds the `epics/EP-<slug>/` ledger — the step state and the approvals — so the
142
- audit trail starts the moment you begin real work. The contract lock (`.sdlc/contract-lock.json`, the
143
- hash of the shared contract surface) is written later, by `yad-architecture`. The one exception is a
144
- change-epic that carries its parent's architecture: `yad epic new <slug> --type change --parent EP-<parent> --inherits architecture,contract`
145
- (run for you by `yad-change`) writes a small **pointer-lock** that points at the parent's lock. `yad epic new <slug>` does the same seeding
146
- from the CLI when you would rather lay the track before the writing starts.
147
-
148
- Before any epic, you can also frame the whole product once: `yad foundation new` seeds the
149
- **Foundation** — the Product level, in `foundation/` — and the `yad-discovery` skill writes its
150
- sections (purpose, scope, MVP, roadmap, stack, repos). It is optional, and each epic reads its approved
151
- roadmap.
152
-
153
- ## Which AI agents are supported
154
-
155
- An **agent skill** is a folder holding a `SKILL.md` file — instructions the agent loads when the task
156
- matches. `SKILL.md` is now a format several agents read, and `.agents/skills/` is the directory
157
- several of them agreed to look in. So one install can serve more than one agent.
158
-
159
- `yad setup` asks which directories to install into. Pick by the agent you use:
160
-
161
- | Directory | Agents that read it |
162
- | --- | --- |
163
- | `.claude/` | Claude Code. Cursor also reads it for compatibility. |
164
- | `.agents/` | Codex CLI, Gemini CLI, Cursor, GitHub Copilot |
165
- | `.cursor/` | Cursor — its own directory. Not needed if you install `.agents/`. |
166
- | `.gemini/` | Gemini CLI — its own directory. Not needed if you install `.agents/`. |
167
- | `.zencoder/` | Zencoder |
168
- | `.opencode/` | opencode — installed as flat `commands/<skill>.md` files, not folders |
169
-
170
- A fresh setup offers **`.claude,.agents`**, which together cover every agent in the table. A project that already
171
- has an INSTALL in one of them — a `skills/` folder, or an armed hook entry — is offered that one
172
- instead; a `.cursor/` holding only Cursor rules is not an install, and is offered the default. Checked against each agent's
173
- own documentation on 2026-09-16; `yad doctor` prints the same table's verdict for your project.
174
-
175
- ### Background capture
176
-
177
- `yad capture` saves your work in progress without touching your checkout (E43). It takes every changed
178
- file under `epics/` and `foundation/` — except the ledger (any `.sdlc/` folder and `reviews/`; the four
179
- files a person or a skill writes there, `contract-lock.json`, `change.json`, `design-links.json` and
180
- `test-links.json`, are included) — and commits it onto
181
- a private branch per epic, `yad/wip/<your git name>/<epic>`. It uses git's low-level commands in a
182
- throwaway index, so your branch, your staged changes and your files stay exactly as they were, and no
183
- git hook runs.
184
-
185
- | What | How |
186
- | --- | --- |
187
- | When | After every agent edit, by a hook yad wires in both ledger modes: Claude Code `PostToolUse` in `.claude/settings.json`, Cursor `afterFileEdit` in `.cursor/hooks.json`. Any other agent or editor: run `yad capture` yourself. Each capture takes every changed artifact, so your own editor's edits ride along |
188
- | Push | A capture commits at once, locally. The hook pushes your capture branches (and fetches everyone else's, for claims) in the background at most once every 5 minutes, with no password prompt and a short timeout, so an edit never waits on the network. `yad capture` by hand pushes straight away. With no remote, or offline, the captures stay local and nothing fails |
189
- | CI | yadflow's own push workflow skips `yad/wip/**`. `yad doctor` names any of **your** workflows a push to `yad/wip/*` would start (no branch filter, `branches: ["**"]`, or a `branches-ignore` that does not name it), so you can add `branches-ignore: ["yad/wip/**"]` |
190
- | Off | `"capture": false` in the Product config (`yad check --fix` then removes the hook), or `YAD_CAPTURE=0` for one shell |
122
+ **3. Start your first feature.** Open `acme/product` in your AI assistant and type this instruction
123
+ to it (not into the terminal):
191
124
 
192
- The capture commits are unsigned on purpose — a signing prompt inside a hook would hang the agent — and
193
- each carries `Yad-Epic`, `Yad-Base` and `Yad-Branch` lines. They are drafts: the commit your history
194
- keeps is the fold, below. The push is never forced: if you capture the same epic on two machines, the second push is refused rather than overwriting the first, and a `yad capture` you run by hand says so and names the branch (delete one copy with `git branch -D` to continue the other) — the hook's background push cannot report it. **To remove a capture branch for good** — say a secret was captured — delete it on origin first, then on every machine that has it run `git branch -D yad/wip/<you>/<epic>` **and** `git branch -dr origin/yad/wip/<you>/<epic>` (the second deletes that machine's saved copy of origin's branch; it says so if there is none): a machine that still holds either one rebuilds the branch and pushes it back. On a fresh clone, a capture continues the branch already on origin. Two people with the same git name share branches. The people count that caps review gates
195
- (E71) does not count capture commits.
125
+ ```text
126
+ Run the yad-epic skill: customers can check out their cart in the mobile app,
127
+ and merchants see a queue of pending orders.
128
+ ```
196
129
 
197
- ### Who else is editing a file (claims)
130
+ **What success looks like:** the assistant writes `epics/EP-<name>/epic.md`, opens its review, and
131
+ stops. `yad next` then says the epic review is waiting. How the review passes depends on the platform:
198
132
 
199
- `yad claims` lists who else is editing which artifact right now (E46). It is **advice, not a lock**:
200
- nothing stops anyone, because with no server a real lock is impossible. There is nothing to record by
201
- hand — a claim is read from the capture branches: someone's `yad/wip/<name>/<epic>` branch holds a
202
- saved change to that file that is not on the default branch yet.
133
+ - **With GitHub or GitLab:** a teammate approves the review pull request and it merges. Then run the
134
+ `yad gate sync` command that `yad next` prints, unless your CI does it for you.
135
+ - **With no platform:** a teammate runs `yad gate approve EP-<name> epic.md --by <their name>`, then
136
+ anyone runs `yad gate advance EP-<name> epic.md`.
203
137
 
204
- | What | How |
205
- | --- | --- |
206
- | A claim | A file of the epic that differs between the capture branch's last save and the commit that save was built on — the person's own edits, never what a pull brought in |
207
- | Ends | 4 hours after that branch's last save, or at once when the file on the default branch matches the saved one (the work was merged) |
208
- | `yad claims [<epic>]` | Fetches everyone's capture branches first (short timeout, no prompts), then lists each claim: file, person, last save. `--no-fetch` reads what is already here; `--json` too |
209
- | At edit time | When an edit changes a file someone else has a claim on, the capture hook says so. Under Claude Code the agent reads it (and you see it); under Cursor it is a line on stderr. It never blocks, never waits on the network, and names the same person and file at most once an hour |
210
- | Fresh enough | The hook's background push (at most every 5 minutes) also fetches everyone's capture branches in the background |
138
+ In solo mode no approval is needed. Merging your own pull request (then the same `yad gate sync`,
139
+ unless CI runs it), or `yad gate advance` with no platform, is the human decision. After that, `yad next` names the next step.
211
140
 
212
- **Limits.** Someone with capture off, or offline, is invisible. A claim can be up to about 5 minutes
213
- late. Two people with the same git name share capture branches, so they never see each other. Times
214
- are the saver's own clock, shown in UTC.
141
+ **Other ways in:**
215
142
 
216
- ### Who owns a step (assign)
143
+ | You have | Run | Then |
144
+ | --- | --- | --- |
145
+ | Existing repositories | `yad init`, in the folder that holds them | Run the `yad-backfill` skill first. It records what already exists. |
146
+ | One existing repository with all the code | `yad setup --brownfield --monorepo`, inside it | The same: run `yad-backfill` first. |
147
+ | A team that already uses Yadflow | `yad join <Product clone URL>` | It clones the Product and every repository it lists. It sets up only this machine and never commits. |
217
148
 
218
- `yad assign` gives one authoring step to one person (E47) — for example "Bob writes the
219
- architecture". It is stronger advice than a claim, because it is decided in advance, but it is still
220
- **advice, not a lock**: it never blocks an edit, never holds a review gate and never stops a fold.
149
+ **Small changes.** Not every change needs the full route:
221
150
 
222
- | What | How |
223
- | --- | --- |
224
- | `yad assign <epic> <step> [--to <name>]` | Assigns the step to you, or to the person whose **git name** you give (the name they commit with). Only authoring steps that write an artifact (`epic`, `architecture`, `stories`, …); review steps are not assigned, because the platform and the gate count decide who approves. If someone else already owns the step it is refused and names them; `--force` replaces them |
225
- | `yad unassign <epic> <step>` | Removes the assignment. Your own freely; someone else's needs `--force` |
226
- | `yad owners [<epic>]` | Lists every assignment, whether it is live, and any owner file that cannot be read. `--json` too |
227
- | Where it is kept | One small file per step: `epics/<epic>/.sdlc/owners/<step>.json` (`foundation/.sdlc/owners/` for the Foundation). It is not a ledger file, so you can write it in both ledger modes. `yad assign` does not commit it, and `yad fold` never takes it (an assignment is not authoring): commit it on its own — on a `verified` Product, in a PR of its own (the Product checks let a PR that changes only owner files through, since E47; run `yad update` so your copies of the checks and of the product-checks workflow have that rule; `yad doctor` warns `owners:rename-blind` if a hand-edited workflow was kept) — so the team sees it when they pull. It is captured to your `yad/wip/…` branch like any artifact, but it is not counted as a claim |
228
- | Live | While the step's work is open: the step is not finished, or its review has not passed yet. After that the file stays as a record; re-opening the step makes it live again. There is no time limit |
229
- | Shown | `yad next` prints `owner: <name>` under the step (and under its review) while it is live |
230
- | At edit time | When your edit changes a file of a step someone else owns, the capture hook says so — to the agent under Claude Code, on stderr under Cursor — at most once an hour per step. One note carries both this and any claim warning |
231
-
232
- **Limits.** The name is the git name, made branch-safe the way capture branch names are — so it matches
233
- the capture hook without asking GitHub or GitLab. Two people with the same git name look like one owner.
234
- A git name with no Latin letters is branch-safe only through the person's email, so someone else can
235
- assign it only once that person has a capture branch here (`--to` finds it by the git name the branch was
236
- saved under). With capture off, there is no edit-time warning.
237
-
238
- ### Folding a step into one commit
239
-
240
- `yad fold <epic> <step>` ends an authoring step (E44). It makes the one commit the record keeps,
241
- `docs(<epic>): author <step>` — for example `docs(EP-checkout): author architecture`. The authoring
242
- skills run it at the end of their step; you can run it yourself too.
243
-
244
- | What | How |
245
- | --- | --- |
246
- | Files | Only that step's files: the ones its review covers (architecture is `architecture.md`, `contract.md` and `.sdlc/contract-lock.json`; stories is everything under `stories/`), plus what the step's skill writes beside them (`DESIGN.md` and `.sdlc/design-links.json` for the UI step, `.sdlc/test-links.json` for test cases). Other changed files of the epic are named and left on disk, so a half-written draft of another step never lands in this commit |
247
- | The ledger | Follows `ledger` mode. `local`: the epic's changed ledger files go in the same commit — one step, one commit. `verified`: CI writes the ledger at merge, so the fold leaves those files for CI — except while the epic is brand new (no `.sdlc/state.json` in HEAD yet): then its new ledger files are its seed, which is the case `ledger-guard` allows and the only way a seed reaches the default branch. Once the epic is seeded, even a NEW ledger file (a `reviews/*.md` written by hand) is left for CI, because the guard would reject it |
248
- | The seed | While the epic is brand new, the first fold also takes the new person-written `.sdlc/` files beside the ledger — a change-epic's `change.json` and its pointer `contract-lock.json` — in both modes |
249
- | The commit | A normal `git commit`, so it is signed if your git signs (with `ledger: verified` it warns when signing is off: the review PR's signature check would fail), and your commit hooks run. Only the step's files are committed; anything else you staged stays staged. It ends with `Yad-Epic`, `Yad-Step` and `Yad-Folded` lines — the last is the tip of your capture branch, the drafts this commit folds (`none` with capture off) |
250
- | Where | With `ledger: verified`, never on the default branch — artifacts reach it only through the review PR. With `ledger: local`, anywhere |
251
- | The drafts | Your `yad/wip/<you>/<epic>` branch is left as it is: the draft history stays for the later rework measurement (E95), and nothing has to be deleted on other machines. The next capture has nothing new to save |
151
+ - `yad epic new <id> --profile chore` gives a short route with just the epic and the stories. This
152
+ route cannot change the shared contract.
153
+ - Commits of type `chore`, `ci`, `build` or `test` (the start of the commit title, for example
154
+ `chore:` or `chore(deps):`) do not need a task link.
155
+ - `yad skip` and `yad defer` pass over optional steps, such as the UI design.
252
156
 
253
- A step with no changed files has nothing to fold, and says so. `yad open-pr` on a review branch warns
254
- when that step's files have changes no fold has committed — they are not in the review.
157
+ **Already using Yadflow?** Follow [staying up to date](docs/CLI.md#staying-up-to-date). Coming from
158
+ 3.x, read [upgrading to 4.0](docs/migrations/upgrading-to-4.md) first.
255
159
 
256
- ### The local ledger guard, per agent
160
+ ## How the project record evolves
257
161
 
258
- In **verified mode** — where CI owns the gate ledger — yadflow installs a local guardrail that stops
259
- an agent hand-editing the gate files, at the moment of the edit rather than twenty minutes later in a
260
- failed pipeline. It needs a hook that can run *before* a write and refuse it. Two agents have one:
162
+ When shipped work needs to change, you do not edit the old plan. You start a **linked change**. The
163
+ `yad-change` skill sorts the change into one of four kinds:
261
164
 
262
- | Agent | Wired into | Event |
263
- | --- | --- | --- |
264
- | Claude Code | `.claude/settings.json` | `PreToolUse` |
265
- | Cursor | `.cursor/hooks.json` | `preToolUse` |
165
+ - a defect fix
166
+ - a behavior change
167
+ - a contract change
168
+ - a new capability
266
169
 
267
- Cursor answers this kind of hook in JSON rather than by exit code, and treats an empty answer as a
268
- refusal — so a `.cursor` project also gets a small adapter script, `hooks/ledger-guard-cursor.mjs`,
269
- which always replies properly. Without it the guard would have blocked every file write instead of
270
- just the gate files.
170
+ The kind decides which documents must be written again. The skill then starts a new epic with
171
+ `yad epic new --type change --parent <epic> --inherits <documents>`. Documents it inherits are not
172
+ copied. They point back to the parent's approved files.
271
173
 
272
- Every other directory gets the script (`hooks/ledger-guard.mjs`) and no wiring — they have no such
273
- hook, so those agents are guarded by CI alone. `yad doctor` says so by name rather than staying
274
- silent. The Cursor wiring follows Cursor's published hook protocol and has not yet been exercised
275
- against a live Cursor session.
174
+ <!-- Source: docs/diagrams/feature-evolution.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
175
+ <img src="https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/feature-evolution.svg" width="720" alt="The checkout feature has two children: a fix that adds a missing queue test, and a change that sorts the queue. The feature's architecture, contract, UI and other stories still apply. The change replaces the epic text and retires one old queue story. The current picture for the next task combines what still applies, the fix's story and tests, and the change's epic text.">
276
176
 
277
- ## Your first five minutes
177
+ *The checkout thread. The fix is a real record in `epics/`; the change is the one the demo adds.*
278
178
 
279
- <!-- IMAGE: docs/media/artifact-waiting.png — "A generated epic waits at its gate — nothing advances until a human approves." -->
179
+ `yad thread <epic>` prints the **current truth**: which epic each document comes from today.
280
180
 
281
- ```text
282
- setup → AI drafts an artifact → ⛔ gate waits → you approve → next step → ⛔ gate waits → …
283
- ```
181
+ - **A document written again** (the epic, architecture, contract or UI design) comes from the epic
182
+ furthest down the thread (the longest chain of parents back to the original feature) that does not
183
+ inherit it and whose route has the step that writes it. A skipped step still counts. When two
184
+ epics are equally far down, the one whose ID sorts last wins. Dates play no part.
185
+ - **Stories and test cases add up** across the thread.
186
+ - **Retired stories drop out.** A change can retire a parent story with `supersedes`.
284
187
 
285
- 1. **Get a workspace** — `npx yadflow new <name>` for a new product, `npx yadflow init` for repos you
286
- already have, or `npx yadflow join <url>` to join a team (see [Quickstart](#quickstart)). The
287
- wizard installs the skills, connects your repos, and wires the gates.
288
- 2. **Run `yad-epic`** in your assistant — it drafts the epic, then **stops** and writes it to a file.
289
- 3. **A gate waits.** Nothing advances until you review it.
290
- 4. **You approve** — by merging the review PR/MR, or, with no GitHub or GitLab, with
291
- `yad gate approve` and `yad gate advance`.
292
- 5. **The workflow continues** to the next step, which stops again.
293
-
294
- Every step is the same contract: *AI proposes → a human decides → the trail is recorded.*
295
-
296
- ## How it works (in five points)
297
-
298
- - **Shape = decide.** Once per epic, in the Product: epic, architecture + a locked contract,
299
- UI, stories, test cases. Always human-gated — nothing auto-advances.
300
- - **Build = make it real.** Once per story per code repo: spec → implement → checks → ship.
301
- - **Every step stops at a gate.** A human moves it forward (local, or by merging a review PR/MR).
302
- <!-- IMAGE: docs/media/pr-gate.png — "The review gate rides a real PR/MR: approve to advance, comment to block." -->
303
- - **Automation is opt-in.** The team switches a Build step to auto with `yad dial`, which shows that
304
- step's run record as advice — and `yad kill` holds everything at manual in one command. A review
305
- gate — the engineer review and every Shape review — is never automatic.
306
- - **Everything is files.** State, approvals, the contract lock, the build log — all plain files under
307
- `epics/EP-<slug>/`. No database. The audit trail *is* the repo.
308
-
309
- ## Why not just use Cursor?
310
-
311
- Because Yadflow lives in a different layer. Cursor, Claude Code, Copilot, Continue, Roo, and Cline
312
- *generate* code. Yadflow *governs* what happens to it — review, architectural control, and an audit
313
- trail — so you get AI speed without losing control of quality or accountability. They're
314
- complementary: bring your favorite, and Yadflow wraps the engineering process around it.
315
-
316
- | | Your AI assistant | **Yadflow** |
317
- |---------------|--------------------------|------------------------------------------------------|
318
- | **Layer** | Writes the code | Governs how it ships |
319
- | **Output** | Diffs, completions | Gated artifacts + a file-based audit trail |
320
- | **Answers** | "Write this for me" | "Should this merge — and who approved it?" |
321
- | **Review** | You eyeball the diff | Human-gated PR/MR, contract lock, switchable automation |
322
- | **Fit** | Bring your own | Wraps around all of them |
323
-
324
- ## Review, made a pairing — and a lesson
325
-
326
- Reviewing AI-generated code is where governance lives or dies, so Yadflow makes the honest review the
327
- *easiest* path. The **Review Companion** turns any PR/MR into a 60-second trailer, swipe-through cards,
328
- and a grounded chat. **Pair Review** (the `yad-pair-review` skill; its CLI side is `yad gate walkthrough` for a Shape
329
- review and `yad review walkthrough` for a code PR) goes further: the AI walks you through the
330
- change one risk-ordered stop at a time, explains each, then asks you about it — until both sides are
331
- satisfied.
332
-
333
- It doubles as a lesson: it teaches a transferable review method, scores you against it, and records
334
- your review-skill growth in a **private, local-only** learning log (the `yad-status` skill rolls it up). It's
335
- **soft and additive** — it never blocks a merge on its own, yet any genuine concern it surfaces blocks
336
- like a normal review comment.
337
-
338
- ## Who it's for
339
-
340
- Tech leads and engineering managers who want their team to move fast with AI-assisted development
341
- **without** giving up review, architectural control, or an audit trail — the governance layer around
342
- AI-assisted software engineering, not another code generator.
343
-
344
- And because the audit trail *is* the repo, **`yad usage`** turns it into a per-member adoption &
345
- behavior report (HTML/JSON/MD): who authored, reviewed, approved, and shipped, with factual
346
- workflow-hygiene flags — derived read-only, so an EM can see how the team actually uses the flow.
188
+ Two rules keep this honest:
347
189
 
348
- ## Documentation
190
+ - **The view includes drafts.** `yad thread` names the epic that will rewrite a document as soon as
191
+ that epic's `epic.md` is written, even as a draft, before the document itself is written or
192
+ reviewed.
193
+ - **Only approved work can be inherited.** A new epic can inherit a step only after that step and its
194
+ review are finished.
195
+
196
+ When every story of an epic has shipped, the epic is **sealed**. New behavior then needs a new linked
197
+ epic. A CI check enforces this when it can reach the Product repository.
198
+
199
+ **Keeping the record fresh.** Nothing refreshes in the background, except the draft-saving hook.
200
+ Yadflow gives you explicit checks, and each one says who acts:
201
+
202
+ | Record | How it is checked | Who refreshes it | Enforced? |
203
+ | --- | --- | --- | --- |
204
+ | Approvals | Tied to the file's exact contents | A person approves again | Yes. An outdated approval does not count at the gate. |
205
+ | Shared contract | A lock file holds its hash | The architecture skill locks it again | Yes. A CI check always requires a contract change to be declared, and checks the lock when it can reach the Product. |
206
+ | Code snapshots of each repository | Out of date once the repository moves on | `yad repo refresh`, then the `yad-connect-repos` skill for the code map | No. `yad doctor` and `yad repo list` warn. |
207
+ | Product index (`.sdlc/index.json`) | A hash of its inputs | `yad` commands, or CI at merge | No. `yad doctor` warns. |
208
+ | Documentation sites | `yad docs sync` (check only by default) | The `yad-docs` skills | No |
209
+ | Drafts in progress | — | A hook saves each edit (Claude Code, Cursor). Elsewhere, run `yad capture`. | No |
210
+
211
+ **What it does not do:**
349
212
 
350
- - **[Guided tutorial](https://abdelrahmannasr.github.io/yadflow/tutorial/)** — learn by doing, setup → first shipped feature.
351
- - **[Terminology & workflow report](https://abdelrahmannasr.github.io/yadflow/)** — every term, artifact, gate, and skill on one illustrated page.
352
- - **[TEAM-GUIDE.md](TEAM-GUIDE.md)** — the short, plain-language version for a developer team.
353
- - **[docs/CLI.md](docs/CLI.md)** — the full `yad` command reference, the PR-driven gate, and `yad doctor` codes.
354
- - **[docs/SKILLS.md](docs/SKILLS.md)** — the catalogue of all 38 agent skills.
355
- - **[docs/WALKTHROUGH.md](docs/WALKTHROUGH.md)** — the by-hand, end-to-end path through every phase.
356
- - **[CONTRIBUTING.md](CONTRIBUTING.md)** · **[RESEARCH-NOTES.md](RESEARCH-NOTES.md)** · **[RELEASING.md](RELEASING.md)**
357
- - **[SECURITY.md](SECURITY.md)** — how to report a vulnerability, which versions get fixes, and the supply-chain stance. **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — the community standards for taking part.
213
+ - It does not record your chats with the assistant.
214
+ - It does not guarantee that a person or an AI reads the record correctly.
215
+ - It does not track deployments. An approved plan says what was agreed. The build log says what
216
+ shipped.
358
217
 
359
- ---
218
+ ## Reviews and human control
360
219
 
361
- **Platform support.** Linux and macOS are first-class (CI runs the test suite, bash gates, and the
362
- end-to-end harness on both). **On Windows, the agent hooks run natively, without WSL** (E113), and the
363
- CLI code they reach has been fixed for Windows — CI runs the hook scripts and those CLI tests on Windows.
364
- The rest of the CLI is not yet tested there. Requires **Node.js ≥ 18**.
220
+ *AI builds. The hand decides.*
365
221
 
366
- | On Windows | What to know |
222
+ The record is worth trusting because people approve what goes into it.
223
+
224
+ - **Planning steps.** Each one stops at a review gate. It moves on only when the approvals arrive,
225
+ review comments are resolved, and the pull request merges. With no platform, `yad gate advance`
226
+ checks the same approval rule. The local gate records the name typed with `--by` and cannot check
227
+ who typed it, so a team that needs proof of who approved should review on GitHub or GitLab.
228
+ - **Required approvals.** The base count is enforced. Extra approvers for risky areas (the contract,
229
+ auth, payments) are advice.
230
+ - **Build steps.** A team can switch a Build step to advance on its own with `yad dial`. `yad kill`
231
+ switches every step back to manual in one command. The engineer code review is always a person.
232
+ - **Checks on every change.** Each change must name its task (spec-link). A contract change must be
233
+ declared and locked again (contract-check). Commits must carry a signature that GitHub or GitLab
234
+ marks as verified (verified-commits; it is skipped, with a warning, when there is no platform).
235
+ To make these checks block a merge, see [branch protection](docs/branch-protection.md).
236
+ - **Pair review.** The `yad-pair-review` skill walks you through a change one risky part at a time.
237
+ It asks you questions and keeps a private log of how your reviewing improves. It never blocks a
238
+ merge by itself.
239
+
240
+ ## Compatibility and limitations
241
+
242
+ | Area | Support |
367
243
  | --- | --- |
368
- | Agent hooks | Each hook is a Node script (`hooks/*.mjs`) that the agent runs as `node <script>`, so nothing needs bash or an execute bit. `node` must be on the PATH your agent runs with — if it is not, the hooks silently do not run |
369
- | Claude Code | Runs hook commands in **Git Bash** (part of Git for Windows). Without Git Bash it falls back to PowerShell, and the hooks do not run there. `yad doctor` warns when it cannot find Git Bash |
370
- | Cursor | Runs hook commands through PowerShell. The entry is `node hooks/<script>.mjs`, which PowerShell runs as it is |
371
- | Line endings | Set `git config core.autocrlf input` in the Product clone. With `true` (the Git for Windows default) git checks files out with CRLF line endings. yad's own managed files still compare equal, but an approval is bound to an artifact's exact bytes, so reviews approved elsewhere read as stale. `yad doctor` warns about this on Windows |
372
- | Check gates | Still bash scripts (`checks/*.sh`). They run on your CI runner, not on your machine |
373
- | Not yet tested on Windows | The full test suite and the end-to-end harness run on Linux and macOS only. A machine with no Git Bash is not covered for Claude Code |
374
-
375
- **Upgrading from a release before E113.** The hooks used to be bash scripts (`hooks/*.sh`). `yad check
376
- --fix` (or `yad update`) rewrites each hook entry to the Node command and deletes the old script — but
377
- only a copy yad's own record (`.sdlc/managed.json`) proves it wrote and nobody changed. A script you
378
- edited, or one your own hook entry still runs, is kept. The old script is also kept until the rewritten
379
- settings file is **committed**: yad never commits that file for you, and a teammate who pulls must not get
380
- an entry that runs a deleted script. So the order is: `yad check --fix`, commit `.claude/settings.json` and
381
- `.cursor/hooks.json`, then `yad check --fix` again to remove the old scripts. Everyone on the team should
382
- upgrade together: an older yadflow does not know the new entries, and its `check --fix` puts the old
383
- script and entry back beside them.
384
-
385
- **Releases** are a human decision. Merging to `main` never publishes; a person fast-forwards the
386
- `release` branch, and [semantic-release](https://semantic-release.gitbook.io/) publishes from there
387
- (Conventional Commits → npm, with provenance). See [RELEASING.md](RELEASING.md).
244
+ | Operating systems | Linux and macOS are fully tested in CI. On Windows, the agent hooks run natively, and the rest of the tool is not yet fully tested. See [platform support](docs/CLI.md#platform-support). |
245
+ | Node.js | 18 or newer |
246
+ | AI assistants | Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub Copilot, Zencoder, opencode. See [which agent reads which folder](docs/CLI.md#which-ai-agents-are-supported). |
247
+ | Hooks | The draft-saving hook runs in Claude Code and Cursor only. The hook that stops an agent editing CI-owned files is added only when CI owns the approval record, and also runs only in those two. The Cursor wiring follows Cursor's published hook format but has not yet been tried in a live Cursor session. Other assistants rely on the CI checks. |
248
+ | Git platforms | GitHub and GitLab for review pull requests and CI. With no platform, reviews run locally with `yad gate`. |
249
+
250
+ ## Available now and planned
251
+
252
+ **Available now:**
253
+
254
+ - workspace setup
255
+ - the Shape and Build steps with review gates
256
+ - linked changes and `yad thread`
257
+ - `yad history`, `yad next` and `yad usage`
258
+ - `yad detect`, which lists the skills, agents, MCP servers and plugins installed for each AI agent
259
+ - draft saving, claims and owners
260
+ - the CI checks
261
+ - the Review Companion
262
+
263
+ **Planned, not built yet** (see the [roadmap](docs/roadmap-idea-1.md)):
264
+
265
+ - a context brief for each task: E24, E82, E89 and E90
266
+ - a cross-repository map with its own staleness tracking: E83
267
+ - a release and deployment phase: E32
268
+ - a single handoff view, an explicit `superseded` status, one combined freshness report, and a
269
+ browsable example project: E126 to E129
270
+
271
+ ## Documentation
272
+
273
+ - **Learn:** the [guided tutorial](https://abdelrahmannasr.github.io/yadflow/tutorial/) (setup to
274
+ your first shipped feature) · the [team guide](TEAM-GUIDE.md) · the
275
+ [terminology and workflow report](https://abdelrahmannasr.github.io/yadflow/)
276
+ - **Reference:**
277
+ - [every `yad` command](docs/CLI.md#commands)
278
+ - [working together: capture, claims, owners, fold](docs/CLI.md#working-together-capture-claims-owners-and-fold)
279
+ - [troubleshooting and error codes](docs/CLI.md#troubleshooting-yad-doctor--error-codes)
280
+ - [all 38 skills](docs/SKILLS.md)
281
+ - [the by-hand walkthrough](docs/WALKTHROUGH.md)
282
+ - **Upgrade:** [staying up to date](docs/CLI.md#staying-up-to-date) ·
283
+ [upgrading to 4.0](docs/migrations/upgrading-to-4.md)
284
+ - **Project:**
285
+ - [CONTRIBUTING.md](CONTRIBUTING.md)
286
+ - [SECURITY.md](SECURITY.md)
287
+ - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
288
+ - [RELEASING.md](RELEASING.md): a person decides every release, and merging to `main` never
289
+ publishes
290
+ - [RESEARCH-NOTES.md](RESEARCH-NOTES.md)