yadflow 3.5.1 → 3.5.2

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/CHANGELOG.md +1 -6
  2. package/README.md +81 -18
  3. package/package.json +8 -2
package/CHANGELOG.md CHANGED
@@ -1,9 +1,4 @@
1
- ## [3.5.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.5.0...v3.5.1) (2026-07-02)
2
-
3
-
4
- ### Bug Fixes
5
-
6
- * preserve roster and verified_authors on hub reconfigure ([84bd0af](https://github.com/abdelrahmannasr/yadflow/commit/84bd0affed378e9b6ed60fa2471816f7a585c9c7))
1
+ ## [3.5.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.5.1...v3.5.2) (2026-07-02)
7
2
 
8
3
  # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
9
4
 
package/README.md CHANGED
@@ -5,9 +5,17 @@
5
5
  [![node](https://img.shields.io/node/v/yadflow?logo=node.js)](https://github.com/abdelrahmannasr/yadflow/blob/main/package.json)
6
6
  [![report](https://img.shields.io/badge/docs-Yadflow%20report-2471a3)](https://abdelrahmannasr.github.io/yadflow/)
7
7
 
8
- **A gated software-development lifecycle where AI builds and a human approves every step.**
8
+ **A governance layer for AI-assisted software engineering — a gated development lifecycle where
9
+ AI builds and a human clears every gate.**
9
10
  *AI builds. The hand decides.* (*yad* — **يد**, Arabic for "hand".) On npm and GitHub as `yadflow`.
10
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** (plus `.agents`, Zencoder, and OpenCode), and **BMAD is the default packaging,
17
+ > not a limitation.**
18
+
11
19
  ## The problem
12
20
 
13
21
  AI writes code faster than any team can review it. Left ungoverned, that speed turns into risk:
@@ -18,8 +26,9 @@ AI, the harder it gets to keep control of quality, architecture, and accountabil
18
26
  ## What Yadflow is
19
27
 
20
28
  Yadflow puts a **human gate on every step** of the lifecycle. Each step does its work, writes its
21
- output to a plain file, and **waits** — it never advances until a human approves it (or, later, until
22
- a step has *earned* the right to auto-advance). Reviews ride real PR/MRs; all state lives in files you
29
+ output to a plain file, and **waits** — it never advances until a human clears its gate (by approving,
30
+ or in solo mode by merging your own PR), or, later, once a step has *earned* the right to auto-advance.
31
+ Reviews ride real PR/MRs; all state lives in files you
23
32
  can read, diff, and edit — no database, nothing hidden. The result is a paper trail for every decision
24
33
  and a hard wall between "AI proposed" and "we shipped it."
25
34
 
@@ -54,39 +63,93 @@ Every step stops at a gate until a human approves. New here? **Walk it lesson-by
54
63
  [guided tutorial](https://abdelrahmannasr.github.io/yadflow/tutorial/)**, or read the
55
64
  [team guide](TEAM-GUIDE.md).
56
65
 
66
+ ## What `npx yadflow setup` installs
67
+
68
+ ![npx yadflow setup — the guided wizard installs the yad-* skills, wires the CI gates, and stamps the .sdlc config](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/media/setup-wizard.gif)
69
+
70
+ The wizard is idempotent and profile-driven (solo/team, greenfield/brownfield, monorepo/separate).
71
+ In one pass it produces:
72
+
73
+ - **The `yad` CLI** — zero-dependency Node (`setup`, `gate`, `commit`, `open-pr`, `ship`, `repo`,
74
+ `thread`, `reconcile`, `usage`, `doctor`), run via `npx` or a global install.
75
+ - **37 workflow skills** installed into your AI assistant — **Claude Code** (`.claude/`) first-class,
76
+ plus `.agents`, Zencoder, and OpenCode.
77
+ - **`.sdlc/` config** — the product hub, connected repos, reviewer roster, and tool connections
78
+ (design, testing, learning), all as plain JSON you can read and diff.
79
+ - **CI gates**, wired into every connected repo and the hub as **GitHub Actions or GitLab CI** —
80
+ spec-link, contract-check, verified-commits, build/test/lint, and the feature-thread gates, shipped
81
+ as CI-agnostic bash under `checks/`.
82
+ - **PR/MR templates** and an opt-in CodeRabbit config.
83
+
84
+ Your first `yad-epic` seeds the `epics/EP-<slug>/` ledger — state, approvals, and the contract lock —
85
+ so the audit trail starts the moment you begin real work.
86
+
87
+ ## Your first five minutes
88
+
89
+ <!-- IMAGE: docs/media/artifact-waiting.png — "A generated epic waits at its gate — nothing advances until a human approves." -->
90
+
91
+ ```text
92
+ setup → AI drafts an artifact → ⛔ gate waits → you approve → next step → ⛔ gate waits → …
93
+ ```
94
+
95
+ 1. **`npx yadflow setup`** — the wizard installs skills, connects your repo, and wires the gates.
96
+ 2. **Run `yad-epic`** in your assistant — it drafts the epic, then **stops** and writes it to a file.
97
+ 3. **A gate waits.** Nothing advances until you review it.
98
+ 4. **You approve** — file-only, or by merging the review PR/MR.
99
+ 5. **The workflow continues** to the next step, which stops again.
100
+
101
+ Every step is the same contract: *AI proposes → a human decides → the trail is recorded.*
102
+
57
103
  ## How it works (in five points)
58
104
 
59
105
  - **Front half = decide.** Once per epic, in the product hub: epic, architecture + a locked contract,
60
106
  UI, stories, test cases. Always human-gated — nothing auto-advances.
61
107
  - **Build half = build.** Once per story per code repo: spec → implement → checks → ship.
62
108
  - **Every step stops at a gate.** A human moves it forward (file-only, or by merging a review PR/MR).
109
+ <!-- IMAGE: docs/media/pr-gate.png — "The review gate rides a real PR/MR: approve to advance, comment to block." -->
63
110
  - **Automation is opt-in and earned.** A safe back-half step can earn auto-advance after it proves
64
111
  itself — and a one-command kill switch reverts everything to manual. The engineer review and all
65
112
  front states are never automatable.
66
113
  - **Everything is files.** State, approvals, the contract lock, the build log — all plain files under
67
114
  `epics/EP-<slug>/`. No database. The audit trail *is* the repo.
68
115
 
116
+ ## Why not just use Cursor?
117
+
118
+ Because Yadflow lives in a different layer. Cursor, Claude Code, Copilot, Continue, Roo, and Cline
119
+ *generate* code. Yadflow *governs* what happens to it — review, architectural control, and an audit
120
+ trail — so you get AI speed without losing control of quality or accountability. They're
121
+ complementary: bring your favorite, and Yadflow wraps the engineering process around it.
122
+
123
+ | | Your AI assistant | **Yadflow** |
124
+ |---------------|--------------------------|------------------------------------------------------|
125
+ | **Layer** | Writes the code | Governs how it ships |
126
+ | **Output** | Diffs, completions | Gated artifacts + a file-based audit trail |
127
+ | **Answers** | "Write this for me" | "Should this merge — and who approved it?" |
128
+ | **Review** | You eyeball the diff | Human-gated PR/MR, contract lock, earned automation |
129
+ | **Fit** | Bring your own | Wraps around all of them |
130
+
69
131
  ## Review, made a pairing — and a lesson
70
132
 
71
133
  Reviewing AI-generated code is where governance lives or dies, so Yadflow makes the honest review the
72
- *easiest* path — and, optionally, a **teaching** one. The **Review Companion** turns a PR/MR into a
73
- 60-second trailer, swipe-through cards, and a grounded chat. On top of it, **Pair Review**
74
- (`yad pair-review`) runs a guided, two-way walkthrough: the AI walks the engineer through the change
75
- **one risk-ordered stop at a time**, explains each change in depth, then **asks them about it**; the
76
- engineer answers and asks back, until **both are satisfied**. The session doubles as a lesson — it
77
- demonstrates a transferable review method, scores the engineer against it, and records their review-skill
78
- growth in a **private, local-only** learning log (`yad status` rolls it up). It's **soft and additive**:
79
- it never blocks a merge, it rides the same `engagement: verified` signal, and any genuine concern it
80
- surfaces blocks like a normal review comment.
134
+ *easiest* path. The **Review Companion** turns any PR/MR into a 60-second trailer, swipe-through cards,
135
+ and a grounded chat. **Pair Review** (`yad pair-review`) goes further: the AI walks you through the
136
+ change one risk-ordered stop at a time, explains each, then asks you about it — until both sides are
137
+ satisfied.
138
+
139
+ It doubles as a lesson: it teaches a transferable review method, scores you against it, and records
140
+ your review-skill growth in a **private, local-only** learning log (`yad status` rolls it up). It's
141
+ **soft and additive** — it never blocks a merge on its own, yet any genuine concern it surfaces blocks
142
+ like a normal review comment.
81
143
 
82
144
  ## Who it's for
83
145
 
84
- Tech leads and engineering managers who want their team to move fast with AI **without** giving up
85
- review, architectural control, or an audit trail — the governance layer around AI-assisted
86
- development, not another code generator. And because the audit trail *is* the repo, `yad usage` turns
87
- it into a per-member **adoption & behavior report** (HTML/JSON/MD) — who authored, reviewed, approved,
88
- and shipped, with factual workflow-hygiene flags — derived read-only, so an EM can see how the team
89
- actually uses the flow.
146
+ Tech leads and engineering managers who want their team to move fast with AI-assisted development
147
+ **without** giving up review, architectural control, or an audit trail — the governance layer around
148
+ AI-assisted software engineering, not another code generator.
149
+
150
+ And because the audit trail *is* the repo, **`yad usage`** turns it into a per-member adoption &
151
+ behavior report (HTML/JSON/MD): who authored, reviewed, approved, and shipped, with factual
152
+ workflow-hygiene flags — derived read-only, so an EM can see how the team actually uses the flow.
90
153
 
91
154
  ## Documentation
92
155
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "yadflow",
3
- "version": "3.5.1",
3
+ "version": "3.5.2",
4
4
  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 37 yad-* skills.",
5
5
  "type": "module",
6
6
  "author": "AbdelRahman Nasr",
@@ -52,7 +52,13 @@
52
52
  "cli",
53
53
  "spec-driven-development",
54
54
  "learning",
55
- "deeptutor"
55
+ "deeptutor",
56
+ "ai-governance",
57
+ "ai-code-review",
58
+ "ai-assisted-development",
59
+ "gated-workflow",
60
+ "code-review",
61
+ "software-delivery"
56
62
  ],
57
63
  "devDependencies": {
58
64
  "@eslint/js": "^10.0.1",