yadflow 1.4.0 → 2.0.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.
- package/CHANGELOG.md +20 -2
- package/README.md +135 -131
- package/bin/{sdlc.mjs → yad.mjs} +18 -17
- package/cli/commit.mjs +3 -3
- package/cli/epic-state.mjs +2 -2
- package/cli/gate.mjs +8 -8
- package/cli/lib.mjs +1 -1
- package/cli/manifest.mjs +77 -36
- package/cli/openpr.mjs +3 -3
- package/cli/plan.mjs +88 -1
- package/cli/platform.mjs +2 -2
- package/cli/reconcile.mjs +18 -10
- package/cli/repo.mjs +5 -5
- package/cli/setup.mjs +7 -7
- package/docs/index.html +1227 -0
- package/package.json +7 -4
- package/skills/sdlc/config.yaml +24 -24
- package/skills/sdlc/install.sh +2 -2
- package/skills/sdlc/module-help.csv +16 -16
- package/skills/{sdlc-author-analysis → yad-analysis}/SKILL.md +12 -12
- package/skills/{sdlc-author-architecture → yad-architecture}/SKILL.md +12 -12
- package/skills/{sdlc-author-architecture → yad-architecture}/references/contract-format.md +1 -1
- package/skills/{sdlc-backfill → yad-backfill}/SKILL.md +4 -4
- package/skills/{sdlc-backfill → yad-backfill}/references/backfill.md +2 -2
- package/skills/{sdlc-backfill → yad-backfill}/templates/checks/backfill-check.sh +1 -1
- package/skills/{sdlc-checks → yad-checks}/SKILL.md +20 -20
- package/skills/{sdlc-checks → yad-checks}/references/check-gates.md +21 -21
- package/skills/{sdlc-checks → yad-checks}/templates/checks/contract-check.sh +2 -2
- package/skills/{sdlc-checks → yad-checks}/templates/checks/verified-commits.sh +2 -2
- package/skills/{sdlc-checks/templates/github/sdlc-checks.yml → yad-checks/templates/github/yad-checks.yml} +3 -3
- package/skills/{sdlc-checks/templates/github/sdlc-verified-commits.yml → yad-checks/templates/github/yad-verified-commits.yml} +4 -4
- package/skills/{sdlc-checks → yad-checks}/templates/gitlab/gitlab-ci.include-root.yml +3 -3
- package/skills/{sdlc-checks/templates/gitlab/sdlc-checks.gitlab-ci.yml → yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml} +7 -7
- package/skills/{sdlc-checks/templates/gitlab/sdlc-verified-commits.gitlab-ci.yml → yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml} +4 -4
- package/skills/{sdlc-connect-repos → yad-connect-repos}/SKILL.md +7 -7
- package/skills/{sdlc-connect-repos → yad-connect-repos}/references/code-context.md +6 -6
- package/skills/{sdlc-connect-repos → yad-connect-repos}/references/hub-config.md +2 -2
- package/skills/{sdlc-author-epic → yad-epic}/SKILL.md +13 -13
- package/skills/{sdlc-author-epic → yad-epic}/references/state-schema.md +13 -13
- package/skills/{sdlc-hub-bridge → yad-hub-bridge}/SKILL.md +24 -24
- package/skills/{sdlc-hub-bridge → yad-hub-bridge}/references/bridge.md +11 -11
- package/skills/{sdlc-hub-bridge → yad-hub-bridge}/references/login-roster.md +2 -2
- package/skills/{sdlc-hub-bridge → yad-hub-bridge}/templates/checks/hub-route.sh +3 -3
- package/skills/{sdlc-hub-bridge/templates/github/sdlc-gate-sync.yml → yad-hub-bridge/templates/github/yad-gate-sync.yml} +10 -10
- package/skills/{sdlc-hub-bridge → yad-hub-bridge}/templates/gitlab/gitlab-ci.include-root.yml +3 -3
- package/skills/{sdlc-hub-bridge/templates/gitlab/sdlc-gate-sync.gitlab-ci.yml → yad-hub-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml} +11 -11
- package/skills/{sdlc-implement → yad-implement}/SKILL.md +14 -14
- package/skills/{sdlc-implement → yad-implement}/references/implement-conventions.md +4 -4
- package/skills/{sdlc-pr-template → yad-pr-template}/SKILL.md +11 -11
- package/skills/{sdlc-pr-template → yad-pr-template}/references/risk-routing.md +5 -5
- package/skills/{sdlc-pr-template → yad-pr-template}/templates/checks/risk-route.sh +2 -2
- package/skills/{sdlc-pr-template → yad-pr-template}/templates/github/pull_request_template.md +1 -1
- package/skills/{sdlc-pr-template → yad-pr-template}/templates/gitlab/merge_request_templates/Default.md +1 -1
- package/skills/{sdlc-pr-template → yad-pr-template}/templates/hub/github/pull_request_template.md +4 -4
- package/skills/{sdlc-pr-template → yad-pr-template}/templates/hub/gitlab/merge_request_templates/Default.md +4 -4
- package/skills/{sdlc-review-comments → yad-review-comments}/SKILL.md +6 -6
- package/skills/{sdlc-review-comments → yad-review-comments}/references/comment-conventions.md +6 -6
- package/skills/{sdlc-review-comments → yad-review-comments}/templates/github/REVIEW_COMMENTS.md +2 -2
- package/skills/{sdlc-review-comments → yad-review-comments}/templates/gitlab/REVIEW_COMMENTS.md +2 -2
- package/skills/{sdlc-review-gate → yad-review-gate}/SKILL.md +13 -13
- package/skills/{sdlc-review-gate → yad-review-gate}/references/gating.md +3 -3
- package/skills/{sdlc-run → yad-run}/SKILL.md +12 -12
- package/skills/{sdlc-run → yad-run}/references/run-loop.md +10 -10
- package/skills/{sdlc-ship → yad-ship}/SKILL.md +8 -8
- package/skills/{sdlc-ship → yad-ship}/references/ship-and-record.md +3 -3
- package/skills/{sdlc-ship → yad-ship}/templates/.coderabbit.yaml +1 -1
- package/skills/{sdlc-spec → yad-spec}/SKILL.md +11 -11
- package/skills/{sdlc-spec → yad-spec}/references/spec-handoff.md +2 -2
- package/skills/{sdlc-status → yad-status}/SKILL.md +6 -6
- package/skills/{sdlc-author-stories → yad-stories}/SKILL.md +10 -10
- package/skills/{sdlc-author-stories → yad-stories}/references/story-schema.md +1 -1
- package/skills/{sdlc-author-ui → yad-ui}/SKILL.md +9 -9
- /package/skills/{sdlc-checks → yad-checks}/templates/checks/build-test-lint.sh +0 -0
- /package/skills/{sdlc-checks → yad-checks}/templates/checks/spec-link.sh +0 -0
- /package/skills/{sdlc-checks → yad-checks}/templates/gitlab/.gitlab-ci.yml +0 -0
- /package/skills/{sdlc-connect-repos → yad-connect-repos}/references/repos-registry.md +0 -0
- /package/skills/{sdlc-implement → yad-implement}/templates/.gitmessage +0 -0
package/docs/index.html
ADDED
|
@@ -0,0 +1,1227 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
+
<title>Yadflow — Terminology & Workflow Structure Report</title>
|
|
7
|
+
<style>
|
|
8
|
+
:root {
|
|
9
|
+
--ink: #1c2733;
|
|
10
|
+
--muted: #5d6b7a;
|
|
11
|
+
--bg: #f6f8fa;
|
|
12
|
+
--card: #ffffff;
|
|
13
|
+
--line: #dde3ea;
|
|
14
|
+
--accent: #2471a3;
|
|
15
|
+
--artifact-bg: #fcf3cf; --artifact-bd: #b7950b;
|
|
16
|
+
--gate-bg: #fdebd0; --gate-bd: #ca6f1e;
|
|
17
|
+
--earns-bg: #d6eaf8; --earns-bd: #2471a3;
|
|
18
|
+
--locked-bg: #eaecee; --locked-bd: #566573;
|
|
19
|
+
--sentinel-bg: #d5f5e3; --sentinel-bd: #1e8449;
|
|
20
|
+
}
|
|
21
|
+
* { box-sizing: border-box; }
|
|
22
|
+
body {
|
|
23
|
+
margin: 0; padding: 0;
|
|
24
|
+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
|
|
25
|
+
color: var(--ink); background: var(--bg);
|
|
26
|
+
line-height: 1.6;
|
|
27
|
+
}
|
|
28
|
+
header.hero {
|
|
29
|
+
background: linear-gradient(135deg, #1c2733 0%, #2471a3 100%);
|
|
30
|
+
color: #fff; padding: 48px 24px 40px;
|
|
31
|
+
}
|
|
32
|
+
header.hero h1 { margin: 0 0 8px; font-size: 2rem; }
|
|
33
|
+
header.hero p { margin: 0; max-width: 880px; opacity: .92; font-size: 1.05rem; }
|
|
34
|
+
.wrap { max-width: 1080px; margin: 0 auto; padding: 0 24px 80px; }
|
|
35
|
+
nav.toc {
|
|
36
|
+
background: var(--card); border: 1px solid var(--line); border-radius: 10px;
|
|
37
|
+
padding: 18px 24px; margin: -26px auto 36px; max-width: 1080px;
|
|
38
|
+
box-shadow: 0 2px 10px rgba(0,0,0,.06);
|
|
39
|
+
}
|
|
40
|
+
nav.toc strong { display: block; margin-bottom: 6px; }
|
|
41
|
+
nav.toc a { color: var(--accent); text-decoration: none; margin-right: 18px; white-space: nowrap; }
|
|
42
|
+
nav.toc a:hover { text-decoration: underline; }
|
|
43
|
+
section { margin-top: 48px; }
|
|
44
|
+
h2 {
|
|
45
|
+
font-size: 1.5rem; border-bottom: 3px solid var(--accent);
|
|
46
|
+
padding-bottom: 6px; margin-bottom: 18px;
|
|
47
|
+
}
|
|
48
|
+
h3 { font-size: 1.15rem; margin-top: 28px; color: #16384f; }
|
|
49
|
+
p.lead { font-size: 1.05rem; }
|
|
50
|
+
.card {
|
|
51
|
+
background: var(--card); border: 1px solid var(--line); border-radius: 10px;
|
|
52
|
+
padding: 20px 24px; margin: 16px 0;
|
|
53
|
+
}
|
|
54
|
+
code, .mono {
|
|
55
|
+
font-family: "SF Mono", SFMono-Regular, Menlo, Consolas, monospace;
|
|
56
|
+
font-size: .88em; background: #eef1f4; border-radius: 4px; padding: 1px 5px;
|
|
57
|
+
}
|
|
58
|
+
pre {
|
|
59
|
+
background: #1c2733; color: #e8eef4; padding: 14px 18px; border-radius: 8px;
|
|
60
|
+
overflow-x: auto; font-size: .85rem; line-height: 1.5;
|
|
61
|
+
}
|
|
62
|
+
pre code { background: none; color: inherit; padding: 0; }
|
|
63
|
+
table { border-collapse: collapse; width: 100%; margin: 14px 0; background: var(--card); font-size: .95rem; }
|
|
64
|
+
th, td { border: 1px solid var(--line); padding: 9px 12px; text-align: left; vertical-align: top; }
|
|
65
|
+
th { background: #eef3f7; }
|
|
66
|
+
tr:nth-child(even) td { background: #fafbfc; }
|
|
67
|
+
|
|
68
|
+
/* ---------- diagram building blocks ---------- */
|
|
69
|
+
.diagram {
|
|
70
|
+
background: var(--card); border: 1px solid var(--line); border-radius: 10px;
|
|
71
|
+
padding: 24px; margin: 18px 0; overflow-x: auto;
|
|
72
|
+
}
|
|
73
|
+
.diagram .caption { text-align: center; color: var(--muted); font-size: .85rem; margin-top: 14px; }
|
|
74
|
+
.flow-v { display: flex; flex-direction: column; align-items: center; gap: 0; }
|
|
75
|
+
.flow-h { display: flex; flex-direction: row; align-items: center; justify-content: center; flex-wrap: wrap; gap: 6px; }
|
|
76
|
+
.node {
|
|
77
|
+
border: 2px solid var(--earns-bd); background: var(--earns-bg);
|
|
78
|
+
border-radius: 8px; padding: 8px 16px; text-align: center;
|
|
79
|
+
min-width: 230px; max-width: 460px; font-size: .92rem;
|
|
80
|
+
}
|
|
81
|
+
.node small { display: block; color: var(--muted); font-size: .78rem; line-height: 1.35; margin-top: 2px; }
|
|
82
|
+
.node.artifact { background: var(--artifact-bg); border-color: var(--artifact-bd); }
|
|
83
|
+
.node.gate { background: var(--gate-bg); border-color: var(--gate-bd); border-radius: 24px; }
|
|
84
|
+
.node.locked { background: var(--locked-bg); border-color: var(--locked-bd); border-style: dashed; }
|
|
85
|
+
.node.sentinel { background: var(--sentinel-bg); border-color: var(--sentinel-bd); border-radius: 24px; }
|
|
86
|
+
.node.plain { background: #f4f6f8; border-color: #90a0af; }
|
|
87
|
+
.arrow-v { color: #7d8b99; font-size: 1.1rem; line-height: 1.4; padding: 2px 0; }
|
|
88
|
+
.arrow-h { color: #7d8b99; font-size: 1.2rem; padding: 0 6px; }
|
|
89
|
+
.lane {
|
|
90
|
+
border: 1.5px dashed #aebac6; border-radius: 12px; padding: 18px 18px 14px; margin: 14px 0;
|
|
91
|
+
background: #fbfcfd;
|
|
92
|
+
}
|
|
93
|
+
.lane > .lane-title {
|
|
94
|
+
font-weight: 700; font-size: .92rem; letter-spacing: .03em; color: #34495e;
|
|
95
|
+
text-transform: uppercase; margin-bottom: 12px;
|
|
96
|
+
}
|
|
97
|
+
.cols { display: flex; gap: 18px; flex-wrap: wrap; align-items: stretch; }
|
|
98
|
+
.cols > div { flex: 1 1 280px; }
|
|
99
|
+
.legend { display: flex; flex-wrap: wrap; gap: 14px; margin-top: 10px; font-size: .85rem; }
|
|
100
|
+
.legend span.key {
|
|
101
|
+
display: inline-block; width: 30px; height: 16px; border-radius: 4px;
|
|
102
|
+
vertical-align: -2px; margin-right: 6px; border: 2px solid;
|
|
103
|
+
}
|
|
104
|
+
.k-artifact { background: var(--artifact-bg); border-color: var(--artifact-bd) !important; }
|
|
105
|
+
.k-gate { background: var(--gate-bg); border-color: var(--gate-bd) !important; }
|
|
106
|
+
.k-earns { background: var(--earns-bg); border-color: var(--earns-bd) !important; }
|
|
107
|
+
.k-locked { background: var(--locked-bg); border-color: var(--locked-bd) !important; border-style: dashed !important; }
|
|
108
|
+
.k-sentinel { background: var(--sentinel-bg); border-color: var(--sentinel-bd) !important; }
|
|
109
|
+
|
|
110
|
+
/* glossary */
|
|
111
|
+
.gsearch {
|
|
112
|
+
width: 100%; padding: 10px 14px; font-size: 1rem; border: 1.5px solid var(--line);
|
|
113
|
+
border-radius: 8px; margin: 8px 0 18px;
|
|
114
|
+
}
|
|
115
|
+
dl.gloss { margin: 0; }
|
|
116
|
+
dl.gloss dt {
|
|
117
|
+
font-weight: 700; margin-top: 14px; font-size: 1rem;
|
|
118
|
+
}
|
|
119
|
+
dl.gloss dt code { font-size: .95em; }
|
|
120
|
+
dl.gloss dd { margin: 2px 0 0 0; color: #2e3d4c; }
|
|
121
|
+
.term { background: var(--card); border: 1px solid var(--line); border-left: 4px solid var(--accent); border-radius: 8px; padding: 12px 16px; margin: 10px 0; }
|
|
122
|
+
.term.hidden { display: none; }
|
|
123
|
+
.badge {
|
|
124
|
+
display: inline-block; font-size: .7rem; font-weight: 700; letter-spacing: .04em;
|
|
125
|
+
text-transform: uppercase; border-radius: 10px; padding: 1px 9px; margin-left: 8px; vertical-align: 2px;
|
|
126
|
+
}
|
|
127
|
+
.b-core { background: #d6eaf8; color: #1a5276; }
|
|
128
|
+
.b-file { background: #fcf3cf; color: #7d6608; }
|
|
129
|
+
.b-gate { background: #fdebd0; color: #935116; }
|
|
130
|
+
.b-build { background: #d5f5e3; color: #186a3b; }
|
|
131
|
+
.b-auto { background: #e8daef; color: #5b2c6f; }
|
|
132
|
+
.b-tool { background: #eaecee; color: #2c3e50; }
|
|
133
|
+
.b-role { background: #fadbd8; color: #922b21; }
|
|
134
|
+
.callout {
|
|
135
|
+
border-left: 4px solid var(--gate-bd); background: var(--gate-bg);
|
|
136
|
+
padding: 12px 16px; border-radius: 0 8px 8px 0; margin: 16px 0;
|
|
137
|
+
}
|
|
138
|
+
.callout.green { border-left-color: var(--sentinel-bd); background: var(--sentinel-bg); }
|
|
139
|
+
.skillcard {
|
|
140
|
+
background: var(--card); border: 1px solid var(--line); border-radius: 10px;
|
|
141
|
+
padding: 16px 20px; margin: 14px 0;
|
|
142
|
+
}
|
|
143
|
+
.skillcard h4 { margin: 0 0 8px; font-size: 1.05rem; }
|
|
144
|
+
.skillcard h4 code { font-size: 1em; background: #eef3f7; }
|
|
145
|
+
.skillcard .row { margin: 6px 0; }
|
|
146
|
+
.skillcard .lbl {
|
|
147
|
+
display: inline-block; min-width: 64px; font-weight: 700; font-size: .78rem;
|
|
148
|
+
letter-spacing: .05em; text-transform: uppercase; color: #fff; text-align: center;
|
|
149
|
+
border-radius: 5px; padding: 1px 8px; margin-right: 8px; vertical-align: 1px;
|
|
150
|
+
}
|
|
151
|
+
.lbl-what { background: #2471a3; }
|
|
152
|
+
.lbl-how { background: #1e8449; }
|
|
153
|
+
.lbl-when { background: #ca6f1e; }
|
|
154
|
+
.skillcard pre { margin: 8px 0 4px; }
|
|
155
|
+
.callout.blue { border-left-color: var(--earns-bd); background: var(--earns-bg); }
|
|
156
|
+
footer { color: var(--muted); font-size: .85rem; margin-top: 60px; border-top: 1px solid var(--line); padding-top: 16px; }
|
|
157
|
+
@media print {
|
|
158
|
+
nav.toc { box-shadow: none; }
|
|
159
|
+
.diagram, .card { break-inside: avoid; }
|
|
160
|
+
}
|
|
161
|
+
</style>
|
|
162
|
+
</head>
|
|
163
|
+
<body>
|
|
164
|
+
|
|
165
|
+
<header class="hero">
|
|
166
|
+
<div class="wrap" style="padding-bottom:0">
|
|
167
|
+
<h1>Yadflow — Terminology & Structure Report</h1>
|
|
168
|
+
<p><strong>Yadflow</strong> (<em>yahd-flow</em> — from <strong>يد</strong>, Arabic for “hand”) is the AI-driven SDLC
|
|
169
|
+
where a human hand moves every gate. <em>AI builds. The hand decides.</em><br>
|
|
170
|
+
A plain-language guide to every term used in the project (npm + GitHub: <code style="background:rgba(255,255,255,.15);color:#fff">yadflow</code>),
|
|
171
|
+
plus the full workflow structure with diagrams — including how to run it on a brand-new (greenfield) project,
|
|
172
|
+
an existing (brownfield) project, and a multi-repo product.</p>
|
|
173
|
+
</div>
|
|
174
|
+
</header>
|
|
175
|
+
|
|
176
|
+
<nav class="toc">
|
|
177
|
+
<strong>Contents</strong>
|
|
178
|
+
<a href="#big-picture">1. The big picture</a>
|
|
179
|
+
<a href="#structure">2. Workflow structure</a>
|
|
180
|
+
<a href="#gate">3. The review gate</a>
|
|
181
|
+
<a href="#glossary">4. Terminology glossary</a>
|
|
182
|
+
<a href="#project-types">5. Project types (greenfield / brownfield / multi-repo)</a>
|
|
183
|
+
<a href="#skills">6. Skills guide (what / how / when)</a>
|
|
184
|
+
<a href="#cli">7. Commands guide (what / how / when)</a>
|
|
185
|
+
<a href="#competitors">8. Competitor analysis</a>
|
|
186
|
+
</nav>
|
|
187
|
+
|
|
188
|
+
<div class="wrap">
|
|
189
|
+
|
|
190
|
+
<!-- ======================================================= -->
|
|
191
|
+
<section id="big-picture">
|
|
192
|
+
<h2>1. The big picture — what Yadflow is</h2>
|
|
193
|
+
<p class="lead">
|
|
194
|
+
<strong>Yadflow</strong> is a team workflow engine built on top of <strong>BMAD</strong>
|
|
195
|
+
(installed from npm as <code>yadflow</code>; the skills are still named <code>sdlc-*</code> and the
|
|
196
|
+
CLI command is <code>yad</code>).
|
|
197
|
+
It takes a feature from a raw idea all the way to shipped code, in small steps.
|
|
198
|
+
Every step does its work, <strong>writes its result to a plain file</strong>, and then
|
|
199
|
+
<strong>stops and waits at a gate</strong> until a human approves. Nothing is hidden in a
|
|
200
|
+
database — all state is files you can read and edit yourself.
|
|
201
|
+
</p>
|
|
202
|
+
<div class="callout green">
|
|
203
|
+
<strong>The one-sentence idea:</strong> AI does the heavy lifting; humans keep every important decision.
|
|
204
|
+
Automation is never assumed — it must be <em>earned</em> with evidence, and it can be switched off in one move.
|
|
205
|
+
</div>
|
|
206
|
+
|
|
207
|
+
<h3>The four repos</h3>
|
|
208
|
+
<p>You work with four separate git repositories, each with exactly one job:</p>
|
|
209
|
+
<div class="diagram">
|
|
210
|
+
<div class="flow-h" style="align-items:flex-start; gap:18px">
|
|
211
|
+
<div class="flow-v" style="flex:1; min-width:220px">
|
|
212
|
+
<div class="node plain"><strong>yadflow</strong><small>the SKILLS SOURCE — you install the workflow from here and pull updates from here. No product work happens inside it.</small></div>
|
|
213
|
+
</div>
|
|
214
|
+
<div class="arrow-h">➜</div>
|
|
215
|
+
<div class="flow-v" style="flex:1; min-width:220px">
|
|
216
|
+
<div class="node artifact"><strong>product-hub</strong><small>the THINKING — all epics, contracts, stories, reviews and state live here under <code>epics/EP-<slug>/</code></small></div>
|
|
217
|
+
</div>
|
|
218
|
+
<div class="arrow-h">⇄</div>
|
|
219
|
+
<div class="flow-v" style="flex:1; min-width:220px; gap:8px">
|
|
220
|
+
<div class="node"><strong>code-repo-1</strong><small>the CODE — real app code + per-story specs under <code>specs/<story-id>/</code></small></div>
|
|
221
|
+
<div class="node"><strong>code-repo-2</strong></div>
|
|
222
|
+
<div class="node"><strong>code-repo-3</strong></div>
|
|
223
|
+
</div>
|
|
224
|
+
</div>
|
|
225
|
+
<div class="caption">Skills install into the hub · the hub caches a “code-map” of each repo · every code PR links back to its story in the hub.</div>
|
|
226
|
+
</div>
|
|
227
|
+
|
|
228
|
+
<div class="callout blue">
|
|
229
|
+
<strong>The handoff rule:</strong> everything <em>up to and including the locked contract</em> lives in the
|
|
230
|
+
<strong>product hub</strong>. Everything <em>from the spec onward</em> (specs, tasks, code) lives in each
|
|
231
|
+
<strong>code repo</strong>, with a link back to its story.
|
|
232
|
+
</div>
|
|
233
|
+
|
|
234
|
+
<h3>The two halves</h3>
|
|
235
|
+
<div class="cols">
|
|
236
|
+
<div class="card">
|
|
237
|
+
<strong>Front half = decide (the “brain”).</strong><br>
|
|
238
|
+
Runs <em>once per epic</em>, in the <strong>product hub</strong>. Here the team agrees on the epic,
|
|
239
|
+
the architecture, the locked contract, the UI design, and the stories.
|
|
240
|
+
<em>Always human-approved — these steps can never auto-advance.</em>
|
|
241
|
+
</div>
|
|
242
|
+
<div class="card">
|
|
243
|
+
<strong>Back half = build.</strong><br>
|
|
244
|
+
Runs <em>once per story, per code repo</em>, inside that code repo:
|
|
245
|
+
spec → implement → check → ship. These are the safe, mechanical steps —
|
|
246
|
+
they can <em>earn</em> automation over time.
|
|
247
|
+
</div>
|
|
248
|
+
</div>
|
|
249
|
+
|
|
250
|
+
<h3>The two dials (set per step)</h3>
|
|
251
|
+
<table>
|
|
252
|
+
<tr><th>Dial</th><th>Values</th><th>What it answers</th></tr>
|
|
253
|
+
<tr>
|
|
254
|
+
<td><strong>Assistance</strong></td>
|
|
255
|
+
<td><code>none</code> · <code>review</code> · <code>heavy</code></td>
|
|
256
|
+
<td>How much does AI help with the work of this step?</td>
|
|
257
|
+
</tr>
|
|
258
|
+
<tr>
|
|
259
|
+
<td><strong>Automation</strong></td>
|
|
260
|
+
<td><code>human_approve</code> · <code>machine_advance</code></td>
|
|
261
|
+
<td>Who moves this step forward — a human or the machine?</td>
|
|
262
|
+
</tr>
|
|
263
|
+
</table>
|
|
264
|
+
<p>Keeping the dials separate lets you say “heavy AI help, but a human must approve” — the exact setting
|
|
265
|
+
for the design steps. Every step starts at <code>human_approve</code>. The front steps and the final
|
|
266
|
+
engineer review are <strong>locked there permanently</strong>.</p>
|
|
267
|
+
</section>
|
|
268
|
+
|
|
269
|
+
<!-- ======================================================= -->
|
|
270
|
+
<section id="structure">
|
|
271
|
+
<h2>2. The workflow structure, end to end</h2>
|
|
272
|
+
<p>Setup is one-time. The front half runs once per epic in the hub; the build half runs once per story
|
|
273
|
+
per code repo; automation is opt-in and earned. The diagram below is the whole lifecycle.</p>
|
|
274
|
+
|
|
275
|
+
<div class="diagram">
|
|
276
|
+
<div class="legend">
|
|
277
|
+
<span><span class="key k-artifact"></span><strong>artifact</strong> — an author step writes a file and stops</span>
|
|
278
|
+
<span><span class="key k-gate"></span><strong>gate</strong> — a human review that must pass</span>
|
|
279
|
+
<span><span class="key k-earns"></span><strong>earns automation</strong> — can later auto-advance once proven</span>
|
|
280
|
+
<span><span class="key k-locked"></span><strong>locked</strong> — permanently human</span>
|
|
281
|
+
<span><span class="key k-sentinel"></span><strong>milestone</strong></span>
|
|
282
|
+
</div>
|
|
283
|
+
|
|
284
|
+
<div class="lane">
|
|
285
|
+
<div class="lane-title">0 · One-time setup (team lead, per project)</div>
|
|
286
|
+
<div class="flow-v">
|
|
287
|
+
<div class="node plain"><strong>Install the module</strong><small><code>npx yadflow setup</code> — copies the 17 skills into your IDE dirs</small></div>
|
|
288
|
+
<div class="arrow-v">▼</div>
|
|
289
|
+
<div class="node plain"><strong>Wire each repo</strong><small><code>yad-checks</code> · <code>yad-pr-template</code> · <code>yad-review-comments</code> (CI gates, PR template, comment scaffold)</small></div>
|
|
290
|
+
<div class="arrow-v">▼</div>
|
|
291
|
+
<div class="node plain"><strong>Connect code repos</strong><small><code>yad-connect-repos</code> → <code>repos.json</code> + a cached code-map per repo <em>(skip if greenfield)</em></small></div>
|
|
292
|
+
<div class="arrow-v">▼</div>
|
|
293
|
+
<div class="node plain"><strong>Optional: hub on a platform</strong><small>detect GitHub/GitLab + reviewer roster, so reviews run on real PRs/MRs</small></div>
|
|
294
|
+
</div>
|
|
295
|
+
</div>
|
|
296
|
+
|
|
297
|
+
<div class="flow-v"><div class="arrow-v">▼</div></div>
|
|
298
|
+
|
|
299
|
+
<div class="lane">
|
|
300
|
+
<div class="lane-title">A · Front half — product hub · human-gated · once per epic</div>
|
|
301
|
+
<div class="flow-v">
|
|
302
|
+
<div class="node artifact"><strong>yad-analysis</strong> <em>(optional)</em><small>pressure-test the idea with the analyst → <code>analysis.md</code></small></div>
|
|
303
|
+
<div class="arrow-v">▼</div>
|
|
304
|
+
<div class="node gate">gate · analysis review</div>
|
|
305
|
+
<div class="arrow-v">▼</div>
|
|
306
|
+
<div class="node artifact"><strong>yad-epic</strong><small>write <code>epic.md</code> · assigns the <code>EP-<slug></code> ID · seeds state</small></div>
|
|
307
|
+
<div class="arrow-v">▼</div>
|
|
308
|
+
<div class="node gate">gate · epic review<small>base rule: owner + 1 reviewer</small></div>
|
|
309
|
+
<div class="arrow-v">▼</div>
|
|
310
|
+
<div class="node artifact"><strong>yad-architecture</strong><small><code>architecture.md</code> + the locked <code>contract.md</code> (hash-locked)</small></div>
|
|
311
|
+
<div class="arrow-v">▼</div>
|
|
312
|
+
<div class="node gate">gate · architecture review<small><strong>escalated:</strong> base rule + a domain owner for every repo in the epic</small></div>
|
|
313
|
+
<div class="arrow-v">▼</div>
|
|
314
|
+
<div class="node artifact"><strong>yad-ui</strong><small><code>ui-design.md</code> + <code>DESIGN.md</code></small></div>
|
|
315
|
+
<div class="arrow-v">▼</div>
|
|
316
|
+
<div class="node gate">gate · UI review<small>base rule</small></div>
|
|
317
|
+
<div class="arrow-v">▼</div>
|
|
318
|
+
<div class="node artifact"><strong>yad-stories</strong><small>repo-tagged stories → <code>stories/EP-<slug>-S0N.md</code></small></div>
|
|
319
|
+
<div class="arrow-v">▼</div>
|
|
320
|
+
<div class="node gate">gate · stories review<small><strong>per-repo:</strong> base rule + the engineer of each touched repo</small></div>
|
|
321
|
+
<div class="arrow-v">▼</div>
|
|
322
|
+
<div class="node sentinel"><strong>ready-for-build</strong><small>the front half is done — building can start</small></div>
|
|
323
|
+
</div>
|
|
324
|
+
</div>
|
|
325
|
+
|
|
326
|
+
<div class="flow-v"><div class="arrow-v">▼</div></div>
|
|
327
|
+
|
|
328
|
+
<div class="lane">
|
|
329
|
+
<div class="lane-title">B · Build half — per story, per code repo</div>
|
|
330
|
+
<div class="flow-v">
|
|
331
|
+
<div class="node plain"><strong>yad-spec</strong><small>Spec Kit ceremony (specify → clarify → plan → analyze → checklist → tasks) → <code>specs/<story-id>/</code></small></div>
|
|
332
|
+
<div class="arrow-v">▼</div>
|
|
333
|
+
<div class="node"><strong>yad-implement</strong><small>1 atomic task = 1 branch = 1 commit (small diff, ≤3 files) — <em>earns automation</em></small></div>
|
|
334
|
+
<div class="arrow-v">▼</div>
|
|
335
|
+
<div class="node"><strong>yad-checks</strong><small>CI gates: spec-link · contract-check · build/test/lint · verified-commits — <em>earns automation</em></small></div>
|
|
336
|
+
<div class="arrow-v">▼</div>
|
|
337
|
+
<div class="node plain"><strong>Open PR/MR</strong><small>from the wired template; risk routing picks the required reviewers</small></div>
|
|
338
|
+
<div class="arrow-v">▼</div>
|
|
339
|
+
<div class="node plain"><strong>yad-ship: AI review</strong><small>CodeRabbit first pass — advisory only, never the authority</small></div>
|
|
340
|
+
<div class="arrow-v">▼</div>
|
|
341
|
+
<div class="node locked"><strong>Engineer review</strong><small>a human reads the diff against the spec — <strong>never automated</strong></small></div>
|
|
342
|
+
<div class="arrow-v">▼</div>
|
|
343
|
+
<div class="node sentinel"><strong>merge → recorded in build-log.json</strong><small>story status: <code>in-build</code> → <code>shipped</code></small></div>
|
|
344
|
+
</div>
|
|
345
|
+
</div>
|
|
346
|
+
|
|
347
|
+
<div class="flow-v"><div class="arrow-v">▼</div></div>
|
|
348
|
+
|
|
349
|
+
<div class="lane">
|
|
350
|
+
<div class="lane-title">C · Automation — earned & reversible (optional)</div>
|
|
351
|
+
<div class="flow-v">
|
|
352
|
+
<div class="node"><strong>yad-run</strong><small>drives the back half on each step’s automation dial, recording every run in <code>trust-log.json</code></small></div>
|
|
353
|
+
<div class="arrow-v">▼</div>
|
|
354
|
+
<div class="node plain"><strong>Kill switch</strong><small><code>yad-run action: kill</code> → everything back to <code>human_approve</code> instantly</small></div>
|
|
355
|
+
</div>
|
|
356
|
+
</div>
|
|
357
|
+
<div class="caption">
|
|
358
|
+
<code>yad-status</code> is a read-only view over all of it · <code>yad-hub-bridge</code> mirrors front-half reviews to real PRs/MRs.
|
|
359
|
+
</div>
|
|
360
|
+
</div>
|
|
361
|
+
|
|
362
|
+
<h3>Where every file lives</h3>
|
|
363
|
+
<p>One rule: <strong>shared thinking lives in the product hub; building lives in each code repo; a link connects them.</strong></p>
|
|
364
|
+
<pre><code>product-hub/
|
|
365
|
+
epics/EP-<slug>/
|
|
366
|
+
analysis.md (optional) the discovery brief
|
|
367
|
+
epic.md the feature, agreed
|
|
368
|
+
architecture.md how it will be built
|
|
369
|
+
contract.md the LOCKED shared surface (APIs, events, data model)
|
|
370
|
+
ui-design.md + DESIGN.md
|
|
371
|
+
stories/ one file per story (EP-<slug>-S01.md …)
|
|
372
|
+
reviews/ reviewer comments, per artifact
|
|
373
|
+
.sdlc/ state.json · approvals.json · contract-lock.json
|
|
374
|
+
build-state/ · trust-log.json · build-log.json
|
|
375
|
+
|
|
376
|
+
each code repo/
|
|
377
|
+
specs/<story-id>/ spec, plan, tasks (+ link.md back to the story)
|
|
378
|
+
+ the real code, branches and PRs</code></pre>
|
|
379
|
+
</section>
|
|
380
|
+
|
|
381
|
+
<!-- ======================================================= -->
|
|
382
|
+
<section id="gate">
|
|
383
|
+
<h2>3. The review gate — the same loop, everywhere</h2>
|
|
384
|
+
<p>Every review in the workflow is the <em>same</em> loop, run by <code>yad-review-gate</code>.
|
|
385
|
+
Commenting never advances anything. Only an explicit <code>advance</code> (file-only mode) or the
|
|
386
|
+
merge of an approved, fully-resolved review PR (platform mode) moves the step forward — and only
|
|
387
|
+
when the approval rule is met.</p>
|
|
388
|
+
|
|
389
|
+
<div class="diagram">
|
|
390
|
+
<div class="flow-h">
|
|
391
|
+
<div class="node artifact">author writes<br>the artifact</div>
|
|
392
|
+
<div class="arrow-h">➜</div>
|
|
393
|
+
<div class="node gate"><strong>open</strong><small>show it / raise the review PR</small></div>
|
|
394
|
+
<div class="arrow-h">➜</div>
|
|
395
|
+
<div class="node gate"><strong>comment</strong><small>reviewers leave notes ↺ owner addresses, edits in place</small></div>
|
|
396
|
+
<div class="arrow-h">➜</div>
|
|
397
|
+
<div class="node gate"><strong>approve</strong><small>name + role recorded</small></div>
|
|
398
|
+
<div class="arrow-h">➜</div>
|
|
399
|
+
<div class="node locked"><strong>advance?</strong><small>rule met · threads resolved · (PR merged)</small></div>
|
|
400
|
+
<div class="arrow-h">➜</div>
|
|
401
|
+
<div class="node sentinel">next step</div>
|
|
402
|
+
</div>
|
|
403
|
+
<div class="caption">If the rule is not met, the gate names exactly who is still missing. If the artifact changes after approval, approvals are revoked (re-hash) and reviewers get a fresh pass.</div>
|
|
404
|
+
</div>
|
|
405
|
+
|
|
406
|
+
<h3>Who approves what (the gate rules)</h3>
|
|
407
|
+
<table>
|
|
408
|
+
<tr><th>Review</th><th>Rule</th><th>Who must approve</th></tr>
|
|
409
|
+
<tr><td>Analysis / Epic / UI</td><td><strong>Base</strong></td><td>owner + 1 reviewer</td></tr>
|
|
410
|
+
<tr><td>Architecture + contract</td><td><strong>Escalated</strong></td><td>owner + 1 reviewer <strong>+ a domain owner for every repo in the epic</strong>. The contract surface is hash-locked; changing it invalidates approvals.</td></tr>
|
|
411
|
+
<tr><td>Stories</td><td><strong>Per-repo</strong></td><td>owner + 1 reviewer <strong>+ the engineer for each repo any story touches</strong></td></tr>
|
|
412
|
+
<tr><td>Engineer review at ship</td><td><strong>Locked</strong></td><td>a human engineer — always, <em>never</em> automated</td></tr>
|
|
413
|
+
</table>
|
|
414
|
+
|
|
415
|
+
<div class="callout">
|
|
416
|
+
<strong>Escalation triggers:</strong> anything touching the shared <strong>contract</strong>,
|
|
417
|
+
<strong>auth</strong>, or <strong>payments</strong> needs the relevant domain owners — both at the
|
|
418
|
+
front-half gates and via risk routing on build-half PRs.
|
|
419
|
+
</div>
|
|
420
|
+
</section>
|
|
421
|
+
|
|
422
|
+
<!-- ======================================================= -->
|
|
423
|
+
<section id="glossary">
|
|
424
|
+
<h2>4. Terminology glossary — every term, in plain language</h2>
|
|
425
|
+
<p>Type to filter. Each term is tagged by area:
|
|
426
|
+
<span class="badge b-core">core</span>
|
|
427
|
+
<span class="badge b-file">files & artifacts</span>
|
|
428
|
+
<span class="badge b-gate">gates & review</span>
|
|
429
|
+
<span class="badge b-build">build half</span>
|
|
430
|
+
<span class="badge b-auto">automation</span>
|
|
431
|
+
<span class="badge b-tool">tools</span>
|
|
432
|
+
<span class="badge b-role">people & roles</span>
|
|
433
|
+
</p>
|
|
434
|
+
<input class="gsearch" id="gsearch" type="search" placeholder="Filter terms… (e.g. contract, dial, gate, trust)" oninput="filterTerms(this.value)">
|
|
435
|
+
|
|
436
|
+
<h3>Core concepts</h3>
|
|
437
|
+
<div class="term"><strong>SDLC</strong><span class="badge b-core">core</span><br>Software Development Life Cycle — the journey of a feature from idea to running code. This repo gives a team one shared, disciplined version of that journey.</div>
|
|
438
|
+
<div class="term"><strong>State machine</strong><span class="badge b-core">core</span><br>The core design: the workflow is a fixed set of <em>states</em> (steps). Each state does its work and waits at a gate. The states never change — only the <em>trigger</em> (who moves work forward) changes. That is what lets the team start fully manual and automate gradually without rebuilding anything.</div>
|
|
439
|
+
<div class="term"><strong>Product hub (product repo)</strong><span class="badge b-core">core</span><br>The git repo that holds the shared “thinking”: epics, architecture, the contract, UI design, stories, reviews and all state. The brain of the project. Code never lives here.</div>
|
|
440
|
+
<div class="term"><strong>Code repo</strong><span class="badge b-core">core</span><br>A separate git repo holding real application code (e.g. backend, mobile, dashboard). Each story’s spec lives inside the code repo it belongs to, with a link back to the story in the hub.</div>
|
|
441
|
+
<div class="term"><strong>Skills source (this repo)</strong><span class="badge b-core">core</span><br>The <code>yadflow</code> repo itself — where the 17 skills live and where you pull updates from. No real product work happens inside it.</div>
|
|
442
|
+
<div class="term"><strong>Front half (“decide” / the brain)</strong><span class="badge b-core">core</span><br>The first half of the workflow, run once per epic in the product hub: analysis (optional) → epic → architecture + contract → UI design → stories — each followed by a human review gate. Permanently human-approved.</div>
|
|
443
|
+
<div class="term"><strong>Back half / build half (“build”)</strong><span class="badge b-core">core</span><br>The second half, run once per story per code repo, inside that repo: spec → implement → checks → PR → ship. These mechanical steps may earn automation over time.</div>
|
|
444
|
+
<div class="term"><strong>Gate</strong><span class="badge b-core">core</span><br>A stopping point after a step. The step writes its output and <em>waits</em>; a human must approve before the workflow moves on. “Every step stops at a gate” is the heart of the whole system.</div>
|
|
445
|
+
<div class="term"><strong>Assistance dial</strong><span class="badge b-core">core</span><br>A per-step setting for how much AI helps with the work: <code>none</code>, <code>review</code> (AI checks human work), or <code>heavy</code> (AI does the drafting, human directs).</div>
|
|
446
|
+
<div class="term"><strong>Automation dial</strong><span class="badge b-core">core</span><br>A per-step setting for who advances the step: <code>human_approve</code> (default — a person clicks/records the approval) or <code>machine_advance</code> (the orchestrator moves on by itself). Front steps and the engineer review can never be set to <code>machine_advance</code>.</div>
|
|
447
|
+
<div class="term"><strong>End-first automation</strong><span class="badge b-core">core</span><br>The rule for <em>which</em> steps get automated first: start from the safe end (checks, implement — a mistake there is one revert, caught by gates) and move toward the valuable end (design decisions), which is never automated at all.</div>
|
|
448
|
+
<div class="term"><strong>Epic</strong><span class="badge b-core">core</span><br>One feature, described well: the problem, the goal, the scope. The unit the front half works on. Gets a stable ID like <code>EP-istifta-inquiries</code>.</div>
|
|
449
|
+
<div class="term"><strong>Story (user story)</strong><span class="badge b-core">core</span><br>A slice of an epic small enough to build and review on its own. Each story is <em>repo-tagged</em> — it lists which code repos must implement it (e.g. <code>repos: [backend, mobile]</code>). ID: <code>EP-<slug>-S01</code>.</div>
|
|
450
|
+
<div class="term"><strong>Atomic task</strong><span class="badge b-core">core</span><br>The smallest unit of building: one task = one branch = one commit = one PR, with a small diff (≤3 files) that stays inside the files the task declared. ID: <code>EP-<slug>-S01-T03</code>.</div>
|
|
451
|
+
<div class="term"><strong>Handoff rule</strong><span class="badge b-core">core</span><br>Where files live: everything up to and including the locked contract lives in the product hub; everything from the spec onward lives in each code repo. The handover point is exactly where Spec Kit begins.</div>
|
|
452
|
+
<div class="term"><strong>Code-aware (the brain reads the code)</strong><span class="badge b-core">core</span><br>When code repos are connected, each front-half author step first loads their cached code-maps — so the epic references what already exists, the architecture cross-checks the contract against real endpoints before locking it, the UI reuses existing components, and stories anchor to real modules.</div>
|
|
453
|
+
|
|
454
|
+
<h3>Files & artifacts</h3>
|
|
455
|
+
<div class="term"><strong>Artifact</strong><span class="badge b-file">files</span><br>The file an author step produces (e.g. <code>epic.md</code>, <code>contract.md</code>). An author step writes its artifact, marks itself done, and stops at its review gate.</div>
|
|
456
|
+
<div class="term"><strong><code>analysis.md</code></strong><span class="badge b-file">files</span><br>The optional discovery brief: the analyst pressure-tests the raw idea before the epic is written. If skipped, the epic step does this shaping inline.</div>
|
|
457
|
+
<div class="term"><strong><code>epic.md</code></strong><span class="badge b-file">files</span><br>The agreed description of the feature. Authoring it assigns the epic’s <code>EP-<slug></code> ID and seeds the epic’s state files.</div>
|
|
458
|
+
<div class="term"><strong><code>architecture.md</code></strong><span class="badge b-file">files</span><br>How the feature will be built technically: stack, components, data flow.</div>
|
|
459
|
+
<div class="term"><strong>Contract / <code>contract.md</code></strong><span class="badge b-file">files</span><br>The <em>locked shared surface</em> between repos: API shapes, events, and the data model that backend, mobile and dashboard all obey. There is exactly <strong>one</strong> contract per epic, kept in the hub; code repos quote it, never re-invent it.</div>
|
|
460
|
+
<div class="term"><strong>Contract surface</strong><span class="badge b-file">files</span><br>The specific block inside <code>contract.md</code> (between <code>CONTRACT-SURFACE:BEGIN/END</code> markers) that is hashed and locked. Changing anything in it is a “contract change”.</div>
|
|
461
|
+
<div class="term"><strong>Contract lock / <code>contract-lock.json</code></strong><span class="badge b-file">files</span><br>A SHA-256 hash of the contract surface, recorded when the architecture is authored. If the surface ever differs from its lock, approvals are invalidated and the change must go back to the architecture gate.</div>
|
|
462
|
+
<div class="term"><strong><code>ui-design.md</code> + <code>DESIGN.md</code></strong><span class="badge b-file">files</span><br>The UI artifacts: the design decisions for this epic plus the reusable design language, authored with the ux-designer (driving Impeccable when installed).</div>
|
|
463
|
+
<div class="term"><strong><code>stories/</code></strong><span class="badge b-file">files</span><br>One markdown file per story (<code>EP-<slug>-S0N.md</code>), each tagged with the repos that must implement it.</div>
|
|
464
|
+
<div class="term"><strong>File ledger</strong><span class="badge b-gate">gates</span><br>The set of state files that is the single source of truth for reviews: <code>approvals.json</code>, <code>comments.json</code>, <code>reviews/*.md</code>. Platform PRs feed <em>into</em> the ledger; the ledger always wins.</div>
|
|
465
|
+
<div class="term"><strong><code>state.json</code></strong><span class="badge b-file">files</span><br>The epic’s state machine on disk: every step, its two dials, its status, and <code>currentStep</code> (where the epic is right now).</div>
|
|
466
|
+
<div class="term"><strong><code>approvals.json</code></strong><span class="badge b-file">files</span><br>Who approved which review, with name + role. The gate reads this to decide whether the rule is met.</div>
|
|
467
|
+
<div class="term"><strong><code>repos.json</code></strong><span class="badge b-file">files</span><br>The project-wide registry of connected code repos (path/URL, platform, domain owner, freshness sha).</div>
|
|
468
|
+
<div class="term"><strong><code>hub.json</code></strong><span class="badge b-file">files</span><br>The hub’s platform record (GitHub or GitLab) plus the reviewer roster, used to run front-half reviews on real PRs/MRs.</div>
|
|
469
|
+
<div class="term"><strong>Roster</strong><span class="badge b-role">roles</span><br>The mapping from each reviewer’s GitHub/GitLab login to their SDLC name + role (owner / reviewer). Domain owners are derived from each repo’s <code>domain_owner</code> in <code>repos.json</code>, not retyped.</div>
|
|
470
|
+
<div class="term"><strong>Code-map</strong><span class="badge b-file">files</span><br>A lightweight, AI-readable summary of a connected code repo — its existing endpoints, events, data models and modules — cached under <code>.sdlc/code-context/</code> so the front-half steps don’t contradict code that already exists.</div>
|
|
471
|
+
<div class="term"><strong>Repomix pack</strong><span class="badge b-tool">tools</span><br>A compressed, secret-scanned snapshot of a repo’s code produced by the Repomix tool (<code>npx repomix</code>), cached alongside the code-map so AI can read the codebase.</div>
|
|
472
|
+
<div class="term"><strong>Fresh / stale</strong><span class="badge b-file">files</span><br>A connected repo’s cached picture is <em>fresh</em> if the repo hasn’t moved since it was packed (tracked by HEAD sha) and <em>stale</em> if it has. Refreshing is a deliberate human decision (<code>yad repo refresh</code>) — skills warn about staleness but never silently re-pack.</div>
|
|
473
|
+
<div class="term"><strong><code>code-context:</code> frontmatter</strong><span class="badge b-file">files</span><br>A stamp each front-half artifact carries recording exactly which repo code-maps (and at which sha) it read while being authored.</div>
|
|
474
|
+
<div class="term"><strong><code>build-log.json</code></strong><span class="badge b-file">files</span><br>The record of every ship: which task, which PR, which merge commit — keeping the epic → story → task → PR chain traceable both ways.</div>
|
|
475
|
+
<div class="term"><strong><code>build-state/<story>.json</code></strong><span class="badge b-auto">automation</span><br>Per story: the back-half steps with their automation dials and statuses, per repo. What <code>yad-run</code> reads to know whether to advance or stop.</div>
|
|
476
|
+
<div class="term"><strong><code>ready-for-build</code></strong><span class="badge b-core">core</span><br>The milestone state an epic reaches when all front gates have passed. From here, stories can enter the build half.</div>
|
|
477
|
+
<div class="term"><strong><code>in-build</code> / <code>shipped</code></strong><span class="badge b-build">build</span><br>A story’s lifecycle status during and after the build half: <code>in-build</code> once its first task merges, <code>shipped</code> when the story is fully delivered.</div>
|
|
478
|
+
|
|
479
|
+
<h3>Gates & review</h3>
|
|
480
|
+
<div class="term"><strong>Review gate (<code>yad-review-gate</code>)</strong><span class="badge b-gate">gates</span><br>The one reusable team review loop used by every front-half review: <code>open → comment → approve → advance</code>. Commenting never advances; <code>advance</code> moves forward only when the approval rule is met — otherwise it names exactly who is still missing.</div>
|
|
481
|
+
<div class="term"><strong>Base rule</strong><span class="badge b-gate">gates</span><br>The default approval requirement: the artifact’s <strong>owner + 1 reviewer</strong>. Used for the analysis, epic and UI reviews.</div>
|
|
482
|
+
<div class="term"><strong>Escalated rule</strong><span class="badge b-gate">gates</span><br>Base rule <em>plus</em> a domain owner for every repo in the epic. Triggered by risky surfaces — the contract, auth, or payments. The architecture + contract review is always escalated.</div>
|
|
483
|
+
<div class="term"><strong>Per-repo rule</strong><span class="badge b-gate">gates</span><br>Base rule <em>plus</em> the engineer (domain owner) of each repo that any story touches. Used for the stories review.</div>
|
|
484
|
+
<div class="term"><strong>Owner</strong><span class="badge b-role">roles</span><br>The person responsible for an artifact, who addresses comments and can advance its gate. Others are commenters — this avoids the “everyone must approve everything” deadlock.</div>
|
|
485
|
+
<div class="term"><strong>Reviewer</strong><span class="badge b-role">roles</span><br>A team member who reads, challenges and comments on an artifact, and records an approval when satisfied.</div>
|
|
486
|
+
<div class="term"><strong>Domain owner</strong><span class="badge b-role">roles</span><br>The engineer responsible for one code repo (e.g. carol for backend, dave for mobile). Pulled into reviews when their repo is affected, and into PR reviews on high-risk changes.</div>
|
|
487
|
+
<div class="term"><strong>File-only gate</strong><span class="badge b-gate">gates</span><br>The gate run purely on files (no platform): reviewers comment in <code>reviews/…--comments.md</code>, approvals land in <code>approvals.json</code>, and an explicit <code>advance</code> moves the step. The mode everything degrades to when there is no GitHub/GitLab or no CLI.</div>
|
|
488
|
+
<div class="term"><strong>PR-driven gate</strong><span class="badge b-gate">gates</span><br>When the hub is on a platform: each artifact’s review rides a real PR/MR. Reviewers approve/comment there; <code>yad gate sync</code> maps that state into the file ledger, and the step auto-advances <em>on merge</em> once the rule is met and every comment thread is resolved. The merge click is the human approval act.</div>
|
|
489
|
+
<div class="term"><strong>Hub bridge (<code>yad-hub-bridge</code>)</strong><span class="badge b-gate">gates</span><br>The machinery that connects the file ledger to platform PRs/MRs: opens the review PR per artifact, sets required reviewers/labels from the routing rule, and provides the read-only <code>gh</code>/<code>glab</code> recipes for syncing approvals and comments back.</div>
|
|
490
|
+
<div class="term"><strong>Event-driven gate sync</strong><span class="badge b-gate">gates</span><br>A CI workflow on the hub that runs <code>yad gate ci</code> automatically on every approval, change request and merge of a review PR — so the ledger updates itself without anyone running <code>sync</code> by hand. CI never approves and never merges; the human keeps the merge click.</div>
|
|
491
|
+
<div class="term"><strong>Approval revocation (re-hash)</strong><span class="badge b-gate">gates</span><br>If a reviewed artifact actually changes after approval, the recorded approvals are revoked automatically (the artifact is re-hashed) — reviewers get a fresh pass at the new content.</div>
|
|
492
|
+
<div class="term"><strong>Review-comment scaffold</strong><span class="badge b-gate">gates</span><br>Committed comment templates (<code>REVIEW_COMMENTS.md</code> / GitLab comment templates) so reviewers leave structured, attributable feedback — each canned comment carries a <code>**name (role)**</code> header that maps cleanly into the file ledger.</div>
|
|
493
|
+
<div class="term"><strong>Risk tags / risk routing</strong><span class="badge b-gate">gates</span><br>Labels (<code>contract</code>, <code>auth</code>, <code>payments</code>) and the PR template’s Impact & Risk block that decide who must review. High risk or a touched risky surface routes the review to the relevant domain owners (<code>risk-route.sh</code> prints them).</div>
|
|
494
|
+
<div class="term"><strong>Impact & Risk block</strong><span class="badge b-gate">gates</span><br>A section in the wired PR/MR template where the author declares the risk level and touched surfaces — the input the risk routing reads.</div>
|
|
495
|
+
|
|
496
|
+
<h3>Build half</h3>
|
|
497
|
+
<div class="term"><strong>Spec Kit ceremony</strong><span class="badge b-build">build</span><br>The heavy specification pass run <em>once</em> per story per repo by <code>yad-spec</code>: <code>specify → clarify → plan → analyze → checklist → tasks</code>, writing <code>specs/<story-id>/</code> in the code repo. It quotes the locked contract; it never widens it.</div>
|
|
498
|
+
<div class="term"><strong><code>link.md</code></strong><span class="badge b-build">build</span><br>The pointer file written into <code>specs/<story-id>/</code> that links the spec back to its story in the product hub — the thread that keeps the two repos connected.</div>
|
|
499
|
+
<div class="term"><strong>Spec-link check</strong><span class="badge b-build">build</span><br>CI gate #1: every code change must link to a real story/spec via the <code>Task:</code> trailer in its commit. No orphan changes.</div>
|
|
500
|
+
<div class="term"><strong>Contract-check</strong><span class="badge b-build">build</span><br>CI gate #2: a diff that changes the contract surface without declaring <code>Contract-Change: yes</code> <em>and</em> an updated, re-locked contract <strong>fails</strong> — routing the change back up to the architecture gate. This is how the contract stays honest.</div>
|
|
501
|
+
<div class="term"><strong>Build/test/lint gate</strong><span class="badge b-build">build</span><br>CI gate #3: the ordinary safety net — the project must build, its tests must pass, lint must be clean.</div>
|
|
502
|
+
<div class="term"><strong>Verified-commits gate</strong><span class="badge b-build">build</span><br>CI gate #4: every commit must carry a platform-verified signature and be authored by a roster-known email — rejecting unverified commits from unknown users, on the hub and every repo.</div>
|
|
503
|
+
<div class="term"><strong><code>Task:</code> trailer</strong><span class="badge b-build">build</span><br>A line at the end of every commit message naming the story + task it implements (e.g. <code>Task: EP-istifta-inquiries-S01-T03</code>). What the spec-link check verifies.</div>
|
|
504
|
+
<div class="term"><strong><code>Contract-Change: yes</code> trailer</strong><span class="badge b-build">build</span><br>A commit trailer added <em>only</em> when the diff deliberately touches the locked contract surface — paired with an updated, re-locked contract, or the contract-check fails.</div>
|
|
505
|
+
<div class="term"><strong>Conventional Commits</strong><span class="badge b-build">build</span><br>The commit/PR title convention used everywhere: <code>feat: …</code>, <code>fix: …</code> (lowercase after the type). Merged <code>feat:</code>/<code>fix:</code> commits also drive automated releases of the CLI itself.</div>
|
|
506
|
+
<div class="term"><strong><code>Co-Authored-By</code> AI trailer</strong><span class="badge b-build">build</span><br>An optional per-commit trailer crediting the AI tool that helped (claude / copilot / cursor / coderabbit). The human author always owns the commit.</div>
|
|
507
|
+
<div class="term"><strong>Scope guard / scope overrun</strong><span class="badge b-build">build</span><br>The implement step’s hard boundary: the diff must stay inside the files the task declared. If it would grow beyond them, the step flags it and STOPS — and during automated runs this always halts for a human, overriding any dial.</div>
|
|
508
|
+
<div class="term"><strong>AI review (advisory)</strong><span class="badge b-build">build</span><br>An automated first-pass review of the PR (e.g. CodeRabbit). A second set of eyes, never the authority — the human engineer review still owns the merge.</div>
|
|
509
|
+
<div class="term"><strong>Engineer review</strong><span class="badge b-build">build</span><br>The final human gate: an engineer reads the diff against the spec and owns the merge. Owner + 1 reviewer, with the same domain-owner escalation. <strong>Permanently human — never automated.</strong></div>
|
|
510
|
+
<div class="term"><strong>Backfill (<code>yad-backfill</code>)</strong><span class="badge b-build">build</span><br>For existing/legacy code: pack <em>one</em> feature with Repomix, have AI draft a spec of <em>what exists</em> (“describe, don’t invent”), mark it DRAFT/unverified, and require human approval before it counts. New work on that feature is blocked until its spec is approved — gated per touched feature, never the whole repo.</div>
|
|
511
|
+
<div class="term"><strong>Draft / unverified spec</strong><span class="badge b-build">build</span><br>A backfilled spec before a human has approved it. It describes existing behaviour but doesn’t yet count as real for gating purposes.</div>
|
|
512
|
+
<div class="term"><strong>Do-not-touch zones</strong><span class="badge b-build">build</span><br>Parts of an existing codebase marked off-limits to AI changes — part of the setup when adopting the workflow on a brownfield project.</div>
|
|
513
|
+
|
|
514
|
+
<h3>Automation & trust</h3>
|
|
515
|
+
<div class="term"><strong>Orchestrator (<code>yad-run</code>)</strong><span class="badge b-auto">automation</span><br>The engine that drives a story’s back half (spec → tasks → implement → checks) reading each step’s automation dial: on <code>machine_advance</code> it advances alone; on <code>human_approve</code> it stops; on any failure, scope overrun, or contract-surface touch it <strong>halts and pulls in a human</strong>. It always stops at the engineer review.</div>
|
|
516
|
+
<div class="term"><strong>Earned automation</strong><span class="badge b-auto">automation</span><br>The principle that no step is automated by promise — only by evidence. A step may be flipped to <code>machine_advance</code> only after its trust record clears the threshold, and the flip is refused otherwise.</div>
|
|
517
|
+
<div class="term"><strong>Trust log (<code>trust-log.json</code>)</strong><span class="badge b-auto">automation</span><br>The evidence base: every orchestrated run’s verdict is recorded here. This is what justifies (or blocks) flipping a step’s dial.</div>
|
|
518
|
+
<div class="term"><strong>Trust threshold</strong><span class="badge b-auto">automation</span><br>The bar a step must clear to earn automation — by default at least 5 runs with ≥80% “approved-unchanged” (configurable in <code>config.yaml</code>).</div>
|
|
519
|
+
<div class="term"><strong>Run verdicts</strong><span class="badge b-auto">automation</span><br>How each engineer review scores an automated run: <code>approved-unchanged</code> (merged exactly as authored — the strongest signal), <code>approved-with-edits</code> (a human fixed it first), <code>rejected</code> (failed).</div>
|
|
520
|
+
<div class="term"><strong>Kill switch</strong><span class="badge b-auto">automation</span><br><code>yad-run action: kill</code> — one move that forces <em>every</em> step system-wide back to <code>human_approve</code> instantly, no code change needed. <code>unkill</code> restores earned automation. Automation is always reversible in one move.</div>
|
|
521
|
+
<div class="term"><strong>Locked steps</strong><span class="badge b-auto">automation</span><br>The steps that may <em>never</em> be set to <code>machine_advance</code>: all four front authoring steps, their reviews, and the engineer review. A front state advances only on a human act.</div>
|
|
522
|
+
<div class="term"><strong>Fleet roll-up</strong><span class="badge b-auto">automation</span><br>The cross-epic summary <code>yad-status</code> prints: where every epic stands, which steps are “earned but still manual” (nudge cost), at a glance.</div>
|
|
523
|
+
|
|
524
|
+
<h3>Tools the workflow builds on</h3>
|
|
525
|
+
<div class="term"><strong>BMAD (BMAD-METHOD)</strong><span class="badge b-tool">tools</span><br>The open-source workflow engine underneath: it provides the step runner, quality gates, the project rules file, and the AI roles. Yadflow is a custom BMAD <em>module</em> that turns it from a solo tool into a team, gated, multi-repo tool.</div>
|
|
526
|
+
<div class="term"><strong>Spec Kit</strong><span class="badge b-tool">tools</span><br>GitHub’s spec-driven development toolkit. Its commands (<code>/speckit.specify</code>, <code>clarify</code>, <code>plan</code>, <code>analyze</code>, <code>checklist</code>, <code>tasks</code>) produce the spec, plan and task files in each code repo. The workflow drives it when installed and authors the same files by hand when not.</div>
|
|
527
|
+
<div class="term"><strong>Repomix</strong><span class="badge b-tool">tools</span><br>A tool (<code>npx repomix</code>) that packs a codebase into one AI-readable file, with compression and secret-scanning. Used to cache the code picture of connected repos and to read legacy features for backfill.</div>
|
|
528
|
+
<div class="term"><strong>Impeccable</strong><span class="badge b-tool">tools</span><br>A UI-design tool driven via slash-commands: <code>document</code> (read the current UI into a design file), <code>extract</code> (save reusable pieces), <code>craft</code> (make new designs that match). Used by the UI step when installed; the step authors directly otherwise.</div>
|
|
529
|
+
<div class="term"><strong>CodeRabbit</strong><span class="badge b-tool">tools</span><br>An AI code-review service used as the advisory first pass on PRs. Optional; never the merge authority.</div>
|
|
530
|
+
<div class="term"><strong>Graceful degradation</strong><span class="badge b-tool">tools</span><br>The rule that every optional tool (Spec Kit, Impeccable, Repomix, CodeRabbit) can be absent: the workflow falls back to doing the work directly and <em>records</em> that the tool was missing. You can start with none of them.</div>
|
|
531
|
+
<div class="term"><strong>Tool-agnostic rule</strong><span class="badge b-tool">tools</span><br>Talk to every tool through its commands and files, never through its internal code — so each tool stays swappable.</div>
|
|
532
|
+
<div class="term"><strong>Skill</strong><span class="badge b-tool">tools</span><br>One of the 17 named agents (e.g. <code>yad-epic</code>) you invoke by name in your AI IDE. Each skill does one step’s work, writes files, and stops at its gate.</div>
|
|
533
|
+
<div class="term"><strong>The <code>yad</code> CLI</strong><span class="badge b-tool">tools</span><br>A zero-dependency command-line tool (npm: <code>yadflow</code>) that installs, wires and reconciles the workflow (<code>setup</code>, <code>check --fix</code>, <code>update</code>) and runs the deterministic pieces (<code>gate</code>, <code>commit</code>, <code>open-pr</code>, <code>repo</code>).</div>
|
|
534
|
+
|
|
535
|
+
<h3>People & AI roles</h3>
|
|
536
|
+
<div class="term"><strong>analyst (“Mary”)</strong><span class="badge b-role">roles</span><br>The BMAD AI role for research, brainstorming and shaping the raw idea — drives the optional analysis step.</div>
|
|
537
|
+
<div class="term"><strong>pm (“John”)</strong><span class="badge b-role">roles</span><br>The product-manager AI role — writes the epic and breaks it into stories.</div>
|
|
538
|
+
<div class="term"><strong>architect (“Winston”)</strong><span class="badge b-role">roles</span><br>The technical AI role — authors the architecture and the contract.</div>
|
|
539
|
+
<div class="term"><strong>ux-designer</strong><span class="badge b-role">roles</span><br>The UI/UX AI role — drives the UI design step (with Impeccable when installed).</div>
|
|
540
|
+
<div class="term"><strong>sm / Scrum Master (“Bob”)</strong><span class="badge b-role">roles</span><br>The AI role that prepares each story in detail for development and sets up the sprint context.</div>
|
|
541
|
+
<div class="term"><strong>dev</strong><span class="badge b-role">roles</span><br>The developer AI role — writes the code for one atomic task in the implement step.</div>
|
|
542
|
+
<div class="term"><strong>tea / Test Architect</strong><span class="badge b-role">roles</span><br>The AI role that sets up and runs tests at the check gates.</div>
|
|
543
|
+
|
|
544
|
+
<h3>IDs & naming (immutable once assigned)</h3>
|
|
545
|
+
<table>
|
|
546
|
+
<tr><th>Thing</th><th>Format</th><th>Example</th></tr>
|
|
547
|
+
<tr><td>Epic ID</td><td><code>EP-<slug></code></td><td><code>EP-istifta-inquiries</code></td></tr>
|
|
548
|
+
<tr><td>Story ID</td><td><code>EP-<slug>-S0N</code></td><td><code>EP-istifta-inquiries-S01</code></td></tr>
|
|
549
|
+
<tr><td>Task ID</td><td><code>EP-<slug>-S0N-T0N</code></td><td><code>EP-istifta-inquiries-S01-T03</code></td></tr>
|
|
550
|
+
<tr><td>Branch</td><td><code>feat/<story-id>-<task-id>-<slug></code></td><td><code>feat/EP-istifta-inquiries-S01-T01-create-inquiry</code></td></tr>
|
|
551
|
+
<tr><td>Commit trailer</td><td><code>Task: <story-id>-<task-id></code></td><td>+ <code>Contract-Change: yes</code> only when the locked surface is touched</td></tr>
|
|
552
|
+
</table>
|
|
553
|
+
<div class="callout">Renaming an ID breaks every downstream link — IDs are <strong>immutable once assigned</strong>.</div>
|
|
554
|
+
</section>
|
|
555
|
+
|
|
556
|
+
<!-- ======================================================= -->
|
|
557
|
+
<section id="project-types">
|
|
558
|
+
<h2>5. Project types — greenfield, brownfield, and multi-repo</h2>
|
|
559
|
+
<p class="lead">The <strong>same workflow runs for every project type — only the one-time setup differs.</strong>
|
|
560
|
+
The design doc defines three project types; multi-repo is an orthogonal option that works with any of them.</p>
|
|
561
|
+
|
|
562
|
+
<h3>Type 1 — Greenfield (new project, full AI)</h3>
|
|
563
|
+
<div class="card">
|
|
564
|
+
<p><strong>What it means:</strong> a brand-new project with no existing code. Specs are written from
|
|
565
|
+
the very start, so there is never undocumented behaviour to protect.</p>
|
|
566
|
+
<p><strong>Setup differences:</strong> the lightest path — <em>no</em> backfill, and you simply
|
|
567
|
+
<strong>skip <code>yad-connect-repos</code></strong> until code exists (the brain proceeds without
|
|
568
|
+
code-maps; the steps are explicitly “greenfield-safe”). For UI, run Impeccable’s
|
|
569
|
+
<code>craft</code> first to create the design, then <code>extract</code> to seed the design language.</p>
|
|
570
|
+
</div>
|
|
571
|
+
<div class="diagram">
|
|
572
|
+
<div class="flow-v">
|
|
573
|
+
<div class="node plain"><strong>Setup</strong><small>install skills · create the hub repo · create empty code repos · wire each repo (CI gates + PR template) · <s>connect-repos</s> <em>skipped — nothing to map yet</em></small></div>
|
|
574
|
+
<div class="arrow-v">▼</div>
|
|
575
|
+
<div class="node artifact"><strong>Front half</strong><small>(analysis) → epic → architecture + contract → UI (<code>craft</code> → <code>extract</code>) → stories — all human-gated</small></div>
|
|
576
|
+
<div class="arrow-v">▼</div>
|
|
577
|
+
<div class="node"><strong>Build half</strong><small>spec → implement → checks → PR → ship, per story per repo — specs exist for 100% of the code from day one</small></div>
|
|
578
|
+
<div class="arrow-v">▼</div>
|
|
579
|
+
<div class="node sentinel"><strong>Later:</strong> connect the repos once they have real code, so future epics become code-aware</div>
|
|
580
|
+
</div>
|
|
581
|
+
</div>
|
|
582
|
+
|
|
583
|
+
<h3>Type 2 — Brownfield, already using AI</h3>
|
|
584
|
+
<div class="card">
|
|
585
|
+
<p><strong>What it means:</strong> an existing codebase where the team already works with AI tools.
|
|
586
|
+
The code is real and live; the risk is new work silently breaking what exists.</p>
|
|
587
|
+
<p><strong>Setup differences:</strong> connect every repo (<code>yad-connect-repos</code>) so the
|
|
588
|
+
brain reads what is already built; <strong>add the spec-link check</strong> so every change links to
|
|
589
|
+
a story; and <strong>mark the “do-not-touch” zones</strong> AI must not modify. Run
|
|
590
|
+
<strong><code>yad-backfill</code></strong> before a new feature touches an old one. For UI, run
|
|
591
|
+
Impeccable’s <code>document</code> first (read the current UI), then <code>extract</code>, then
|
|
592
|
+
<code>craft</code> new designs that match.</p>
|
|
593
|
+
</div>
|
|
594
|
+
<div class="diagram">
|
|
595
|
+
<div class="flow-v">
|
|
596
|
+
<div class="node plain"><strong>Setup</strong><small>install skills · wire each repo · <strong>connect every repo</strong> → cached Repomix pack + code-map · mark do-not-touch zones · enable spec-link</small></div>
|
|
597
|
+
<div class="arrow-v">▼</div>
|
|
598
|
+
<div class="node artifact"><strong>Front half — code-aware</strong><small>each author step loads the code-maps: the epic references existing behaviour, the architecture cross-checks the contract against real endpoints <em>before</em> locking it, UI reuses existing components (<code>document → extract → craft</code>), stories anchor to real modules</small></div>
|
|
599
|
+
<div class="arrow-v">▼</div>
|
|
600
|
+
<div class="node gate"><strong>Touching an old, unspecced feature?</strong><small>run <code>yad-backfill</code> first: Repomix-pack that one feature → AI drafts a “describe what exists” spec → DRAFT until a human approves → only then may changes touch it</small></div>
|
|
601
|
+
<div class="arrow-v">▼</div>
|
|
602
|
+
<div class="node"><strong>Build half</strong><small>same as always — spec → implement → checks (incl. contract-check) → PR → ship</small></div>
|
|
603
|
+
</div>
|
|
604
|
+
</div>
|
|
605
|
+
|
|
606
|
+
<h3>Type 3 — Brownfield, no AI yet</h3>
|
|
607
|
+
<div class="card">
|
|
608
|
+
<p><strong>What it means:</strong> an existing codebase and a team adopting AI for the first time.
|
|
609
|
+
Trust must be built before AI touches anything important.</p>
|
|
610
|
+
<p><strong>Setup differences:</strong> same wiring as Type 2, but <strong>start AI on safe tasks only</strong>
|
|
611
|
+
— tests, docs, refactors — with every dial at <code>human_approve</code>. Run the <strong>backfill step
|
|
612
|
+
before any new feature touches old code</strong>. Let automation be earned slowly through the trust log,
|
|
613
|
+
exactly as the end-first rule prescribes.</p>
|
|
614
|
+
</div>
|
|
615
|
+
<div class="diagram">
|
|
616
|
+
<div class="flow-v">
|
|
617
|
+
<div class="node plain"><strong>Setup</strong><small>install skills · wire + connect repos · everything at <code>human_approve</code> · AI assistance limited to safe tasks (tests, docs, refactors)</small></div>
|
|
618
|
+
<div class="arrow-v">▼</div>
|
|
619
|
+
<div class="node gate"><strong>Backfill first</strong><small>before new features touch old code, produce human-verified specs for the features they touch</small></div>
|
|
620
|
+
<div class="arrow-v">▼</div>
|
|
621
|
+
<div class="node artifact"><strong>Front + build halves, fully manual gates</strong><small>the team learns the rhythm: author → gate → approve, with heavy AI <em>assistance</em> but zero AI <em>advancement</em></small></div>
|
|
622
|
+
<div class="arrow-v">▼</div>
|
|
623
|
+
<div class="node"><strong>Earn automation step by step</strong><small>after months of evidence in <code>trust-log.json</code>, flip <code>checks</code> first, then <code>implement</code> — end-first, never the front</small></div>
|
|
624
|
+
<div class="arrow-v">▼</div>
|
|
625
|
+
<div class="node sentinel"><strong>Kill switch always available</strong><small><code>yad-run action: kill</code> — back to fully manual in one move</small></div>
|
|
626
|
+
</div>
|
|
627
|
+
</div>
|
|
628
|
+
|
|
629
|
+
<h3>Option for all types — Multi-repo stories</h3>
|
|
630
|
+
<div class="card">
|
|
631
|
+
<p>A story tagged <code>repos: [backend, mobile]</code> simply runs the build half in <em>each</em> repo
|
|
632
|
+
independently — but every repo builds from the <strong>same one locked contract</strong> in the hub.
|
|
633
|
+
The contract-check blocks a surface bypass in either repo, so the repos can never drift apart.</p>
|
|
634
|
+
</div>
|
|
635
|
+
<div class="diagram">
|
|
636
|
+
<div class="flow-v">
|
|
637
|
+
<div class="node artifact"><strong>ONE locked contract.md</strong><small>in the product hub — hash-locked at the architecture gate</small></div>
|
|
638
|
+
<div class="arrow-v">▼</div>
|
|
639
|
+
<div class="flow-h" style="gap:14px; align-items:stretch">
|
|
640
|
+
<div class="flow-v" style="min-width:240px">
|
|
641
|
+
<div class="node"><strong>backend repo</strong><small>spec → implement → checks → PR → ship</small></div>
|
|
642
|
+
</div>
|
|
643
|
+
<div class="flow-v" style="min-width:240px">
|
|
644
|
+
<div class="node"><strong>mobile repo</strong><small>spec → implement → checks → PR → ship</small></div>
|
|
645
|
+
</div>
|
|
646
|
+
<div class="flow-v" style="min-width:240px">
|
|
647
|
+
<div class="node"><strong>dashboard repo</strong><small>spec → implement → checks → PR → ship</small></div>
|
|
648
|
+
</div>
|
|
649
|
+
</div>
|
|
650
|
+
<div class="arrow-v">▼</div>
|
|
651
|
+
<div class="node gate"><strong>contract-check in every repo</strong><small>any diff that touches the contract surface without a re-locked contract FAILS → back to the architecture gate</small></div>
|
|
652
|
+
</div>
|
|
653
|
+
<div class="caption">Independent pipelines, one shared truth.</div>
|
|
654
|
+
</div>
|
|
655
|
+
|
|
656
|
+
<h3>Cheat sheet — what changes per project type</h3>
|
|
657
|
+
<table>
|
|
658
|
+
<tr>
|
|
659
|
+
<th>Aspect</th>
|
|
660
|
+
<th>Greenfield (new, full AI)</th>
|
|
661
|
+
<th>Brownfield + AI already</th>
|
|
662
|
+
<th>Brownfield, no AI yet</th>
|
|
663
|
+
</tr>
|
|
664
|
+
<tr><td>Connect repos / code-maps</td><td>Skip until code exists</td><td>Yes — connect everything</td><td>Yes — connect everything</td></tr>
|
|
665
|
+
<tr><td>Backfill (<code>yad-backfill</code>)</td><td>Never needed</td><td>Before touching unspecced features</td><td><strong>Before any new feature touches old code</strong></td></tr>
|
|
666
|
+
<tr><td>Spec-link check</td><td>On from day one</td><td><strong>Add it</strong> + mark do-not-touch zones</td><td>Add with the rest of the wiring</td></tr>
|
|
667
|
+
<tr><td>Impeccable order (UI)</td><td><code>craft</code> → <code>extract</code></td><td><code>document</code> → <code>extract</code> → <code>craft</code></td><td><code>document</code> → <code>extract</code> → <code>craft</code></td></tr>
|
|
668
|
+
<tr><td>AI scope at start</td><td>Full (specs from the start)</td><td>Full, minus do-not-touch zones</td><td><strong>Safe tasks only</strong> (tests, docs, refactors)</td></tr>
|
|
669
|
+
<tr><td>Automation pace</td><td colspan="3">Identical for all: every dial starts <code>human_approve</code>; back steps earn <code>machine_advance</code> via the trust log; front steps + engineer review locked human forever.</td></tr>
|
|
670
|
+
</table>
|
|
671
|
+
</section>
|
|
672
|
+
|
|
673
|
+
<!-- ======================================================= -->
|
|
674
|
+
<section id="skills">
|
|
675
|
+
<h2>6. The 17 skills — what each does, how to use it, and when</h2>
|
|
676
|
+
<p>A <strong>skill</strong> is an agent you invoke <em>by name</em> in your AI IDE — you just ask in
|
|
677
|
+
plain words, e.g. <em>“run <code>yad-epic</code>”</em>, adding any inputs the skill needs
|
|
678
|
+
(<code>repo: backend</code>, <code>story: EP-…-S01</code>, <code>action: wire</code>, …).
|
|
679
|
+
Every skill writes plain files and then <strong>stops at its gate</strong> — none of them advances
|
|
680
|
+
the workflow on its own. The quick table is below; full “what / how / when” cards follow.</p>
|
|
681
|
+
|
|
682
|
+
<table>
|
|
683
|
+
<tr><th>Skill</th><th>Half</th><th>One line</th></tr>
|
|
684
|
+
<tr><td><a href="#sk-connect"><code>yad-connect-repos</code></a></td><td>Setup</td><td>Register a code repo with the hub + cache its code-map.</td></tr>
|
|
685
|
+
<tr><td><a href="#sk-analysis"><code>yad-analysis</code></a></td><td>Front</td><td><em>(Optional)</em> pressure-test an idea into <code>analysis.md</code>.</td></tr>
|
|
686
|
+
<tr><td><a href="#sk-epic"><code>yad-epic</code></a></td><td>Front</td><td>Start a feature: write <code>epic.md</code>, assign the ID.</td></tr>
|
|
687
|
+
<tr><td><a href="#sk-arch"><code>yad-architecture</code></a></td><td>Front</td><td>Author <code>architecture.md</code> + the locked <code>contract.md</code>.</td></tr>
|
|
688
|
+
<tr><td><a href="#sk-ui"><code>yad-ui</code></a></td><td>Front</td><td>Author <code>ui-design.md</code> + <code>DESIGN.md</code>.</td></tr>
|
|
689
|
+
<tr><td><a href="#sk-stories"><code>yad-stories</code></a></td><td>Front</td><td>Break the epic into repo-tagged stories.</td></tr>
|
|
690
|
+
<tr><td><a href="#sk-gate"><code>yad-review-gate</code></a></td><td>Cross-cutting</td><td>Review / comment / approve / advance <strong>any</strong> gate.</td></tr>
|
|
691
|
+
<tr><td><a href="#sk-bridge"><code>yad-hub-bridge</code></a></td><td>Cross-cutting</td><td>Run front-half reviews over real PRs/MRs and sync them back.</td></tr>
|
|
692
|
+
<tr><td><a href="#sk-comments"><code>yad-review-comments</code></a></td><td>Setup</td><td>Install the structured review-comment scaffolds.</td></tr>
|
|
693
|
+
<tr><td><a href="#sk-spec"><code>yad-spec</code></a></td><td>Build A</td><td>Spec one ready story in one repo (Spec Kit ceremony).</td></tr>
|
|
694
|
+
<tr><td><a href="#sk-impl"><code>yad-implement</code></a></td><td>Build B</td><td>Implement one atomic task as a small branch.</td></tr>
|
|
695
|
+
<tr><td><a href="#sk-checks"><code>yad-checks</code></a></td><td>Build C</td><td>Wire / run the CI gates.</td></tr>
|
|
696
|
+
<tr><td><a href="#sk-prt"><code>yad-pr-template</code></a></td><td>Build D</td><td>Install the PR/MR template + risk routing.</td></tr>
|
|
697
|
+
<tr><td><a href="#sk-ship"><code>yad-ship</code></a></td><td>Build E</td><td>AI review → engineer review → ship + record.</td></tr>
|
|
698
|
+
<tr><td><a href="#sk-backfill"><code>yad-backfill</code></a></td><td>Build G</td><td>Spec already-built / legacy code before changing it.</td></tr>
|
|
699
|
+
<tr><td><a href="#sk-run"><code>yad-run</code></a></td><td>Automation</td><td>Drive the back half on the dials; set dials; kill switch.</td></tr>
|
|
700
|
+
<tr><td><a href="#sk-status"><code>yad-status</code></a></td><td>Anytime</td><td>Read-only view: where everything is and what’s blocking.</td></tr>
|
|
701
|
+
</table>
|
|
702
|
+
|
|
703
|
+
<h3>Setup & code-awareness</h3>
|
|
704
|
+
|
|
705
|
+
<div class="skillcard" id="sk-connect">
|
|
706
|
+
<h4><code>yad-connect-repos</code></h4>
|
|
707
|
+
<div class="row"><span class="lbl lbl-what">What</span> Introduces your code repos to the product hub so the “brain” knows what is already built. It registers each repo in <code>repos.json</code> and caches an AI-readable picture of it (a Repomix pack + a code-map of existing endpoints, events, data models and modules). Also sets up the hub’s own platform record and reviewer roster.</div>
|
|
708
|
+
<div class="row"><span class="lbl lbl-how">How</span> Run it in the product hub, once per repo:</div>
|
|
709
|
+
<pre><code>yad-connect-repos action: connect repo: backend path: ../backend-repo domain_owner: carol
|
|
710
|
+
yad-connect-repos action: list # see every repo as fresh / stale
|
|
711
|
+
yad-connect-repos action: refresh repo: backend # re-pack after the code moved
|
|
712
|
+
yad-connect-repos action: disconnect repo: backend
|
|
713
|
+
yad-connect-repos action: detect-hub # record the hub's GitHub/GitLab platform
|
|
714
|
+
yad-connect-repos action: roster login: alice-gh name: alice role: owner # once per reviewer</code></pre>
|
|
715
|
+
<div class="row"><span class="lbl lbl-when">When</span> During one-time setup, and again any time you add a new code repo. Re-run <code>refresh</code> when a skill warns a repo is stale. <strong>Greenfield with no code yet? Skip it entirely</strong> — the brain proceeds without it.</div>
|
|
716
|
+
</div>
|
|
717
|
+
|
|
718
|
+
<h3>Front half — author the thinking (in the product hub)</h3>
|
|
719
|
+
|
|
720
|
+
<div class="skillcard" id="sk-analysis">
|
|
721
|
+
<h4><code>yad-analysis</code> <em>(optional)</em></h4>
|
|
722
|
+
<div class="row"><span class="lbl lbl-what">What</span> A dedicated discovery pass: the analyst AI pressure-tests your raw idea — is it worth building, for whom, what could kill it — and writes the brief into <code>analysis.md</code>. It assigns the epic’s <code>EP-<slug></code> ID and seeds the state files.</div>
|
|
723
|
+
<div class="row"><span class="lbl lbl-how">How</span> In the product hub, just describe the idea:</div>
|
|
724
|
+
<pre><code>run yad-analysis — idea: "let users submit religious inquiries and track answers"</code></pre>
|
|
725
|
+
<div class="row"><span class="lbl lbl-when">When</span> Before the epic, when the idea is still fuzzy and deserves its own gated discovery round. <strong>Skip it freely</strong> — the epic step does the same shaping inline.</div>
|
|
726
|
+
</div>
|
|
727
|
+
|
|
728
|
+
<div class="skillcard" id="sk-epic">
|
|
729
|
+
<h4><code>yad-epic</code></h4>
|
|
730
|
+
<div class="row"><span class="lbl lbl-what">What</span> Writes the feature down properly: problem, goal, scope, the repos it will touch → <code>epic.md</code>. The analyst shapes the idea, the pm writes the epic. If analysis didn’t run, this is the entry point: it assigns the <code>EP-<slug></code> ID and seeds <code>.sdlc/</code> state. If repos are connected, it reads their code-maps so the epic references what already exists.</div>
|
|
731
|
+
<div class="row"><span class="lbl lbl-how">How</span> In the product hub:</div>
|
|
732
|
+
<pre><code>run yad-epic — feature: "inquiry submission and tracking"</code></pre>
|
|
733
|
+
<div class="row"><span class="lbl lbl-when">When</span> The start of every new feature (or right after the analysis gate passes). It ends by stopping at the <strong>epic review gate</strong>.</div>
|
|
734
|
+
</div>
|
|
735
|
+
|
|
736
|
+
<div class="skillcard" id="sk-arch">
|
|
737
|
+
<h4><code>yad-architecture</code></h4>
|
|
738
|
+
<div class="row"><span class="lbl lbl-what">What</span> With the architect AI, decides <em>how</em> the feature is built (<code>architecture.md</code>) and writes the <strong>locked contract</strong> (<code>contract.md</code>) — the one shared surface (APIs, events, data model) every repo must obey. It hash-locks the contract surface into <code>contract-lock.json</code>. Code-aware: it cross-checks the surface against existing endpoints before locking.</div>
|
|
739
|
+
<div class="row"><span class="lbl lbl-how">How</span> In the product hub, after the epic gate passes:</div>
|
|
740
|
+
<pre><code>run yad-architecture — epic: EP-istifta-inquiries</code></pre>
|
|
741
|
+
<div class="row"><span class="lbl lbl-when">When</span> Right after the epic review is approved. Stops at the <strong>architecture review gate</strong>, which is always <em>escalated</em> (domain owners of every repo must approve).</div>
|
|
742
|
+
</div>
|
|
743
|
+
|
|
744
|
+
<div class="skillcard" id="sk-ui">
|
|
745
|
+
<h4><code>yad-ui</code></h4>
|
|
746
|
+
<div class="row"><span class="lbl lbl-what">What</span> With the ux-designer AI, authors the UI design for the epic: <code>ui-design.md</code> (this feature’s screens and flows) + <code>DESIGN.md</code> (the reusable design language). Drives Impeccable’s <code>document / extract / craft</code> commands when installed; writes the files directly when not (and records that).</div>
|
|
747
|
+
<div class="row"><span class="lbl lbl-how">How</span> In the product hub, after the architecture gate passes:</div>
|
|
748
|
+
<pre><code>run yad-ui — epic: EP-istifta-inquiries</code></pre>
|
|
749
|
+
<div class="row"><span class="lbl lbl-when">When</span> After architecture, before stories. Skip-able only if the epic genuinely has no UI. Stops at the <strong>UI review gate</strong> (base rule).</div>
|
|
750
|
+
</div>
|
|
751
|
+
|
|
752
|
+
<div class="skillcard" id="sk-stories">
|
|
753
|
+
<h4><code>yad-stories</code></h4>
|
|
754
|
+
<div class="row"><span class="lbl lbl-what">What</span> With the pm AI, slices the approved epic into user stories small enough to build — one file each under <code>stories/</code>, with stable IDs (<code>EP-<slug>-S01</code>…) and a <code>repos:</code> tag naming which code repos must implement each one. Reads epic + architecture + contract + UI as input.</div>
|
|
755
|
+
<div class="row"><span class="lbl lbl-how">How</span> In the product hub, after the UI gate passes:</div>
|
|
756
|
+
<pre><code>run yad-stories — epic: EP-istifta-inquiries</code></pre>
|
|
757
|
+
<div class="row"><span class="lbl lbl-when">When</span> The last front-half author step. Stops at the <strong>stories review gate</strong> (per-repo rule). When that gate passes, the epic is <code>ready-for-build</code>.</div>
|
|
758
|
+
</div>
|
|
759
|
+
|
|
760
|
+
<h3>The review gate & its plumbing (cross-cutting)</h3>
|
|
761
|
+
|
|
762
|
+
<div class="skillcard" id="sk-gate">
|
|
763
|
+
<h4><code>yad-review-gate</code></h4>
|
|
764
|
+
<div class="row"><span class="lbl lbl-what">What</span> The one reusable team review loop used by <em>every</em> front-half review. It shows the artifact, records comments and approvals as files, enforces the approval rule (owner + 1 reviewer, escalating on contract/auth/payments), and moves the step forward <strong>only</strong> when the rule is met.</div>
|
|
765
|
+
<div class="row"><span class="lbl lbl-how">How</span> In the product hub, one action at a time:</div>
|
|
766
|
+
<pre><code>yad-review-gate epic: EP-istifta-inquiries artifact: epic.md action: open # present it for review
|
|
767
|
+
yad-review-gate … action: comment # record a reviewer's notes (never advances)
|
|
768
|
+
yad-review-gate … action: approve # record an approval (name + role)
|
|
769
|
+
yad-review-gate … action: sync # pull approvals/comments from the hub review PR
|
|
770
|
+
yad-review-gate … action: advance # move on — only if the rule is met, else it names who's missing</code></pre>
|
|
771
|
+
<div class="row"><span class="lbl lbl-when">When</span> After every author step — the artifact is written and waiting. Use <code>open → comment → approve → advance</code> for the file-only gate; add <code>sync</code> when the hub is on a platform and reviewers worked on the PR.</div>
|
|
772
|
+
</div>
|
|
773
|
+
|
|
774
|
+
<div class="skillcard" id="sk-bridge">
|
|
775
|
+
<h4><code>yad-hub-bridge</code></h4>
|
|
776
|
+
<div class="row"><span class="lbl lbl-what">What</span> The bridge between the file ledger and real PRs/MRs on the hub: opens a review PR per artifact, sets the required reviewers and labels from the routing rule, and provides the read-only <code>gh</code>/<code>glab</code> recipes that pull platform approvals and comments back into the files. The file ledger always stays the source of truth.</div>
|
|
777
|
+
<div class="row"><span class="lbl lbl-how">How</span> Mostly invoked <em>for</em> you by the gate (its <code>open</code>/<code>sync</code>). You call it directly once, to wire the event-driven sync CI:</div>
|
|
778
|
+
<pre><code>yad-hub-bridge action: wire # hub CI runs `yad gate ci` on every approve / request-changes / merge</code></pre>
|
|
779
|
+
<div class="row"><span class="lbl lbl-when">When</span> Once during setup (step “wire the hub”), if you want front-half reviews to ride real PRs/MRs. No platform or no <code>gh</code>/<code>glab</code>? Everything degrades to the file-only gate with no error — you never <em>need</em> this skill.</div>
|
|
780
|
+
</div>
|
|
781
|
+
|
|
782
|
+
<div class="skillcard" id="sk-comments">
|
|
783
|
+
<h4><code>yad-review-comments</code></h4>
|
|
784
|
+
<div class="row"><span class="lbl lbl-what">What</span> Installs ready-made review-comment templates into a repo (a committed <code>REVIEW_COMMENTS.md</code> on GitHub / comment templates on GitLab), so reviewers leave structured, attributable feedback — each comment carries a <code>**name (role)**</code> header that maps cleanly into the file ledger.</div>
|
|
785
|
+
<div class="row"><span class="lbl lbl-how">How</span> Once per repo (and once for the hub):</div>
|
|
786
|
+
<pre><code>yad-review-comments repo: backend action: wire
|
|
787
|
+
yad-review-comments repo: hub action: wire</code></pre>
|
|
788
|
+
<div class="row"><span class="lbl lbl-when">When</span> During one-time setup, together with the other wiring. Re-running is a harmless no-op.</div>
|
|
789
|
+
</div>
|
|
790
|
+
|
|
791
|
+
<h3>Build half — turn stories into shipped code (in a code repo)</h3>
|
|
792
|
+
|
|
793
|
+
<div class="skillcard" id="sk-spec">
|
|
794
|
+
<h4><code>yad-spec</code> — Build Step A</h4>
|
|
795
|
+
<div class="row"><span class="lbl lbl-what">What</span> Runs the heavy Spec Kit ceremony <strong>once</strong> for one story in one repo — <code>specify → clarify → plan → analyze → checklist → tasks</code> — writing <code>specs/<story-id>/</code> inside the code repo plus a <code>link.md</code> back to the story. It <em>quotes</em> the locked contract; it never widens it. Drives <code>/speckit.*</code> when installed, authors the same files by hand when not.</div>
|
|
796
|
+
<div class="row"><span class="lbl lbl-how">How</span> From the code repo (or naming it):</div>
|
|
797
|
+
<pre><code>yad-spec story: EP-istifta-inquiries-S01 repo: backend</code></pre>
|
|
798
|
+
<div class="row"><span class="lbl lbl-when">When</span> The first build step for every <code>ready-for-build</code> story — once per repo the story is tagged with. The tasks it produces feed <code>yad-implement</code>.</div>
|
|
799
|
+
</div>
|
|
800
|
+
|
|
801
|
+
<div class="skillcard" id="sk-impl">
|
|
802
|
+
<h4><code>yad-implement</code> — Build Step B</h4>
|
|
803
|
+
<div class="row"><span class="lbl lbl-what">What</span> With the dev AI, implements <strong>one atomic task</strong> from the story’s <code>tasks.md</code> as a small diff (≤3 files) on its own branch: <em>one task = one branch = one commit = one PR</em>. The diff must stay inside the files the task declared — if it would grow, the skill flags it and STOPS. The commit follows the convention (Conventional subject, <code>Task:</code> trailer, optional AI co-author, <code>Contract-Change: yes</code> only if the locked surface is touched).</div>
|
|
804
|
+
<div class="row"><span class="lbl lbl-how">How</span> Once per task, repeating until the story’s tasks are done:</div>
|
|
805
|
+
<pre><code>yad-implement story: EP-istifta-inquiries-S01 repo: backend task: T01
|
|
806
|
+
# then commit + open the PR with the CLI:
|
|
807
|
+
yad commit --type feat -m "create inquiry endpoint" --ai claude
|
|
808
|
+
yad open-pr --repo backend</code></pre>
|
|
809
|
+
<div class="row"><span class="lbl lbl-when">When</span> After the story is spec’d. Run it once per task ID (<code>T01</code>, <code>T02</code>, …). It hands off to the check gates — never merges anything itself.</div>
|
|
810
|
+
</div>
|
|
811
|
+
|
|
812
|
+
<div class="skillcard" id="sk-checks">
|
|
813
|
+
<h4><code>yad-checks</code> — Build Step C</h4>
|
|
814
|
+
<div class="row"><span class="lbl lbl-what">What</span> The production-safety CI gates: <strong>spec-link</strong> (every change links a real story/spec), <strong>contract-check</strong> (a contract-surface diff without a re-locked contract FAILS), <strong>build/test/lint</strong>, and <strong>verified-commits</strong> (signed commits from roster-known authors). <code>wire</code> installs them into the repo’s CI (merging with any existing CI, never clobbering); <code>run</code> executes them right now, locally.</div>
|
|
815
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
816
|
+
<pre><code>yad-checks repo: backend action: wire # once, during setup
|
|
817
|
+
yad-checks repo: backend action: run # before opening each PR
|
|
818
|
+
yad-checks repo: hub action: wire # hub-flavored gates for the product hub</code></pre>
|
|
819
|
+
<div class="row"><span class="lbl lbl-when">When</span> <code>wire</code> once per repo at setup; <code>run</code> after implementing, before the PR — the same gates also run automatically in CI on every PR and must pass before merge.</div>
|
|
820
|
+
</div>
|
|
821
|
+
|
|
822
|
+
<div class="skillcard" id="sk-prt">
|
|
823
|
+
<h4><code>yad-pr-template</code> — Build Step D</h4>
|
|
824
|
+
<div class="row"><span class="lbl lbl-what">What</span> Detects the repo’s platform and commits the matching PR/MR template, which carries an <strong>Impact & Risk block</strong>. A <code>high</code> risk level — or a touched contract/auth/payments surface — routes the review to the domain owners. <code>route</code> reads a PR body and prints exactly who must review it.</div>
|
|
825
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
826
|
+
<pre><code>yad-pr-template repo: backend action: wire # once, during setup
|
|
827
|
+
yad-pr-template repo: backend action: route # who must review this PR?
|
|
828
|
+
yad-pr-template repo: hub action: wire # the hub's front-half review template</code></pre>
|
|
829
|
+
<div class="row"><span class="lbl lbl-when">When</span> <code>wire</code> once per repo (and the hub) at setup; <code>route</code> whenever you’ve opened a PR and want the required reviewer list.</div>
|
|
830
|
+
</div>
|
|
831
|
+
|
|
832
|
+
<div class="skillcard" id="sk-ship">
|
|
833
|
+
<h4><code>yad-ship</code> — Build Step E</h4>
|
|
834
|
+
<div class="row"><span class="lbl lbl-what">What</span> The last mile of a task’s PR: <code>ai-review</code> triggers the advisory AI pass (CodeRabbit — a second set of eyes, never the authority); <code>approve</code> records the <strong>human engineer approval</strong> (owner + 1 reviewer, same escalation); <code>ship</code> merges and records the ship in <code>build-log.json</code>, moving the story to <code>in-build</code> → <code>shipped</code> so the epic → story → task → PR chain stays traceable.</div>
|
|
835
|
+
<div class="row"><span class="lbl lbl-how">How</span> Against the task’s PR, in order:</div>
|
|
836
|
+
<pre><code>yad-ship story: EP-istifta-inquiries-S01 task: T01 repo: backend action: ai-review
|
|
837
|
+
yad-ship … action: approve # the human engineer's approval
|
|
838
|
+
yad-ship … action: ship # merge + record in build-log.json</code></pre>
|
|
839
|
+
<div class="row"><span class="lbl lbl-when">When</span> Once a task’s PR is open and the check gates are green. The engineer approval here is <strong>permanently human</strong> — no dial can ever automate it.</div>
|
|
840
|
+
</div>
|
|
841
|
+
|
|
842
|
+
<div class="skillcard" id="sk-backfill">
|
|
843
|
+
<h4><code>yad-backfill</code> — Build Step G</h4>
|
|
844
|
+
<div class="row"><span class="lbl lbl-what">What</span> Writes specs for code that was built <em>before</em> the workflow existed, so new work doesn’t break it. It packs <strong>one feature at a time</strong> with Repomix (secret-scanned), has AI draft a “describe what exists, do not invent” spec marked <strong>DRAFT/unverified</strong>, and requires a human approval (through the same review gate) before the spec counts. Until then, changes to that feature are blocked — gated per touched feature, never the whole repo.</div>
|
|
845
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
846
|
+
<pre><code>yad-backfill repo: backend feature: health # globs e.g. src/health/**</code></pre>
|
|
847
|
+
<div class="row"><span class="lbl lbl-when">When</span> Brownfield projects, <em>before</em> a new story touches an old, unspecced feature. Never needed on greenfield.</div>
|
|
848
|
+
</div>
|
|
849
|
+
|
|
850
|
+
<h3>Automation & status</h3>
|
|
851
|
+
|
|
852
|
+
<div class="skillcard" id="sk-run">
|
|
853
|
+
<h4><code>yad-run</code></h4>
|
|
854
|
+
<div class="row"><span class="lbl lbl-what">What</span> The orchestrator that makes automation real. It walks a story’s back half (spec → tasks → implement → checks) reading each step’s automation dial: <code>machine_advance</code> → it proceeds alone; <code>human_approve</code> → it stops for you. Any failure, scope overrun, or contract-surface touch <strong>halts and pulls in a human</strong>, and it always stops at the engineer review. Every run lands in the trust log. It also flips dials (refusing without enough evidence) and owns the kill switch.</div>
|
|
855
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
856
|
+
<pre><code>yad-run story: EP-istifta-inquiries-S02 repo: backend # drive the back half on the dials
|
|
857
|
+
yad-run action: set-dial step: checks to: machine_advance # earn automation (needs trust evidence)
|
|
858
|
+
yad-run action: set-dial step: checks to: human_approve # revert — always allowed
|
|
859
|
+
yad-run action: kill # everything back to human, system-wide, instantly
|
|
860
|
+
yad-run action: unkill # restore earned automation</code></pre>
|
|
861
|
+
<div class="row"><span class="lbl lbl-when">When</span> Entirely optional — ignore it at first; every step is human-approved by default. Reach for it once a back step’s trust record clears the threshold (default: ≥5 runs, ≥80% approved-unchanged). Use <code>kill</code> the moment anything feels wrong.</div>
|
|
862
|
+
</div>
|
|
863
|
+
|
|
864
|
+
<div class="skillcard" id="sk-status">
|
|
865
|
+
<h4><code>yad-status</code></h4>
|
|
866
|
+
<div class="row"><span class="lbl lbl-what">What</span> A <strong>read-only</strong> dashboard in text: the epic’s full step chain, every step’s two dials and status, the contract lock, which approvals the active gate is still waiting on, each back step’s trust record, the kill-switch state — and across epics, the fleet roll-up. It changes nothing.</div>
|
|
867
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
868
|
+
<pre><code>yad-status # everything, across epics (fleet view)
|
|
869
|
+
yad-status EP-istifta-inquiries # one epic in detail</code></pre>
|
|
870
|
+
<div class="row"><span class="lbl lbl-when">When</span> Any time, freely — it’s the “where are we and what’s blocking?” command. The best first move whenever you’re unsure what to do next.</div>
|
|
871
|
+
</div>
|
|
872
|
+
</section>
|
|
873
|
+
|
|
874
|
+
<!-- ======================================================= -->
|
|
875
|
+
<section id="cli">
|
|
876
|
+
<h2>7. All CLI commands — what each does, how to use it, and when</h2>
|
|
877
|
+
<p>The <code>yad</code> CLI is the <em>deterministic</em> half of the system — the skills think,
|
|
878
|
+
the CLI does the predictable file-and-platform work. It’s published to npm as
|
|
879
|
+
<code>yadflow</code>; run it from your <strong>product hub</strong> repo with
|
|
880
|
+
<code>npx</code> — no clone needed, nothing to install globally.</p>
|
|
881
|
+
|
|
882
|
+
<h3>Install & keep in sync</h3>
|
|
883
|
+
|
|
884
|
+
<div class="skillcard">
|
|
885
|
+
<h4><code>npx yadflow setup</code></h4>
|
|
886
|
+
<div class="row"><span class="lbl lbl-what">What</span> The guided first-run wizard. Seven steps: preflight (git/node check), install all 17 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, connect your code repos, wire each one (CI gates, PR template, comment scaffold), optionally write the AI-review config, and stamp the installed version.</div>
|
|
887
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
888
|
+
<pre><code>cd <product-hub-repo>
|
|
889
|
+
npx yadflow setup</code></pre>
|
|
890
|
+
<div class="row"><span class="lbl lbl-when">When</span> Exactly once per project, by the team lead, from inside the (possibly empty) product hub repo. It never re-asks for answers you already gave.</div>
|
|
891
|
+
</div>
|
|
892
|
+
|
|
893
|
+
<div class="skillcard">
|
|
894
|
+
<h4><code>… check</code> / <code>… check --fix</code> / <code>… update</code></h4>
|
|
895
|
+
<div class="row"><span class="lbl lbl-what">What</span> The health check and repair tools. <code>check</code> is read-only: it reports what is <strong>missing</strong> (never installed), <strong>outdated/drifted</strong> (the workflow shipped a newer version), or <strong>stale</strong> (a repo’s cached code picture is behind its code). <code>check --fix</code> reconciles all of it — filling gaps and applying updates while touching nothing that is already correct. <code>update</code> applies drift only (an alias for <code>check --fix --scope=changed</code>).</div>
|
|
896
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
897
|
+
<pre><code>npx yadflow check # just tell me — read-only
|
|
898
|
+
npx yadflow check --fix # and fix it
|
|
899
|
+
npx yadflow update # apply updates only</code></pre>
|
|
900
|
+
<div class="row"><span class="lbl lbl-when">When</span> After any workflow update (a new version on npm), after a BMAD update, or whenever something seems off. Safe to run any time — <code>check</code> changes nothing.</div>
|
|
901
|
+
</div>
|
|
902
|
+
|
|
903
|
+
<div class="skillcard">
|
|
904
|
+
<h4><code>… --version</code></h4>
|
|
905
|
+
<div class="row"><span class="lbl lbl-what">What</span> Prints the installed CLI version.</div>
|
|
906
|
+
<div class="row"><span class="lbl lbl-how">How</span> <code>npx yadflow --version</code></div>
|
|
907
|
+
<div class="row"><span class="lbl lbl-when">When</span> Checking whether you’re behind, or reporting a bug.</div>
|
|
908
|
+
</div>
|
|
909
|
+
|
|
910
|
+
<h3>The front-half review gate (<code>yad gate …</code>)</h3>
|
|
911
|
+
|
|
912
|
+
<div class="skillcard">
|
|
913
|
+
<h4><code>yad gate open <epic> <artifact></code></h4>
|
|
914
|
+
<div class="row"><span class="lbl lbl-what">What</span> Opens the review PR/MR on the hub for one authored artifact (epic, architecture, UI, stories…), sets the required reviewers and labels from the routing rule, and marks the step <code>in_review</code>.</div>
|
|
915
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
916
|
+
<pre><code>yad gate open EP-istifta-inquiries epic.md</code></pre>
|
|
917
|
+
<div class="row"><span class="lbl lbl-when">When</span> Right after an author step finishes, when the hub is on a platform. (No platform? Use the <code>yad-review-gate</code> skill file-only instead.)</div>
|
|
918
|
+
</div>
|
|
919
|
+
|
|
920
|
+
<div class="skillcard">
|
|
921
|
+
<h4><code>yad gate sync <epic> [artifact]</code></h4>
|
|
922
|
+
<div class="row"><span class="lbl lbl-what">What</span> Pulls the review PR’s approvals and comment threads into the file ledger (<code>approvals.json</code>, <code>comments.json</code>, <code>reviews/*.md</code>) using your own <code>gh</code>/<code>glab</code> login — and <strong>auto-advances the step</strong> once three things hold: the approval rule is satisfied, every comment thread is resolved, and the PR is merged. Approvals are revoked automatically if the artifact changed since they were given.</div>
|
|
923
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
924
|
+
<pre><code>yad gate sync EP-istifta-inquiries # all open reviews of the epic
|
|
925
|
+
yad gate sync EP-istifta-inquiries epic.md # just this one</code></pre>
|
|
926
|
+
<div class="row"><span class="lbl lbl-when">When</span> After reviewers acted on the platform. <strong>Usually you don’t run it at all</strong> — with the gate-sync CI wired, every approval / change request / merge triggers it automatically; this stays valid as the manual fallback.</div>
|
|
927
|
+
</div>
|
|
928
|
+
|
|
929
|
+
<div class="skillcard">
|
|
930
|
+
<h4><code>yad gate comments <epic> [artifact]</code></h4>
|
|
931
|
+
<div class="row"><span class="lbl lbl-what">What</span> Fetches the <em>unresolved</em> review comment threads so the artifact owner can address them. (You reply on the PR; the reviewer resolves their own thread.)</div>
|
|
932
|
+
<div class="row"><span class="lbl lbl-how">How</span> <code>yad gate comments EP-istifta-inquiries</code></div>
|
|
933
|
+
<div class="row"><span class="lbl lbl-when">When</span> A gate is stuck <code>in_review</code> and you want the to-do list of open feedback.</div>
|
|
934
|
+
</div>
|
|
935
|
+
|
|
936
|
+
<div class="skillcard">
|
|
937
|
+
<h4><code>yad gate status <epic></code></h4>
|
|
938
|
+
<div class="row"><span class="lbl lbl-what">What</span> Shows each review step and its recorded approvals — counting only the non-stale ones.</div>
|
|
939
|
+
<div class="row"><span class="lbl lbl-how">How</span> <code>yad gate status EP-istifta-inquiries</code></div>
|
|
940
|
+
<div class="row"><span class="lbl lbl-when">When</span> Quick check of “who has approved what, and who is still missing” on the front half.</div>
|
|
941
|
+
</div>
|
|
942
|
+
|
|
943
|
+
<div class="skillcard">
|
|
944
|
+
<h4><code>yad gate ci [--branch <head>] [--pr <n>]</code></h4>
|
|
945
|
+
<div class="row"><span class="lbl lbl-what">What</span> The entry point the hub’s <em>CI</em> calls on review events: it derives the epic/artifact from the <code>review/EP-*</code> branch, runs the same sync, and commits <strong>only the ledger files</strong> to the hub’s default branch. With no <code>--branch</code> it sweeps every open review PR. CI never approves and never merges — the merge click stays human.</div>
|
|
946
|
+
<div class="row"><span class="lbl lbl-how">How</span> You don’t run it by hand — the wired workflow (<code>yad-gate-sync.yml</code>) calls it on every approve / request-changes / merge.</div>
|
|
947
|
+
<div class="row"><span class="lbl lbl-when">When</span> Automatically, once the hub bridge is wired. Good to know it exists when reading the hub’s CI logs.</div>
|
|
948
|
+
</div>
|
|
949
|
+
|
|
950
|
+
<h3>Build-half helpers</h3>
|
|
951
|
+
|
|
952
|
+
<div class="skillcard">
|
|
953
|
+
<h4><code>yad commit --type <t> -m <subject></code></h4>
|
|
954
|
+
<div class="row"><span class="lbl lbl-what">What</span> Commits by the SDLC convention so you never hand-build a trailer: it forms the Conventional subject (<code>feat: …</code>), derives the <code>Task:</code> trailer from your branch name, optionally appends an AI <code>Co-Authored-By:</code>, adds <code>Contract-Change: yes</code> only when you say so, and <strong>refuses a non-atomic stage</strong> (changes outside the task’s declared files).</div>
|
|
955
|
+
<div class="row"><span class="lbl lbl-how">How</span> From the task branch in a code repo:</div>
|
|
956
|
+
<pre><code>yad commit --type feat -m "create inquiry endpoint" --ai claude
|
|
957
|
+
yad commit --type fix -m "handle empty answer" --contract-change # only if the locked surface moved
|
|
958
|
+
yad commit --type feat -m "…" --dry-run # preview without committing</code></pre>
|
|
959
|
+
<div class="row"><span class="lbl lbl-when">When</span> Every commit during <code>yad-implement</code>. Flags: <code>--type</code>, <code>-m/--message</code>, <code>--task</code>, <code>--ai claude|copilot|cursor|coderabbit|none</code>, <code>--contract-change</code>, <code>--dry-run</code>, <code>--force</code> (bypass the atomic guard — use sparingly).</div>
|
|
960
|
+
</div>
|
|
961
|
+
|
|
962
|
+
<div class="skillcard">
|
|
963
|
+
<h4><code>yad open-pr [--repo <name>] [--risk <level>]</code></h4>
|
|
964
|
+
<div class="row"><span class="lbl lbl-what">What</span> Pushes the task branch and opens the code-repo PR/MR <em>pre-filled from the wired template</em> — story/task links and the Impact & Risk block included. Aborts cleanly if the branch push fails.</div>
|
|
965
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
966
|
+
<pre><code>yad open-pr --repo backend
|
|
967
|
+
yad open-pr --repo backend --risk high # routes review to the domain owners
|
|
968
|
+
yad open-pr --repo backend --contract-change # declares a locked-surface change</code></pre>
|
|
969
|
+
<div class="row"><span class="lbl lbl-when">When</span> After the task is committed and <code>yad-checks action: run</code> is green — one PR per atomic task.</div>
|
|
970
|
+
</div>
|
|
971
|
+
|
|
972
|
+
<h3>Connected-repo freshness</h3>
|
|
973
|
+
|
|
974
|
+
<div class="skillcard">
|
|
975
|
+
<h4><code>yad repo list</code> / <code>yad repo refresh [name]</code></h4>
|
|
976
|
+
<div class="row"><span class="lbl lbl-what">What</span> <code>list</code> shows every connected code repo as <strong>fresh</strong> (the cached code-map still matches the code) or <strong>stale</strong> (the repo has moved since it was packed). <code>refresh</code> deliberately re-packs a stale one. Staleness is a <em>human decision</em> — skills warn and point here; they never silently re-pack.</div>
|
|
977
|
+
<div class="row"><span class="lbl lbl-how">How</span></div>
|
|
978
|
+
<pre><code>yad repo list
|
|
979
|
+
yad repo refresh backend</code></pre>
|
|
980
|
+
<div class="row"><span class="lbl lbl-when">When</span> <code>list</code> any time you wonder how current the brain’s picture is; <code>refresh</code> when a front-half step flags a stale repo before authoring against it.</div>
|
|
981
|
+
</div>
|
|
982
|
+
|
|
983
|
+
<h3>Global flags</h3>
|
|
984
|
+
<table>
|
|
985
|
+
<tr><th>Flag</th><th>Meaning</th></tr>
|
|
986
|
+
<tr><td><code>--dir <path></code></td><td>Target a project other than the current directory.</td></tr>
|
|
987
|
+
<tr><td><code>--force</code></td><td>Re-copy unchanged files during install, or bypass the commit atomic guard.</td></tr>
|
|
988
|
+
</table>
|
|
989
|
+
|
|
990
|
+
<div class="callout blue">
|
|
991
|
+
<strong>Skill or CLI?</strong> Rule of thumb: <strong>skills</strong> for anything that needs thinking
|
|
992
|
+
(authoring, specs, implementing, reviews-as-conversation); the <strong>CLI</strong> for anything
|
|
993
|
+
deterministic (installing, wiring, committing by convention, opening PRs, syncing platform state).
|
|
994
|
+
They write to the same files, so you can mix freely.
|
|
995
|
+
</div>
|
|
996
|
+
</section>
|
|
997
|
+
|
|
998
|
+
<!-- ======================================================= -->
|
|
999
|
+
<section id="competitors">
|
|
1000
|
+
<h2>8. Competitor analysis — who else does this, and how close they get</h2>
|
|
1001
|
+
<p class="lead">
|
|
1002
|
+
Yadflow sits in the <strong>spec-driven / AI-governed development</strong> market. The honest
|
|
1003
|
+
headline first: as of mid-2026, <strong>no single tool on the market offers the exact same package</strong>
|
|
1004
|
+
— a team-gated, file-driven SDLC with a hash-locked multi-repo contract and evidence-based (“earned”)
|
|
1005
|
+
automation. But many tools cover <em>slices</em> of it, several with far bigger communities, and one
|
|
1006
|
+
(AWS AI-DLC) shares almost the same philosophy. This section maps them honestly.
|
|
1007
|
+
<em>(Market facts checked via web research on 2026-06-12; sources at the end.)</em>
|
|
1008
|
+
</p>
|
|
1009
|
+
|
|
1010
|
+
<h3>How to read the market — the five pillars</h3>
|
|
1011
|
+
<p>Yadflow is really five capabilities in one. Each competitor below is strong in one or two
|
|
1012
|
+
pillars and absent in the rest:</p>
|
|
1013
|
+
<table>
|
|
1014
|
+
<tr><th>Pillar</th><th>What it means</th><th>Who else has it</th></tr>
|
|
1015
|
+
<tr><td><strong>1 · Spec-driven authoring</strong></td><td>Write the thinking (spec/plan/tasks) before code.</td><td>Almost everyone — Spec Kit, Kiro, BMAD, OpenSpec, GSD, Tessl.</td></tr>
|
|
1016
|
+
<tr><td><strong>2 · Team review gates</strong></td><td>Named humans must approve each step; rules + escalation.</td><td>AI-DLC (rituals, not records) · enterprise platforms (policies). Rare elsewhere — most tools are <em>solo</em>.</td></tr>
|
|
1017
|
+
<tr><td><strong>3 · Multi-repo contract</strong></td><td>One locked cross-repo surface that CI enforces.</td><td><strong>Essentially nobody.</strong> The clearest differentiator.</td></tr>
|
|
1018
|
+
<tr><td><strong>4 · Brownfield support</strong></td><td>Spec what already exists before changing it.</td><td>OpenSpec (delta specs) · Kiro (steering files) · Repomix-style packers.</td></tr>
|
|
1019
|
+
<tr><td><strong>5 · Earned, reversible automation</strong></td><td>Automation unlocked by recorded evidence; kill switch.</td><td><strong>Essentially nobody</strong> — others are either always-manual or always-auto.</td></tr>
|
|
1020
|
+
</table>
|
|
1021
|
+
|
|
1022
|
+
<h3>Positioning map</h3>
|
|
1023
|
+
<div class="diagram">
|
|
1024
|
+
<div style="display:grid; grid-template-columns: 28px 1fr 1fr; grid-template-rows: 1fr 1fr 28px; gap:0; min-width:640px">
|
|
1025
|
+
<div style="grid-row:1/3; writing-mode:vertical-rl; transform:rotate(180deg); text-align:center; font-size:.8rem; color:var(--muted); font-weight:700">solo developer → team governance</div>
|
|
1026
|
+
<div style="border:1.5px solid var(--line); border-bottom:2.5px solid #90a0af; padding:12px 14px; background:#fbfcfd">
|
|
1027
|
+
<div style="font-size:.75rem; font-weight:700; color:var(--muted); text-transform:uppercase">team · spec slice</div>
|
|
1028
|
+
<div class="flow-h" style="justify-content:flex-start; gap:6px; margin-top:8px">
|
|
1029
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">Tessl <small>spec registry for teams</small></span>
|
|
1030
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">CodeRabbit <small>review slice only</small></span>
|
|
1031
|
+
</div>
|
|
1032
|
+
</div>
|
|
1033
|
+
<div style="border:1.5px solid var(--line); border-bottom:2.5px solid #90a0af; border-left:2.5px solid #90a0af; padding:12px 14px; background:#eef7f0">
|
|
1034
|
+
<div style="font-size:.75rem; font-weight:700; color:var(--sentinel-bd); text-transform:uppercase">team · whole lifecycle</div>
|
|
1035
|
+
<div class="flow-h" style="justify-content:flex-start; gap:6px; margin-top:8px">
|
|
1036
|
+
<span class="node sentinel" style="min-width:0; font-size:.82rem"><strong>Yadflow</strong></span>
|
|
1037
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">AWS AI-DLC <small>methodology</small></span>
|
|
1038
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">Augment Cosmos / MS agentic SDLC <small>enterprise platforms</small></span>
|
|
1039
|
+
</div>
|
|
1040
|
+
</div>
|
|
1041
|
+
<div style="border:1.5px solid var(--line); padding:12px 14px; background:#fbfcfd">
|
|
1042
|
+
<div style="font-size:.75rem; font-weight:700; color:var(--muted); text-transform:uppercase">solo · spec slice</div>
|
|
1043
|
+
<div class="flow-h" style="justify-content:flex-start; gap:6px; margin-top:8px">
|
|
1044
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">GitHub Spec Kit</span>
|
|
1045
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">OpenSpec <small>brownfield deltas</small></span>
|
|
1046
|
+
</div>
|
|
1047
|
+
</div>
|
|
1048
|
+
<div style="border:1.5px solid var(--line); border-left:2.5px solid #90a0af; padding:12px 14px; background:#fbfcfd">
|
|
1049
|
+
<div style="font-size:.75rem; font-weight:700; color:var(--muted); text-transform:uppercase">solo · whole lifecycle</div>
|
|
1050
|
+
<div class="flow-h" style="justify-content:flex-start; gap:6px; margin-top:8px">
|
|
1051
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">BMAD-METHOD</span>
|
|
1052
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">Kiro (AWS IDE)</span>
|
|
1053
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">GSD</span>
|
|
1054
|
+
<span class="node plain" style="min-width:0; font-size:.82rem">Agent OS · Taskmaster</span>
|
|
1055
|
+
</div>
|
|
1056
|
+
</div>
|
|
1057
|
+
<div></div>
|
|
1058
|
+
<div style="grid-column:2/4; text-align:center; font-size:.8rem; color:var(--muted); font-weight:700; padding-top:6px">covers the spec phase only → covers the whole lifecycle (idea → ship)</div>
|
|
1059
|
+
</div>
|
|
1060
|
+
<div class="caption">The crowded quadrant is bottom-left/bottom-right (solo tools). Yadflow’s quadrant — team governance over the whole lifecycle — has one methodology peer (AI-DLC) and heavyweight enterprise platforms, not file-driven toolkits.</div>
|
|
1061
|
+
</div>
|
|
1062
|
+
|
|
1063
|
+
<h3>The competitors, one by one</h3>
|
|
1064
|
+
|
|
1065
|
+
<div class="skillcard">
|
|
1066
|
+
<h4>BMAD-METHOD <span class="badge b-tool">the base — and the nearest “sibling”</span></h4>
|
|
1067
|
+
<div class="row"><span class="lbl lbl-what">What</span> The open-source (MIT) framework Yadflow is <em>built on</em>: 12+ AI agent personas (analyst, pm, architect, dev…) orchestrated across the full lifecycle. One of the most popular frameworks in the space (~46,700+ GitHub stars; this repo verified and targets v6.8.0 stable). Free.</div>
|
|
1068
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> The whole front-half shape — agents authoring epics, architecture, stories in order — comes from BMAD. Anyone could adopt raw BMAD and get the same authoring experience.</div>
|
|
1069
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> BMAD is fundamentally a <strong>solo tool</strong>: one person drives it, gates are AI-checked quality gates, not <em>named-human</em> approvals. It has no multi-repo contract, no approval ledger, no PR/MR review bridge, no trust log, no kill switch. That delta — “BMAD as a <em>team</em> tool” — is precisely what this repo exists to add.</div>
|
|
1070
|
+
</div>
|
|
1071
|
+
|
|
1072
|
+
<div class="skillcard">
|
|
1073
|
+
<h4>AWS AI-DLC (aidlc-workflows) <span class="badge b-gate">closest in philosophy</span></h4>
|
|
1074
|
+
<div class="row"><span class="lbl lbl-what">What</span> Amazon’s open-source <em>methodology</em> for AI-driven development: adaptive workflow “steering rules” for coding agents. Epics become <strong>Units of Work</strong>, sprints become <strong>Bolts</strong> (hours/days), and every phase transition needs <strong>explicit human approval</strong> — 10–26 verification points per bolt, with team rituals (“Mob Elaboration”, “Mob Construction”) where the team validates AI proposals in real time.</div>
|
|
1075
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> The deepest philosophical overlap on the market: AI does the heavy lifting, humans hold every gate, AI may never advance on its own. If you pitch Yadflow to an AWS-native team, AI-DLC is the comparison they’ll raise.</div>
|
|
1076
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> AI-DLC’s gates are <strong>rituals, not records</strong> — synchronous meetings rather than a durable file ledger with named approvals, rules and escalation. It has no per-step automation dial (everything stays manual; nothing is <em>earned</em>), no multi-repo locked contract, no CI enforcement of spec-links, and no brownfield backfill mechanism. It tells you <em>how to behave</em>; Yadflow gives you <em>machinery that enforces it</em>.</div>
|
|
1077
|
+
</div>
|
|
1078
|
+
|
|
1079
|
+
<div class="skillcard">
|
|
1080
|
+
<h4>GitHub Spec Kit <span class="badge b-tool">most adopted — and a component here</span></h4>
|
|
1081
|
+
<div class="row"><span class="lbl lbl-what">What</span> GitHub’s spec-driven toolkit (≈93,000+ stars, v0.8.7, 30+ supported agents): <code>specify → clarify → plan → tasks → analyze → checklist → implement</code> slash-commands plus a project “constitution”. Free, open source.</div>
|
|
1082
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> Total — by design: Yadflow <em>drives Spec Kit</em> as its build-half Step A rather than competing with it. The spec ceremony is literally the same commands.</div>
|
|
1083
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> Spec Kit covers one pillar only: it specs a feature in <strong>one repo</strong> for <strong>one developer</strong>. No team approvals, no cross-repo contract, no review routing, no automation policy, nothing upstream of the spec (epic/architecture/UI as team decisions). A team adopting bare Spec Kit still has to invent all the governance this repo provides.</div>
|
|
1084
|
+
</div>
|
|
1085
|
+
|
|
1086
|
+
<div class="skillcard">
|
|
1087
|
+
<h4>Kiro (AWS) <span class="badge b-tool">the polished product</span></h4>
|
|
1088
|
+
<div class="row"><span class="lbl lbl-what">What</span> Amazon’s agentic <em>IDE</em> (Code OSS base, launched July 2025) built around specs: every feature gets <code>requirements.md</code> (EARS syntax) → <code>design.md</code> → <code>tasks.md</code>, plus automated hooks and steering files. Free tier; Pro $20 / Pro+ $40 / Power $200 per month.</div>
|
|
1089
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> The same spec-before-code conviction, productized with the smoothest UX in the market. Its three-file spec maps roughly onto this workflow’s epic → architecture → tasks chain.</div>
|
|
1090
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> Single developer, single repo, single IDE — and a paid, closed product with AWS lock-in. The “gate” is one person clicking approve in their own editor; there is no team rule, no named-approval ledger, no contract shared across repos, no earned automation. Yadflow is IDE-agnostic (Claude Code, agents, zencoder, opencode) and the state is portable files in git.</div>
|
|
1091
|
+
</div>
|
|
1092
|
+
|
|
1093
|
+
<div class="skillcard">
|
|
1094
|
+
<h4>OpenSpec <span class="badge b-build">strongest at brownfield</span></h4>
|
|
1095
|
+
<div class="row"><span class="lbl lbl-what">What</span> A lightweight open-source framework for spec-driven change on <strong>existing codebases</strong>: <code>specs/</code> records current behaviour, each change is a self-contained package with <strong>delta specs</strong> (“what’s changing”), through a Propose → Validate → Apply → Archive state machine.</div>
|
|
1096
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> Its specs-for-what-exists idea parallels <code>yad-backfill</code>, and its change-isolation parallels the one-task-one-branch discipline. Reviewers in the market consistently rank it the best pure brownfield tool.</div>
|
|
1097
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> Solo, single-repo, no human-approval machinery (validation is structural, not a team gate), no contract, no automation policy. Notably, its delta-spec approach is <em>lighter</em> than backfill — a fair criticism to absorb: Yadflow’s backfill requires packing and approving a feature spec before touching it, which is heavier but produces a human-verified record.</div>
|
|
1098
|
+
</div>
|
|
1099
|
+
|
|
1100
|
+
<div class="skillcard">
|
|
1101
|
+
<h4>GSD (“Get Stuff Done”) <span class="badge b-tool">the speed play</span></h4>
|
|
1102
|
+
<div class="row"><span class="lbl lbl-what">What</span> A lean meta-prompting framework for Claude Code (~61,000 stars within five months of its Dec 2025 launch): one PLANNING prompt → prioritized TODO → one BUILDING loop until tests are green. Its focus is execution hygiene — keeping the agent’s context clean across a multi-task build.</div>
|
|
1103
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> Almost none in governance — but its explosive growth shows where the market’s center of gravity is: solo speed, minimal ceremony. It is the strongest argument <em>against</em> heavy process.</div>
|
|
1104
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> Deliberately everything: no team, no gates, no contract, no audit trail. The right tool for a solo dev prototyping; the wrong one the day two repos and five engineers must agree on an API. The two aren’t really substitutes — but a small team will feel GSD’s pull.</div>
|
|
1105
|
+
</div>
|
|
1106
|
+
|
|
1107
|
+
<div class="skillcard">
|
|
1108
|
+
<h4>Tessl <span class="badge b-tool">the spec-as-source bet</span></h4>
|
|
1109
|
+
<div class="row"><span class="lbl lbl-what">What</span> A language-agnostic “agent enablement” platform: installs as tiles in <code>.tessl/</code>, teaches any MCP-compatible agent a spec-driven workflow, and runs a <strong>Spec Registry</strong> of 10,000+ library specs to stop API hallucinations. Exploring “spec-as-source” — specs literally generating the code.</div>
|
|
1110
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> Shares the locked-truth instinct: its registry specs play a similar role to the locked contract — an agreed surface agents must not re-invent.</div>
|
|
1111
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> Its locked truth is about <em>third-party libraries</em>, not <em>your team’s cross-repo API</em>. No review gates, no SDLC states, no automation governance. Different bet: Tessl thinks the spec replaces the code; this workflow thinks the team’s judgment stays the product.</div>
|
|
1112
|
+
</div>
|
|
1113
|
+
|
|
1114
|
+
<div class="skillcard">
|
|
1115
|
+
<h4>Agent OS & Taskmaster AI <span class="badge b-tool">workflow plumbing</span></h4>
|
|
1116
|
+
<div class="row"><span class="lbl lbl-what">What</span> Agent OS (Builder Methods) standardizes multi-agent workflows and coding standards across different AI tools; Taskmaster AI decomposes a PRD into an executable task graph for agents.</div>
|
|
1117
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> Both formalize “plan → tasks → execute” like the build half, and Agent OS shares the works-in-any-IDE stance.</div>
|
|
1118
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> Both are solo orchestration layers: no human gates, no approvals, no contract, no trust evidence. They answer “how do my agents stay organized?”, not “how does my <em>team</em> stay in control?”.</div>
|
|
1119
|
+
</div>
|
|
1120
|
+
|
|
1121
|
+
<div class="skillcard">
|
|
1122
|
+
<h4>Enterprise platforms (Augment Cosmos, Microsoft’s agentic SDLC on Azure/GitHub) <span class="badge b-gate">the from-above threat</span></h4>
|
|
1123
|
+
<div class="row"><span class="lbl lbl-what">What</span> Platform-level offerings where agents run on shared context with telemetry, replayable sessions, and human-in-the-loop <em>policies</em> across the SDLC; Microsoft publishes a reference end-to-end agentic SDLC on Azure + GitHub.</div>
|
|
1124
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> They take governance as seriously as this workflow does — approval authority stays human, deterministic checks validate agent output. For a large enterprise, this is the budget-line competitor.</div>
|
|
1125
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> Heavy, vendor-bound, and platform-priced; governance lives in <em>their</em> control plane, not in your git history. Yadflow’s counter-position is radical lightness: plain files, your repos, your CI, local-user auth, zero stored tokens, zero dashboard until measured need (the deliberately unbuilt Phase 5).</div>
|
|
1126
|
+
</div>
|
|
1127
|
+
|
|
1128
|
+
<div class="skillcard">
|
|
1129
|
+
<h4>Adjacent, not competing: CodeRabbit, Graphite, Greptile <span class="badge b-build">the review slice</span></h4>
|
|
1130
|
+
<div class="row"><span class="lbl lbl-what">What</span> AI code-review services that comment on PRs. They cover exactly one box of the build half — the advisory AI review.</div>
|
|
1131
|
+
<div class="row"><span class="lbl lbl-how">Overlap</span> None to defend: Yadflow already <em>uses</em> CodeRabbit as its advisory pass and treats it as never-the-authority.</div>
|
|
1132
|
+
<div class="row"><span class="lbl lbl-when">Gaps vs this</span> They review diffs; they don’t govern a lifecycle. Complementary by design.</div>
|
|
1133
|
+
</div>
|
|
1134
|
+
|
|
1135
|
+
<h3>Head-to-head capability matrix</h3>
|
|
1136
|
+
<table style="font-size:.85rem">
|
|
1137
|
+
<tr>
|
|
1138
|
+
<th>Capability</th><th>Yadflow</th><th>BMAD</th><th>Spec Kit</th><th>Kiro</th><th>AI-DLC</th><th>OpenSpec</th><th>GSD</th><th>Tessl</th>
|
|
1139
|
+
</tr>
|
|
1140
|
+
<tr><td>Spec-driven authoring</td><td>✅ (drives Spec Kit)</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅ deltas</td><td>✅ light</td><td>✅</td></tr>
|
|
1141
|
+
<tr><td>Full lifecycle (idea → ship)</td><td>✅</td><td>✅</td><td>❌ spec only</td><td>✅ in-IDE</td><td>✅</td><td>❌ change only</td><td>✅ thin</td><td>❌</td></tr>
|
|
1142
|
+
<tr><td><strong>Named-human team gates</strong> (rules + escalation + ledger)</td><td>✅</td><td>❌ solo</td><td>❌</td><td>❌ self-approve</td><td>◐ rituals, no ledger</td><td>❌</td><td>❌</td><td>❌</td></tr>
|
|
1143
|
+
<tr><td><strong>Locked multi-repo contract</strong> (hash + CI enforcement)</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>◐ library specs only</td></tr>
|
|
1144
|
+
<tr><td>PR/MR-native reviews (GitHub <em>and</em> GitLab)</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
|
|
1145
|
+
<tr><td>Brownfield (spec what exists, gate changes)</td><td>✅ backfill, human-verified</td><td>◐ document-project</td><td>❌</td><td>◐ steering</td><td>◐</td><td>✅ best-in-class deltas</td><td>❌</td><td>◐</td></tr>
|
|
1146
|
+
<tr><td><strong>Earned automation</strong> (trust log + threshold)</td><td>✅</td><td>❌</td><td>❌</td><td>❌ hooks ≠ earned</td><td>❌ always manual</td><td>❌</td><td>❌ always auto</td><td>❌</td></tr>
|
|
1147
|
+
<tr><td>One-move kill switch</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
|
|
1148
|
+
<tr><td>All state = plain files in git</td><td>✅</td><td>✅</td><td>✅</td><td>◐ IDE-bound</td><td>✅</td><td>✅</td><td>✅</td><td>◐ platform</td></tr>
|
|
1149
|
+
<tr><td>IDE/agent-agnostic</td><td>✅ 4 harnesses</td><td>✅</td><td>✅ 30+</td><td>❌ its own IDE</td><td>✅</td><td>✅</td><td>❌ Claude Code</td><td>✅ MCP</td></tr>
|
|
1150
|
+
<tr><td>Cost / license</td><td>Free, on npm</td><td>Free MIT</td><td>Free MIT</td><td>Freemium → $200/mo</td><td>Free (awslabs)</td><td>Free</td><td>Free</td><td>Commercial</td></tr>
|
|
1151
|
+
<tr><td>Community size (≈ stars)</td><td>tiny (new)</td><td>~46.7k</td><td>~93k</td><td>product (n/a)</td><td>new</td><td>growing</td><td>~61k</td><td>startup</td></tr>
|
|
1152
|
+
</table>
|
|
1153
|
+
<p style="font-size:.85rem; color:var(--muted)">✅ = has it · ◐ = partially / different form · ❌ = doesn’t have it. Star counts and versions as reported by market coverage, May–June 2026.</p>
|
|
1154
|
+
|
|
1155
|
+
<h3>The honest scorecard — where competitors genuinely win</h3>
|
|
1156
|
+
<div class="callout">
|
|
1157
|
+
A deep analysis has to cut both ways. Where the market beats Yadflow today:
|
|
1158
|
+
<ul style="margin:8px 0 0">
|
|
1159
|
+
<li><strong>Ecosystem & trust-by-numbers:</strong> Spec Kit (~93k stars), GSD (~61k), BMAD (~46.7k) have communities, tutorials and hiring familiarity; this repo is effectively a single-maintainer npm package.</li>
|
|
1160
|
+
<li><strong>Product polish:</strong> Kiro is a real IDE with a UI; this workflow is markdown, JSON and CLI output. Teams that buy with their eyes will pick Kiro.</li>
|
|
1161
|
+
<li><strong>Ceremony cost:</strong> GSD and OpenSpec prove many teams want <em>less</em> process. For a 1–2 person project, this workflow’s five gates are overhead, not safety — its own docs effectively say so.</li>
|
|
1162
|
+
<li><strong>Foundation risk:</strong> it inherits BMAD’s youth (v6, parts in alpha — flagged in the repo’s own cautions) and depends on its file conventions surviving upstream changes.</li>
|
|
1163
|
+
<li><strong>No dashboards/analytics:</strong> deliberately (Phase 5 is trigger-gated), but enterprise buyers comparing against Cosmos-class platforms will count it as a gap.</li>
|
|
1164
|
+
</ul>
|
|
1165
|
+
</div>
|
|
1166
|
+
|
|
1167
|
+
<h3>When to choose what — the decision table</h3>
|
|
1168
|
+
<table>
|
|
1169
|
+
<tr><th>Your situation</th><th>Strongest choice</th><th>Why</th></tr>
|
|
1170
|
+
<tr><td>Solo dev, greenfield, speed first</td><td><strong>GSD</strong> or bare Spec Kit</td><td>Minimum ceremony, fastest loop. Governance would be dead weight.</td></tr>
|
|
1171
|
+
<tr><td>Solo dev, big brownfield codebase</td><td><strong>OpenSpec</strong></td><td>Delta specs are the lightest safe way to change existing code alone.</td></tr>
|
|
1172
|
+
<tr><td>Want a polished commercial IDE, AWS shop</td><td><strong>Kiro</strong></td><td>Best UX; specs + hooks out of the box; budget required.</td></tr>
|
|
1173
|
+
<tr><td>One developer driving a full lifecycle with AI roles</td><td><strong>BMAD-METHOD</strong></td><td>The full agent crew without the team machinery.</td></tr>
|
|
1174
|
+
<tr><td><strong>A real team (2+ engineers), multiple repos, production stakes, who must <em>prove</em> who approved what</strong></td><td><strong>Yadflow</strong></td><td>The only file-driven tool with named-human gates, a hash-locked cross-repo contract enforced in CI, PR-native reviews on GitHub <em>and</em> GitLab, and automation that must earn trust and can be killed in one move.</td></tr>
|
|
1175
|
+
<tr><td>Enterprise wanting a managed platform + dashboards</td><td>Augment Cosmos / Azure+GitHub agentic SDLC</td><td>Control-plane governance at platform price — the opposite trade to “plain files in git”.</td></tr>
|
|
1176
|
+
</table>
|
|
1177
|
+
|
|
1178
|
+
<div class="callout green">
|
|
1179
|
+
<strong>Bottom line.</strong> The market is crowded at “help one developer spec and build” and nearly
|
|
1180
|
+
empty at “help a <em>team</em> stay provably in control across <em>several repos</em>”. Yadflow’s
|
|
1181
|
+
three structural moats — the <strong>locked contract with CI enforcement</strong>, the
|
|
1182
|
+
<strong>named-approval file ledger riding real PRs/MRs</strong>, and <strong>earned-with-evidence
|
|
1183
|
+
automation + kill switch</strong> — have no direct equivalent in any tool surveyed. Its real
|
|
1184
|
+
competition is not a feature gap but adoption gravity: the pull of lighter tools (GSD), bigger
|
|
1185
|
+
communities (Spec Kit), and shinier products (Kiro).
|
|
1186
|
+
</div>
|
|
1187
|
+
|
|
1188
|
+
<h3>Sources</h3>
|
|
1189
|
+
<p style="font-size:.85rem">
|
|
1190
|
+
<a href="https://www.marktechpost.com/2026/05/08/9-best-ai-tools-for-spec-driven-development-in-2026-kiro-bmad-gsd-and-more-compare/">MarkTechPost — 9 Best AI Tools for Spec-Driven Development in 2026</a> ·
|
|
1191
|
+
<a href="https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html">martinfowler.com — Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl</a> ·
|
|
1192
|
+
<a href="https://github.com/cameronsjo/spec-compare">spec-compare — research comparing 6 SDD tools</a> ·
|
|
1193
|
+
<a href="https://www.augmentcode.com/tools/best-spec-driven-development-tools">Augment Code — Best Spec-Driven Development Tools</a> ·
|
|
1194
|
+
<a href="https://reenbit.com/bmad-vs-spec-kit-vs-openspec-choosing-your-spec-driven-ai-framework/">Reenbit — BMAD vs Spec Kit vs OpenSpec</a> ·
|
|
1195
|
+
<a href="https://aws.amazon.com/blogs/devops/open-sourcing-adaptive-workflows-for-ai-driven-development-life-cycle-ai-dlc/">AWS — Open-Sourcing AI-DLC Adaptive Workflows</a> ·
|
|
1196
|
+
<a href="https://github.com/awslabs/aidlc-workflows">awslabs/aidlc-workflows</a> ·
|
|
1197
|
+
<a href="https://zenn.dev/kiakiraki/articles/437ba4d9441b2b?locale=en">Zenn — AI-DLC: extreme decision-making via mob work</a> ·
|
|
1198
|
+
<a href="https://medium.com/@richardhightower/agentic-coding-gsd-vs-spec-kit-vs-openspec-vs-taskmaster-ai-where-sdd-tools-diverge-0414dcb97e46">Hightower — GSD vs Spec Kit vs OpenSpec vs Taskmaster</a> ·
|
|
1199
|
+
<a href="https://somniosoftware.com/blog/spec-driven-development-in-practice-github-spec-kit-openspec-and-gsd-compared">Somnio — Spec Kit, OpenSpec and GSD compared</a> ·
|
|
1200
|
+
<a href="https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md">OpenSpec — concepts</a> ·
|
|
1201
|
+
<a href="https://techcommunity.microsoft.com/blog/appsonazureblog/an-ai-led-sdlc-building-an-end-to-end-agentic-software-development-lifecycle-wit/4491896">Microsoft — an end-to-end agentic SDLC on Azure + GitHub</a> ·
|
|
1202
|
+
<a href="https://www.augmentcode.com/guides/ai-sdlc-framework-reference-architecture">Augment Code — AI SDLC reference architecture</a> ·
|
|
1203
|
+
plus this repo’s own <code>RESEARCH-NOTES.md</code> (verified tool facts, 2026-06-04).
|
|
1204
|
+
</p>
|
|
1205
|
+
|
|
1206
|
+
<footer>
|
|
1207
|
+
Generated 2026-06-12 from the project’s own docs: <code>README.md</code>, <code>TEAM-GUIDE.md</code>,
|
|
1208
|
+
and <code>docs/sdlc-workflow-plan.md</code> (incl. §8 “The three project types”).
|
|
1209
|
+
A worked end-to-end example lives in <code>epics/EP-istifta-inquiries/</code>.
|
|
1210
|
+
Renamed <strong>Yadflow</strong> at v2.0.0 — npm package previously <code>@abdelrahmannasr/sdlc-workflow</code>
|
|
1211
|
+
(now deprecated), GitHub repo previously <code>sdlc-workflow</code> (old URLs redirect); both are now
|
|
1212
|
+
<code>yadflow</code>.
|
|
1213
|
+
</footer>
|
|
1214
|
+
</section>
|
|
1215
|
+
|
|
1216
|
+
</div><!-- /wrap -->
|
|
1217
|
+
|
|
1218
|
+
<script>
|
|
1219
|
+
function filterTerms(q) {
|
|
1220
|
+
q = q.trim().toLowerCase();
|
|
1221
|
+
document.querySelectorAll('.term').forEach(function (el) {
|
|
1222
|
+
el.classList.toggle('hidden', q !== '' && el.textContent.toLowerCase().indexOf(q) === -1);
|
|
1223
|
+
});
|
|
1224
|
+
}
|
|
1225
|
+
</script>
|
|
1226
|
+
</body>
|
|
1227
|
+
</html>
|