archgen-mcp 0.0.7 → 0.1.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.
Files changed (42) hide show
  1. package/README.md +2 -6
  2. package/assets/briefs/investigate.md +16 -17
  3. package/assets/briefs/review.md +41 -29
  4. package/assets/briefs/survey.md +17 -20
  5. package/assets/briefs/verifier.md +52 -40
  6. package/assets/harness-mcp.json +6 -6
  7. package/assets/platform-capabilities.json +387 -71
  8. package/assets/references/artifact-templates.md +67 -232
  9. package/assets/references/interview.md +83 -199
  10. package/assets/references/mcp-and-skills.md +35 -125
  11. package/assets/references/orchestration.md +96 -209
  12. package/assets/references/platforms.md +41 -110
  13. package/assets/skill-registry.json +10 -1
  14. package/assets/templates/adr.md +3 -3
  15. package/assets/templates/architecture.yaml +31 -28
  16. package/assets/templates/edge-matrix.md +8 -8
  17. package/assets/templates/mermaid.md +3 -10
  18. package/assets/templates/prd.md +15 -15
  19. package/assets/templates/tasks.yaml +25 -18
  20. package/package.json +2 -2
  21. package/src/cli.mjs +1 -2
  22. package/src/context.mjs +12 -42
  23. package/src/core/brief-context.mjs +106 -0
  24. package/src/core/brief-scope.mjs +218 -0
  25. package/src/core/briefs.mjs +109 -1
  26. package/src/core/codegraph-manager.mjs +12 -0
  27. package/src/core/doc-navigator.mjs +101 -17
  28. package/src/core/errors.mjs +1 -1
  29. package/src/core/harness-wiring.mjs +65 -22
  30. package/src/core/jsonc-config.mjs +706 -0
  31. package/src/core/plan-grapher.mjs +11 -3
  32. package/src/core/skill-manager.mjs +181 -13
  33. package/src/core/skill-roots.mjs +92 -0
  34. package/src/core/tokens.mjs +78 -0
  35. package/src/core/worker-contract.mjs +145 -18
  36. package/src/server.mjs +0 -3
  37. package/src/tools/help.mjs +17 -34
  38. package/src/tools/plan.mjs +36 -22
  39. package/src/tools/skills.mjs +67 -5
  40. package/src/tools/tasks.mjs +44 -18
  41. package/src/core/ui-channel.mjs +0 -222
  42. package/src/tools/ui.mjs +0 -67
@@ -98,10 +98,18 @@ export function resolvePlanScope(input, projectRoot = null) {
98
98
 
99
99
  /**
100
100
  * Load + normalize the plan graph.
101
+ *
102
+ * The project root is an EXPLICIT parameter. It used to be read from `opts` —
103
+ * a name that exists only in the CALLER's scope — so every call to this
104
+ * function threw `ReferenceError: opts is not defined` and the whole
105
+ * `archgen_plan{action:'graph'}` action was dead on arrival. A module-level
106
+ * function must never read a variable from its caller's frame.
107
+ *
101
108
  * @param {string} input slug dir or tasks.yaml path
109
+ * @param {string|null} projectRoot the project root the artifact space must be inside
102
110
  */
103
- function loadPlan(input) {
104
- const { root, slug, tasksFile } = resolvePlanScope(input, opts.projectRoot ?? null);
111
+ function loadPlan(input, projectRoot = null) {
112
+ const { root, slug, tasksFile } = resolvePlanScope(input, projectRoot);
105
113
 
106
114
  let raw;
107
115
  try {
@@ -224,7 +232,7 @@ export function planGraph(input, opts = {}) {
224
232
  }
225
233
  if (status && !mermaid) throw invalidInput('status requires mermaid');
226
234
 
227
- const plan = loadPlan(input);
235
+ const plan = loadPlan(input, opts.projectRoot ?? null);
228
236
  const { uniqueTasks, duplicatesCollapsed, quality, byId, prerequisites, dependents, waves, root, slug, tasksFile } = plan;
229
237
  const byIdAsc = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
230
238
 
@@ -19,6 +19,7 @@ import { spawnSync } from 'node:child_process';
19
19
  import { existsSync, readFileSync } from 'node:fs';
20
20
  import { homedir } from 'node:os';
21
21
  import { join } from 'node:path';
22
+ import { skillSearchPaths } from './skill-roots.mjs';
22
23
 
23
24
  /**
24
25
  * Registry shape (see assets/skill-registry.json).
@@ -66,6 +67,7 @@ export function matchSkills(registry, task) {
66
67
  slug: entry.slug,
67
68
  repo: entry.repo,
68
69
  purpose: entry.purpose,
70
+ domain: entry.domain ?? entry.family ?? 'Capability',
69
71
  policy: entry.policy,
70
72
  matched,
71
73
  });
@@ -116,14 +118,30 @@ export function skillInstallPaths(projectRoot, slug, opts = {}) {
116
118
 
117
119
  /**
118
120
  * Is a capability skill already installed for this project?
119
- * @returns {{installed: boolean, path: string|null, scope: 'project'|'global'|null}}
121
+ *
122
+ * The SEARCH walks the same roots the archgen skill itself is resolved from
123
+ * (core/skill-roots.mjs): the project chain upward, across every harness
124
+ * directory, then the user-global roots.
125
+ *
126
+ * It used to look at exactly ONE path — `<projectRoot>/.agents/skills/<slug>/
127
+ * SKILL.md` — so a skill installed one level up, or under a harness-specific
128
+ * directory, was reported as "not installed" by the very tool that had just
129
+ * installed it. `archgen_skills{action:'load'}` then returned
130
+ * `loaded:false` for a skill that was sitting on disk.
131
+ *
132
+ * @returns {{installed: boolean, path: string|null, scope: 'project'|'global'|null, searchedPaths: string[]}}
120
133
  */
121
134
  export function findInstalledSkill(projectRoot, slug, opts = {}) {
122
- const project = skillInstallPaths(projectRoot, slug, { global: false }).skillFile;
123
- if (existsSync(project)) return { installed: true, path: project, scope: 'project' };
124
- const global = skillInstallPaths(projectRoot, slug, { global: true, home: opts.home }).skillFile;
125
- if (existsSync(global)) return { installed: true, path: global, scope: 'global' };
126
- return { installed: false, path: null, scope: null };
135
+ const home = opts.home ?? homedir();
136
+ const searched = [];
137
+ for (const candidate of skillSearchPaths(projectRoot, slug, { home })) {
138
+ const file = join(candidate.dir, 'SKILL.md');
139
+ searched.push(file);
140
+ if (existsSync(file)) {
141
+ return { installed: true, path: file, scope: candidate.scope, searchedPaths: searched };
142
+ }
143
+ }
144
+ return { installed: false, path: null, scope: null, searchedPaths: searched.slice(0, 24) };
127
145
  }
128
146
 
129
147
  /**
@@ -271,20 +289,36 @@ export async function installSkill(opts) {
271
289
  * Load a skill's SKILL.md so it can be injected into a worker prompt.
272
290
  *
273
291
  * @param {{projectRoot: string, slug: string, home?: string}} opts
274
- * @returns {{loaded: boolean, path: string|null, scope: string|null, content: string|null, bytes: number}}
292
+ * @returns {{loaded: boolean, path: string|null, scope: string|null, content: string|null, bytes: number, searchedPaths: string[]}}
275
293
  */
276
294
  export function loadSkill(opts) {
277
295
  const found = findInstalledSkill(opts.projectRoot, opts.slug, { home: opts.home });
278
296
  if (!found.installed || !found.path) {
279
- return { loaded: false, path: null, scope: null, content: null, bytes: 0 };
297
+ return {
298
+ loaded: false,
299
+ path: null,
300
+ scope: null,
301
+ content: null,
302
+ bytes: 0,
303
+ // Where the tool looked — so "not installed" is diagnosable in ONE call
304
+ // instead of two.
305
+ searchedPaths: found.searchedPaths ?? [],
306
+ };
280
307
  }
281
308
  let content;
282
309
  try {
283
310
  content = readFileSync(found.path, 'utf8');
284
311
  } catch {
285
- return { loaded: false, path: found.path, scope: found.scope, content: null, bytes: 0 };
312
+ return { loaded: false, path: found.path, scope: found.scope, content: null, bytes: 0, searchedPaths: found.searchedPaths ?? [] };
286
313
  }
287
- return { loaded: true, path: found.path, scope: found.scope, content, bytes: content.length };
314
+ return {
315
+ loaded: true,
316
+ path: found.path,
317
+ scope: found.scope,
318
+ content,
319
+ bytes: content.length,
320
+ searchedPaths: found.searchedPaths ?? [],
321
+ };
288
322
  }
289
323
 
290
324
  /**
@@ -303,9 +337,143 @@ export function listInstalled(opts) {
303
337
  }
304
338
 
305
339
  /**
306
- * The follow-instruction injected into a worker prompt (the registry's
307
- * canonical wording, so every worker gets the same contract).
340
+ * The ONE wording for "follow this capability skill".
341
+ *
342
+ * The wording used to exist in THREE places with three different texts —
343
+ * the worker contract, this module, and references/mcp-and-skills.md — and
344
+ * the contract's copy shipped the literal `<Domain>` placeholder into every
345
+ * worker prompt. One owner, one sentence, no placeholder.
346
+ *
347
+ * @param {{slug?: string, path?: string|null, domain?: string|null}} entry
348
+ * @returns {string}
349
+ */
350
+ export function skillDirective(entry) {
351
+ const slug = entry?.slug ?? 'the skill';
352
+ const path = entry?.path ?? `.agents/skills/${slug}/SKILL.md`;
353
+ const domain = entry?.domain ?? 'Capability';
354
+ return `${domain} work: follow ${path} (installed via FETCH-SKILL) — apply its standards to every relevant decision.`;
355
+ }
356
+
357
+ /**
358
+ * The follow-instruction injected into a worker prompt.
359
+ *
360
+ * Kept as the historical name; it is now a thin alias of `skillDirective`,
361
+ * which is the single owner of the wording.
308
362
  */
309
363
  export function followInstruction(entry) {
310
- return `Follow ${entry.path ?? `.agents/skills/${entry.slug}/SKILL.md`} for this work — apply its standards to every relevant decision.`;
364
+ return skillDirective(entry);
365
+ }
366
+
367
+ /**
368
+ * The NORMATIVE rules of a skill — the lines that carry a MUST, SHOULD,
369
+ * NEVER, ALWAYS, REQUIRED or DO NOT.
370
+ *
371
+ * WHY A SEMANTIC FILTER AND NOT A SIZE CAP: a cap is a guess about how much
372
+ * is enough, and a guess cuts a skill's rules in half — the worker then
373
+ * complies with the half it was shown. A rule filter is not a guess: it
374
+ * selects the lines that actually change a decision, and leaves the prose
375
+ * (the "How to use", the intro, the examples) behind, because prose does not
376
+ * change what a worker builds.
377
+ *
378
+ * The result is the skill's real operative content — complete, never
379
+ * truncated. How much of it reaches a given prompt is the AGENT's call: the
380
+ * worker contract carries the rules, and `archgen_skills{action:'load',
381
+ * section}` is the lens for pulling any single section of the skill when the
382
+ * agent decides it needs more.
383
+ *
384
+ * @param {string} text the skill's SKILL.md content
385
+ * @returns {{rules: string, count: number, headings: string[]}}
386
+ */
387
+ export function skillRules(text) {
388
+ const lines = String(text ?? '').split('\n');
389
+ const rules = [];
390
+ const headings = [];
391
+ let heading = null;
392
+ let inFence = false;
393
+
394
+ for (const raw of lines) {
395
+ const line = raw.trimEnd();
396
+ // A fenced block is code, not a rule.
397
+ if (/^ {0,3}```/.test(line)) {
398
+ inFence = !inFence;
399
+ continue;
400
+ }
401
+ if (inFence) continue;
402
+ const h = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
403
+ if (h) {
404
+ heading = h[2];
405
+ headings.push(heading);
406
+ continue;
407
+ }
408
+ const bullet = /^\s*[-*]\s+(.*)$/.exec(line);
409
+ if (!bullet) continue;
410
+ const rule = bullet[1].trim();
411
+ if (!/\b(MUST|SHOULD|NEVER|ALWAYS|REQUIRED|DO NOT)\b/.test(rule)) continue;
412
+ rules.push(heading ? `[${heading}] ${rule}` : rule);
413
+ }
414
+ return { rules: rules.join('\n'), count: rules.length, headings };
415
+ }
416
+
417
+ /**
418
+ * The section index of a skill — the lens the agent drives.
419
+ *
420
+ * Same shape as `archgen_docs{action:'digest'}`: a map, not a copy. The
421
+ * agent sees every section of the skill and pulls exactly the one it needs.
422
+ *
423
+ * @param {string} text the skill's SKILL.md content
424
+ * @returns {Array<{slug: string, title: string, level: number, line: number, endLine: number, normative: boolean}>}
425
+ */
426
+ export function skillSections(text) {
427
+ const lines = String(text ?? '').split('\n');
428
+ const headings = [];
429
+ let inFence = false;
430
+ for (let i = 0; i < lines.length; i++) {
431
+ const line = lines[i];
432
+ if (/^ {0,3}```/.test(line)) {
433
+ inFence = !inFence;
434
+ continue;
435
+ }
436
+ if (inFence) continue;
437
+ const h = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
438
+ if (h) headings.push({ level: h[1].length, text: h[2], line: i + 1 });
439
+ }
440
+ const counts = new Map();
441
+ const out = [];
442
+ for (let i = 0; i < headings.length; i++) {
443
+ const h = headings[i];
444
+ const base = slugifyHeading(h.text);
445
+ if (!base) continue;
446
+ const n = counts.get(base) ?? 0;
447
+ counts.set(base, n + 1);
448
+ const slug = n === 0 ? base : `${base}-${n}`;
449
+ let endLine = lines.length;
450
+ for (let j = i + 1; j < headings.length; j++) {
451
+ if (headings[j].level <= h.level) {
452
+ endLine = headings[j].line - 1;
453
+ break;
454
+ }
455
+ }
456
+ const body = lines.slice(h.line - 1, endLine).join('\n');
457
+ out.push({
458
+ slug,
459
+ title: h.text,
460
+ level: h.level,
461
+ line: h.line,
462
+ endLine,
463
+ normative: /\b(MUST|SHOULD|NEVER|ALWAYS|REQUIRED|DO NOT)\b/.test(body),
464
+ });
465
+ }
466
+ return out;
467
+ }
468
+
469
+ /**
470
+ * GitHub-exact heading slug — the same rule the artifact lens uses, so a
471
+ * skill section slug and a plan section slug mean the same thing.
472
+ */
473
+ function slugifyHeading(text) {
474
+ return String(text)
475
+ .trim()
476
+ .toLowerCase()
477
+ .replace(/[^\p{L}\p{N}\s_-]/gu, '')
478
+ .replace(/\s/g, '-');
311
479
  }
@@ -0,0 +1,92 @@
1
+ // skill-roots.mjs — the ONE list of directories a skill can live in.
2
+ //
3
+ // WHY ONE LIST: the archgen skill and the CAPABILITY skills are installed by
4
+ // different mechanisms, but they land in the same kind of place — and each
5
+ // used to carry its own private idea of where that place is.
6
+ //
7
+ // - The archgen skill was resolved from a list that walked UP from the
8
+ // project root, across several harness directories.
9
+ // - A capability skill was only ever looked for at
10
+ // `<projectRoot>/.agents/skills/<slug>/SKILL.md`.
11
+ //
12
+ // So a capability skill installed one level up, or in a harness-specific
13
+ // directory, was reported as "not installed" by the very tool that had just
14
+ // installed it — which is why `archgen_skills{action:'load'}` could say
15
+ // "not installed" for a skill sitting on disk.
16
+ //
17
+ // ONE list, used by both, is the fix. The installer still WRITES to the
18
+ // universal `.agents/skills/` store; this list is about READING, and a read
19
+ // that misses an installed skill is the expensive failure.
20
+ import { existsSync } from 'node:fs';
21
+ import { dirname, join, resolve } from 'node:path';
22
+
23
+ /** The per-project skill roots, relative to a project directory. */
24
+ export const PROJECT_SKILL_ROOTS = [
25
+ '.agents/skills',
26
+ '.claude/skills',
27
+ '.github/skills',
28
+ '.gemini/skills',
29
+ '.cursor/skills',
30
+ '.opencode/skills',
31
+ '.codex/skills',
32
+ '.kiro/skills',
33
+ '.trae/skills',
34
+ '.windsurf/skills',
35
+ ];
36
+
37
+ /** The user-global skill roots, relative to $HOME. */
38
+ export const GLOBAL_SKILL_ROOTS = [
39
+ '.agents/skills',
40
+ '.claude/skills',
41
+ '.config/opencode/skills',
42
+ '.gemini/skills',
43
+ '.copilot/skills',
44
+ '.codex/skills',
45
+ '.kiro/skills',
46
+ '.trae/skills',
47
+ ];
48
+
49
+ /**
50
+ * Every directory a skill with this slug could be in — nearest first.
51
+ *
52
+ * The project chain is walked UP (a monorepo may install the skill at its
53
+ * root while the agent works in a nested package), then the user-global
54
+ * roots are checked.
55
+ *
56
+ * @param {string} projectRoot
57
+ * @param {string} slug the skill's directory name
58
+ * @param {{home?: string|null}} [opts]
59
+ * @returns {Array<{dir: string, scope: 'project'|'global'}>}
60
+ */
61
+ export function skillSearchPaths(projectRoot, slug, opts = {}) {
62
+ const home = opts.home ?? null;
63
+ const out = [];
64
+ let dir = resolve(projectRoot);
65
+ for (;;) {
66
+ for (const root of PROJECT_SKILL_ROOTS) out.push({ dir: join(dir, root, slug), scope: 'project' });
67
+ const parent = dirname(dir);
68
+ if (parent === dir) break;
69
+ dir = parent;
70
+ }
71
+ if (home) {
72
+ for (const root of GLOBAL_SKILL_ROOTS) out.push({ dir: join(home, root, slug), scope: 'global' });
73
+ }
74
+ return out;
75
+ }
76
+
77
+ /**
78
+ * The first skill directory that actually holds a SKILL.md.
79
+ *
80
+ * @param {string} projectRoot
81
+ * @param {string} slug
82
+ * @param {{home?: string|null}} [opts]
83
+ * @returns {{path: string, scope: 'project'|'global'}|null}
84
+ */
85
+ export function findSkillDir(projectRoot, slug, opts = {}) {
86
+ for (const candidate of skillSearchPaths(projectRoot, slug, opts)) {
87
+ if (existsSync(join(candidate.dir, 'SKILL.md'))) {
88
+ return { path: join(candidate.dir, 'SKILL.md'), scope: candidate.scope };
89
+ }
90
+ }
91
+ return null;
92
+ }
@@ -0,0 +1,78 @@
1
+ // tokens.mjs — the ONE token estimator.
2
+ //
3
+ // WHY IT LIVES HERE AND NOT ONLY IN internal/: the estimate is now part of
4
+ // the SERVER's output. Every envelope carries what the call cost, and every
5
+ // dispatch brief and worker contract carries what the prompt will cost — so
6
+ // the orchestrator can see the price of its own behaviour instead of
7
+ // discovering it at the end of a run.
8
+ //
9
+ // The repo's QA tool (`internal/tools/context-budget.mjs`) imports THIS one,
10
+ // so the number the CI gate reports and the number the server reports are
11
+ // the same number.
12
+ //
13
+ // Approximation via a BPE-style pre-tokenizer (±10% for English prose,
14
+ // markdown and YAML).
15
+
16
+ /** CJK + full-width ranges: ~1 token per character. */
17
+ const CJK_RE = /[\u1100-\u11ff\u2e80-\u303f\u3040-\u30ff\u3130-\u318f\u3400-\u4dbf\u4e00-\u9fff\ua960-\ua97f\uac00-\ud7af\uf900-\ufaff\ufe30-\ufe4f\uff00-\uffef]/gu;
18
+
19
+ /** Alphanumeric runs (letters, marks, numbers) — one "word" to the estimator. */
20
+ const WORD_RE = /[\p{L}\p{M}\p{N}]+/gu;
21
+
22
+ /**
23
+ * Estimate the token count of a string.
24
+ *
25
+ * @param {string} text
26
+ * @param {{calibration?: number}} [opts] multiplier on the raw estimate
27
+ * @returns {number}
28
+ */
29
+ export function estimateTokens(text, opts = {}) {
30
+ if (typeof text !== 'string' || text.length === 0) return 0;
31
+ const calibration = typeof opts.calibration === 'number' && opts.calibration > 0 ? opts.calibration : 1;
32
+
33
+ let tokens = 0;
34
+
35
+ // CJK first: these characters are \p{L}, so the word regex would swallow
36
+ // them into long "words" and undercount badly.
37
+ const cjk = text.match(CJK_RE);
38
+ if (cjk) tokens += cjk.length;
39
+
40
+ // Strip CJK so the latin pass never double-counts it.
41
+ const latin = text.replace(CJK_RE, ' ');
42
+
43
+ // Words: max(1, round(len/4)).
44
+ const words = latin.match(WORD_RE);
45
+ if (words) {
46
+ for (const w of words) {
47
+ const len = w.length;
48
+ // Long identifiers/digits pack denser than prose (roughly len/3.5);
49
+ // short words pack looser. One threshold keeps the model simple and
50
+ // monotonic in length.
51
+ tokens += len <= 6 ? 1 : Math.max(1, Math.round(len / (len > 12 ? 3.5 : 4)));
52
+ }
53
+ }
54
+
55
+ // Symbols: every non-space, non-alphanumeric character is its own token
56
+ // in practice ("tasks.yaml" -> "tasks" "." "yaml").
57
+ const symbols = latin.match(/[^\s\p{L}\p{M}\p{N}]/gu);
58
+ if (symbols) tokens += symbols.length;
59
+
60
+ return Math.max(0, Math.round(tokens * calibration));
61
+ }
62
+
63
+ /**
64
+ * Estimate the token count of any payload — a string, or anything JSON-able.
65
+ *
66
+ * @param {unknown} value
67
+ * @returns {number}
68
+ */
69
+ export function estimatePayloadTokens(value) {
70
+ if (value === null || value === undefined) return 0;
71
+ if (typeof value === 'string') return estimateTokens(value);
72
+ if (typeof value === 'number' || typeof value === 'boolean') return estimateTokens(String(value));
73
+ try {
74
+ return estimateTokens(JSON.stringify(value) ?? '');
75
+ } catch {
76
+ return 0;
77
+ }
78
+ }
@@ -10,10 +10,26 @@
10
10
  // system reads: tasks.yaml (verbatim paths + acceptance), the dependency graph,
11
11
  // the plan's doc sections, and the capability-skill registry. One assembly,
12
12
  // no assembly drift.
13
+ //
14
+ // WHY THE FIRST GENERATION MUST BE COMPLETE: a worker that comes back with
15
+ // "I could not find the design skill" or "the acceptance criteria did not say
16
+ // which components to use" costs a whole second dispatch — the prompt, the
17
+ // agent, its exploration and its output, all again. So the contract carries
18
+ // everything the worker needs to produce a correct first answer: the rules of
19
+ // the capability skill (not a pointer to a file it may never open), the exact
20
+ // sections to read, and an explicit statement of what it must NOT do.
21
+ //
22
+ // NOTE ON SIZE: there is deliberately NO token count in the prompt or the
23
+ // returned payload. A number the model can see becomes a number it tries to
24
+ // shrink — and an agent optimizing for a byte count produces a smaller,
25
+ // weaker contract and then needs another round to fix what it dropped. The
26
+ // cost of a dispatch is measured where it belongs (the server, the CI gate,
27
+ // the report to the user), and paid for by making the first answer complete.
13
28
  import { readFileSync } from 'node:fs';
14
- import { join } from 'node:path';
29
+ import { dirname, join } from 'node:path';
15
30
  import { parseYaml } from './yaml.mjs';
16
31
  import { buildGraph, GraphError } from './graph.mjs';
32
+ import { skillDirective } from './skill-manager.mjs';
17
33
  import { invalidInput, notFound } from './errors.mjs';
18
34
 
19
35
  /**
@@ -22,10 +38,12 @@ import { invalidInput, notFound } from './errors.mjs';
22
38
  * @param {{
23
39
  * tasksYaml: string,
24
40
  * taskId: string,
25
- * slugDir?: string,
26
- * codeStandardsPath?: string,
27
- * capability?: {slug: string, path: string|null, purpose?: string}|null,
41
+ * slugDir?: string|null,
42
+ * projectRoot?: string|null,
43
+ * codeStandardsPath?: string|null,
44
+ * capabilities?: Array<{slug: string, path: string|null, purpose?: string, domain?: string, installed?: boolean, rules?: string, sections?: Array<{slug: string, title: string, normative?: boolean}>}>,
28
45
  * docSections?: Array<{file: string, section: string, title: string, matches?: Array<{line: number, text: string}>}>,
46
+ * codegraph?: boolean,
29
47
  * }} opts
30
48
  */
31
49
  export function buildWorkerContract(opts) {
@@ -72,6 +90,8 @@ export function buildWorkerContract(opts) {
72
90
  const ownership = Array.isArray(task.file_ownership) ? task.file_ownership : [];
73
91
  const artifacts = Array.isArray(task.artifacts) ? task.artifacts : [];
74
92
 
93
+ const capabilities = Array.isArray(opts.capabilities) ? opts.capabilities : [];
94
+
75
95
  const lines = [];
76
96
  lines.push(`# Task ${task.id} — ${task.title ?? ''}`.trim());
77
97
  lines.push('');
@@ -119,13 +139,44 @@ export function buildWorkerContract(opts) {
119
139
  lines.push('');
120
140
  }
121
141
 
122
- if (opts.capability?.path) {
123
- lines.push('## Capability skill (REQUIRED)');
124
- lines.push('');
125
- lines.push(
126
- `<Domain> work: follow ${opts.capability.path} (installed via FETCH-SKILL) — apply its standards to every relevant decision.`,
127
- );
142
+ // ── the capability skills ────────────────────────────────────────────────
143
+ //
144
+ // EVERY matched required skill is here, not just the first one. The old
145
+ // contract injected `required[0]` — so a task matching the baseline AND
146
+ // the accessibility skill silently lost the second one, even though it had
147
+ // been installed on purpose. A skill that is installed but never named is
148
+ // a skill that is never applied.
149
+ if (capabilities.length) {
150
+ lines.push('## Capability skills (REQUIRED — apply these rules)');
128
151
  lines.push('');
152
+ for (const cap of capabilities) {
153
+ lines.push(`### ${cap.domain ?? 'Capability'} — ${cap.slug}`);
154
+ lines.push('');
155
+ lines.push(skillDirective(cap));
156
+ lines.push('');
157
+ if (!cap.installed) {
158
+ lines.push(
159
+ `**NOT INSTALLED — the worker cannot comply until it is.** The orchestrator must install it with ` +
160
+ `archgen_skills { action: 'install', skillId: '${cap.slug}', approve: true } and re-dispatch.`,
161
+ );
162
+ lines.push('');
163
+ continue;
164
+ }
165
+ if (cap.rules) {
166
+ lines.push('These rules are binding for this task:');
167
+ lines.push('');
168
+ for (const rule of cap.rules.split('\n')) lines.push(`- ${rule}`);
169
+ lines.push('');
170
+ }
171
+ if (cap.sections?.length) {
172
+ lines.push(`The skill's full text is at ${cap.path}. Its sections (pull ONE if you need more):`);
173
+ lines.push('');
174
+ for (const s of cap.sections) {
175
+ lines.push(`- ${s.slug}${s.normative ? ' (normative)' : ''} — ${s.title}`);
176
+ }
177
+ lines.push('');
178
+ }
179
+ }
129
180
  }
130
181
 
131
182
  if (opts.docSections && opts.docSections.length) {
@@ -138,20 +189,88 @@ export function buildWorkerContract(opts) {
138
189
  lines.push('');
139
190
  }
140
191
 
192
+ // ── CodeGraph ────────────────────────────────────────────────────────────
193
+ //
194
+ // Server-detected, not left for the worker to work out. The orchestrator's
195
+ // prose mentioned CodeGraph, but the PROMPT never did — so the instruction
196
+ // never reached the agent that needed it.
197
+ if (opts.codegraph) {
198
+ lines.push('## CodeGraph — use it for understanding');
199
+ lines.push('');
200
+ lines.push(
201
+ 'This project has a CodeGraph index. Use the CodeGraph MCP tools for anything that needs ' +
202
+ 'understanding — dependencies, callers, blast radius. It returns the real source and the call ' +
203
+ 'paths between symbols, which is faster and more accurate than grep.',
204
+ );
205
+ lines.push('');
206
+ lines.push('- Never re-index it — the watcher keeps it live.');
207
+ lines.push('- Never grep for what the index can answer.');
208
+ lines.push('');
209
+ }
210
+
211
+ // ── what the worker must NOT do ──────────────────────────────────────────
212
+ //
213
+ // Without this, a worker reads the archgen skill and its references (the
214
+ // orchestrator's protocol, not its), and runs the archgen tool suite to
215
+ // re-derive what this contract already says. That is a second and third
216
+ // reading of the same facts — pure cost, and a chance to drift from the
217
+ // protocol the orchestrator is actually following.
218
+ lines.push('## Rules for you');
219
+ lines.push('');
220
+ lines.push(
221
+ '- Do NOT read the archgen skill, its references, or any protocol document. They belong to the ' +
222
+ 'orchestrator. Everything you need is in this contract.',
223
+ );
224
+ lines.push(
225
+ '- Do NOT run the archgen tool suite. The ONLY archgen call you make is the set_status in ' +
226
+ '"When you finish". The orchestrator already ran every deterministic check.',
227
+ );
228
+ lines.push('- Edit NOTHING outside your owned files.');
229
+ lines.push('- Do NOT talk to other workers — coordination happens through tasks.yaml.');
230
+ lines.push('- Finish in ONE pass: the contract above is complete. Do not come back asking for context.');
231
+ lines.push('');
232
+
141
233
  lines.push('## Paths and working state');
142
234
  lines.push('');
143
235
  lines.push('- Every path above is repo-root-relative and VERBATIM from tasks.yaml — never reconstruct a path from memory.');
144
- lines.push(`- Your working state goes under \`${slugDir ? join(slugDir, '.agent') : '.archgen/<slug>/.agent'}/\`: notes to \`.agent/notes/${taskId}.md\`, decisions to \`.agent/decisions/\`.`);
236
+ // The slug dir is known — it is the directory the tasks file lives in — so
237
+ // the working-state path is a real path, never a literal "<slug>".
238
+ const workingRoot = slugDir ?? dirname(tasksYaml);
239
+ lines.push(`- Your working state goes under \`${join(workingRoot, '.agent')}/\`: notes to \`.agent/notes/${taskId}.md\`, decisions to \`.agent/decisions/\`.`);
145
240
  lines.push('- NEVER create ad-hoc note/context/decision folders at the repo root or anywhere outside `.archgen/`.');
146
241
  lines.push('');
147
242
 
148
243
  lines.push('## When you finish');
149
244
  lines.push('');
150
- lines.push('1. Call `archgen_tasks { action: \'set_status\', taskId: \'' + task.id + '\', status: \'done\' }` — or `status: \'failed\'` if you could not complete it. Do this IN THE SAME TURN you finish, before anything else.');
151
- lines.push('2. State whether you followed the capability skill, one auditable line: `Skill compliance: followed <skill> (<path>)` or `Skill compliance: NOT followed — <reason>`.');
245
+ lines.push(
246
+ "1. Call `archgen_tasks { action: 'set_status', taskId: '" +
247
+ task.id +
248
+ "', status: 'done' }` — or `status: 'failed'` if you could not complete it. Do this IN THE SAME TURN you finish, before anything else.",
249
+ );
250
+ if (capabilities.length && capabilities[0].installed) {
251
+ lines.push(
252
+ `2. State whether you followed the capability skill, one auditable line: ` +
253
+ `\`Skill compliance: followed ${capabilities[0].slug} (${capabilities[0].path})\` — or, if you did not, ` +
254
+ `write \`Skill compliance: NOT followed —\` and then the reason in your own words.`,
255
+ );
256
+ } else {
257
+ // The line is always there, so the audit is uniform — but it never
258
+ // contains a placeholder the worker has to fill with a name it was not
259
+ // given.
260
+ lines.push(
261
+ '2. State one auditable line: `Skill compliance: N/A — no capability skill was required for this task` ' +
262
+ '(or, if one was required and you did not follow it, `Skill compliance: NOT followed —` and the reason).',
263
+ );
264
+ }
152
265
  lines.push('3. Commit your work scoped to the owned files.');
153
266
  lines.push('');
154
267
 
268
+ const warnings = [
269
+ ...(acceptance.length === 0 ? ['task has NO acceptance criteria — the verifier rejects it'] : []),
270
+ ...(ownership.length === 0 ? ['task has NO file_ownership — a worker could edit anything'] : []),
271
+ ...(capabilities.filter((c) => !c.installed).map((c) => `capability skill '${c.slug}' is REQUIRED but NOT installed — install it with archgen_skills{action:'install'} before dispatch`)),
272
+ ];
273
+
155
274
  return {
156
275
  taskId: task.id,
157
276
  title: task.title ?? null,
@@ -161,10 +280,18 @@ export function buildWorkerContract(opts) {
161
280
  artifacts,
162
281
  upstream,
163
282
  downstream,
164
- dispatchable: acceptance.length > 0 && ownership.length > 0,
165
- warnings: [
166
- ...(acceptance.length === 0 ? ['task has NO acceptance criteria — the verifier rejects it'] : []),
167
- ...(ownership.length === 0 ? ['task has NO file_ownership — a worker could edit anything'] : []),
168
- ],
283
+ dispatchable: acceptance.length > 0 && ownership.length > 0 && capabilities.every((c) => c.installed !== false),
284
+ // The ledger key for the dispatch table: one task = one worker session, so
285
+ // a follow-up on the same files continues that session instead of
286
+ // starting a fresh agent that has to re-read everything.
287
+ dispatchKey: `${slugDir ? slugDir.split('/').pop() : '<slug>'}/${task.id}`,
288
+ capabilities: capabilities.map((c) => ({
289
+ slug: c.slug,
290
+ path: c.path,
291
+ domain: c.domain ?? null,
292
+ installed: c.installed !== false,
293
+ ruleCount: c.rules ? c.rules.split('\n').filter(Boolean).length : 0,
294
+ })),
295
+ warnings,
169
296
  };
170
297
  }