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.
- package/README.md +2 -6
- package/assets/briefs/investigate.md +16 -17
- package/assets/briefs/review.md +41 -29
- package/assets/briefs/survey.md +17 -20
- package/assets/briefs/verifier.md +52 -40
- package/assets/harness-mcp.json +6 -6
- package/assets/platform-capabilities.json +387 -71
- package/assets/references/artifact-templates.md +67 -232
- package/assets/references/interview.md +83 -199
- package/assets/references/mcp-and-skills.md +35 -125
- package/assets/references/orchestration.md +96 -209
- package/assets/references/platforms.md +41 -110
- package/assets/skill-registry.json +10 -1
- package/assets/templates/adr.md +3 -3
- package/assets/templates/architecture.yaml +31 -28
- package/assets/templates/edge-matrix.md +8 -8
- package/assets/templates/mermaid.md +3 -10
- package/assets/templates/prd.md +15 -15
- package/assets/templates/tasks.yaml +25 -18
- package/package.json +2 -2
- package/src/cli.mjs +1 -2
- package/src/context.mjs +12 -42
- package/src/core/brief-context.mjs +106 -0
- package/src/core/brief-scope.mjs +218 -0
- package/src/core/briefs.mjs +109 -1
- package/src/core/codegraph-manager.mjs +12 -0
- package/src/core/doc-navigator.mjs +101 -17
- package/src/core/errors.mjs +1 -1
- package/src/core/harness-wiring.mjs +65 -22
- package/src/core/jsonc-config.mjs +706 -0
- package/src/core/plan-grapher.mjs +11 -3
- package/src/core/skill-manager.mjs +181 -13
- package/src/core/skill-roots.mjs +92 -0
- package/src/core/tokens.mjs +78 -0
- package/src/core/worker-contract.mjs +145 -18
- package/src/server.mjs +0 -3
- package/src/tools/help.mjs +17 -34
- package/src/tools/plan.mjs +36 -22
- package/src/tools/skills.mjs +67 -5
- package/src/tools/tasks.mjs +44 -18
- package/src/core/ui-channel.mjs +0 -222
- 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,
|
|
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
|
-
*
|
|
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
|
|
123
|
-
|
|
124
|
-
const
|
|
125
|
-
|
|
126
|
-
|
|
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 {
|
|
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 {
|
|
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
|
|
307
|
-
*
|
|
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
|
|
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
|
-
*
|
|
27
|
-
*
|
|
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
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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
|
-
|
|
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(
|
|
151
|
-
|
|
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
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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
|
}
|