yadflow 4.6.0 → 4.8.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 +259 -0
- package/README.md +46 -4
- package/bin/commands.mjs +9 -2
- package/bin/yad.mjs +309 -30
- package/cli/agent-guard.mjs +511 -0
- package/cli/agent-guide.mjs +83 -0
- package/cli/agent-rules.mjs +381 -0
- package/cli/argv-flags.mjs +7 -0
- package/cli/artifact-status.mjs +88 -20
- package/cli/build.mjs +1372 -0
- package/cli/checkpoint.mjs +2 -2
- package/cli/ci-check.mjs +492 -0
- package/cli/commit.mjs +1 -0
- package/cli/dial.mjs +21 -1
- package/cli/docs.mjs +7 -2
- package/cli/doctor.mjs +176 -33
- package/cli/epic-state.mjs +360 -12
- package/cli/errors.mjs +3 -0
- package/cli/find-product.mjs +36 -2
- package/cli/fold.mjs +9 -5
- package/cli/gate-local.mjs +9 -1
- package/cli/gate.mjs +364 -22
- package/cli/guide.mjs +549 -0
- package/cli/history.mjs +22 -2
- package/cli/hook.mjs +35 -4
- package/cli/index-command.mjs +2 -2
- package/cli/ledger.mjs +60 -0
- package/cli/lib.mjs +46 -0
- package/cli/lifecycle/defaults/2.json +124 -0
- package/cli/lifecycle/lifecycle.schema.json +5 -2
- package/cli/lifecycle.mjs +16 -3
- package/cli/manifest.mjs +75 -0
- package/cli/marked-block.mjs +48 -0
- package/cli/members.mjs +19 -5
- package/cli/migrate.mjs +17 -19
- package/cli/next.mjs +35 -12
- package/cli/openpr.mjs +81 -5
- package/cli/plan.mjs +326 -22
- package/cli/platform.mjs +21 -0
- package/cli/pr-list.mjs +5 -3
- package/cli/product-index.mjs +6 -3
- package/cli/product-token.mjs +186 -0
- package/cli/productcommit.mjs +33 -0
- package/cli/protection.mjs +50 -0
- package/cli/recommend.mjs +3 -1
- package/cli/reconcile.mjs +187 -26
- package/cli/repo-publish.mjs +2 -2
- package/cli/report.mjs +62 -14
- package/cli/run-checks.mjs +586 -0
- package/cli/setup.mjs +244 -25
- package/cli/ship-drift.mjs +49 -18
- package/cli/signing.mjs +377 -0
- package/cli/standup.mjs +1 -1
- package/cli/status.mjs +282 -0
- package/cli/test-agents-file.mjs +993 -0
- package/cli/test-build.mjs +1559 -0
- package/cli/test-ci-check.mjs +616 -0
- package/cli/test-guide.mjs +1267 -0
- package/cli/test-node.mjs +129 -0
- package/cli/test-run-checks.mjs +603 -0
- package/cli/test-setup-agent.mjs +352 -0
- package/cli/test-signing.mjs +524 -0
- package/cli/test-worktree.mjs +520 -0
- package/cli/thread.mjs +4 -0
- package/cli/tidy.mjs +2 -2
- package/cli/toolbox.mjs +37 -6
- package/cli/update-commit.mjs +313 -11
- package/cli/workspace.mjs +38 -10
- package/cli/worktree-record.mjs +53 -0
- package/cli/worktree.mjs +379 -0
- package/package.json +6 -4
- package/skills/sdlc/config.yaml +5 -5
- package/skills/sdlc/module-help.csv +2 -1
- package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
- package/skills/yad-change/SKILL.md +5 -1
- package/skills/yad-checks/SKILL.md +61 -12
- package/skills/yad-checks/references/check-gates.md +78 -14
- package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
- package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
- package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
- package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
- package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
- package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
- package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
- package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
- package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
- package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
- package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
- package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
- package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
- package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
- package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
- package/skills/yad-commit/SKILL.md +8 -5
- package/skills/yad-connect-repos/SKILL.md +5 -3
- package/skills/yad-connect-repos/references/code-context.md +2 -1
- package/skills/yad-connect-repos/references/repos-registry.md +2 -1
- package/skills/yad-docs/templates/app/package-lock.json +395 -106
- package/skills/yad-docs/templates/app/package.json +2 -2
- package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
- package/skills/yad-engineer-review/SKILL.md +55 -25
- package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
- package/skills/yad-epic/SKILL.md +2 -1
- package/skills/yad-epic/references/state-schema.md +76 -17
- package/skills/yad-guide/SKILL.md +192 -0
- package/skills/yad-implement/SKILL.md +75 -13
- package/skills/yad-implement/references/implement-conventions.md +8 -1
- package/skills/yad-implement/templates/.gitmessage +3 -0
- package/skills/yad-open-pr/SKILL.md +21 -0
- package/skills/yad-pair-review/SKILL.md +14 -5
- package/skills/yad-pr-template/SKILL.md +6 -2
- package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
- package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
- package/skills/yad-product-bridge/SKILL.md +44 -12
- package/skills/yad-product-bridge/references/bridge.md +11 -5
- package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
- package/skills/yad-reconcile/SKILL.md +9 -3
- package/skills/yad-report/SKILL.md +15 -0
- package/skills/yad-review-companion/SKILL.md +5 -3
- package/skills/yad-review-gate/SKILL.md +16 -8
- package/skills/yad-review-gate/references/gating.md +26 -1
- package/skills/yad-run/SKILL.md +61 -33
- package/skills/yad-run/references/run-loop.md +44 -22
- package/skills/yad-spec/SKILL.md +137 -16
- package/skills/yad-spec/references/spec-handoff.md +50 -3
- package/skills/yad-status/SKILL.md +7 -0
- package/skills/yad-stories/references/story-schema.md +1 -1
- package/skills/yad-sync-repos/SKILL.md +2 -1
- package/skills/yad-ui/SKILL.md +2 -2
|
@@ -17,7 +17,7 @@ spec → tasks → implement → checks → engineer-review(locked)
|
|
|
17
17
|
project's setting in `.sdlc/skills.json` — for every epic, or for one route only — so the loop reads
|
|
18
18
|
`yad skill list --epic <epic> --json` (that epic's route, E51) once at Step 0 and
|
|
19
19
|
runs every entry of that step's `skills`, in order, when it is bound to more than one. Unbound: `spec` and `tasks` are the two legs of `yad-spec` (the heavy ceremony, then the atomic
|
|
20
|
-
`tasks.md`), `implement` is one atomic task via `yad-implement`, and `checks` is
|
|
20
|
+
`tasks.md`, or the tasks block of a light `spec.md`, #348), `implement` is one atomic task via `yad-implement`, and `checks` is
|
|
21
21
|
`yad-checks (action: run)`. `engineer-review` is the human gate at `yad-engineer-review` — always a
|
|
22
22
|
stop, never automated, and bindable like any other step.
|
|
23
23
|
|
|
@@ -25,44 +25,61 @@ stop, never automated, and bindable like any other step.
|
|
|
25
25
|
|
|
26
26
|
```
|
|
27
27
|
cfg = config.yaml.automation
|
|
28
|
-
bs = build-state/<story>.json.repos[<repo>] #
|
|
29
|
-
#
|
|
30
|
-
#
|
|
28
|
+
bs = build-state/<story>.json.repos[<repo>] # absent: `yad build start <story> --repo <repo>` seeds it
|
|
29
|
+
# from the defaults (it never touches another repo's
|
|
30
|
+
# entry). Never write this file by hand (#346).
|
|
31
31
|
if bs.status == "skipped": # E39: the whole lane was set aside with
|
|
32
32
|
STOP — report bs.record.reason # `yad skip <epic> <story> --repo <repo>`; do not drive it.
|
|
33
33
|
# `yad unskip <epic> <story> --repo <repo>` puts it back.
|
|
34
34
|
# Never write a single Build step as skipped or deferred.
|
|
35
|
-
step = from or bs.currentStep
|
|
35
|
+
step = from or bs.currentStep # from: the lane's current step only
|
|
36
|
+
if task and bs.currentStep == "engineer-review" and task has no close on implement:
|
|
37
|
+
yad build step <story> --repo <repo> implement in_progress --task <task> # reopens implement and checks
|
|
38
|
+
step = "implement" # for the next task
|
|
36
39
|
|
|
37
40
|
while step is a Build step (not engineer-review):
|
|
38
41
|
result = run_step_skill(step) # the skill(s) `yad next --json` names for this lane
|
|
42
|
+
# (yad-spec moves spec/tasks to in_progress itself,
|
|
43
|
+
# which pins Spec Kit's feature folder — #348)
|
|
44
|
+
|
|
45
|
+
if result stopped to ask human-only questions — its first batch or a later one (#357) —
|
|
46
|
+
and did NOT hit its contract STOP (a contract item is the contract-touch HALT below):
|
|
47
|
+
# the output is not finished (a draft spec.md is not output), so no trust entry — only the halt
|
|
48
|
+
yad build step <story> --repo <repo> <step> blocked [--task <T>] --reason "waiting on human decisions: <the questions, short>"
|
|
49
|
+
checkpoint; STOP and report the questions
|
|
39
50
|
|
|
40
51
|
signals = derive_signals(step, result) # see "Deriving signals"
|
|
41
52
|
verdict = derive_verdict(signals) # rejected | approved-with-edits | approved-unchanged
|
|
42
|
-
uid =
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
# `automation` is recorded in the OLD vocabulary (this is a history record, and `yad migrate`
|
|
46
|
-
# deliberately leaves it alone). Read the step's dial from EITHER spelling.
|
|
47
|
-
= { story, repo, step, uid, automation: bs.step.automation ?? old_name_for(bs.step.advance), verdict, signals, ranBy, date }
|
|
53
|
+
uid = `yad build trust <story> --repo <repo> <step> --verdict <verdict> --signal <name>=<value> …
|
|
54
|
+
--ran-by <machine|human> {--task <T>} --json`.uid # writes ONE shard, trust-log/<story>-<repo>-<step>-<uid>.json,
|
|
55
|
+
# with a fresh uid and the dial in force; never by hand
|
|
48
56
|
|
|
49
57
|
eff = effective_dial(step, bs, cfg) # see "Effective dial"
|
|
50
58
|
|
|
51
59
|
if result is a HALT (failed / scope overrun / contract touch / ambiguous):
|
|
52
60
|
# `blocked` needs its `record` (E38) — that is what separates a halted lane from one that has
|
|
53
61
|
# simply not started. `reason` is the halt cause you already have in hand.
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>" }
|
|
57
|
-
persist; checkpoint; STOP and report the human action needed
|
|
62
|
+
yad build step <story> --repo <repo> <step> blocked [--task <T>] --reason "<check FAIL | scope overrun | contract touch | ambiguous>"
|
|
63
|
+
checkpoint; STOP and report the human action needed
|
|
58
64
|
elif eff == "auto":
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
advance bs.currentStep to next; persist; checkpoint; continue # Step B advance
|
|
65
|
+
yad build step <story> --repo <repo> <step> done --via auto --run <uid> {--task <T>} # the closing record; currentStep moves on
|
|
66
|
+
checkpoint; if step == checks: OPEN_PR; continue # Step B advance
|
|
62
67
|
else: # "human"
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
68
|
+
yad build step <story> --repo <repo> <step> done --run <uid> {--task <T>}
|
|
69
|
+
checkpoint; if step == checks: OPEN_PR; STOP and report "waiting for human at <next>"
|
|
70
|
+
|
|
71
|
+
# OPEN_PR — checks closed for a task, by either dial: open its PR/MR (#356)
|
|
72
|
+
if `yad dial open-pr --json`.advance == "auto":
|
|
73
|
+
yad open-pr --via auto # from the task branch; refuses unless the checks step is closed now
|
|
74
|
+
# and each task the commits carry (a group, #350) has its newest
|
|
75
|
+
# close (--task above) with a run that passed and was not rejected;
|
|
76
|
+
# records `opened` on the lane, once per task
|
|
77
|
+
else:
|
|
78
|
+
STOP and ask the person to approve opening it; then `yad open-pr`
|
|
79
|
+
|
|
80
|
+
# {--task <T>}: REQUIRED on the implement and checks legs, left out on spec and tasks. <T> is the `task`
|
|
81
|
+
# input, else the task `yad-implement` worked on. Without it the checks close names no task, and
|
|
82
|
+
# `yad open-pr --via auto` refuses it.
|
|
66
83
|
|
|
67
84
|
# reached engineer-review: always stop, hand to yad-engineer-review (human gate, finalizes the verdict)
|
|
68
85
|
```
|
|
@@ -78,7 +95,8 @@ Write it only when you write `done`, and never over a `closed` already on the st
|
|
|
78
95
|
nudge; otherwise `human`. Persist build-state after every transition so a halt leaves an accurate,
|
|
79
96
|
resumable record.
|
|
80
97
|
|
|
81
|
-
`checkpoint` = run `yad checkpoint --push` from `{project-root}
|
|
98
|
+
`checkpoint` = ask the person, then run `yad checkpoint --push` from `{project-root}` (it pushes to the default
|
|
99
|
+
branch, which an agent asks about every time, E158). It commits the machine-written
|
|
82
100
|
Build ledgers (in this loop, the loose `trust-log/` shards this run wrote + `build-state/<story>.json`;
|
|
83
101
|
also the `build-log/` shards at engineer-review) — the shard dirs are what checkpoint stages, the same
|
|
84
102
|
way `git gc` folds loose objects later (`yad tidy up` folds finished shards into the folded
|
|
@@ -156,6 +174,10 @@ Reverting (`--to human`) and the kill switch are always one move.
|
|
|
156
174
|
## What stays human, always
|
|
157
175
|
|
|
158
176
|
- `engineer-review` — the merge gate. `yad-run` always stops here and hands to `yad-engineer-review`.
|
|
177
|
+
Opening a task's PR/MR asks a person too, unless the project gave a standing approval with
|
|
178
|
+
`yad dial open-pr --to auto` (#356) — the kill switch holds it at human.
|
|
179
|
+
The merge stays a person's; whether it happened is asked of the platform with
|
|
180
|
+
`yad build merged <story> --task <T> --repo <r> --ship` (#355) — never waited for in chat.
|
|
159
181
|
- The Shape steps — this loop never drives them. A Shape author step's dial may be set to auto for the
|
|
160
182
|
project (`yad dial <step> --to auto`), and is only recorded until the engine runs agents (E26); every
|
|
161
183
|
Shape review gate is a person.
|
package/skills/yad-spec/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: yad-spec
|
|
3
|
-
description: 'Build Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
|
|
3
|
+
description: 'Build Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. For a small story with no contract surface, offers a light spec (one spec.md with the plan and tasks) that a human confirms (#348). Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# SDLC — Author Spec (Build Step A)
|
|
@@ -43,7 +43,7 @@ Tell the person which tools you used and which fallbacks, and why.
|
|
|
43
43
|
|
|
44
44
|
- **Spec Kit** (`spec-kit`). Use it when its entry has `used: true` and `status.state` is `installed` or `available`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (`yad toolbox remove spec-kit`) — use the fallback.
|
|
45
45
|
- Fallback — yad-spec writes the same spec files by hand, in Spec Kit's layout.
|
|
46
|
-
- Record `speckit: not-installed`. It means the tool was not used, whatever the reason.
|
|
46
|
+
- Record `speckit: not-installed`. It means the tool was not used, whatever the reason — except a light spec, which never runs Spec Kit and records `speckit: not-used` (#348).
|
|
47
47
|
|
|
48
48
|
<!-- end: When a tool is missing -->
|
|
49
49
|
|
|
@@ -68,6 +68,45 @@ Tell the person which tools you used and which fallbacks, and why.
|
|
|
68
68
|
- `repo` — one entry from that story's `repos` (the ONE repo to spec; ask if the story lists more
|
|
69
69
|
than one).
|
|
70
70
|
|
|
71
|
+
## Ask the human-only questions first, in one batch
|
|
72
|
+
|
|
73
|
+
<!-- The same section is in yad-spec and yad-implement: a test holds the two copies equal (#357). -->
|
|
74
|
+
|
|
75
|
+
Some decisions belong to the human alone. If one turns up late, the long work stops and waits for it.
|
|
76
|
+
So before the long work starts, list every such decision together with every open question, and ask
|
|
77
|
+
them all in **one** message.
|
|
78
|
+
|
|
79
|
+
**Human-only decisions** — never decide these yourself, and never pick a default just to keep going:
|
|
80
|
+
- **Security trade-offs.** Who may call or see what, what data is stored, logged or shown, how
|
|
81
|
+
people sign in, and any check made weaker on purpose.
|
|
82
|
+
- **Secrets and tokens.** Which secret or token the work needs, who creates it, where it is kept,
|
|
83
|
+
and what it may access.
|
|
84
|
+
- **Contract changes.** The work needs the shared cross-repo surface (the locked `contract.md`) to
|
|
85
|
+
change. Nobody decides this here, and no answer lets the step go on: it goes back to the
|
|
86
|
+
architecture gate, or, on a short lane, to a new epic on `classic`. Name it in the batch so the
|
|
87
|
+
person learns it now, not halfway through. Then end the step with this skill's own contract STOP
|
|
88
|
+
(`yad-spec` Step 3, `yad-implement` Step 5), and its `contract touch` halt under `yad-run`.
|
|
89
|
+
- **Changes that cannot be undone.** Deleting data, or a data migration with no way back.
|
|
90
|
+
|
|
91
|
+
**How to ask:**
|
|
92
|
+
1. Number each item. For each one, say what must be decided, why only a human can decide it, and the
|
|
93
|
+
options, with your recommendation where a safe one exists.
|
|
94
|
+
2. Wait for the answers, then record them where the step below says, so no later step asks again.
|
|
95
|
+
`yad-implement` first reads the answers `yad-spec` recorded in `spec.md`, and asks only what is
|
|
96
|
+
still open.
|
|
97
|
+
3. If nothing is open, say "no human-only decisions or open questions" and go on.
|
|
98
|
+
4. If a new one still turns up later, stop, collect any others that are open at that point, and ask
|
|
99
|
+
them together. In the report, say the first batch missed it.
|
|
100
|
+
5. **Run by the orchestrator (`yad-run`):** a stop to ask — the first batch or a later one — is its
|
|
101
|
+
own halt, **waiting on human decisions**. Run `yad build step <story> --repo <repo> <step> blocked
|
|
102
|
+
--reason "waiting on human decisions: <the questions, short>"` (add `--task <task>` on the
|
|
103
|
+
implement leg). Write **no** trust entry: the step's output is not finished, and files already
|
|
104
|
+
drafted (such as `spec.md`) are not output to judge. Then stop. Once a person answers, the step
|
|
105
|
+
runs again and goes on from what is already drafted. That is a resume, not a re-run, so it is not
|
|
106
|
+
graded `rejected` for being run again.
|
|
107
|
+
|
|
108
|
+
<!-- end: Ask the human-only questions first -->
|
|
109
|
+
|
|
71
110
|
## On Activation
|
|
72
111
|
|
|
73
112
|
### Step 1 — Resolve the story and check readiness
|
|
@@ -111,18 +150,94 @@ contract here. (On a route that HAS one; the short lanes do not — see below.)
|
|
|
111
150
|
Read Spec Kit's entry in `yad toolbox list --json --dir demo-repos/<repo>`, as **When a tool is
|
|
112
151
|
missing** says. If yad cannot answer, check for `/speckit.*` slash-commands and/or
|
|
113
152
|
`demo-repos/<repo>/.specify/`. Record the result for Step 6's
|
|
114
|
-
frontmatter (`speckit: installed | not-installed`).
|
|
153
|
+
frontmatter (`speckit: installed | not-installed`; a light spec records `not-used` whatever is found).
|
|
115
154
|
|
|
116
155
|
### Step 5 — Run the heavy ceremony ONCE (or degrade)
|
|
117
|
-
**
|
|
118
|
-
|
|
156
|
+
**Start the step (#348).** From the Product, run `yad build step <story> --repo <repo> <step> in_progress`,
|
|
157
|
+
where `<step>` is the lane's current step when it is `spec` or `tasks` (yad-spec runs both). Run
|
|
158
|
+
`yad build start <story> --repo <repo>` first if the story has no lane in this repo yet. The command
|
|
159
|
+
records the step, and in a repo that uses Spec Kit it points `.specify/feature.json` at `specs/<story>`,
|
|
160
|
+
so Spec Kit never writes into the previous story's folder. Run it again on a resume: it changes nothing
|
|
161
|
+
that is already right. If the lane is past both steps (a re-run after a rejected spec, say), do not move
|
|
162
|
+
the lane: set `.specify/feature.json` to `{"feature_directory":"specs/<story>"}` by hand instead.
|
|
163
|
+
|
|
164
|
+
**Ask first (#357).** Before the long part of the ceremony, ask the batch that **Ask the human-only
|
|
165
|
+
questions first** above describes. Its items come from the story, `epic.md`, the contract read in
|
|
166
|
+
Step 3, and the first draft of `spec.md`. Record the answers in `spec.md`, under `## Clarifications`,
|
|
167
|
+
as `- Q: <question> → A: <answer>` lines below a `### Session <YYYY-MM-DD>` heading. This is the format
|
|
168
|
+
`/speckit.clarify` writes, and both paths below leave the answers there.
|
|
169
|
+
When the story qualifies for a **light spec** (below), put that question in the same batch.
|
|
170
|
+
|
|
171
|
+
**Light spec (#348).** A small story can have one `spec.md` instead of the full set of files. Suggest it
|
|
172
|
+
only when ALL of these hold:
|
|
173
|
+
- the route is `chore` or `spike`, or `epics/<epic>/.sdlc/change.json` says `depth: defect-fix` or
|
|
174
|
+
`depth: behavioral-no-surface`;
|
|
175
|
+
- the story's **Notes for build** says the contract surface touched is none, and Step 3 found nothing
|
|
176
|
+
to quote, so the spec needs no `contracts/` slice;
|
|
177
|
+
- nothing marks it high risk: no step in `epics/<epic>/.sdlc/state.json` carries an `auth` or
|
|
178
|
+
`payments` risk tag; the code repo's risk map gives no file the work will touch the level `high`
|
|
179
|
+
(below); and the person has not called it high risk.
|
|
180
|
+
|
|
181
|
+
**Reading the risk map for it.** The tasks do not exist yet, so judge the files the work will touch
|
|
182
|
+
from the draft `spec.md` and the code; if you cannot say which files, do not offer light. Read
|
|
183
|
+
`.sdlc/risk-map` as the default branch has it (`default_branch` in the Product's `.sdlc/repos.json`, else the
|
|
184
|
+
clone's `origin/HEAD`):
|
|
185
|
+
fetch it, then ask git whether the branch holds the file, as yad does:
|
|
186
|
+
`git -C demo-repos/<repo> ls-tree --full-tree origin/<default> -- .sdlc/risk-map`. Empty output (or an
|
|
187
|
+
entry that is not a plain file) means there is no map, so it gives no `high`; a git error (no such
|
|
188
|
+
branch, no fetch) is no answer. Otherwise read it with
|
|
189
|
+
`git -C demo-repos/<repo> show origin/<default>:.sdlc/risk-map`. `yad risk-map check` reads the
|
|
190
|
+
clone's working copy instead, so use its report only when the clone is on the default branch with the
|
|
191
|
+
map unchanged. A file's level is the one on the deepest directory listed above it (`./` covers only the
|
|
192
|
+
files at the root); `guessed` counts the same as `confirmed`; an `unset` line, or a file no line covers,
|
|
193
|
+
is not high. The map gives **no answer**, so do not offer light, when its first line that is not blank
|
|
194
|
+
is not the header `# yad-risk-map v1`, or a line (blank lines and `#` comments
|
|
195
|
+
aside) is neither `<dir>/ <high|medium|low> <guessed|confirmed>` nor `<dir>/ unset` (optionally
|
|
196
|
+
`<dir>/ unset guessed`), each with an optional ` # reason`, or a directory is listed twice.
|
|
197
|
+
|
|
198
|
+
Never suggest it for a story that touches the contract, and never choose it yourself: ask in the batch
|
|
199
|
+
("Light spec — one `spec.md` holding the spec, the plan and the tasks?"), with the reason it qualifies,
|
|
200
|
+
and record the answer in `## Clarifications`. Without a clear yes, write the full spec. A light spec:
|
|
201
|
+
- is **only** `spec.md` and `link.md` under `demo-repos/<repo>/specs/<story>/`. `spec.md` holds the spec,
|
|
202
|
+
then `## Plan` (the approach, in a few lines), then `## Tasks`. No `research.md`, `data-model.md`,
|
|
203
|
+
`plan.md`, `tasks.md` or `contracts/`. A re-run that turns a full spec into a light one deletes
|
|
204
|
+
everything else in the folder (a `tasks.md` that is still there wins over the light block);
|
|
205
|
+
- keeps its tasks between the two marker lines `<!-- yad:tasks -->` and `<!-- /yad:tasks -->` under
|
|
206
|
+
`## Tasks`, once each, in the same shape as `tasks.md` (`## T01 — <goal>` and a **Files:** list).
|
|
207
|
+
`yad build done` and `yad-implement` read the tasks only from between the markers;
|
|
208
|
+
- does not run Spec Kit, whose commands need `plan.md` and `tasks.md`. Step 6 records `speckit: not-used`
|
|
209
|
+
and `spec-mode: light`.
|
|
210
|
+
|
|
211
|
+
**When it qualifies, ask before any Spec Kit command.** Draft `spec.md` by hand and ask the batch, the
|
|
212
|
+
light question in it, before running any `/speckit.*` command, so the choice is known before the path
|
|
213
|
+
is. On a yes, write the light spec. On a no, take one of the two paths below; on **Used**, the batch is
|
|
214
|
+
already asked, so copy the recorded `## Clarifications` lines out first (`/speckit.specify` replaces
|
|
215
|
+
`spec.md` with its template), then put them into the `spec.md` it writes instead of asking again.
|
|
216
|
+
|
|
217
|
+
The spec leg writes the whole light spec, tasks included. When the lane then reaches the `tasks` leg,
|
|
218
|
+
start that step as above and check that the tasks block is there and whole; write nothing else.
|
|
219
|
+
|
|
220
|
+
**Used** (and the spec is not light) — from inside `demo-repos/<repo>/`, drive, in order:
|
|
221
|
+
`/speckit.specify` → (ask the batch) → `/speckit.clarify` → `/speckit.plan` → `/speckit.analyze` →
|
|
119
222
|
`/speckit.checklist` → `/speckit.tasks`. **Pin the feature to `<story>`** (do not accept an
|
|
120
|
-
auto-slug)
|
|
223
|
+
auto-slug): start `/speckit.specify` with `SPECIFY_FEATURE_DIRECTORY=specs/<story>`, because without it
|
|
224
|
+
specify makes a numbered folder of its own. Before `/speckit.plan` and again before `/speckit.tasks`,
|
|
225
|
+
check that `.specify/feature.json` still names `specs/<story>`; if it does not, set it back to
|
|
226
|
+
`{"feature_directory":"specs/<story>"}`. Seed `specify` from the story's acceptance criteria and the contract elements from Step 3.
|
|
227
|
+
If Step 3 found nothing to quote, keep `contracts/` out: delete any `contracts/` folder `/speckit.specify`
|
|
228
|
+
or `/speckit.plan` writes, since lines that are not quoted from the lock fail contract-check.
|
|
229
|
+
On a resume after a question halt, keep the `spec.md` that `/speckit.specify` already wrote: do not run
|
|
230
|
+
it again. A hand draft made only to ask the light question is not that: run `/speckit.specify` and carry
|
|
231
|
+
its `## Clarifications` in. Tell them apart by `specs/<story>/checklists/requirements.md`: specify
|
|
232
|
+
writes it, a hand draft never does. Answer `/speckit.clarify`'s questions from the batch answers. A question it asks that the batch did not
|
|
233
|
+
cover is a late one: ask all such questions together, as rule 4 of the batch says.
|
|
121
234
|
`/speckit.constitution` and `/speckit.implement` are **out of scope for Step A** (implement is Step B).
|
|
122
235
|
|
|
123
|
-
**Not used (degrade)** —
|
|
236
|
+
**Not used (degrade)** (and the spec is not light) — draft `spec.md` first, ask the batch, record the answers in it, and only then
|
|
237
|
+
write the rest (after a "no" to light, the batch is already asked: do not ask it again). Hand-author the identical files in Spec Kit's layout under
|
|
124
238
|
`demo-repos/<repo>/specs/<story>/`: `spec.md`, `research.md`, `data-model.md`, `contracts/`,
|
|
125
|
-
`plan.md`, `tasks.md`.
|
|
239
|
+
`plan.md`, `tasks.md`. Write `contracts/` only when Step 3 found surface to quote: a story with nothing to
|
|
240
|
+
quote has no `contracts/` folder at all (git keeps no empty folder, and an empty one quotes nothing). The content is what a real Spec Kit run would produce, traceable to the story's
|
|
126
241
|
acceptance criteria and the locked contract surface. `tasks.md` MUST be numbered atomic tasks (`T01…`),
|
|
127
242
|
each declaring the files it may touch, so Step B's "stay inside the declared files" rule has something
|
|
128
243
|
to read. See `references/spec-handoff.md` for the exact file map and per-file degradation rules.
|
|
@@ -134,12 +249,13 @@ frontmatter linking the spec back to the product repo: `story`, `epic`, `repo`,
|
|
|
134
249
|
place CI checks the Product out; the gates read that record first anyway), `contract-lock` (the hash **copied** from `contract-lock.json`, NOT recomputed
|
|
135
250
|
in the code repo — or the literal `none` on a short-lane epic, which has no lock; never a made-up or
|
|
136
251
|
empty hash, which the CI gate reads as a broken lock and fails), `speckit`
|
|
137
|
-
(`installed | not-installed`), `
|
|
252
|
+
(`installed | not-installed`, or `not-used` for a light spec), `spec-mode` (`light` for a light spec,
|
|
253
|
+
else `full`; nothing after the value on that line), `generated` (date). This `link.md` plus the
|
|
138
254
|
spec folder is the authoritative record that this story's spec exists.
|
|
139
255
|
|
|
140
256
|
### Step 7 — Stop (Shape state untouched)
|
|
141
257
|
Report: the spec folder path, the files written, whether Spec Kit was used, the task count from
|
|
142
|
-
`tasks.md
|
|
258
|
+
`tasks.md` (or the light spec's tasks block), whether the spec is light, and that the next action is **Step B — `yad-implement`**. Do **not** edit the epic's
|
|
143
259
|
`state.json`, `approvals.json`, or `contract-lock.json`. Step A is a generation step, not a Shape gate.
|
|
144
260
|
|
|
145
261
|
### Step 8 — Record the `spec` trust signal (Phase 4b)
|
|
@@ -149,11 +265,12 @@ verdict is **anchored to the human who accepts the spec**, never self-graded:
|
|
|
149
265
|
- the human approves the generated `specs/<story>/` untouched → `approved-unchanged`;
|
|
150
266
|
- the human edits the spec/plan/tasks before accepting → `approved-with-edits` (signal
|
|
151
267
|
`human_edited_spec: true`);
|
|
152
|
-
- the spec is rejected or the ceremony re-run → `rejected
|
|
268
|
+
- the spec is rejected or the ceremony re-run → `rejected` (a resume after a question halt, #357, is
|
|
269
|
+
not a re-run).
|
|
153
270
|
`yad-run` records a provisional entry when the spec is generated; this acceptance finalizes it (same
|
|
154
|
-
pattern as the engineer review finalizing `implement` at `yad-engineer-review`).
|
|
155
|
-
|
|
156
|
-
|
|
271
|
+
pattern as the engineer review finalizing `implement` at `yad-engineer-review`). Finalize it with
|
|
272
|
+
`yad build trust <story> --repo <repo> spec --uid <uid> --verdict <v>` — the `uid` is `closed.run` on the
|
|
273
|
+
`spec` step in `build-state/<story>.json`. Never write the shard by hand. Schema:
|
|
157
274
|
`../yad-epic/references/state-schema.md`. **Run standalone, no trust entry is written** — the
|
|
158
275
|
log measures orchestrated runs. The record is advice: the `spec` dial is
|
|
159
276
|
whatever the team sets with `yad dial`, and this step never changes it.
|
|
@@ -161,10 +278,14 @@ whatever the team sets with `yad dial`, and this step never changes it.
|
|
|
161
278
|
## Hard rules (build plan §A, Cross-cutting)
|
|
162
279
|
|
|
163
280
|
- **Heavy spec once per story, not per task.** specify/clarify/plan/analyze/checklist/tasks run once
|
|
164
|
-
per story per repo. Do not re-run the ceremony for each task.
|
|
281
|
+
per story per repo. Do not re-run the ceremony for each task. A **light spec** (#348) skips it, and only
|
|
282
|
+
when a human confirms it in the batch.
|
|
165
283
|
- **Per-repo spec, shared contract.** Spec/plan/tasks live in the code repo; the contract stays
|
|
166
284
|
singular in the product repo. Never widen the contract surface from here.
|
|
167
|
-
- **Nothing auto-advances.** Step A generates files and stops; no state machine is advanced.
|
|
285
|
+
- **Nothing auto-advances.** Step A generates files and stops; no state machine is advanced. Step 5
|
|
286
|
+
only starts the lane's spec or tasks step (`in_progress`); it never closes one.
|
|
287
|
+
- **Human-only decisions are asked first, in one batch** (#357), before the long work — never decided
|
|
288
|
+
by the agent.
|
|
168
289
|
|
|
169
290
|
## Reference
|
|
170
291
|
- Command list, output map, degradation rules, link.md template: `references/spec-handoff.md`.
|
|
@@ -18,10 +18,21 @@ Driven as harness slash-commands (RESEARCH-NOTES §2, Deviation 3), from **insid
|
|
|
18
18
|
| 5 | `/speckit.checklist` | Quality checklist for the spec | checklist section under `specs/<feature-id>/` (in the degraded path, folded into `spec.md`) |
|
|
19
19
|
| 6 | `/speckit.tasks` | Atomic task list | `specs/<feature-id>/tasks.md` |
|
|
20
20
|
|
|
21
|
+
**Ask first (#357).** Between `specify` and `clarify` — or, when the story qualifies for a light spec
|
|
22
|
+
(#348), on a hand draft before any Spec Kit command (SKILL.md Step 5) — the skill asks every human-only
|
|
23
|
+
decision and open question in one batch (SKILL.md, **Ask the human-only questions first**). The answers go into
|
|
24
|
+
`spec.md` under `## Clarifications`, as `- Q: <question> → A: <answer>` lines below a
|
|
25
|
+
`### Session <YYYY-MM-DD>` heading — the format `/speckit.clarify` writes. The degraded path writes
|
|
26
|
+
the same section, so `yad-implement` finds the answers in one place on both paths.
|
|
27
|
+
|
|
21
28
|
**Excluded from Step A:** `/speckit.constitution` (project-level, one-time bootstrap) and
|
|
22
29
|
`/speckit.implement` (that is Step B — the per-task build loop). Stop at `tasks`.
|
|
23
30
|
|
|
24
|
-
**Feature-id is pinned** to the story ID (`EP-<slug>-S0N`), never Spec Kit's numbered auto-slug.
|
|
31
|
+
**Feature-id is pinned** to the story ID (`EP-<slug>-S0N`), never Spec Kit's numbered auto-slug. Two
|
|
32
|
+
things pin it (#348): `yad build step <story> --repo <repo> spec|tasks in_progress` writes
|
|
33
|
+
`{"feature_directory":"specs/<story>"}` to `.specify/feature.json`, which `/speckit.plan`, `/speckit.tasks`
|
|
34
|
+
and the rest read; and `/speckit.specify`, which does not read that file, is started with
|
|
35
|
+
`SPECIFY_FEATURE_DIRECTORY=specs/<story>`. If a
|
|
25
36
|
Spec Kit version forces its own folder name, keep the run but make `link.md` (below) the crosswalk
|
|
26
37
|
between the Spec-Kit slug and the permanent story ID.
|
|
27
38
|
|
|
@@ -33,12 +44,45 @@ demo-repos/<repo>/specs/<story-id>/
|
|
|
33
44
|
research.md # decisions/unknowns resolved during clarify
|
|
34
45
|
data-model.md # entities/fields THIS repo implements (quoting the shared ones from the contract)
|
|
35
46
|
contracts/ # the API/event surface this repo implements (quoted from the locked contract)
|
|
36
|
-
# OMITTED ENTIRELY on a short-lane epic — see below
|
|
47
|
+
# OMITTED ENTIRELY on a short-lane epic, and for a story with nothing to quote — see below
|
|
37
48
|
plan.md # technical approach for this repo
|
|
38
49
|
tasks.md # numbered atomic tasks (T01…), each scoped to the files it may touch
|
|
39
50
|
link.md # back-pointer to the story in the product repo (Step A adds this; not a Spec Kit file)
|
|
40
51
|
```
|
|
41
52
|
|
|
53
|
+
## Light spec (#348)
|
|
54
|
+
|
|
55
|
+
A small story the human confirmed as light (SKILL.md Step 5 says when to offer it) has two files only:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
demo-repos/<repo>/specs/<story-id>/
|
|
59
|
+
spec.md # the spec, then ## Plan, then ## Tasks with the marked tasks block
|
|
60
|
+
link.md # as below, with speckit: not-used and spec-mode: light
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
# Spec — EP-<slug>-S0N
|
|
65
|
+
|
|
66
|
+
<the spec: context, the need, in scope, out of scope, acceptance criteria copied from the story>
|
|
67
|
+
|
|
68
|
+
## Clarifications
|
|
69
|
+
### Session <YYYY-MM-DD>
|
|
70
|
+
- Q: Light spec — one spec.md holding the spec, the plan and the tasks? → A: yes
|
|
71
|
+
|
|
72
|
+
## Plan
|
|
73
|
+
<the approach for this repo in a few lines: what changes, and how it is tested>
|
|
74
|
+
|
|
75
|
+
## Tasks
|
|
76
|
+
<!-- yad:tasks -->
|
|
77
|
+
## T01 — <one-line goal>
|
|
78
|
+
**Files:** <the files it may touch>
|
|
79
|
+
<!-- /yad:tasks -->
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Each marker line appears once, alone on its line, begin before end. The tasks are read **only** from
|
|
83
|
+
between them (`yad build done`, `yad-implement`), so a `T01` mentioned in the spec or the plan is never
|
|
84
|
+
taken for a task. Spec Kit is not run for a light spec: its commands need `plan.md` and `tasks.md`.
|
|
85
|
+
|
|
42
86
|
## Degradation rules (when Spec Kit is not used)
|
|
43
87
|
|
|
44
88
|
Author each file by hand so it is **indistinguishable in shape** from a real Spec Kit run. The content
|
|
@@ -71,6 +115,8 @@ comes from the story's acceptance criteria and the **locked contract surface**
|
|
|
71
115
|
Markdown (`.md`). The contract-check gate then passes the slice with **no** `Contract-Change` trailer,
|
|
72
116
|
because it can prove every quoted line is in the lock (issue #344). Never reword, reorder or skip a line
|
|
73
117
|
inside a block: that is a surface change, and it needs the trailer.
|
|
118
|
+
**Leave the folder out when there is nothing to quote** — a story on a locked epic that touches none of
|
|
119
|
+
the surface has no `contracts/` folder (an empty one cannot be committed and quotes nothing).
|
|
74
120
|
**Do NOT create this folder on a short-lane epic** (`profile: chore` or `spike`). Those routes have
|
|
75
121
|
no architecture step, so there is no locked `contract.md` to quote and no lock for CI to check the
|
|
76
122
|
quote against — the gate refuses a slice under a lockless epic. A short-lane story consumes the
|
|
@@ -94,7 +140,8 @@ product-repo: <path to the product repo — absolute, or relative to THIS file's
|
|
|
94
140
|
contract-lock: sha256:<hex copied from epics/EP-<slug>/.sdlc/contract-lock.json> # or the literal
|
|
95
141
|
# `none` on a short-lane epic, which has no lock. Never an empty or invented hash:
|
|
96
142
|
# CI reads an unparseable value as a broken lock and fails.
|
|
97
|
-
speckit: installed | not-installed
|
|
143
|
+
speckit: installed | not-installed | not-used
|
|
144
|
+
spec-mode: full | light
|
|
98
145
|
generated: <YYYY-MM-DD>
|
|
99
146
|
---
|
|
100
147
|
|
|
@@ -18,6 +18,13 @@ reads `.sdlc/` and `reviews/` and reports.
|
|
|
18
18
|
This skill reports on epics. For people — what each team member did since the previous working day,
|
|
19
19
|
what they are working on and what is waiting — point to `yad standup` (E132) instead of rebuilding it.
|
|
20
20
|
|
|
21
|
+
**Start from `yad status --brief` (#349).** It prints, in about 20 lines, where the work stands: the
|
|
22
|
+
task branch this checkout is on and its Build step, each open epic and its next action, your open
|
|
23
|
+
PRs/MRs, and what is owed (debt, recorded blockers, hotfix debt, open follow-up PRs). After a context
|
|
24
|
+
reset — a summary, a new session — run it first, and act on what it prints rather than on what you
|
|
25
|
+
remember. Read the files below only for the detail it leaves out. `--json` gives the same view as data;
|
|
26
|
+
`--no-fetch` asks no platform.
|
|
27
|
+
|
|
21
28
|
### Step 1 — Resolve the epic
|
|
22
29
|
If no `EP-<slug>` was given, list the epics under `{project-root}/epics/` and ask which one (or
|
|
23
30
|
report all if the user asked for an overview).
|
|
@@ -10,7 +10,7 @@ Each story authored at Shape step 7 is one Markdown file under `epics/EP-<slug>/
|
|
|
10
10
|
| `id` | `EP-<slug>-S0N` | Stable story ID. Engine-assigned, zero-padded, never renamed. |
|
|
11
11
|
| `epic` | `EP-<slug>` | Parent epic ID — the unbroken link back to the epic. |
|
|
12
12
|
| `owner` | name | Inherited from `epic.md` `owner` (the single source — not retyped per story). Carries the responsible owner through to Build. |
|
|
13
|
-
| `status` | `draft` \| `
|
|
13
|
+
| `status` | `draft` \| `in-review` \| `approved`, then `in-build` \| `shipped` | Story lifecycle: the first three within the stories gate (`yad sync-status` moves them), the last two in Build (`yad build ship` sets `in-build`, `yad build done` sets `shipped`). |
|
|
14
14
|
| `repos` | subset of the epic's `repos` | Which repos must implement this story. **Labels the stories review PR with the touched repos now and (Phase 3) decides where specs are scaffolded.** |
|
|
15
15
|
| `code-context` | `{ repos: [<name@sha>], loaded: <date> }` | Optional. Which connected-repo code-maps anchored "Notes for build" (Shape step 7 Step 2b). The `@sha` (a repo's `syncedHead`) is recommended so freshness is recorded but may be omitted; the SKILL templates show the empty placeholder `{ repos: [], loaded: <date or none> }`. `none` / `[]` when no repos are connected. |
|
|
16
16
|
|
|
@@ -81,7 +81,8 @@ so any repo whose `HEAD` now differs from its registry `syncedHead` has a **stal
|
|
|
81
81
|
the command ends by pointing the human at `yad repo refresh` to repack (that is a separate human
|
|
82
82
|
decision; this skill never repacks or writes the registry). After the repack + AI code-map
|
|
83
83
|
regeneration, `yad repo refresh --push` publishes the refreshed code-maps + registry to the Product's
|
|
84
|
-
default branch as a `chore(product): sync code-context … [skip ci]` audit commit.
|
|
84
|
+
default branch as a `chore(product): sync code-context … [skip ci]` audit commit. It pushes to the default
|
|
85
|
+
branch, so an AI agent asks the person first, every time (E158).
|
|
85
86
|
|
|
86
87
|
## Hard rules
|
|
87
88
|
|
package/skills/yad-ui/SKILL.md
CHANGED
|
@@ -81,8 +81,8 @@ pipeline, infra work), it does not need a UI design. Two signals to watch for:
|
|
|
81
81
|
from before shape 7, `done` with `skipped: true` beside it — the step was marked N/A. If it is
|
|
82
82
|
`deferred`, the team set it aside to come back to later. Either way the `--check` above refuses it
|
|
83
83
|
(`ui-design is already skipped`, or `already deferred`). **STOP**, there is nothing to author now;
|
|
84
|
-
point the user at `yad next EP-<slug>` (the next step is `stories`).
|
|
85
|
-
run `yad undefer EP-<slug> ui-design` first.
|
|
84
|
+
point the user at `yad next EP-<slug>` (the next step is `stories`). When the person asks to pick a
|
|
85
|
+
deferred UI back up, run `yad undefer EP-<slug> ui-design` first.
|
|
86
86
|
- **Should be skipped:** if you reach this step and the epic clearly produces no screens, do **not**
|
|
87
87
|
invent a hollow UI artifact. Offer to mark it N/A instead:
|
|
88
88
|
`yad skip EP-<slug> ui-design --reason "<why, e.g. backend-only service>"`. That marks both the
|