Yadflow — Terminology & Structure Report

Yadflow (yahd-flow — from يد, Arabic for “hand”) is the AI-driven SDLC where a human hand moves every gate. AI builds. The hand decides.
A plain-language guide to every term used in the project (npm + GitHub: yadflow), plus the full workflow structure with diagrams — including how to run it on a brand-new (greenfield) project, an existing (brownfield) project, and a multi-repo product.

Open the interactive workflow map

1. The big picture — what Yadflow is

Yadflow is a team workflow engine built on top of BMAD (installed from npm as yadflow; the skills are still named sdlc-* and the CLI command is yad). It takes a feature from a raw idea all the way to shipped code, in small steps. Every step does its work, writes its result to a plain file, and then stops and waits at a gate until a human approves. Nothing is hidden in a database — all state is files you can read and edit yourself.

The one-sentence idea: AI does the heavy lifting; humans keep every important decision. Automation is never assumed — it must be earned with evidence, and it can be switched off in one move.

The four repos

You work with four separate git repositories, each with exactly one job:

yadflowthe SKILLS SOURCE — you install the workflow from here and pull updates from here. No product work happens inside it.
➜
product-hubthe THINKING — all epics, contracts, stories, reviews and state live here under epics/EP-<slug>/
⇄
code-repo-1the CODE — real app code + per-story specs under specs/<story-id>/
code-repo-2
code-repo-3
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.
The handoff rule: everything up to and including the locked contract lives in the product hub. Everything from the spec onward (specs, tasks, code) lives in each code repo, with a link back to its story.

The two halves

Front half = decide (the “brain”).
Runs once per epic, in the product hub. Here the team agrees on the epic, the architecture, the locked contract, the UI design, and the stories. Always human-approved — these steps can never auto-advance.
Back half = build.
Runs once per story, per code repo, inside that code repo: spec → implement → check → ship. These are the safe, mechanical steps — they can earn automation over time.

The two dials (set per step)

DialValuesWhat it answers
Assistance none · review · heavy How much does AI help with the work of this step?
Automation human_approve · machine_advance Who moves this step forward — a human or the machine?

Keeping the dials separate lets you say “heavy AI help, but a human must approve” — the exact setting for the design steps. Every step starts at human_approve. The front steps and the final engineer review are locked there permanently.

2. The workflow structure, end to end

Setup is one-time. The front half runs once per epic in the hub; the build half runs once per story per code repo; automation is opt-in and earned. The diagram below is the whole lifecycle.

artifact — an author step writes a file and stops gate — a human review that must pass earns automation — can later auto-advance once proven locked — permanently human milestone
0 · One-time setup (team lead, per project)
Install the modulenpx yadflow setup — copies the 30 skills into your IDE dirs
▼
Wire each repoyad-checks · yad-pr-template · yad-review-comments (CI gates, PR template, comment scaffold)
▼
Connect code reposyad-connect-repos → repos.json + a cached code-map per repo (skip if greenfield)
▼
Connect a design toolyad-connect-design → design.json (Figma-first, pluggable) so yad-ui can materialize the screens (optional — degrades to markdown-only)
▼
Connect a testing toolyad-connect-testing → testing.json (Playwright-first, pluggable) so yad-test-cases can implement the automation (optional — degrades to artifacts-only)
▼
Connect a learning toolyad-connect-learning → learning.json (DeepTutor-first, pluggable) so the learning layer can tutor in context (optional — degrades to harness-native)
▼
Optional: hub on a platformdetect GitHub/GitLab + reviewer roster, so reviews run on real PRs/MRs
▼
A · Front half — product hub · human-gated · once per epic
yad-analysis (optional)pressure-test the idea with the analyst → analysis.md
▼
gate · analysis review
▼
yad-epicwrite epic.md · assigns the EP-<slug> ID · seeds state
▼
gate · epic reviewbase rule: owner + 1 reviewer
▼
yad-architecturearchitecture.md + the locked contract.md (hash-locked)
▼
gate · architecture reviewescalated: base rule + a domain owner for every repo in the epic
▼
yad-uiui-design.md + DESIGN.md + the screens in the connected design tool (design-links.json)
▼
gate · UI reviewbase rule
▼
yad-storiesrepo-tagged stories → stories/EP-<slug>-S0N.md
▼
gate · stories reviewper-repo: base rule + the engineer of each touched repo
▼
ready-for-buildthe gating front half is done — building can start (and yad-test-cases opens in parallel)
▼
yad-test-cases (parallel · non-blocking)opens when the stories gate passes and runs alongside the build half — with the test architect → test-cases.md + the automation tests in the connected testing tool (test-links.json) → its own base-rule review. Never blocks ready-for-build.
▼
B · Build half — per story, per code repo
yad-specSpec Kit ceremony (specify → clarify → plan → analyze → checklist → tasks) → specs/<story-id>/
▼
yad-implement1 atomic task = 1 branch = 1 commit (small diff, ≤3 files) — earns automation
▼
yad-checksCI gates: spec-link · contract-check · build/test/lint · verified-commits — earns automation
▼
Open PR/MRfrom the wired template; risk routing picks the required reviewers
▼
yad-engineer-review: AI reviewCodeRabbit first pass — advisory only, never the authority
▼
Engineer reviewa human reads the diff against the spec — never automated
▼
merge → recorded in build-log.jsonstory status: in-build → shipped
▼
C · Automation — earned & reversible (optional)
yad-rundrives the back half on each step’s automation dial, recording every run in trust-log.json
▼
Kill switchyad-run action: kill → everything back to human_approve instantly
yad-status is a read-only view over all of it · yad-hub-bridge mirrors front-half reviews to real PRs/MRs.

Where every file lives

One rule: shared thinking lives in the product hub; building lives in each code repo; a link connects them.

product-hub/
  epics/EP-<slug>/
    analysis.md          (optional) the discovery brief
    epic.md              the feature, agreed
    architecture.md      how it will be built
    contract.md          the LOCKED shared surface (APIs, events, data model)
    ui-design.md         + DESIGN.md (+ the screens in the connected design tool)
    stories/             one file per story (EP-<slug>-S01.md …)
    test-cases.md        the test cases (+ the automation tests when a testing tool is connected)
    reviews/             reviewer comments, per artifact
    .sdlc/               state.json · approvals.json · contract-lock.json
                         design-links.json · test-links.json · build-state/ · trust-log.json · build-log.json

each code repo/
  specs/<story-id>/      spec, plan, tasks (+ link.md back to the story)
  + the real code, branches and PRs

3. The review gate — the same loop, everywhere

Every review in the workflow is the same loop, run by yad-review-gate. Commenting never advances anything. Only an explicit advance (file-only mode) or the merge of an approved, fully-resolved review PR (platform mode) moves the step forward — and only when the approval rule is met.

author writes
the artifact
➜
openshow it / raise the review PR
➜
commentreviewers leave notes ↺ owner addresses, edits in place
➜
approvename + role recorded
➜
advance?rule met · threads resolved · (PR merged)
➜
next step
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.

Who approves what (the gate rules)

ReviewRuleWho must approve
Analysis / Epic / UIBaseowner + 1 reviewer
Architecture + contractEscalatedowner + 1 reviewer + a domain owner for every repo in the epic. The contract surface is hash-locked; changing it invalidates approvals.
StoriesPer-repoowner + 1 reviewer + the engineer for each repo any story touches
Engineer review at shipLockeda human engineer — always, never automated
Escalation triggers: anything touching the shared contract, auth, or payments needs the relevant domain owners — both at the front-half gates and via risk routing on build-half PRs.

4. Terminology glossary — every term, in plain language

Type to filter. Each term is tagged by area: core files & artifacts gates & review build half automation tools people & roles

Core concepts

SDLCcore
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.
State machinecore
The core design: the workflow is a fixed set of states (steps). Each state does its work and waits at a gate. The states never change — only the trigger (who moves work forward) changes. That is what lets the team start fully manual and automate gradually without rebuilding anything.
Product hub (product repo)core
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.
Code repocore
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.
Skills source (this repo)core
The yadflow repo itself — where the 30 skills live and where you pull updates from. No real product work happens inside it.
Front half (“decide” / the brain)core
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, ending at ready-for-build. Test cases is a parallel, non-blocking track that opens at the stories gate and runs alongside the build half. Permanently human-approved.
Back half / build half (“build”)core
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.
Gatecore
A stopping point after a step. The step writes its output and waits; a human must approve before the workflow moves on. “Every step stops at a gate” is the heart of the whole system.
Assistance dialcore
A per-step setting for how much AI helps with the work: none, review (AI checks human work), or heavy (AI does the drafting, human directs).
Automation dialcore
A per-step setting for who advances the step: human_approve (default — a person clicks/records the approval) or machine_advance (the orchestrator moves on by itself). Front steps and the engineer review can never be set to machine_advance.
End-first automationcore
The rule for which 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.
Epiccore
One feature, described well: the problem, the goal, the scope. The unit the front half works on. Gets a stable ID like EP-istifta-inquiries.
Story (user story)core
A slice of an epic small enough to build and review on its own. Each story is repo-tagged — it lists which code repos must implement it (e.g. repos: [backend, mobile]). ID: EP-<slug>-S01.
Atomic taskcore
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: EP-<slug>-S01-T03.
Handoff rulecore
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.
Code-aware (the brain reads the code)core
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.

Files & artifacts

Artifactfiles
The file an author step produces (e.g. epic.md, contract.md). An author step writes its artifact, marks itself done, and stops at its review gate.
analysis.mdfiles
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.
epic.mdfiles
The agreed description of the feature. Authoring it assigns the epic’s EP-<slug> ID and seeds the epic’s state files.
architecture.mdfiles
How the feature will be built technically: stack, components, data flow.
Contract / contract.mdfiles
The locked shared surface between repos: API shapes, events, and the data model that backend, mobile and dashboard all obey. There is exactly one contract per epic, kept in the hub; code repos quote it, never re-invent it.
Contract surfacefiles
The specific block inside contract.md (between CONTRACT-SURFACE:BEGIN/END markers) that is hashed and locked. Changing anything in it is a “contract change”.
Contract lock / contract-lock.jsonfiles
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.
ui-design.md + DESIGN.mdfiles
The UI artifacts: the design decisions for this epic plus the reusable design language, authored with the ux-designer (driving Impeccable when installed).
stories/files
One markdown file per story (EP-<slug>-S0N.md), each tagged with the repos that must implement it.
File ledgergates
The set of state files that is the single source of truth for reviews: approvals.json, comments.json, reviews/*.md. Platform PRs feed into the ledger; the ledger always wins.
state.jsonfiles
The epic’s state machine on disk: every step, its two dials, its status, and currentStep (where the epic is right now).
approvals.jsonfiles
Who approved which review, with name + role. The gate reads this to decide whether the rule is met.
repos.jsonfiles
The project-wide registry of connected code repos (path/URL, platform, domain owner, freshness sha).
hub.jsonfiles
The hub’s platform record (GitHub or GitLab) plus the reviewer roster, used to run front-half reviews on real PRs/MRs.
Rosterroles
The mapping from each person’s GitHub/GitLab login + commit email to their SDLC name and a per-scope roles map (roles: { hub: […], <repo>: […] }). One person can be owner, reviewer and domain owner at once; one repo can have several people per role. Logins are validated against GitHub/GitLab at setup (warn-only). When a PR/MR is opened, the committer becomes the assignee and the scope’s reviewers + domain owners are auto-requested.
Code-mapfiles
A lightweight, AI-readable summary of a connected code repo — its existing endpoints, events, data models and modules — cached under .sdlc/code-context/ so the front-half steps don’t contradict code that already exists.
Repomix packtools
A compressed, secret-scanned snapshot of a repo’s code produced by the Repomix tool (npx repomix), cached alongside the code-map so AI can read the codebase.
Fresh / stalefiles
A connected repo’s cached picture is fresh if the repo hasn’t moved since it was packed (tracked by HEAD sha) and stale if it has. Refreshing is a deliberate human decision (yad repo refresh) — skills warn about staleness but never silently re-pack.
code-context: frontmatterfiles
A stamp each front-half artifact carries recording exactly which repo code-maps (and at which sha) it read while being authored.
build-log.jsonfiles
The record of every ship: which task, which PR, which merge commit — keeping the epic → story → task → PR chain traceable both ways.
build-state/<story>.jsonautomation
Per story: the back-half steps with their automation dials and statuses, per repo. What yad-run reads to know whether to advance or stop.
ready-for-buildcore
The milestone state an epic reaches when all front gates have passed. From here, stories can enter the build half.
in-build / shippedbuild
A story’s lifecycle status during and after the build half: in-build once its first task merges, shipped when the story is fully delivered.

Gates & review

Review gate (yad-review-gate)gates
The one reusable team review loop used by every front-half review: open → comment → approve → advance. Commenting never advances; advance moves forward only when the approval rule is met — otherwise it names exactly who is still missing.
Base rulegates
The default approval requirement: the artifact’s owner + 1 reviewer. Used for the analysis, epic and UI reviews.
Escalated rulegates
Base rule plus 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.
Per-repo rulegates
Base rule plus the engineer (domain owner) of each repo that any story touches. Used for the stories review.
Ownerroles
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.
Reviewerroles
A team member who reads, challenges and comments on an artifact, and records an approval when satisfied.
Domain ownerroles
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.
File-only gategates
The gate run purely on files (no platform): reviewers comment in reviews/…--comments.md, approvals land in approvals.json, and an explicit advance moves the step. The mode everything degrades to when there is no GitHub/GitLab or no CLI.
PR-driven gategates
When the hub is on a platform: each artifact’s review rides a real PR/MR. Reviewers approve/comment there; yad gate sync maps that state into the file ledger, and the step auto-advances on merge once the rule is met and every comment thread is resolved. The merge click is the human approval act.
Hub bridge (yad-hub-bridge)gates
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 gh/glab recipes for syncing approvals and comments back.
Event-driven gate syncgates
A CI workflow on the hub that runs yad gate ci automatically on every approval, change request and merge of a review PR — so the ledger updates itself without anyone running sync by hand. CI never approves and never merges; the human keeps the merge click.
Approval revocation (re-hash)gates
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.
Review-comment scaffoldgates
Committed comment templates (REVIEW_COMMENTS.md / GitLab comment templates) so reviewers leave structured, attributable feedback — each canned comment carries a **name (role)** header that maps cleanly into the file ledger.
Risk tags / risk routinggates
Labels (contract, auth, payments) 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 (risk-route.sh prints them).
Impact & Risk blockgates
A section in the wired PR/MR template where the author declares the risk level and touched surfaces — the input the risk routing reads.

Build half

Spec Kit ceremonybuild
The heavy specification pass run once per story per repo by yad-spec: specify → clarify → plan → analyze → checklist → tasks, writing specs/<story-id>/ in the code repo. It quotes the locked contract; it never widens it.
link.mdbuild
The pointer file written into specs/<story-id>/ that links the spec back to its story in the product hub — the thread that keeps the two repos connected.
Spec-link checkbuild
CI gate #1: every code change must link to a real story/spec via the Task: trailer in its commit. No orphan changes.
Contract-checkbuild
CI gate #2: a diff that changes the contract surface without declaring Contract-Change: yes and an updated, re-locked contract fails — routing the change back up to the architecture gate. This is how the contract stays honest.
Build/test/lint gatebuild
CI gate #3: the ordinary safety net — the project must build, its tests must pass, lint must be clean.
Verified-commits gatebuild
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.
Commit-message gatebuild
CI gate #5: every commit subject must follow Conventional Commits (<type>: …, no trailing period) and its trailers must be ordered Task → Contract-Change → Co-Authored-By. Profile-aware (code|hub).
PR-title gatebuild
CI gate #6: the PR/MR title must follow the convention — a Conventional-Commits subject on code repos, a review: <artifact> (EP-<slug>) title on the hub.
PR-template gatebuild
CI gate #7: the PR/MR body must actually use the committed template (its required sections present + the risk field filled), so the review and routing have their inputs. Profile-aware (code|hub).
Task: trailerbuild
A line at the end of every commit message naming the story + task it implements (e.g. Task: EP-istifta-inquiries-S01-T03). What the spec-link check verifies.
Contract-Change: yes trailerbuild
A commit trailer added only when the diff deliberately touches the locked contract surface — paired with an updated, re-locked contract, or the contract-check fails.
Conventional Commitsbuild
The commit/PR title convention used everywhere: feat: …, fix: … (lowercase after the type). Merged feat:/fix: commits also drive automated releases of the CLI itself.
Co-Authored-By AI trailerbuild
An optional per-commit trailer crediting the AI tool that helped (claude / copilot / cursor / coderabbit). The human author always owns the commit.
Scope guard / scope overrunbuild
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.
AI review (advisory)build
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.
Engineer reviewbuild
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. Permanently human — never automated.
Backfill (yad-backfill)build
For existing/legacy code: pack one feature with Repomix, have AI draft a spec of what exists (“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.
Draft / unverified specbuild
A backfilled spec before a human has approved it. It describes existing behaviour but doesn’t yet count as real for gating purposes.
Do-not-touch zonesbuild
Parts of an existing codebase marked off-limits to AI changes — part of the setup when adopting the workflow on a brownfield project.

Automation & trust

Orchestrator (yad-run)automation
The engine that drives a story’s back half (spec → tasks → implement → checks) reading each step’s automation dial: on machine_advance it advances alone; on human_approve it stops; on any failure, scope overrun, or contract-surface touch it halts and pulls in a human. It always stops at the engineer review.
Earned automationautomation
The principle that no step is automated by promise — only by evidence. A step may be flipped to machine_advance only after its trust record clears the threshold, and the flip is refused otherwise.
Trust log (trust-log.json)automation
The evidence base: every orchestrated run’s verdict is recorded here. This is what justifies (or blocks) flipping a step’s dial.
Trust thresholdautomation
The bar a step must clear to earn automation — by default at least 5 runs with ≥80% “approved-unchanged” (configurable in config.yaml).
Run verdictsautomation
How each engineer review scores an automated run: approved-unchanged (merged exactly as authored — the strongest signal), approved-with-edits (a human fixed it first), rejected (failed).
Kill switchautomation
yad-run action: kill — one move that forces every step system-wide back to human_approve instantly, no code change needed. unkill restores earned automation. Automation is always reversible in one move.
Locked stepsautomation
The steps that may never be set to machine_advance: all five front authoring steps, their reviews, and the engineer review. A front state advances only on a human act.
Fleet roll-upautomation
The cross-epic summary yad-status prints: where every epic stands, which steps are “earned but still manual” (nudge cost), at a glance.

Tools the workflow builds on

BMAD (BMAD-METHOD)tools
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 module that turns it from a solo tool into a team, gated, multi-repo tool.
Spec Kittools
GitHub’s spec-driven development toolkit. Its commands (/speckit.specify, clarify, plan, analyze, checklist, tasks) 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.
Repomixtools
A tool (npx repomix) 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.
Impeccabletools
A UI-design tool driven via slash-commands: document (read the current UI into a design file), extract (save reusable pieces), craft (make new designs that match). Used by the UI step when installed; the step authors directly otherwise.
CodeRabbittools
An AI code-review service used as the advisory first pass on PRs. Optional; never the merge authority.
Graceful degradationtools
The rule that every optional tool (Spec Kit, Impeccable, Repomix, CodeRabbit) can be absent: the workflow falls back to doing the work directly and records that the tool was missing. You can start with none of them.
Tool-agnostic ruletools
Talk to every tool through its commands and files, never through its internal code — so each tool stays swappable.
Skilltools
One of the 30 named agents (e.g. yad-epic) you invoke by name in your AI IDE. Each skill does one step’s work, writes files, and stops at its gate.
The yad CLItools
A zero-dependency command-line tool (npm: yadflow) that installs, wires and reconciles the workflow (setup, check --fix, update) and runs the deterministic pieces (gate, commit, open-pr, repo).

People & AI roles

analyst (“Mary”)roles
The BMAD AI role for research, brainstorming and shaping the raw idea — drives the optional analysis step.
pm (“John”)roles
The product-manager AI role — writes the epic and breaks it into stories.
architect (“Winston”)roles
The technical AI role — authors the architecture and the contract.
ux-designerroles
The UI/UX AI role — drives the UI design step (with Impeccable when installed).
sm / Scrum Master (“Bob”)roles
The AI role that prepares each story in detail for development and sets up the sprint context.
devroles
The developer AI role — writes the code for one atomic task in the implement step.
tea / Test Architectroles
The AI role that sets up and runs tests at the check gates.

IDs & naming (immutable once assigned)

ThingFormatExample
Epic IDEP-<slug>EP-istifta-inquiries
Story IDEP-<slug>-S0NEP-istifta-inquiries-S01
Task IDEP-<slug>-S0N-T0NEP-istifta-inquiries-S01-T03
Branchfeat/<story-id>-<task-id>-<slug>feat/EP-istifta-inquiries-S01-T01-create-inquiry
Commit trailerTask: <story-id>-<task-id>+ Contract-Change: yes only when the locked surface is touched
Renaming an ID breaks every downstream link — IDs are immutable once assigned.

5. Project types — greenfield, brownfield, and multi-repo

The same workflow runs for every project type — only the one-time setup differs. The design doc defines three project types; multi-repo is an orthogonal option that works with any of them.

Type 1 — Greenfield (new project, full AI)

What it means: a brand-new project with no existing code. Specs are written from the very start, so there is never undocumented behaviour to protect.

Setup differences: the lightest path — no backfill, and you simply skip yad-connect-repos until code exists (the brain proceeds without code-maps; the steps are explicitly “greenfield-safe”). For UI, run Impeccable’s craft first to create the design, then extract to seed the design language.

Setupinstall skills · create the hub repo · create empty code repos · wire each repo (CI gates + PR template) · connect-repos skipped — nothing to map yet
▼
Front half(analysis) → epic → architecture + contract → UI (craft → extract) → stories — all human-gated; then test cases runs in parallel with the build half
▼
Build halfspec → implement → checks → PR → ship, per story per repo — specs exist for 100% of the code from day one
▼
Later: connect the repos once they have real code, so future epics become code-aware

Type 2 — Brownfield, already using AI

What it means: an existing codebase where the team already works with AI tools. The code is real and live; the risk is new work silently breaking what exists.

Setup differences: connect every repo (yad-connect-repos) so the brain reads what is already built; add the spec-link check so every change links to a story; and mark the “do-not-touch” zones AI must not modify. Run yad-backfill before a new feature touches an old one. For UI, run Impeccable’s document first (read the current UI), then extract, then craft new designs that match.

Setupinstall skills · wire each repo · connect every repo → cached Repomix pack + code-map · mark do-not-touch zones · enable spec-link
▼
Front half — code-awareeach author step loads the code-maps: the epic references existing behaviour, the architecture cross-checks the contract against real endpoints before locking it, UI reuses existing components (document → extract → craft), stories anchor to real modules
▼
Touching an old, unspecced feature?run yad-backfill first: Repomix-pack that one feature → AI drafts a “describe what exists” spec → DRAFT until a human approves → only then may changes touch it
▼
Build halfsame as always — spec → implement → checks (incl. contract-check) → PR → ship

Type 3 — Brownfield, no AI yet

What it means: an existing codebase and a team adopting AI for the first time. Trust must be built before AI touches anything important.

Setup differences: same wiring as Type 2, but start AI on safe tasks only — tests, docs, refactors — with every dial at human_approve. Run the backfill step before any new feature touches old code. Let automation be earned slowly through the trust log, exactly as the end-first rule prescribes.

Setupinstall skills · wire + connect repos · everything at human_approve · AI assistance limited to safe tasks (tests, docs, refactors)
▼
Backfill firstbefore new features touch old code, produce human-verified specs for the features they touch
▼
Front + build halves, fully manual gatesthe team learns the rhythm: author → gate → approve, with heavy AI assistance but zero AI advancement
▼
Earn automation step by stepafter months of evidence in trust-log.json, flip checks first, then implement — end-first, never the front
▼
Kill switch always availableyad-run action: kill — back to fully manual in one move

Option for all types — Multi-repo stories

A story tagged repos: [backend, mobile] simply runs the build half in each repo independently — but every repo builds from the same one locked contract in the hub. The contract-check blocks a surface bypass in either repo, so the repos can never drift apart.

ONE locked contract.mdin the product hub — hash-locked at the architecture gate
▼
backend repospec → implement → checks → PR → ship
mobile repospec → implement → checks → PR → ship
dashboard repospec → implement → checks → PR → ship
▼
contract-check in every repoany diff that touches the contract surface without a re-locked contract FAILS → back to the architecture gate
Independent pipelines, one shared truth.

Cheat sheet — what changes per project type

Aspect Greenfield (new, full AI) Brownfield + AI already Brownfield, no AI yet
Connect repos / code-mapsSkip until code existsYes — connect everythingYes — connect everything
Backfill (yad-backfill)Never neededBefore touching unspecced featuresBefore any new feature touches old code
Spec-link checkOn from day oneAdd it + mark do-not-touch zonesAdd with the rest of the wiring
Impeccable order (UI)craft → extractdocument → extract → craftdocument → extract → craft
AI scope at startFull (specs from the start)Full, minus do-not-touch zonesSafe tasks only (tests, docs, refactors)
Automation paceIdentical for all: every dial starts human_approve; back steps earn machine_advance via the trust log; front steps + engineer review locked human forever.

6. The 30 skills — what each does, how to use it, and when

A skill is an agent you invoke by name in your AI IDE — you just ask in plain words, e.g. “run yad-epic”, adding any inputs the skill needs (repo: backend, story: EP-…-S01, action: wire, …). Every skill writes plain files and then stops at its gate — none of them advances the workflow on its own. The quick table is below; full “what / how / when” cards follow.

SkillHalfOne line
yad-connect-reposSetupRegister a code repo with the hub + cache its code-map.
yad-sync-reposSetupSwitch every connected repo to its default branch + fast-forward from origin.
yad-connect-designSetupConnect a design tool (Figma-first) so yad-ui can materialize the screens.
yad-connect-testingSetupConnect a testing tool (Playwright-first) so yad-test-cases can implement the automation.
yad-analysisFront(Optional) pressure-test an idea into analysis.md.
yad-epicFrontStart a feature: write epic.md, assign the ID.
yad-architectureFrontAuthor architecture.md + the locked contract.md.
yad-uiFrontAuthor ui-design.md + DESIGN.md; materialize the screens in the connected design tool.
yad-storiesFrontBreak the epic into repo-tagged stories.
yad-test-casesFrontWith the test architect, author the test cases; implement the automation when a testing tool is connected.
yad-review-gateCross-cuttingReview / comment / approve / advance any gate.
yad-hub-bridgeCross-cuttingRun front-half reviews over real PRs/MRs and sync them back.
yad-review-commentsSetupInstall the structured review-comment scaffolds.
yad-specBuild ASpec one ready story in one repo (Spec Kit ceremony).
yad-implementBuild BImplement one atomic task as a small branch.
yad-checksBuild CWire / run the CI gates.
yad-pr-templateBuild DInstall the PR/MR template + risk routing.
yad-commitBuild helperCommit one staged atomic change by the conventions.
yad-open-prBuild helperOpen a code-repo task PR/MR from the committed template.
yad-shipBuild helperCommit and open the task PR/MR in one step.
yad-engineer-reviewBuild EAI review → engineer review → merge + record.
yad-backfillBuild GSpec already-built / legacy code before changing it.
yad-runAutomationDrive the back half on the dials; set dials; kill switch.
yad-statusAnytimeRead-only view: where everything is and what’s blocking.

Setup & code-awareness

yad-connect-repos

What Introduces your code repos to the product hub so the “brain” knows what is already built. It registers each repo in repos.json 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.
How Run it in the product hub, once per repo:
yad-connect-repos action: connect repo: backend path: ../backend-repo domain_owners: carol,dave
yad-connect-repos action: list                 # see every repo as fresh / stale
yad-connect-repos action: refresh repo: backend  # re-pack after the code moved
yad-connect-repos action: disconnect repo: backend
yad-connect-repos action: detect-hub           # record the hub's GitHub/GitLab platform
yad roster add alice-gh --name alice --email alice@x.com --roles "hub=owner,reviewer"  # reviewer roster, any time (validated vs the hub)
yad roster grant carol backend domain-owner    # per-repo role; keeps repos.json domain_owners in sync
When During one-time setup, and again any time you add a new code repo. Re-run refresh when a skill warns a repo is stale. Greenfield with no code yet? Skip it entirely — the brain proceeds without it.

yad-sync-repos

What Brings every connected repo up to date in one shot: switches each repo in repos.json to its default branch and fast-forwards it from origin (your own git credentials — no tokens stored). The default branch is the registry’s default_branch when set, otherwise it falls back to origin/HEAD and then main — so default_branch is not mandatory. A repo with no remote still switches branches (no fetch). A working-tree-only maintenance op — never a gate and it never writes the registry. A repo with uncommitted changes is skipped and reported, never overwritten; a diverged branch is left for you to resolve (fast-forward only).
How Run it in the product hub before starting work:
yad repo sync            # switch every connected repo to its default branch + ff pull
yad repo sync backend    # just one repo
When Before you start a new epic or task, to make sure no one is implementing on a stale or wrong branch. After it pulls, a repo’s cached code-map goes stale — it points you at yad repo refresh to re-pack.

yad-connect-design

What Connects a design tool to the product hub so the UI step can materialize the actual feature design — mobile screens / web pages — inside it, alongside the Markdown. Figma-first but pluggable (a design-tool adapter; pencil is a second provider). It records the tool + project/file references in design.json through your own authenticated MCP session — no tokens are ever stored — and degrades to markdown-only when no design-tool MCP is available.
How Run it in the product hub, once per project:
yad-connect-design action: connect tool: figma project_url: https://figma.com/files/project/…
yad-connect-design action: list                  # show the connection + whether the MCP is available
yad-connect-design action: refresh               # re-detect the MCP (after authenticating a session)
yad-connect-design action: disconnect
When During one-time setup (the wizard records it), and again any time you switch design tools. No design tool? Skip it — yad-ui simply authors the Markdown, exactly as before.

yad-connect-testing

What Connects a testing tool to the product hub so the test-cases step can implement the actual automation tests inside it, alongside the Markdown. Playwright-first but pluggable (a testing-tool adapter; cypress and pytest are second providers). It records the tool + project/suite references in testing.json through your own authenticated MCP session — no tokens are ever stored — and degrades to artifacts-only when no testing-tool MCP is available.
How Run it in the product hub, once per project:
yad-connect-testing action: connect tool: playwright project_url: tests/playwright.config.ts
yad-connect-testing action: list                 # show the connection + whether the MCP is available
yad-connect-testing action: refresh              # re-detect the MCP (after authenticating a session)
yad-connect-testing action: disconnect
When During one-time setup (the wizard records it), and again any time you switch testing tools. No testing tool? Skip it — yad-test-cases simply authors the test cases, exactly as before.

yad-connect-learning

What Connects a learning/tutoring tool to the product hub so the cross-cutting learning layer can tutor any team member, at any stage, in the context of what's being built. DeepTutor-first but pluggable. Unlike the design/testing tools, DeepTutor is a CLI subprocess (like Repomix's npx) — it ships no MCP — so this skill detects the deeptutor binary on PATH and optionally builds a project knowledge base from the SDLC artifacts + secret-scanned code-maps. It records the connection in learning.json — no tokens are ever stored — and degrades to harness-native tutoring when DeepTutor isn't installed.
How Run it in the product hub, once per project:
yad-connect-learning action: connect tool: deeptutor
yad-connect-learning action: list                # show the connection + whether the CLI is available
yad-connect-learning action: refresh             # re-detect the CLI + rebuild the knowledge base
yad-connect-learning action: disconnect
When During one-time setup (the wizard records it), and again any time you switch learning tools. No DeepTutor? Skip it — yad-learn still tutors using the harness model reading your artifacts.

The learning layer — tutor any member, any stage (cross-cutting)

yad-learn

What The learning layer. At any SDLC stage a team member can ask to learn a concept and be tutored in the context of what the team is building — e.g. "teach me why the architecture hash-locks the contract surface." It routes to the connected learning tool (DeepTutor, grounded in the project knowledge base) or degrades to harness-native tutoring, renders a tutorial artifact, and appends to a per-member learning ledger kept local-only (gitignored — never committed or pushed, to the hub or any code repo) so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — it never blocks a gate and never touches epic state, approvals, or the contract lock.
How Any time, from any stage:
run yad-learn — concept: "contract versioning" epic: EP-istifta-inquiries stage: architecture-review
yad-learn action: list                           # your local skills-log records for this epic
yad-learn action: complete concept: "contract versioning"   # mark it learned
When Whenever a member wants to understand what is being built — to review a gate with confidence, onboard onto a domain, or grow a skill. It is additive and reversible: learning never gates the work.

Front half — author the thinking (in the product hub)

yad-analysis (optional)

What 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 analysis.md. It assigns the epic’s EP-<slug> ID and seeds the state files.
How In the product hub, just describe the idea:
run yad-analysis — idea: "let users submit religious inquiries and track answers"
When Before the epic, when the idea is still fuzzy and deserves its own gated discovery round. Skip it freely — the epic step does the same shaping inline.

yad-epic

What Writes the feature down properly: problem, goal, scope, the repos it will touch → epic.md. The analyst shapes the idea, the pm writes the epic. If analysis didn’t run, this is the entry point: it assigns the EP-<slug> ID and seeds .sdlc/ state. If repos are connected, it reads their code-maps so the epic references what already exists.
How In the product hub:
run yad-epic — feature: "inquiry submission and tracking"
When The start of every new feature (or right after the analysis gate passes). It ends by stopping at the epic review gate.

yad-architecture

What With the architect AI, decides how the feature is built (architecture.md) and writes the locked contract (contract.md) — the one shared surface (APIs, events, data model) every repo must obey. It hash-locks the contract surface into contract-lock.json. Code-aware: it cross-checks the surface against existing endpoints before locking.
How In the product hub, after the epic gate passes:
run yad-architecture — epic: EP-istifta-inquiries
When Right after the epic review is approved. Stops at the architecture review gate, which is always escalated (domain owners of every repo must approve).

yad-ui

What With the ux-designer AI, authors the UI design for the epic: ui-design.md (this feature’s screens and flows) + DESIGN.md (the reusable design language). Drives Impeccable’s document / extract / craft commands when installed; writes the files directly when not (and records that). When a design tool is connected (yad-connect-design), it also materializes the screens in that tool — generating them from the spec or linking an existing design — and records the screen→frame map in design-links.json; otherwise it stays markdown-only.
How In the product hub, after the architecture gate passes:
run yad-ui — epic: EP-istifta-inquiries
When After architecture, before stories. Skip-able only if the epic genuinely has no UI. Stops at the UI review gate (base rule).

yad-stories

What With the pm AI, slices the approved epic into user stories small enough to build — one file each under stories/, with stable IDs (EP-<slug>-S01…) and a repos: tag naming which code repos must implement each one. Reads epic + architecture + contract + UI as input.
How In the product hub, after the UI gate passes:
run yad-stories — epic: EP-istifta-inquiries
When After the UI gate passes. Stops at the stories review gate (per-repo rule). When it passes the epic is ready-for-build — the build half can start, and yad-test-cases opens in parallel.

yad-test-cases

What With the test architect AI (Murat), authors the risk-based test cases that cover the approved stories → test-cases.md (cases prioritised P0–P3, with story→case traceability). When a testing tool is connected (yad-connect-testing), it also implements the automation tests in that tool — generating them into the connected code repo(s) or linking an existing suite — and records the case→test map in test-links.json; otherwise it stays artifacts-only. Reads epic + architecture + contract + UI + stories as input.
How In the product hub, after the stories gate passes:
run yad-test-cases — epic: EP-istifta-inquiries
When A parallel, non-blocking track: it opens the moment the stories gate passes — the epic is already ready-for-build, so this runs alongside the build half, not before it. Stops at its own test-cases review gate (base rule); that review never blocks building.

The review gate & its plumbing (cross-cutting)

yad-review-gate

What The one reusable team review loop used by every 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 only when the rule is met.
How In the product hub, one action at a time:
yad-review-gate epic: EP-istifta-inquiries artifact: epic.md action: open      # present it for review
yad-review-gate … action: comment    # record a reviewer's notes (never advances)
yad-review-gate … action: approve    # record an approval (name + role)
yad-review-gate … action: sync       # pull approvals/comments from the hub review PR
yad-review-gate … action: advance    # move on — only if the rule is met, else it names who's missing
When After every author step — the artifact is written and waiting. Use open → comment → approve → advance for the file-only gate; add sync when the hub is on a platform and reviewers worked on the PR.

yad-hub-bridge

What 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 gh/glab recipes that pull platform approvals and comments back into the files. The file ledger always stays the source of truth.
How Mostly invoked for you by the gate (its open/sync). You call it directly once, to wire the event-driven sync CI:
yad-hub-bridge action: wire    # hub CI runs `yad gate ci` on every approve / request-changes / merge
When Once during setup (step “wire the hub”), if you want front-half reviews to ride real PRs/MRs. No platform or no gh/glab? Everything degrades to the file-only gate with no error — you never need this skill.

yad-review-comments

What Installs ready-made review-comment templates into a repo (a committed REVIEW_COMMENTS.md on GitHub / comment templates on GitLab), so reviewers leave structured, attributable feedback — each comment carries a **name (role)** header that maps cleanly into the file ledger.
How Once per repo (and once for the hub):
yad-review-comments repo: backend action: wire
yad-review-comments repo: hub action: wire
When During one-time setup, together with the other wiring. Re-running is a harmless no-op.

Build half — turn stories into shipped code (in a code repo)

yad-spec — Build Step A

What Runs the heavy Spec Kit ceremony once for one story in one repo — specify → clarify → plan → analyze → checklist → tasks — writing specs/<story-id>/ inside the code repo plus a link.md back to the story. It quotes the locked contract; it never widens it. Drives /speckit.* when installed, authors the same files by hand when not.
How From the code repo (or naming it):
yad-spec story: EP-istifta-inquiries-S01 repo: backend
When The first build step for every ready-for-build story — once per repo the story is tagged with. The tasks it produces feed yad-implement.

yad-implement — Build Step B

What With the dev AI, implements one atomic task from the story’s tasks.md as a small diff (≤3 files) on its own branch: one task = one branch = one commit = one PR. 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, Task: trailer, optional AI co-author, Contract-Change: yes only if the locked surface is touched).
How Once per task, repeating until the story’s tasks are done:
yad-implement story: EP-istifta-inquiries-S01 repo: backend task: T01
# then commit + open the PR with the CLI:
yad commit --type feat -m "create inquiry endpoint" --ai claude
yad open-pr --repo backend
When After the story is spec’d. Run it once per task ID (T01, T02, …). It hands off to the check gates — never merges anything itself.

yad-checks — Build Step C

What The production-safety CI gates: spec-link (every non-maintenance commit links a real story/spec, checked per commit; ci/chore/build/test commits are exempt), contract-check (a contract-surface diff without a re-locked contract FAILS), build/test/lint, verified-commits (signed commits from roster-known authors), and the pattern gates — commit-message (Conventional subject + trailer order), pr-title, and pr-template (the PR/MR body uses the template). The pattern gates are profile-aware (code|hub), so they run on code repos and the product hub. wire installs them into the repo’s CI (merging with any existing CI, never clobbering); run executes them right now, locally.
How
yad-checks repo: backend action: wire   # once, during setup
yad-checks repo: backend action: run    # before opening each PR
yad-checks repo: hub action: wire       # hub-flavored gates for the product hub
When wire once per repo at setup; run after implementing, before the PR — the same gates also run automatically in CI on every PR and must pass before merge.

yad-pr-template — Build Step D

What Detects the repo’s platform and commits the matching PR/MR template, which carries an Impact & Risk block. A high risk level — or a touched contract/auth/payments surface — routes the review to the domain owners. route reads a PR body and prints exactly who must review it. It also ships the pr-title.sh / pr-template.sh gate scripts that yad-checks runs.
How
yad-pr-template repo: backend action: wire    # once, during setup
yad-pr-template repo: backend action: route   # who must review this PR?
yad-pr-template repo: hub action: wire        # the hub's front-half review template
When wire once per repo (and the hub) at setup; route whenever you’ve opened a PR and want the required reviewer list.

yad-commit — Build helper

What Commits one staged atomic change by the conventions: a Conventional-Commits subject, the fixed trailer block (Task → Contract-Change → Co-Authored-By), and a ≤3-file atomic guard. The human git author owns the commit; an assisting AI is recorded only as a Co-Authored-By footer chosen per-commit with --ai (default none, human-only).
How From the repo holding the staged change:
yad commit --type feat -m "add the inquiry endpoint" --ai claude
yad commit --type fix -m "handle null user" --dry-run   # preview only
When Any time you have a staged atomic change to commit by the rules — on a code repo or the hub.

yad-open-pr — Build helper

What Opens a code-repo task PR/MR from the committed platform template: detects GitHub/GitLab, pushes the task branch, and creates the PR/MR with the body prefilled and the title defaulting to the commit subject. Auto-assigns from the hub roster — assignee = the committer, reviewers = the repo’s reviewers + domain-owners. It never merges.
How On the task branch:
yad open-pr --repo backend --risk low
When After committing a task, to raise its PR/MR for the check gates + engineer review.

yad-ship — Build helper

What Does the two routine build-half hand-actions for one task in one step: commit by convention, then open the task PR/MR. A thin wrapper over yad-commit then yad-open-pr — the PR step runs only if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). It never merges.
How On the task branch, with the change staged:
yad ship --type feat -m "add the inquiry endpoint" --ai claude --repo backend --risk low
When The common case — turn an implemented, staged task into a reviewable PR/MR in one command.

yad-engineer-review — Build Step E

What The last mile of a task’s PR: ai-review triggers the advisory AI pass (CodeRabbit — a second set of eyes, never the authority); approve records the human engineer approval (owner + 1 reviewer, same escalation); ship merges and records the ship in build-log.json, moving the story to in-build → shipped so the epic → story → task → PR chain stays traceable.
How Against the task’s PR, in order:
yad-engineer-review story: EP-istifta-inquiries-S01 task: T01 repo: backend action: ai-review
yad-engineer-review … action: approve     # the human engineer's approval
yad-engineer-review … action: ship        # merge + record in build-log.json
When Once a task’s PR is open and the check gates are green. The engineer approval here is permanently human — no dial can ever automate it.

yad-backfill — Build Step G

What Writes specs for code that was built before the workflow existed, so new work doesn’t break it. It packs one feature at a time with Repomix (secret-scanned), has AI draft a “describe what exists, do not invent” spec marked DRAFT/unverified, 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.
How
yad-backfill repo: backend feature: health   # globs e.g. src/health/**
When Brownfield projects, before a new story touches an old, unspecced feature. Never needed on greenfield.

Automation & status

yad-run

What The orchestrator that makes automation real. It walks a story’s back half (spec → tasks → implement → checks) reading each step’s automation dial: machine_advance → it proceeds alone; human_approve → it stops for you. Any failure, scope overrun, or contract-surface touch halts and pulls in a human, 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.
How
yad-run story: EP-istifta-inquiries-S02 repo: backend        # drive the back half on the dials
yad-run action: set-dial step: checks to: machine_advance    # earn automation (needs trust evidence)
yad-run action: set-dial step: checks to: human_approve      # revert — always allowed
yad-run action: kill      # everything back to human, system-wide, instantly
yad-run action: unkill    # restore earned automation
When 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 kill the moment anything feels wrong.

yad-status

What A read-only 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.
How
yad-status                          # everything, across epics (fleet view)
yad-status EP-istifta-inquiries     # one epic in detail
When 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.

7. All CLI commands — what each does, how to use it, and when

The yad CLI is the deterministic half of the system — the skills think, the CLI does the predictable file-and-platform work. It’s published to npm as yadflow; run it from your product hub repo with npx — no clone needed, nothing to install globally.

Install & keep in sync

npx yadflow setup

What The guided first-run wizard. Ten steps: preflight (git/node check), install all 30 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, connect a design tool (Figma-first; optional), connect a testing tool (Playwright-first; optional), connect a learning tool (DeepTutor-first; optional), connect your code repos, wire each one (CI gates, PR template, comment scaffold), optionally write the AI-review config, and stamp the installed version.
How
cd <product-hub-repo>
npx yadflow setup
When 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.

… check  /  … check --fix  /  … update

What The health check and repair tools. check is read-only: it reports what is missing (never installed), outdated/drifted (the workflow shipped a newer version), or stale (a repo’s cached code picture is behind its code). check --fix reconciles all of it — filling gaps and applying updates while touching nothing that is already correct. update applies drift only (an alias for check --fix --scope=changed).
How
npx yadflow check        # just tell me — read-only
npx yadflow check --fix  # and fix it
npx yadflow update       # apply updates only
When After any workflow update (a new version on npm), after a BMAD update, or whenever something seems off. Safe to run any time — check changes nothing.

… --version

What Prints the installed CLI version.
How npx yadflow --version
When Checking whether you’re behind, or reporting a bug.

The front-half review gate (yad gate …)

yad gate open <epic> <artifact>

What 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 in_review.
How
yad gate open EP-istifta-inquiries epic.md
When Right after an author step finishes, when the hub is on a platform. (No platform? Use the yad-review-gate skill file-only instead.)

yad gate sync <epic> [artifact]

What Pulls the review PR’s approvals and comment threads into the file ledger (approvals.json, comments.json, reviews/*.md) using your own gh/glab login — and auto-advances the step 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.
How
yad gate sync EP-istifta-inquiries            # all open reviews of the epic
yad gate sync EP-istifta-inquiries epic.md    # just this one
When After reviewers acted on the platform. Usually you don’t run it at all — with the gate-sync CI wired, every approval / change request / merge triggers it automatically; this stays valid as the manual fallback.

yad gate comments <epic> [artifact]

What Fetches the unresolved review comment threads so the artifact owner can address them. (You reply on the PR; the reviewer resolves their own thread.)
How yad gate comments EP-istifta-inquiries
When A gate is stuck in_review and you want the to-do list of open feedback.

yad gate status <epic>

What Shows each review step and its recorded approvals — counting only the non-stale ones.
How yad gate status EP-istifta-inquiries
When Quick check of “who has approved what, and who is still missing” on the front half.

yad gate ci [--branch <head>] [--pr <n>]

What The entry point the hub’s CI calls on review events: it derives the epic/artifact from the review/EP-* branch, runs the same sync, and commits only the ledger files to the hub’s default branch. With no --branch it sweeps every open review PR. CI never approves and never merges — the merge click stays human.
How You don’t run it by hand — the wired workflow (yad-gate-sync.yml) calls it on every approve / request-changes / merge.
When Automatically, once the hub bridge is wired. Good to know it exists when reading the hub’s CI logs.

Build-half helpers

yad commit --type <t> -m <subject>

What Commits by the SDLC convention so you never hand-build a trailer: it forms the Conventional subject (feat: …), derives the Task: trailer from your branch name, optionally appends an AI Co-Authored-By:, adds Contract-Change: yes only when you say so, and refuses a non-atomic stage (changes outside the task’s declared files).
How From the task branch in a code repo:
yad commit --type feat -m "create inquiry endpoint" --ai claude
yad commit --type fix  -m "handle empty answer" --contract-change   # only if the locked surface moved
yad commit --type feat -m "…" --dry-run                             # preview without committing
When Every commit during yad-implement. Flags: --type, -m/--message, --task, --ai claude|copilot|cursor|coderabbit|none, --contract-change, --dry-run, --force (bypass the atomic guard — use sparingly).

yad open-pr [--repo <name>] [--risk <level>]

What Pushes the task branch and opens the code-repo PR/MR pre-filled from the wired template — story/task links and the Impact & Risk block included. Aborts cleanly if the branch push fails.
How
yad open-pr --repo backend
yad open-pr --repo backend --risk high            # routes review to the domain owners
yad open-pr --repo backend --contract-change      # declares a locked-surface change
When After the task is committed and yad-checks action: run is green — one PR per atomic task.

Connected-repo freshness

yad repo list  /  yad repo refresh [name]

What list shows every connected code repo as fresh (the cached code-map still matches the code) or stale (the repo has moved since it was packed). refresh deliberately re-packs a stale one. Staleness is a human decision — skills warn and point here; they never silently re-pack.
How
yad repo list
yad repo refresh backend
When list any time you wonder how current the brain’s picture is; refresh when a front-half step flags a stale repo before authoring against it.

Reviewer roster

yad roster list | add | grant | revoke | remove

What Manages the reviewer roster in hub.json (platform login → SDLC name + per-scope roles) any time, not just during yad setup. add upserts a member then walks each connected repo asking for their role; grant/revoke set one directly. A domain-owner grant keeps repos.json domain_owners in sync, and list flags any drift between the two.
How
yad roster list
yad roster add carol-gh --name carol --email carol@x.com --roles "hub=reviewer backend=domain-owner"
yad roster grant carol backend domain-owner       # one per-repo role; syncs repos.json
yad roster revoke carol backend domain-owner
yad roster remove carol-gh
When Setting up reviewers, onboarding a new team member, or fixing who owns a repo — without re-running the whole setup wizard.

Global flags

FlagMeaning
--dir <path>Target a project other than the current directory.
--forceRe-copy unchanged files during install, or bypass the commit atomic guard.
Skill or CLI? Rule of thumb: skills for anything that needs thinking (authoring, specs, implementing, reviews-as-conversation); the CLI for anything deterministic (installing, wiring, committing by convention, opening PRs, syncing platform state). They write to the same files, so you can mix freely.

8. Competitor analysis — who else does this, and how close they get

Yadflow sits in the spec-driven / AI-governed development market. The honest headline first: as of mid-2026, no single tool on the market offers the exact same package — a team-gated, file-driven SDLC with a hash-locked multi-repo contract and evidence-based (“earned”) automation. But many tools cover slices of it, several with far bigger communities, and one (AWS AI-DLC) shares almost the same philosophy. This section maps them honestly. (Market facts checked via web research on 2026-06-12; sources at the end.)

How to read the market — the five pillars

Yadflow is really five capabilities in one. Each competitor below is strong in one or two pillars and absent in the rest:

PillarWhat it meansWho else has it
1 · Spec-driven authoringWrite the thinking (spec/plan/tasks) before code.Almost everyone — Spec Kit, Kiro, BMAD, OpenSpec, GSD, Tessl.
2 · Team review gatesNamed humans must approve each step; rules + escalation.AI-DLC (rituals, not records) · enterprise platforms (policies). Rare elsewhere — most tools are solo.
3 · Multi-repo contractOne locked cross-repo surface that CI enforces.Essentially nobody. The clearest differentiator.
4 · Brownfield supportSpec what already exists before changing it.OpenSpec (delta specs) · Kiro (steering files) · Repomix-style packers.
5 · Earned, reversible automationAutomation unlocked by recorded evidence; kill switch.Essentially nobody — others are either always-manual or always-auto.

Positioning map

solo developer  →  team governance
team · spec slice
Tessl spec registry for teams CodeRabbit review slice only
team · whole lifecycle
Yadflow AWS AI-DLC methodology Augment Cosmos / MS agentic SDLC enterprise platforms
solo · spec slice
GitHub Spec Kit OpenSpec brownfield deltas
solo · whole lifecycle
BMAD-METHOD Kiro (AWS IDE) GSD Agent OS · Taskmaster
covers the spec phase only  →  covers the whole lifecycle (idea → ship)
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.

The competitors, one by one

BMAD-METHOD the base — and the nearest “sibling”

What The open-source (MIT) framework Yadflow is built on: 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.
Overlap 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.
Gaps vs this BMAD is fundamentally a solo tool: one person drives it, gates are AI-checked quality gates, not named-human 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 team tool” — is precisely what this repo exists to add.

AWS AI-DLC (aidlc-workflows) closest in philosophy

What Amazon’s open-source methodology for AI-driven development: adaptive workflow “steering rules” for coding agents. Epics become Units of Work, sprints become Bolts (hours/days), and every phase transition needs explicit human approval — 10–26 verification points per bolt, with team rituals (“Mob Elaboration”, “Mob Construction”) where the team validates AI proposals in real time.
Overlap 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.
Gaps vs this AI-DLC’s gates are rituals, not records — 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 earned), no multi-repo locked contract, no CI enforcement of spec-links, and no brownfield backfill mechanism. It tells you how to behave; Yadflow gives you machinery that enforces it.

GitHub Spec Kit most adopted — and a component here

What GitHub’s spec-driven toolkit (≈93,000+ stars, v0.8.7, 30+ supported agents): specify → clarify → plan → tasks → analyze → checklist → implement slash-commands plus a project “constitution”. Free, open source.
Overlap Total — by design: Yadflow drives Spec Kit as its build-half Step A rather than competing with it. The spec ceremony is literally the same commands.
Gaps vs this Spec Kit covers one pillar only: it specs a feature in one repo for one developer. 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.

Kiro (AWS) the polished product

What Amazon’s agentic IDE (Code OSS base, launched July 2025) built around specs: every feature gets requirements.md (EARS syntax) → design.md → tasks.md, plus automated hooks and steering files. Free tier; Pro $20 / Pro+ $40 / Power $200 per month.
Overlap 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.
Gaps vs this 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.

OpenSpec strongest at brownfield

What A lightweight open-source framework for spec-driven change on existing codebases: specs/ records current behaviour, each change is a self-contained package with delta specs (“what’s changing”), through a Propose → Validate → Apply → Archive state machine.
Overlap Its specs-for-what-exists idea parallels yad-backfill, and its change-isolation parallels the one-task-one-branch discipline. Reviewers in the market consistently rank it the best pure brownfield tool.
Gaps vs this 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 lighter 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.

GSD (“Get Stuff Done”) the speed play

What 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.
Overlap 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 against heavy process.
Gaps vs this 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.

Tessl the spec-as-source bet

What A language-agnostic “agent enablement” platform: installs as tiles in .tessl/, teaches any MCP-compatible agent a spec-driven workflow, and runs a Spec Registry of 10,000+ library specs to stop API hallucinations. Exploring “spec-as-source” — specs literally generating the code.
Overlap Shares the locked-truth instinct: its registry specs play a similar role to the locked contract — an agreed surface agents must not re-invent.
Gaps vs this Its locked truth is about third-party libraries, not your team’s cross-repo API. 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.

Agent OS & Taskmaster AI workflow plumbing

What 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.
Overlap Both formalize “plan → tasks → execute” like the build half, and Agent OS shares the works-in-any-IDE stance.
Gaps vs this 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 team stay in control?”.

Enterprise platforms (Augment Cosmos, Microsoft’s agentic SDLC on Azure/GitHub) the from-above threat

What Platform-level offerings where agents run on shared context with telemetry, replayable sessions, and human-in-the-loop policies across the SDLC; Microsoft publishes a reference end-to-end agentic SDLC on Azure + GitHub.
Overlap 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.
Gaps vs this Heavy, vendor-bound, and platform-priced; governance lives in their 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).

Adjacent, not competing: CodeRabbit, Graphite, Greptile the review slice

What AI code-review services that comment on PRs. They cover exactly one box of the build half — the advisory AI review.
Overlap None to defend: Yadflow already uses CodeRabbit as its advisory pass and treats it as never-the-authority.
Gaps vs this They review diffs; they don’t govern a lifecycle. Complementary by design.

Head-to-head capability matrix

CapabilityYadflowBMADSpec KitKiroAI-DLCOpenSpecGSDTessl
Spec-driven authoring✅ (drives Spec Kit)✅✅✅✅✅ deltas✅ light✅
Full lifecycle (idea → ship)✅✅❌ spec only✅ in-IDE✅❌ change only✅ thin❌
Named-human team gates (rules + escalation + ledger)✅❌ solo❌❌ self-approve◐ rituals, no ledger❌❌❌
Locked multi-repo contract (hash + CI enforcement)✅❌❌❌❌❌❌◐ library specs only
PR/MR-native reviews (GitHub and GitLab)✅❌❌❌❌❌❌❌
Brownfield (spec what exists, gate changes)✅ backfill, human-verified◐ document-project❌◐ steering◐✅ best-in-class deltas❌◐
Earned automation (trust log + threshold)✅❌❌❌ hooks ≠ earned❌ always manual❌❌ always auto❌
One-move kill switch✅❌❌❌❌❌❌❌
All state = plain files in git✅✅✅◐ IDE-bound✅✅✅◐ platform
IDE/agent-agnostic✅ 4 harnesses✅✅ 30+❌ its own IDE✅✅❌ Claude Code✅ MCP
Cost / licenseFree, on npmFree MITFree MITFreemium → $200/moFree (awslabs)FreeFreeCommercial
Community size (≈ stars)tiny (new)~46.7k~93kproduct (n/a)newgrowing~61kstartup

✅ = has it · ◐ = partially / different form · ❌ = doesn’t have it. Star counts and versions as reported by market coverage, May–June 2026.

The honest scorecard — where competitors genuinely win

A deep analysis has to cut both ways. Where the market beats Yadflow today:
  • Ecosystem & trust-by-numbers: Spec Kit (~93k stars), GSD (~61k), BMAD (~46.7k) have communities, tutorials and hiring familiarity; this repo is effectively a single-maintainer npm package.
  • Product polish: 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.
  • Ceremony cost: GSD and OpenSpec prove many teams want less process. For a 1–2 person project, this workflow’s five gates are overhead, not safety — its own docs effectively say so.
  • Foundation risk: 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.
  • No dashboards/analytics: deliberately (Phase 5 is trigger-gated), but enterprise buyers comparing against Cosmos-class platforms will count it as a gap.

When to choose what — the decision table

Your situationStrongest choiceWhy
Solo dev, greenfield, speed firstGSD or bare Spec KitMinimum ceremony, fastest loop. Governance would be dead weight.
Solo dev, big brownfield codebaseOpenSpecDelta specs are the lightest safe way to change existing code alone.
Want a polished commercial IDE, AWS shopKiroBest UX; specs + hooks out of the box; budget required.
One developer driving a full lifecycle with AI rolesBMAD-METHODThe full agent crew without the team machinery.
A real team (2+ engineers), multiple repos, production stakes, who must prove who approved whatYadflowThe only file-driven tool with named-human gates, a hash-locked cross-repo contract enforced in CI, PR-native reviews on GitHub and GitLab, and automation that must earn trust and can be killed in one move.
Enterprise wanting a managed platform + dashboardsAugment Cosmos / Azure+GitHub agentic SDLCControl-plane governance at platform price — the opposite trade to “plain files in git”.
Bottom line. The market is crowded at “help one developer spec and build” and nearly empty at “help a team stay provably in control across several repos”. Yadflow’s three structural moats — the locked contract with CI enforcement, the named-approval file ledger riding real PRs/MRs, and earned-with-evidence automation + kill switch — have no direct equivalent in any tool surveyed. Its real competition is not a feature gap but adoption gravity: the pull of lighter tools (GSD), bigger communities (Spec Kit), and shinier products (Kiro).

Sources

MarkTechPost — 9 Best AI Tools for Spec-Driven Development in 2026 · martinfowler.com — Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl · spec-compare — research comparing 6 SDD tools · Augment Code — Best Spec-Driven Development Tools · Reenbit — BMAD vs Spec Kit vs OpenSpec · AWS — Open-Sourcing AI-DLC Adaptive Workflows · awslabs/aidlc-workflows · Zenn — AI-DLC: extreme decision-making via mob work · Hightower — GSD vs Spec Kit vs OpenSpec vs Taskmaster · Somnio — Spec Kit, OpenSpec and GSD compared · OpenSpec — concepts · Microsoft — an end-to-end agentic SDLC on Azure + GitHub · Augment Code — AI SDLC reference architecture · plus this repo’s own RESEARCH-NOTES.md (verified tool facts, 2026-06-04).