yadflow 4.9.0 → 4.11.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 +184 -0
- package/README.md +15 -5
- package/bin/commands.mjs +11 -1
- package/bin/yad.mjs +203 -14
- package/cli/agent-guard-worker.mjs +13 -0
- package/cli/agent-guard.mjs +1797 -73
- package/cli/agent-rules.mjs +64 -5
- package/cli/argv-flags.mjs +2 -2
- package/cli/brain/vendor/LICENSE-graphology-library.txt +21 -0
- package/cli/brain/vendor/LICENSE-graphology.txt +21 -0
- package/cli/brain/vendor/LICENSE-sigma.txt +12 -0
- package/cli/brain/vendor/graphology-library.min.js +2 -0
- package/cli/brain/vendor/graphology.umd.min.js +2 -0
- package/cli/brain/vendor/sigma.min.js +1369 -0
- package/cli/brain/view/app.js +382 -0
- package/cli/brain/view/index.html +63 -0
- package/cli/brain/view/live.css +228 -0
- package/cli/brain/view/live.html +110 -0
- package/cli/brain/view/live.js +884 -0
- package/cli/brain/view/style.css +141 -0
- package/cli/brain-about.mjs +206 -0
- package/cli/brain-activity.mjs +285 -0
- package/cli/brain-skills.mjs +118 -0
- package/cli/brain-vendor.mjs +71 -0
- package/cli/brain-view.mjs +344 -0
- package/cli/brain.mjs +810 -0
- package/cli/ci-check.mjs +48 -4
- package/cli/codeowners-command.mjs +72 -6
- package/cli/commit.mjs +17 -3
- package/cli/docs.mjs +2 -0
- package/cli/doctor.mjs +151 -25
- package/cli/epic-state.mjs +186 -4
- package/cli/epic.mjs +26 -10
- package/cli/errors.mjs +2 -1
- package/cli/find-product.mjs +69 -15
- package/cli/fold.mjs +31 -6
- package/cli/foundation-publish.mjs +256 -0
- package/cli/gate.mjs +29 -3
- package/cli/git-read.mjs +38 -0
- package/cli/guard-stream.mjs +409 -0
- package/cli/guide.mjs +3 -1
- package/cli/hook.mjs +102 -9
- package/cli/issue-links.mjs +61 -0
- package/cli/issues-act.mjs +371 -0
- package/cli/issues-write.mjs +441 -0
- package/cli/issues.mjs +513 -0
- package/cli/lib.mjs +37 -2
- package/cli/lifecycle.mjs +7 -0
- package/cli/local-page.mjs +138 -0
- package/cli/machine.mjs +1 -1
- package/cli/manifest.mjs +59 -3
- package/cli/map/view/app.js +712 -0
- package/cli/map/view/index.html +50 -0
- package/cli/map/view/style.css +142 -0
- package/cli/map-view.mjs +186 -0
- package/cli/map.mjs +637 -0
- package/cli/members.mjs +9 -15
- package/cli/next.mjs +1 -1
- package/cli/openpr.mjs +26 -6
- package/cli/plan.mjs +127 -0
- package/cli/platform.mjs +159 -4
- package/cli/product-index.mjs +1 -1
- package/cli/protection.mjs +53 -3
- package/cli/reconcile.mjs +9 -3
- package/cli/report.mjs +9 -3
- package/cli/reports-dir.mjs +391 -0
- package/cli/reports.mjs +65 -0
- package/cli/run-checks.mjs +15 -4
- package/cli/scan.mjs +314 -0
- package/cli/setup.mjs +42 -8
- package/cli/standup.mjs +120 -78
- package/cli/status.mjs +6 -5
- package/cli/story-frames.mjs +17 -6
- package/cli/test-agents-file.mjs +985 -12
- package/cli/test-brain-activity.mjs +753 -0
- package/cli/test-brain-view.mjs +381 -0
- package/cli/test-brain.mjs +795 -0
- package/cli/test-build.mjs +25 -0
- package/cli/test-ci-check.mjs +469 -10
- package/cli/test-guide.mjs +218 -0
- package/cli/test-machine.mjs +59 -0
- package/cli/test-map.mjs +615 -0
- package/cli/test-node.mjs +15 -0
- package/cli/test-reports.mjs +382 -0
- package/cli/test-run-checks.mjs +21 -0
- package/cli/test-setup-agent.mjs +14 -0
- package/cli/test-story-frames.mjs +74 -4
- package/cli/test-worktree.mjs +24 -3
- package/cli/toolbox-connect.mjs +259 -0
- package/cli/toolbox.mjs +187 -12
- package/cli/update-commit.mjs +101 -9
- package/cli/usage.mjs +8 -4
- package/package.json +12 -4
- package/skills/sdlc/config.yaml +1 -1
- package/skills/sdlc/module-help.csv +3 -1
- package/skills/yad-analysis/SKILL.md +4 -0
- package/skills/yad-architecture/SKILL.md +22 -4
- package/skills/yad-backfill/SKILL.md +4 -0
- package/skills/yad-change/SKILL.md +7 -1
- package/skills/yad-change/references/triage.md +2 -0
- package/skills/yad-checks/SKILL.md +15 -7
- package/skills/yad-checks/references/check-gates.md +70 -35
- package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
- package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
- package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
- package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
- package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
- package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
- package/skills/yad-checks/templates/github/yad-checks.yml +358 -69
- package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
- package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
- package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
- package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
- package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +80 -20
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
- package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
- package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
- package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
- package/skills/yad-commit/SKILL.md +3 -1
- package/skills/yad-connect-design/SKILL.md +42 -10
- package/skills/yad-connect-design/references/design-context.md +35 -5
- package/skills/yad-connect-design/references/design-registry.md +3 -3
- package/skills/yad-connect-learning/SKILL.md +12 -2
- package/skills/yad-connect-repos/SKILL.md +18 -0
- package/skills/yad-connect-testing/SKILL.md +22 -5
- package/skills/yad-connect-testing/references/testing-context.md +1 -1
- package/skills/yad-discovery/SKILL.md +11 -0
- package/skills/yad-discovery/references/foundation-schema.md +11 -0
- package/skills/yad-docs/templates/app/package-lock.json +18 -10
- package/skills/yad-docs/templates/app/package.json +6 -1
- package/skills/yad-epic/SKILL.md +7 -0
- package/skills/yad-epic/references/state-schema.md +50 -1
- package/skills/yad-guide/SKILL.md +8 -4
- package/skills/yad-implement/SKILL.md +117 -4
- package/skills/yad-implement/references/implement-conventions.md +2 -1
- package/skills/yad-issues/SKILL.md +54 -0
- package/skills/yad-learn/SKILL.md +4 -0
- package/skills/yad-open-pr/SKILL.md +6 -0
- package/skills/yad-pr-template/SKILL.md +2 -1
- package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
- package/skills/yad-pr-template/templates/checks/pr-title.sh +42 -6
- package/skills/yad-product-bridge/references/bridge.md +28 -0
- package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
- package/skills/yad-run/SKILL.md +5 -0
- package/skills/yad-scan/SKILL.md +51 -0
- package/skills/yad-spec/SKILL.md +32 -2
- package/skills/yad-stories/SKILL.md +22 -4
- package/skills/yad-stories/references/story-schema.md +1 -1
- package/skills/yad-test-cases/SKILL.md +18 -2
- package/skills/yad-ui/SKILL.md +43 -8
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
// yad-activity HARNESS HOOK — the live activity record behind `yad brain view --live` (E178).
|
|
2
|
+
//
|
|
3
|
+
// Runs AFTER an agent uses a tool, and appends ONE line to `<git common dir>/yad-activity.jsonl`: what kind
|
|
4
|
+
// of thing it did (read, search, edit, run), which files of this repo it touched, and when. The live view
|
|
5
|
+
// tails that file and lights up the brain as the agent works.
|
|
6
|
+
//
|
|
7
|
+
// Wired by `yad check --fix` only when the Product sets `"activity": true` (off by default), in the Product
|
|
8
|
+
// and in each cloned code repo:
|
|
9
|
+
// Claude Code a `PostToolUse` hook in `.claude/settings.json`:
|
|
10
|
+
// node "$CLAUDE_PROJECT_DIR/hooks/yad-activity.mjs" --format claude
|
|
11
|
+
// Cursor `afterFileEdit` and `afterShellExecution` hooks in `.cursor/hooks.json`:
|
|
12
|
+
// node hooks/yad-activity.mjs --format cursor
|
|
13
|
+
// (in a code repo the file is `checks/yad-activity.mjs`, since a repo's own `hooks/` is often the app's).
|
|
14
|
+
//
|
|
15
|
+
// IT NEVER STARTS YAD: it fires on every file the agent reads, so it writes the line itself, with nothing
|
|
16
|
+
// but `node:` modules, in a few milliseconds.
|
|
17
|
+
//
|
|
18
|
+
// WHAT A LINE HOLDS — and nothing else, whatever the harness sends:
|
|
19
|
+
// { v: 1, ts, s, h, op, tool, paths, yad? }
|
|
20
|
+
// s the first 12 hex characters of sha256(session id) — sessions told apart, never named
|
|
21
|
+
// h 'claude' or 'cursor'
|
|
22
|
+
// op 'read' | 'search' | 'edit' | 'run'
|
|
23
|
+
// tool the harness's tool name (Read, Grep, Edit, Bash, afterFileEdit, …)
|
|
24
|
+
// paths up to 20 paths, relative to this repo; a path outside it, absolute, or reached through a link
|
|
25
|
+
// that leaves it is dropped
|
|
26
|
+
// yad for a shell command that is a yad command: '<command> [<action>]' from yad's own list — never the
|
|
27
|
+
// rest of the line
|
|
28
|
+
// NEVER STORED: search patterns, command text, prompts, file content, tool output, absolute paths.
|
|
29
|
+
//
|
|
30
|
+
// THE CONTRACT: it ALWAYS exits 0 and prints nothing on stdout, so it can never block or slow the agent. A
|
|
31
|
+
// problem is at most one line on stderr. A line is at most 4 KB, so an append lands whole even when two
|
|
32
|
+
// agents write at once. Above 5 MB the file is renamed to `yad-activity.1.jsonl` (one old file is kept).
|
|
33
|
+
import { createHash } from 'node:crypto';
|
|
34
|
+
import { spawnSync } from 'node:child_process';
|
|
35
|
+
import fs from 'node:fs';
|
|
36
|
+
import path from 'node:path';
|
|
37
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
38
|
+
|
|
39
|
+
export const LOG_NAME = 'yad-activity.jsonl';
|
|
40
|
+
export const OLD_LOG_NAME = 'yad-activity.1.jsonl';
|
|
41
|
+
export const ROTATE_AT = 5 * 1024 * 1024;
|
|
42
|
+
export const MAX_LINE = 4096;
|
|
43
|
+
export const MAX_PATHS = 20;
|
|
44
|
+
|
|
45
|
+
// The yad commands a `run` may name: every key of COMMAND_CLASS (cli/agent-rules.mjs), frozen here because a
|
|
46
|
+
// hook imports nothing of yad's. A test holds the two lists equal.
|
|
47
|
+
export const YAD_COMMANDS = Object.freeze([
|
|
48
|
+
'assign', 'brain build', 'brain file', 'brain query', 'brain status', 'brain story', 'brain view', 'build done', 'build merged',
|
|
49
|
+
'build ship', 'build start', 'build step', 'build sync', 'build trust', 'capture', 'check', 'checkpoint',
|
|
50
|
+
'ci check', 'claims', 'codeowners check', 'commit', 'defer', 'detect', 'dial', 'docs build', 'docs deploy',
|
|
51
|
+
'docs list', 'docs sync', 'doctor', 'epic new', 'fold', 'foundation new', 'foundation publish',
|
|
52
|
+
'foundation status', 'gate advance', 'gate approve', 'gate ci', 'gate comment', 'gate comments',
|
|
53
|
+
'gate open', 'gate reopen', 'gate repair', 'gate review', 'gate status', 'gate sync', 'gate trailer',
|
|
54
|
+
'gate walkthrough', 'guide', 'help', 'history list', 'history search', 'history show', 'hook agent-guard',
|
|
55
|
+
'hook ledger-guard', 'index', 'init', 'issues assign', 'issues close', 'issues comment', 'issues edit',
|
|
56
|
+
'issues label', 'issues labels', 'issues link', 'issues list', 'issues new', 'issues reopen',
|
|
57
|
+
'issues show', 'issues sync', 'issues unlink', 'join', 'kill', 'map', 'member add', 'member list',
|
|
58
|
+
'member remove', 'migrate', 'mode', 'mode solo', 'mode team', 'new', 'next', 'open-pr', 'owners',
|
|
59
|
+
'reconcile check', 'reconcile refresh', 'reconcile wire', 'repo clone', 'repo list', 'repo preview',
|
|
60
|
+
'repo refresh', 'repo sync', 'report', 'reports list', 'reports open', 'reports prune', 'review cards', 'review chat', 'review context', 'review nudge',
|
|
61
|
+
'review reconcile', 'review trailer', 'review walkthrough', 'risk-map check', 'risk-map draft', 'roster',
|
|
62
|
+
'run checks', 'scan file', 'setup', 'ship', 'signing check', 'skill bind', 'skill list', 'skill recommend',
|
|
63
|
+
'skill unbind', 'skip', 'standup', 'status', 'story frames', 'sync-status', 'thread', 'tidy up',
|
|
64
|
+
'toolbox add', 'toolbox check', 'toolbox connect', 'toolbox list', 'toolbox remove', 'unassign', 'unblock',
|
|
65
|
+
'undefer', 'unkill', 'unskip', 'update', 'usage', 'worktree add', 'worktree list', 'worktree remove',
|
|
66
|
+
]);
|
|
67
|
+
const KNOWN = new Set(YAD_COMMANDS);
|
|
68
|
+
|
|
69
|
+
const CLAUDE_OPS = new Map([
|
|
70
|
+
['Read', 'read'], ['Grep', 'search'], ['Glob', 'search'],
|
|
71
|
+
['Edit', 'edit'], ['Write', 'edit'], ['MultiEdit', 'edit'], ['NotebookEdit', 'edit'],
|
|
72
|
+
['Bash', 'run'],
|
|
73
|
+
]);
|
|
74
|
+
const CURSOR_OPS = new Map([['afterFileEdit', 'edit'], ['afterShellExecution', 'run']]);
|
|
75
|
+
|
|
76
|
+
const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
|
|
77
|
+
const short = (v, n) => (typeof v === 'string' ? v.slice(0, n) : null);
|
|
78
|
+
|
|
79
|
+
// The real path of `abs`: its nearest part that exists, resolved through its links, with the rest (not
|
|
80
|
+
// written yet, or deleted) added back by name. Null when nothing on the way exists.
|
|
81
|
+
function realOf(abs) {
|
|
82
|
+
let head = abs;
|
|
83
|
+
const tail = [];
|
|
84
|
+
for (;;) {
|
|
85
|
+
try { return path.join(fs.realpathSync(head), ...tail); } catch { /* go up one */ }
|
|
86
|
+
const up = path.dirname(head);
|
|
87
|
+
if (up === head) return null;
|
|
88
|
+
tail.unshift(path.basename(head));
|
|
89
|
+
head = up;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
// Text no harness sends as a file path, but that would read as a relative name: a home (`~`), a variable
|
|
94
|
+
// (`$HOME`, `%USERPROFILE%`), a URL (`file://…`), and — off Windows — a drive or a backslash path.
|
|
95
|
+
const NOT_A_PATH = process.platform === 'win32' ? /^[~$%]|^[a-z][a-z0-9+.-]*:\/\//i : /^[~$%]|[:\\]/;
|
|
96
|
+
|
|
97
|
+
// A path the harness gave, as a path relative to the repo, or null when it is not inside it. Judged on the
|
|
98
|
+
// REAL path (links resolved), against the repo's real root: a link inside the repo that points out is not the
|
|
99
|
+
// repo's, and a repo opened through a link (macOS /tmp, a linked projects folder, a Windows junction) still
|
|
100
|
+
// matches what the agent typed (E178 review 1).
|
|
101
|
+
export function repoPath(given, root, realRoot = root) {
|
|
102
|
+
if (typeof given !== 'string' || !given || given.length > 1024 || given.includes('\0') || NOT_A_PATH.test(given)) return null;
|
|
103
|
+
const real = realOf(path.resolve(root, given));
|
|
104
|
+
if (real === null) return null;
|
|
105
|
+
const rel = path.relative(realRoot, real);
|
|
106
|
+
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
|
|
107
|
+
return rel.split(path.sep).join('/');
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
// The yad command a shell line runs, as '<command> [<action>]', or null. Only a line that IS a yad command
|
|
111
|
+
// (optionally through npx) counts, and only words yad itself names are kept.
|
|
112
|
+
export function yadCommand(line) {
|
|
113
|
+
if (typeof line !== 'string') return null;
|
|
114
|
+
const m = /^\s*(?:npx\s+(?:--no-install\s+)?)?yad\s+([a-z][a-z-]{0,30})(?:\s+([a-z][a-z-]{0,30}))?(?=\s|$)/.exec(line);
|
|
115
|
+
if (!m) return null;
|
|
116
|
+
if (m[2] && KNOWN.has(`${m[1]} ${m[2]}`)) return `${m[1]} ${m[2]}`;
|
|
117
|
+
return KNOWN.has(m[1]) || YAD_COMMANDS.some((k) => k.startsWith(`${m[1]} `)) ? m[1] : null;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
// The record for one payload, or null when the tool is not one this records.
|
|
121
|
+
export function recordOf(payload, { root, realRoot = root, now = Date.now(), format = 'claude' } = {}) {
|
|
122
|
+
if (!isObject(payload) || !root) return null;
|
|
123
|
+
const claude = format === 'claude';
|
|
124
|
+
const tool = claude ? short(payload.tool_name, 40) : short(payload.hook_event_name, 40);
|
|
125
|
+
const op = tool && (claude ? CLAUDE_OPS : CURSOR_OPS).get(tool);
|
|
126
|
+
if (!op) return null;
|
|
127
|
+
const input = claude ? (isObject(payload.tool_input) ? payload.tool_input : {}) : payload;
|
|
128
|
+
const given = [];
|
|
129
|
+
for (const key of ['file_path', 'notebook_path', 'path']) if (typeof input[key] === 'string') given.push(input[key]);
|
|
130
|
+
if (Array.isArray(input.edits)) for (const e of input.edits) if (isObject(e) && typeof e.file_path === 'string') given.push(e.file_path);
|
|
131
|
+
const paths = [];
|
|
132
|
+
for (const g of given) {
|
|
133
|
+
const p = repoPath(g, root, realRoot);
|
|
134
|
+
if (p && !paths.includes(p) && paths.length < MAX_PATHS) paths.push(p);
|
|
135
|
+
}
|
|
136
|
+
const session = short(claude ? payload.session_id : payload.conversation_id, 200);
|
|
137
|
+
const rec = {
|
|
138
|
+
v: 1,
|
|
139
|
+
ts: new Date(now).toISOString(),
|
|
140
|
+
s: session ? createHash('sha256').update(session).digest('hex').slice(0, 12) : null,
|
|
141
|
+
h: claude ? 'claude' : 'cursor',
|
|
142
|
+
op,
|
|
143
|
+
tool,
|
|
144
|
+
paths,
|
|
145
|
+
};
|
|
146
|
+
if (op === 'run') {
|
|
147
|
+
const y = yadCommand(input.command);
|
|
148
|
+
if (y) rec.yad = y;
|
|
149
|
+
}
|
|
150
|
+
return rec;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
// One line, never longer than MAX_LINE: paths are dropped from the end until it fits.
|
|
154
|
+
export function lineOf(rec) {
|
|
155
|
+
const r = { ...rec, paths: [...rec.paths] };
|
|
156
|
+
let line = `${JSON.stringify(r)}\n`;
|
|
157
|
+
while (Buffer.byteLength(line) > MAX_LINE && r.paths.length) { r.paths.pop(); line = `${JSON.stringify(r)}\n`; }
|
|
158
|
+
return Buffer.byteLength(line) > MAX_LINE ? null : line;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
// The folder git keeps this repo's shared data in. `<root>/.git` when it is a folder (the usual case, with
|
|
162
|
+
// no process started); for a worktree or a submodule, where `.git` is a file, git is asked.
|
|
163
|
+
export function gitCommonDir(root) {
|
|
164
|
+
const dotGit = path.join(root, '.git');
|
|
165
|
+
let here = null;
|
|
166
|
+
try { here = fs.lstatSync(dotGit); } catch { /* none here */ }
|
|
167
|
+
if (here && here.isDirectory()) return dotGit;
|
|
168
|
+
// No `.git` here: a repo whose root is ABOVE this folder (a Product in a subfolder, a monorepo app) —
|
|
169
|
+
// but only one that TRACKS files under it. A folder that merely sits inside some other repo (a home folder
|
|
170
|
+
// kept in git) is not that repo's, and its activity is written nowhere (E178 review 2). With no `.git`
|
|
171
|
+
// anywhere above, git is never started.
|
|
172
|
+
if (!here) {
|
|
173
|
+
let up = path.dirname(root);
|
|
174
|
+
let found = false;
|
|
175
|
+
for (;;) {
|
|
176
|
+
try { fs.lstatSync(path.join(up, '.git')); found = true; break; } catch { /* keep going */ }
|
|
177
|
+
const next = path.dirname(up);
|
|
178
|
+
if (next === up) break;
|
|
179
|
+
up = next;
|
|
180
|
+
}
|
|
181
|
+
if (!found) return null;
|
|
182
|
+
// One tracked file is the answer; a big folder's full list overflows a small buffer, and that is a yes
|
|
183
|
+
// too (E178 review 3), never a no.
|
|
184
|
+
const tracked = spawnSync('git', ['-C', root, 'ls-files', '-z', '--', '.'], { encoding: 'utf8', timeout: 2000, maxBuffer: 4096 });
|
|
185
|
+
const listed = String(tracked.stdout || '').length > 0;
|
|
186
|
+
if (!listed || (tracked.status !== 0 && tracked.error?.code !== 'ENOBUFS')) return null;
|
|
187
|
+
}
|
|
188
|
+
const r = spawnSync('git', ['-C', root, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8', timeout: 2000 });
|
|
189
|
+
const out = r.status === 0 ? String(r.stdout).trim() : '';
|
|
190
|
+
return out && path.isAbsolute(out) ? out : null;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
// Append one line, renaming a full log aside first.
|
|
194
|
+
export function appendLine(dir, line) {
|
|
195
|
+
const file = path.join(dir, LOG_NAME);
|
|
196
|
+
let size = 0;
|
|
197
|
+
try { const st = fs.lstatSync(file); if (!st.isFile()) return; size = st.size; } catch { /* first line */ }
|
|
198
|
+
if (size + Buffer.byteLength(line) > ROTATE_AT) {
|
|
199
|
+
try { fs.renameSync(file, path.join(dir, OLD_LOG_NAME)); } catch { /* another agent rotated it first */ }
|
|
200
|
+
}
|
|
201
|
+
fs.appendFileSync(file, line, { flag: 'a' });
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
// Read the payload: never from a terminal, at most a second, at most 1 MB.
|
|
205
|
+
function readStdin() {
|
|
206
|
+
if (process.stdin.isTTY) return Promise.resolve('');
|
|
207
|
+
return new Promise((resolve) => {
|
|
208
|
+
const chunks = [];
|
|
209
|
+
let size = 0;
|
|
210
|
+
const done = () => { clearTimeout(timer); process.stdin.pause(); resolve(Buffer.concat(chunks).toString('utf8')); };
|
|
211
|
+
const timer = setTimeout(done, 1000);
|
|
212
|
+
process.stdin.on('data', (d) => { size += d.length; if (size <= 1024 * 1024) chunks.push(d); });
|
|
213
|
+
process.stdin.on('end', done);
|
|
214
|
+
process.stdin.on('error', done);
|
|
215
|
+
process.stdin.resume();
|
|
216
|
+
});
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
async function main() {
|
|
220
|
+
const text = await readStdin();
|
|
221
|
+
const argv = process.argv.slice(2);
|
|
222
|
+
const i = argv.indexOf('--format');
|
|
223
|
+
const format = i >= 0 && argv[i + 1] === 'cursor' ? 'cursor' : 'claude';
|
|
224
|
+
// The repo is this script's grandparent: `<repo>/hooks/yad-activity.mjs` or `<repo>/checks/yad-activity.mjs`.
|
|
225
|
+
const root = path.dirname(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))));
|
|
226
|
+
let payload;
|
|
227
|
+
try { payload = JSON.parse(text); } catch { return; }
|
|
228
|
+
const rec = recordOf(payload, { root, realRoot: fs.realpathSync(root), format });
|
|
229
|
+
if (!rec) return;
|
|
230
|
+
const line = lineOf(rec);
|
|
231
|
+
const dir = line && gitCommonDir(root);
|
|
232
|
+
if (dir) appendLine(dir, line);
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
// Run only as the hook itself; a test imports the functions above.
|
|
236
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {
|
|
237
|
+
main().catch((e) => { process.stderr.write(` • yad activity: ${String(e?.message || e).slice(0, 200)}\n`); }).finally(() => process.exit(0));
|
|
238
|
+
}
|
|
@@ -16,7 +16,9 @@ and `yad-ship` use. It **never auto-advances**; it just commits.
|
|
|
16
16
|
- Run **inside the repo holding the staged change** — a code repo under
|
|
17
17
|
`{project-root}/demo-repos/<repo>/`, or the Product itself. Use absolute paths.
|
|
18
18
|
- **Stage first.** Only the staged (`git add`) atomic change is committed. The guard refuses more than
|
|
19
|
-
`ATOMIC_FILE_LIMIT` (3) staged files unless `--force` — split the change instead.
|
|
19
|
+
`ATOMIC_FILE_LIMIT` (3) staged files unless `--force` — split the change instead. In a Unity repo
|
|
20
|
+
(`ProjectSettings/ProjectVersion.txt` and `Assets/`), a staged `.meta` whose own file or folder is staged
|
|
21
|
+
too is not counted (#321).
|
|
20
22
|
- **Subject** — `<type>: <lowercase imperative description, no trailing period>`; types are
|
|
21
23
|
`feat|fix|docs|refactor|test|perf|build|ci|chore|revert`; proper nouns/acronyms keep their case.
|
|
22
24
|
- **Task trailer** — required on a code repo (anchors the `spec-link` + `commit-message` gates). Given
|
|
@@ -23,12 +23,18 @@ markdown-only exactly as before.
|
|
|
23
23
|
No tool below is required. When one is missing, this skill still finishes, using the fallback written
|
|
24
24
|
beside it.
|
|
25
25
|
|
|
26
|
+
Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
|
|
27
|
+
by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
|
|
28
|
+
connect-tool rule. On a no, or when a step fails, use the fallback.
|
|
29
|
+
|
|
26
30
|
Tell the person which tools you used and which fallbacks, and why.
|
|
27
31
|
|
|
28
32
|
- **Figma** (`figma`, a connector). This skill connects it, by writing `.sdlc/design.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
|
|
29
33
|
- Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
|
|
30
34
|
- **Pencil (pen.dev)** (`pencil`, a connector). This skill connects it, by writing `.sdlc/design.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
|
|
31
35
|
- Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
|
|
36
|
+
- **OpenPencil** (`openpencil`, a connector). This skill connects it, by writing `.sdlc/design.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
|
|
37
|
+
- Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
|
|
32
38
|
|
|
33
39
|
<!-- end: When a tool is missing -->
|
|
34
40
|
|
|
@@ -37,10 +43,14 @@ Tell the person which tools you used and which fallbacks, and why.
|
|
|
37
43
|
- `{project-root}` resolves from the project working directory (the **Product**).
|
|
38
44
|
- The integration is **Figma-first but pluggable** (`config.yaml` `design.tools`): a design-tool
|
|
39
45
|
*adapter*, like the GitHub/GitLab platform adapter. Figma is the primary provider; `pencil`
|
|
40
|
-
(the `.pen` web/mobile editor) is a second, write-capable provider; `
|
|
41
|
-
-
|
|
42
|
-
|
|
43
|
-
|
|
46
|
+
(the `.pen` web/mobile editor) is a second, write-capable provider; `openpencil` (OpenPencil, an
|
|
47
|
+
open-source editor whose CLI writes a design file in the repo with no account and no app open, E164)
|
|
48
|
+
is a third; `none` → markdown-only.
|
|
49
|
+
- **The design tool is reached through its MCP** (a harness MCP server) — the same shape as Impeccable's
|
|
50
|
+
slash-commands, not Repomix's `npx`. **One exception: OpenPencil** is reached through its CLI
|
|
51
|
+
(`openpencil` on PATH) first, and its MCP only while its desktop app is open. The skill detects the MCP
|
|
52
|
+
(or, for OpenPencil, the CLI) and, when it is absent, offers to connect it with `yad toolbox connect`
|
|
53
|
+
(E165) before it degrades; it never installs anything another way.
|
|
44
54
|
- Registry: `{project-root}/.sdlc/design.json` (project-wide, shared across all epics — NOT per-epic),
|
|
45
55
|
the sibling of `.sdlc/repos.json` and `.sdlc/product.json`.
|
|
46
56
|
- Per-epic screen→frame links are written later by `yad-ui` (`epics/EP-<slug>/.sdlc/design-links.json`),
|
|
@@ -50,7 +60,7 @@ Tell the person which tools you used and which fallbacks, and why.
|
|
|
50
60
|
## Inputs
|
|
51
61
|
|
|
52
62
|
- `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
|
|
53
|
-
- `tool` — `figma` | `pencil` | another adapter id (`config.yaml` `design.tools`). `none` records a
|
|
63
|
+
- `tool` — `figma` | `pencil` | `openpencil` | another adapter id (`config.yaml` `design.tools`). `none` records a
|
|
54
64
|
deliberate markdown-only project.
|
|
55
65
|
- `project_url` — the design tool's team/project/file reference (e.g. a Figma project or file URL).
|
|
56
66
|
Optional — a connection with no file yet is valid; `yad-ui` can create one on first generate.
|
|
@@ -65,18 +75,37 @@ Determine which tool is being connected from `tool` (default `figma`); reject a
|
|
|
65
75
|
|
|
66
76
|
- **figma** → a Figma MCP server (Dev Mode MCP for read/link; html.to.design for HTML→Figma *generate*).
|
|
67
77
|
- **pencil** → the `pencil` MCP (`batch_design` writes `.pen` web/mobile screens — generate-capable).
|
|
78
|
+
- **openpencil** → its **CLI** first (`openpencil`, found on PATH): `openpencil eval <file> --code … --write`
|
|
79
|
+
runs Figma Plugin API code on the design file and saves it, with no app open — generate-capable. Its MCP
|
|
80
|
+
server (`open-pencil`, `openpencil-mcp`) is only a bridge to the running desktop app, so it is used only
|
|
81
|
+
when the app is open with the file; it reads only files inside `OPENPENCIL_MCP_ROOT` (the folder it
|
|
82
|
+
starts in by default; the home folder on Windows). Each epic keeps its design file in its own folder,
|
|
83
|
+
`epics/EP-<slug>/design/` (for example `epics/EP-<slug>/design/screens.fig`), so `project_url` may stay
|
|
84
|
+
empty. No account: `auth` stays `"user"` and there is nothing to sign in to. Record `provider`
|
|
85
|
+
`openpencil-cli` when the CLI is found, `openpencil-mcp` when only the MCP is.
|
|
68
86
|
- another adapter → its named MCP.
|
|
69
87
|
|
|
70
88
|
Record `provider` (the concrete MCP) and whether it is available. For Figma, say which server it is,
|
|
71
89
|
because a UI task checks it before it starts (#358): `figma-desktop` (the Dev Mode MCP server inside the
|
|
72
90
|
running desktop app — the app must be open), `figma` (Figma's hosted server — a sign-in, no app), or
|
|
73
|
-
`html-to-design` (writes screens only, cannot read a frame). For Pencil, `pencil-mcp`. The older value
|
|
91
|
+
`html-to-design` (writes screens only, cannot read a frame). For Pencil, `pencil-mcp`. For OpenPencil, `openpencil-cli` (or `openpencil-mcp`, above). The older value
|
|
74
92
|
`figma-mcp` does not say which Figma server it is: on a refresh, record the exact one. **Auth is the local user's own** — the user's authenticated MCP session. The skill
|
|
75
93
|
**stores no tokens**; `project_url`/`files` are plain references, never credentials.
|
|
76
94
|
|
|
77
|
-
**
|
|
95
|
+
**Offer to connect it first (E165):** when the tool is not found, run `yad toolbox connect <tool> --json`
|
|
96
|
+
and follow the connect-tool rule: show its `ask` word for word, ask once, and on a yes run only its `agent`
|
|
97
|
+
steps, hand over its `person` steps, then run the `verify` command it gives (`yad toolbox connect <tool> --verify --json`,
|
|
98
|
+
with `--replace` only when its question said which tool it replaces). Never install
|
|
99
|
+
it any other way. When `--verify` passes, detect again — you can reach the tool when you find
|
|
100
|
+
its MCP server in your session (in Claude Code, `/mcp`), or for OpenPencil its CLI on PATH. **If you can**, go on to Step 2 and record what you found. **If you cannot**, the server is
|
|
101
|
+
most likely just added: a new MCP server is loaded when the agent starts. Then do **not** write the file:
|
|
102
|
+
skip the degrade below and Step 2, and in Step 3 tell the person to restart the agent and run this skill
|
|
103
|
+
again with `action: refresh` and the same `tool`. On a no, or when a step fails, degrade:
|
|
104
|
+
|
|
105
|
+
**Graceful degradation** (never right after a `--verify` that passed — see above)**:** if no design-tool MCP is available (for OpenPencil: neither its CLI on PATH nor
|
|
106
|
+
its MCP), record `source: "unavailable"` and report
|
|
78
107
|
that `yad-ui` will run **markdown-only** until an MCP is connected (no error — the design tool is purely
|
|
79
|
-
additive, exactly like Impeccable being absent).
|
|
108
|
+
additive, exactly like Impeccable being absent).
|
|
80
109
|
|
|
81
110
|
### Step 2 — Record the connection in the registry
|
|
82
111
|
Upsert into `{project-root}/.sdlc/design.json` (create the file + parent `.sdlc/` if absent):
|
|
@@ -102,11 +131,14 @@ Upsert into `{project-root}/.sdlc/design.json` (create the file + parent `.sdlc/
|
|
|
102
131
|
### Step 3 — Report (never auto-advance)
|
|
103
132
|
Report the connected `tool`, its `provider`, whether the MCP is available (or that `yad-ui` will degrade
|
|
104
133
|
to markdown-only), the `project_url`, and that **`yad-ui` will now generate/link the design here**.
|
|
105
|
-
Nothing auto-advances; this is setup.
|
|
134
|
+
Nothing auto-advances; this is setup. **Right after a `--verify` that passed but could not reach the
|
|
135
|
+
tool yet:** report only that it is installed and recorded as the team's tool, that its server loads when the
|
|
136
|
+
agent starts, and that the person restarts the agent and runs this skill again with `action: refresh` and the same `tool` —
|
|
137
|
+
not what `yad-ui` will do, which that refresh decides.
|
|
106
138
|
|
|
107
139
|
## Other actions
|
|
108
140
|
|
|
109
|
-
- **`refresh`** — re-detect the MCP and update `lastSyncedAt` (after the user authenticates a session or
|
|
141
|
+
- **`refresh`** — re-detect the MCP (for OpenPencil, the CLI first) and update `lastSyncedAt` (after the user authenticates a session or
|
|
110
142
|
changes tools). Same machinery as `connect`. Re-detection may flip `source` between an MCP id and
|
|
111
143
|
`unavailable` — report the change.
|
|
112
144
|
- **`list`** — print the current connection: `tool`, `provider`, `project_url`, the file mapping, and a
|
|
@@ -8,18 +8,20 @@ analogue of `yad-connect-repos`'s code-context.
|
|
|
8
8
|
## Provider detection
|
|
9
9
|
|
|
10
10
|
`connect`/`refresh` records `provider` (the concrete MCP) and `source` (the MCP id, or `unavailable`).
|
|
11
|
-
Detection is best-effort against the user's own authenticated MCP session
|
|
11
|
+
Detection is best-effort against the user's own authenticated MCP session (for OpenPencil, its CLI on
|
|
12
|
+
PATH first):
|
|
12
13
|
|
|
13
14
|
| `tool` | MCP / provider | Capability |
|
|
14
15
|
|--------|----------------|------------|
|
|
15
16
|
| `figma` | a Figma Dev Mode MCP | **read/link** — reference a file, read frames back into `ui-design.md` |
|
|
16
17
|
| `figma` | html.to.design MCP (`import-html`) | **generate** — render HTML/CSS screens into a Figma file |
|
|
17
18
|
| `pencil` | the `pencil` MCP (`batch_design`) | **generate** — author `.pen` web/mobile screens directly |
|
|
19
|
+
| `openpencil` | its CLI (`openpencil eval … --write`), or its MCP while the desktop app is open | **generate** — create frames in the epic's design file in the repo, then save it |
|
|
18
20
|
| other | the adapter's named MCP | per that adapter |
|
|
19
21
|
|
|
20
22
|
**Honest capability note:** not every design-tool MCP can *write*. A read-only Figma Dev Mode MCP
|
|
21
23
|
supports **link + read-back** only; *generate* needs a write-capable provider (html.to.design for Figma,
|
|
22
|
-
or `
|
|
24
|
+
`pencil` or `openpencil`). `yad-ui` picks the direction the connected provider actually supports and records which one
|
|
23
25
|
it used (`direction: generated | linked`). It never claims to have generated screens a read-only MCP
|
|
24
26
|
cannot produce.
|
|
25
27
|
|
|
@@ -32,6 +34,19 @@ tool, covering the screens/states `ui-design.md` enumerates and the user flows t
|
|
|
32
34
|
then imports it into the Figma file via the MCP's `import-html`, one frame per screen.
|
|
33
35
|
- **pencil** — the lens calls `batch_design` to author the screens as `.pen` frames directly (mobile
|
|
34
36
|
and/or web per the epic).
|
|
37
|
+
- **openpencil** — the lens writes the screens into the epic's design file, `epics/EP-<slug>/design/<name>.fig`,
|
|
38
|
+
one frame per screen. `eval` cannot create a file: the first time, make it with
|
|
39
|
+
`openpencil import <seed.html> -o epics/EP-<slug>/design/<name>.fig` (a small HTML page, such as the first
|
|
40
|
+
screen), then add each frame with `openpencil eval <file> --stdin --write` (Figma
|
|
41
|
+
Plugin API code, run on the file with no app open). With the desktop app open on the file, the
|
|
42
|
+
`open-pencil` MCP may be used instead. **Give each frame yad's own ID:** OpenPencil numbers nodes in the
|
|
43
|
+
order it loads them, so its own node IDs change when the file is reopened after a frame is deleted or
|
|
44
|
+
added — and an old ID can then name another frame. Store a plain, unique ID on each frame with
|
|
45
|
+
`frame.setSharedPluginData('yad', 'nodeId', '<id>')` (for example `checkout-mobile`), and record that as
|
|
46
|
+
the screen's `nodeId`. Every read finds the frame by it:
|
|
47
|
+
`figma.root.findAll((n) => n.getSharedPluginData('yad', 'nodeId') === '<id>')`. `yad fold` commits the
|
|
48
|
+
`design/` folder with the UI review, and the review covers it: a change to the design file after
|
|
49
|
+
approval needs a fresh review.
|
|
35
50
|
|
|
36
51
|
Reuse what already exists: load the connected code repos' code-maps (`yad-ui` Step 2b) and any
|
|
37
52
|
Impeccable `DESIGN.md` tokens so generated screens match built components, not invented ones.
|
|
@@ -58,8 +73,10 @@ purely additive.
|
|
|
58
73
|
|
|
59
74
|
## Reachable before Build (#358)
|
|
60
75
|
|
|
61
|
-
A design tool read through its running desktop app — Pencil,
|
|
62
|
-
read while the app is closed or the design file is not open
|
|
76
|
+
A design tool read through its running desktop app — Pencil, Figma's `figma-desktop` server, or
|
|
77
|
+
OpenPencil's MCP server — cannot be read while the app is closed or the design file is not open; a
|
|
78
|
+
hosted server needs a sign-in; and a CLI that works on the file (OpenPencil's) needs the file and the
|
|
79
|
+
program. So before a UI task, `yad-spec` and
|
|
63
80
|
`yad-implement` check it first, and stop early when it fails. yad itself cannot call an MCP server (it
|
|
64
81
|
belongs to the agent's session), so `yad story frames <story> --json` returns a `preflight` block that says
|
|
65
82
|
how to check and what to tell the person; the text for each tool is the toolbox entry's `reach` field.
|
|
@@ -71,17 +88,30 @@ how to check and what to tell the person; the text for each tool is the toolbox
|
|
|
71
88
|
| `figma`, provider `figma` (hosted) | `get_metadata` on one recorded frame | sign in to Figma in your agent; no app is needed |
|
|
72
89
|
| `figma`, provider `figma-mcp` (older value), any other name, or none | `get_metadata` on one recorded frame | either of the two above — yad cannot tell which server it is |
|
|
73
90
|
| `figma`, provider `html-to-design` | nothing: it writes screens and cannot read a frame | not checked; build from the frame links |
|
|
91
|
+
| `openpencil`, provider `openpencil-cli` | the design file is in the Product checkout, `openpencil --version` runs, and `openpencil eval` on the file finds the frame whose shared plugin data `yad`/`nodeId` is the recorded ID. No app, no sign-in | pull the Product so the file is there with the frame in it, and make sure `openpencil` runs |
|
|
92
|
+
| `openpencil`, provider `openpencil-mcp` | the MCP's `eval` tool finds the frame by its stored `yad`/`nodeId` | open the OpenPencil desktop app with the file loaded (inside `OPENPENCIL_MCP_ROOT`) |
|
|
93
|
+
| `openpencil`, no provider or another name | the CLI check above, and the MCP check when that does not find the frame | either of the two above |
|
|
74
94
|
|
|
75
95
|
Also not checked (build from the frame links): no `design.json`, tool `none`, source `unavailable`; no
|
|
76
96
|
`design-links.json`, one that cannot be read, or one recorded for another tool (re-run the UI step); and a
|
|
77
97
|
story whose recorded frame IDs are all missing from `design-links.json` — the bad IDs are the problem then.
|
|
78
98
|
|
|
99
|
+
When the check fails because the tool is not on this machine at all (no such MCP server in the agent's
|
|
100
|
+
session), the skill first offers `preflight.connect` — `yad toolbox connect <tool> --json`, under the
|
|
101
|
+
connect-tool rule — and checks again once it is found (E165). A closed app, the wrong file or a sign-in
|
|
102
|
+
is never offered: those are the person's. Nor is Figma's `figma-desktop` provider: it is the desktop app's
|
|
103
|
+
own server, and Figma's connect step sets up the hosted one, so the person opens the app instead
|
|
104
|
+
(OpenPencil's MCP server is offered: its connect step adds it). An
|
|
105
|
+
older `design.json` that names no provider (or `figma-mcp`) is still offered the hosted one: the question
|
|
106
|
+
names what it installs, so a person who uses the desktop app says no. A server just added is seen only
|
|
107
|
+
after the agent restarts (check `/mcp`); until then the skill says so and stops.
|
|
108
|
+
|
|
79
109
|
A failed check stops the step. The person may choose to go on from the frame links only; that choice is
|
|
80
110
|
recorded (in `spec.md`'s Clarifications, or the commit's Decisions paragraph).
|
|
81
111
|
|
|
82
112
|
## Staleness / refresh
|
|
83
113
|
|
|
84
114
|
A re-generated or designer-edited file is like a moved code repo: `yad-ui` **flags** a divergence and
|
|
85
|
-
lets a human decide (re-run the step, or `yad-connect-design` action: refresh). It never silently
|
|
115
|
+
lets a human decide (re-run the step, or `yad-connect-design` with `action: refresh` and the same `tool`). It never silently
|
|
86
116
|
overwrites a designer's frames — refreshing the design is a human decision, the same discipline as
|
|
87
117
|
`code_context.refresh: human`.
|
|
@@ -14,8 +14,8 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
|
|
|
14
14
|
|
|
15
15
|
```json
|
|
16
16
|
{
|
|
17
|
-
"tool": "figma", // figma | pencil | <adapter id> | none (markdown-only)
|
|
18
|
-
"provider": "figma-desktop", // the concrete MCP: figma-desktop | figma | html-to-design | pencil-mcp | null (figma-mcp: older, either Figma server)
|
|
17
|
+
"tool": "figma", // figma | pencil | openpencil | <adapter id> | none (markdown-only)
|
|
18
|
+
"provider": "figma-desktop", // the concrete MCP: figma-desktop | figma | html-to-design | pencil-mcp | openpencil-cli | openpencil-mcp | null (figma-mcp: older, either Figma server)
|
|
19
19
|
"project_url": "https://www.figma.com/files/project/123/feature", // team/project/file reference; null if none yet
|
|
20
20
|
"auth": "user", // ALWAYS the user's own MCP session — never a token
|
|
21
21
|
"files": { "web": null, "mobile": null }, // optional default file refs per platform
|
|
@@ -36,7 +36,7 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
|
|
|
36
36
|
session.
|
|
37
37
|
- **`connect` overwrites in place** — a project carries exactly one design connection at a time;
|
|
38
38
|
switching tools is just another `connect`. There is no array (unlike `repos.json`).
|
|
39
|
-
- **`source`** is the authority for availability: an MCP id (`figma-desktop` / `figma` / `pencil-mcp` / …) means
|
|
39
|
+
- **`source`** is the authority for availability: an MCP id (`figma-desktop` / `figma` / `pencil-mcp` / `openpencil-cli` / `openpencil-mcp` / …) means
|
|
40
40
|
`yad-ui` can generate/link; `unavailable` means `yad-ui` degrades to markdown-only. `refresh`
|
|
41
41
|
re-detects and may flip it.
|
|
42
42
|
- **`tool: "none"`** is a valid, deliberate state: a project that has chosen markdown-only. `yad-ui`
|
|
@@ -24,6 +24,10 @@ explains the concept. The learning layer is **purely opt-in and never blocks a g
|
|
|
24
24
|
No tool below is required. When one is missing, this skill still finishes, using the fallback written
|
|
25
25
|
beside it.
|
|
26
26
|
|
|
27
|
+
Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
|
|
28
|
+
by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
|
|
29
|
+
connect-tool rule. On a no, or when a step fails, use the fallback.
|
|
30
|
+
|
|
27
31
|
Tell the person which tools you used and which fallbacks, and why.
|
|
28
32
|
|
|
29
33
|
- **DeepTutor** (`deeptutor`, a connector). This skill connects it, by writing `.sdlc/learning.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
|
|
@@ -39,7 +43,8 @@ Tell the person which tools you used and which fallbacks, and why.
|
|
|
39
43
|
harness model).
|
|
40
44
|
- **DeepTutor is reached as a CLI SUBPROCESS** (`deeptutor …`), the same shape as Repomix's `npx` — NOT
|
|
41
45
|
an MCP like the design/testing tools (DeepTutor ships no MCP server). The skill detects the **binary on
|
|
42
|
-
PATH** and
|
|
46
|
+
PATH** and, when it is absent, offers to connect it with `yad toolbox connect deeptutor` (E165) before it
|
|
47
|
+
degrades; it never installs DeepTutor another way.
|
|
43
48
|
- Registry: `{project-root}/.sdlc/learning.json` (project-wide, shared across all epics — NOT per-epic),
|
|
44
49
|
the sibling of `.sdlc/repos.json`, `.sdlc/product.json`, `.sdlc/design.json`, and `.sdlc/testing.json`.
|
|
45
50
|
- Per-epic, per-member learning records + rendered tutorials are written later by `yad-learn`
|
|
@@ -70,10 +75,15 @@ way `registerRepo`/`registerDesign` fall back). Then **detect the tool's CLI on
|
|
|
70
75
|
**Auth is the local user's own** — DeepTutor's own config (`deeptutor init`, `data/user/settings/`) and
|
|
71
76
|
the user's LLM provider keys. The skill **stores no tokens**; `kb`/`kb_sources` are plain references.
|
|
72
77
|
|
|
78
|
+
**Offer to connect it first (E165):** when DeepTutor is not found, run `yad toolbox connect deeptutor --json`
|
|
79
|
+
and follow the connect-tool rule: show its `ask` word for word, ask once, hand over its `person` steps (its
|
|
80
|
+
install and `deeptutor init` are the person's), then run the `verify` command it gives (`yad toolbox connect deeptutor --verify --json`).
|
|
81
|
+
On a no, or when a step fails, degrade:
|
|
82
|
+
|
|
73
83
|
**Graceful degradation:** if the `deeptutor` binary is not on PATH, record `source: "harness-native"`
|
|
74
84
|
and report that `yad-learn` will still tutor **using the harness model reading the project artifacts**
|
|
75
85
|
(no error — the learning layer is additive and always works; DeepTutor only adds knowledge-base
|
|
76
|
-
grounding, quizzes, and deep research).
|
|
86
|
+
grounding, quizzes, and deep research).
|
|
77
87
|
|
|
78
88
|
### Step 2 — Ground it in the project (optional, when DeepTutor is available)
|
|
79
89
|
When `ground: true` and DeepTutor is available, build or refresh a project **knowledge base** so tutoring
|
|
@@ -34,6 +34,10 @@ there are found.
|
|
|
34
34
|
- **When yad cannot answer** (yad is not installed here, or the command fails), use the check in the
|
|
35
35
|
steps below.
|
|
36
36
|
|
|
37
|
+
Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
|
|
38
|
+
by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
|
|
39
|
+
connect-tool rule. On a no, or when a step fails, use the fallback.
|
|
40
|
+
|
|
37
41
|
Tell the person which tools you used and which fallbacks, and why.
|
|
38
42
|
|
|
39
43
|
- **Repomix** (`repomix`). 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 repomix`) — use the fallback.
|
|
@@ -192,6 +196,20 @@ locally only.
|
|
|
192
196
|
Report the connected repo, its `platform`, the pack + code-map paths, the secret-scan result, and that
|
|
193
197
|
the Shape phases will now load this repo's code-map. Nothing auto-advances; this is setup.
|
|
194
198
|
|
|
199
|
+
Optionally, offer to build the **project brain** (E176) — one knowledge graph of the code and the work
|
|
200
|
+
items, on this machine only: **`yad brain build`**. It runs Graphify in each connected repo with its LLM
|
|
201
|
+
pass off (code is parsed locally; nothing leaves the machine), writes `.sdlc/brain/`, which ignores
|
|
202
|
+
itself, and commits nothing. Without Graphify it builds the work items alone and says how to install it
|
|
203
|
+
(`yad toolbox connect graphify`). Then `yad brain query <text>` answers "which story touches this file?",
|
|
204
|
+
and `yad brain view --open` draws the graph in the person's browser (E177): a local page only this machine
|
|
205
|
+
can reach, until Ctrl-C. It keeps running, so start it for the person to open rather than waiting on it; or
|
|
206
|
+
use `yad brain view --html --open`, which writes one offline file and returns.
|
|
207
|
+
To watch an agent work through the brain live (E178), the Product sets `"activity": true` and runs
|
|
208
|
+
`yad check --fix`; then `yad brain view --live --open` shows each file the agent reads, searches or edits
|
|
209
|
+
against the task's declared files. It records what the agent did, never why.
|
|
210
|
+
Once built, the planning and building skills ask it themselves (E179): `yad brain file <repo>/<path>`
|
|
211
|
+
(who declares a file, what uses it) and `yad brain story <id>` (a story's tasks and their files).
|
|
212
|
+
|
|
195
213
|
## Other actions
|
|
196
214
|
|
|
197
215
|
- **`refresh`** — re-run Steps 2–4 (including Step 3b) for an already-connected repo (after its code moves). A new directory gets an `unset` line and a guess; a `confirmed` line is only ever suggested against. Updates
|
|
@@ -23,6 +23,10 @@ connected, `yad-test-cases` runs artifacts-only exactly as before.
|
|
|
23
23
|
No tool below is required. When one is missing, this skill still finishes, using the fallback written
|
|
24
24
|
beside it.
|
|
25
25
|
|
|
26
|
+
Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
|
|
27
|
+
by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
|
|
28
|
+
connect-tool rule. On a no, or when a step fails, use the fallback.
|
|
29
|
+
|
|
26
30
|
Tell the person which tools you used and which fallbacks, and why.
|
|
27
31
|
|
|
28
32
|
- **Playwright MCP** (`playwright`, a connector). This skill connects it, by writing `.sdlc/testing.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
|
|
@@ -44,7 +48,8 @@ Tell the person which tools you used and which fallbacks, and why.
|
|
|
44
48
|
primary provider; `cypress`, `pytest` and `maestro` are second providers; `none` → artifacts-only.
|
|
45
49
|
- **The testing tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the
|
|
46
50
|
same shape as the design tool's MCP, not Repomix's `npx`. The skill detects the MCP and degrades when
|
|
47
|
-
it is absent; it never installs
|
|
51
|
+
it is absent, offering first to connect it with `yad toolbox connect` (E165); it never installs anything
|
|
52
|
+
another way.
|
|
48
53
|
- Registry: `{project-root}/.sdlc/testing.json` (project-wide, shared across all epics — NOT per-epic),
|
|
49
54
|
the sibling of `.sdlc/repos.json`, `.sdlc/product.json`, and `.sdlc/design.json`.
|
|
50
55
|
- Per-epic test→suite links are written later by `yad-test-cases`
|
|
@@ -81,10 +86,19 @@ Record `provider` (the concrete MCP, e.g. `playwright-mcp` | `cypress-mcp` | `py
|
|
|
81
86
|
it is available. **Auth is the local user's own** — the user's authenticated MCP session. The skill
|
|
82
87
|
**stores no tokens**; `project_url`/`suites` are plain references, never credentials.
|
|
83
88
|
|
|
84
|
-
**
|
|
89
|
+
**Offer to connect it first (E165):** when the tool is not found, run `yad toolbox connect <tool> --json`
|
|
90
|
+
and follow the connect-tool rule: show its `ask` word for word, ask once, and on a yes run only its `agent`
|
|
91
|
+
steps, hand over its `person` steps, then run the `verify` command it gives (`yad toolbox connect <tool> --verify --json`,
|
|
92
|
+
with `--replace` only when its question said which tool it replaces). Never install
|
|
93
|
+
it any other way. When `--verify` passes, detect again — you can reach the tool when you find
|
|
94
|
+
its MCP server in your session (in Claude Code, `/mcp`). **If you can**, go on to Step 2 and record what you found. **If you cannot**, the server is
|
|
95
|
+
most likely just added: a new MCP server is loaded when the agent starts. Then do **not** write the file:
|
|
96
|
+
skip the degrade below and Step 2, and in Step 3 tell the person to restart the agent and run this skill
|
|
97
|
+
again with `action: refresh` and the same `tool`. On a no, or when a step fails, degrade:
|
|
98
|
+
|
|
99
|
+
**Graceful degradation** (never right after a `--verify` that passed — see above)**:** if no testing-tool MCP is available, record `source: "unavailable"` and report
|
|
85
100
|
that `yad-test-cases` will run **artifacts-only** until an MCP is connected (no error — the testing tool
|
|
86
|
-
is purely additive, exactly like the design tool being absent).
|
|
87
|
-
of this step.
|
|
101
|
+
is purely additive, exactly like the design tool being absent).
|
|
88
102
|
|
|
89
103
|
### Step 2 — Record the connection in the registry
|
|
90
104
|
Upsert into `{project-root}/.sdlc/testing.json` (create the file + parent `.sdlc/` if absent):
|
|
@@ -110,7 +124,10 @@ Upsert into `{project-root}/.sdlc/testing.json` (create the file + parent `.sdlc
|
|
|
110
124
|
### Step 3 — Report (never auto-advance)
|
|
111
125
|
Report the connected `tool`, its `provider`, whether the MCP is available (or that `yad-test-cases` will
|
|
112
126
|
degrade to artifacts-only), the `project_url`, and that **`yad-test-cases` will now generate/link the
|
|
113
|
-
automation tests here**. Nothing auto-advances; this is setup.
|
|
127
|
+
automation tests here**. Nothing auto-advances; this is setup. **Right after a `--verify` that passed but could not reach the
|
|
128
|
+
tool yet:** report only that it is installed and recorded as the team's tool, that its server loads when the
|
|
129
|
+
agent starts, and that the person restarts the agent and runs this skill again with `action: refresh` and the same `tool` —
|
|
130
|
+
not what `yad-test-cases` will do, which that refresh decides.
|
|
114
131
|
|
|
115
132
|
## Other actions
|
|
116
133
|
|
|
@@ -67,6 +67,6 @@ purely additive.
|
|
|
67
67
|
## Staleness / refresh
|
|
68
68
|
|
|
69
69
|
A re-generated or hand-edited suite is like a moved code repo: `yad-test-cases` **flags** a divergence
|
|
70
|
-
and lets a human decide (re-run the step, or `yad-connect-testing` action: refresh). It never silently
|
|
70
|
+
and lets a human decide (re-run the step, or `yad-connect-testing` with `action: refresh` and the same `tool`). It never silently
|
|
71
71
|
overwrites a hand-written suite — refreshing the automation is a human decision, the same discipline as
|
|
72
72
|
`code_context.refresh: human`.
|
|
@@ -162,6 +162,17 @@ each `yad-epic` reads (its "Step 2c"). When the Product has a platform, the gate
|
|
|
162
162
|
Product (via `yad-product-bridge`) and `yad-review-gate action: sync` pulls platform approvals and comments
|
|
163
163
|
into the ledger; otherwise the review is recorded locally.
|
|
164
164
|
|
|
165
|
+
**Once the review has passed and the Product has a platform, offer to publish the roadmap** (E174). Ask the
|
|
166
|
+
person, then run `yad foundation publish --dry-run` to show what it would create, then `yad foundation publish`.
|
|
167
|
+
It opens one issue or work item per roadmap feature in the Product repo: type feature, a priority by phase
|
|
168
|
+
(the first phase, the MVP, is P1; the next P2; later ones P3), the label `epic: EP-x`, and the phase as its
|
|
169
|
+
milestone. The `Later / parked` phase is left out. If the Foundation changed after its review, the command refuses:
|
|
170
|
+
the changed roadmap needs a new review first. Report the links, and remind the person to commit
|
|
171
|
+
`foundation/.sdlc/roadmap-items.json` on a branch of its own, not a `review/…` one, and open a pull request
|
|
172
|
+
(`chore: record tracker links`). A review branch would advance a step. On a verified Product, the Product
|
|
173
|
+
checks let a pull request of that file, the epics' `.sdlc/issue-links.json` files and step owner files alone
|
|
174
|
+
through from any branch (#512), once a `yad update` carrying that rule has merged on the default branch.
|
|
175
|
+
|
|
165
176
|
## Reference
|
|
166
177
|
- Foundation section templates: `references/foundation-schema.md`.
|
|
167
178
|
- The older spelling of the Product level (`EP-discovery`, its six files, and how it converts):
|