@vaubaan/harness 1.3.2 → 2.0.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 +303 -167
- package/dist/cli/index.js +908 -1781
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +4 -2
- package/dist/index.js +380 -1063
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +29 -20
- package/dist/init.js +531 -655
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +687 -31
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +1 -26
- package/dist/parser/index.js +1 -17
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-B9_kNtQc.d.ts → render-C-FWmUfX.d.ts} +8 -15
- package/dist/render.d.ts +1 -1
- package/dist/render.js +16 -278
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +3 -4
- package/dist/skills/doc-audit.skill.md +7 -7
- package/dist/skills/drift-detector.skill.md +1 -1
- package/dist/skills/handbook-writer.skill.md +2 -2
- package/dist/skills/readme-writer.skill.md +3 -3
- package/dist/skills/spec-writer.skill.md +89 -71
- package/dist/skills/test-plan-writer.skill.md +3 -3
- package/dist/skills/workflow-writer.skill.md +20 -3
- package/dist/templates/code-quality.md.tmpl +2 -2
- package/dist/templates/coding-workflow.md.tmpl +10 -0
- package/package.json +1 -1
- package/dist/agents/coding.agent.md +0 -182
- package/dist/agents/merge.agent.md +0 -139
- package/dist/agents/planning.agent.md +0 -194
- package/dist/agents/review.agent.md +0 -176
- package/dist/commands/clean-code.cmd.md +0 -26
- package/dist/skills/clean-code-guardian.skill.md +0 -391
package/dist/linters/index.js
CHANGED
|
@@ -349,57 +349,712 @@ var frontmatterTracks = {
|
|
|
349
349
|
}
|
|
350
350
|
};
|
|
351
351
|
|
|
352
|
+
// src/linters/generated-fresh.ts
|
|
353
|
+
import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
|
|
354
|
+
import { join as join8, resolve as resolve4 } from "path";
|
|
355
|
+
|
|
356
|
+
// src/cli/managed-paths.ts
|
|
357
|
+
import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
|
|
358
|
+
import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join4, resolve as resolve2, win32 } from "path";
|
|
359
|
+
var MANAGED_FILES = /* @__PURE__ */ new Set(["AGENTS.md", "CLAUDE.md", ".harness-manifest.json"]);
|
|
360
|
+
var RELEASED_PATHS = [
|
|
361
|
+
".mcp.json",
|
|
362
|
+
".codex/config.toml",
|
|
363
|
+
".opencode/opencode.json",
|
|
364
|
+
".opencode/mcp.json",
|
|
365
|
+
".claude/settings.json",
|
|
366
|
+
".codex/hooks.json"
|
|
367
|
+
];
|
|
368
|
+
var MANAGED_DIRECTORIES = [
|
|
369
|
+
".claude/agents/",
|
|
370
|
+
".claude/commands/",
|
|
371
|
+
".claude/skills/",
|
|
372
|
+
".codex/agents/",
|
|
373
|
+
".codex/commands/",
|
|
374
|
+
".codex/skills/",
|
|
375
|
+
".agents/skills/",
|
|
376
|
+
".opencode/agents/",
|
|
377
|
+
".opencode/commands/",
|
|
378
|
+
".opencode/skills/",
|
|
379
|
+
".opencode/plugins/"
|
|
380
|
+
];
|
|
381
|
+
function canonicalTargetRoot(root) {
|
|
382
|
+
let ancestor = resolve2(root);
|
|
383
|
+
const missing = [];
|
|
384
|
+
while (!lstatSync(ancestor, { throwIfNoEntry: false })) {
|
|
385
|
+
missing.unshift(basename(ancestor));
|
|
386
|
+
ancestor = dirname2(ancestor);
|
|
387
|
+
}
|
|
388
|
+
const canonical = realpathSync(ancestor);
|
|
389
|
+
if (!statSync2(canonical).isDirectory()) {
|
|
390
|
+
throw new Error(`harness target is not a directory: ${root}`);
|
|
391
|
+
}
|
|
392
|
+
return join4(canonical, ...missing);
|
|
393
|
+
}
|
|
394
|
+
function assertManagedLocation(path) {
|
|
395
|
+
const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
|
|
396
|
+
if (isAbsolute2(path) || win32.isAbsolute(path) || path.includes("\\") || path.includes("\0") || invalidSegment) {
|
|
397
|
+
throw new Error(`unsafe harness path: ${path}`);
|
|
398
|
+
}
|
|
399
|
+
if (!MANAGED_FILES.has(path) && !MANAGED_DIRECTORIES.some((prefix) => path.startsWith(prefix))) {
|
|
400
|
+
throw new Error(`path is outside harness-managed locations: ${path}`);
|
|
401
|
+
}
|
|
402
|
+
}
|
|
403
|
+
function assertNoSymbolicComponents(root, path) {
|
|
404
|
+
const parts = path.split("/");
|
|
405
|
+
let current = root;
|
|
406
|
+
for (const [index, part] of parts.entries()) {
|
|
407
|
+
current = join4(current, part);
|
|
408
|
+
const info = lstatSync(current, { throwIfNoEntry: false });
|
|
409
|
+
if (!info) return;
|
|
410
|
+
if (info.isSymbolicLink()) {
|
|
411
|
+
throw new Error(`symbolic link in harness path: ${path}`);
|
|
412
|
+
}
|
|
413
|
+
const isLeaf = index === parts.length - 1;
|
|
414
|
+
if (isLeaf ? !info.isFile() : !info.isDirectory()) {
|
|
415
|
+
throw new Error(`unexpected file type in harness path: ${path}`);
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
}
|
|
419
|
+
function assertManagedPaths(root, files) {
|
|
420
|
+
for (const path of files) assertManagedLocation(path);
|
|
421
|
+
const canonicalRoot = canonicalTargetRoot(root);
|
|
422
|
+
for (const path of files) assertNoSymbolicComponents(canonicalRoot, path);
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
// src/cli/manifest.ts
|
|
426
|
+
import { createHash } from "crypto";
|
|
427
|
+
import { chmodSync, existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync } from "fs";
|
|
428
|
+
import { join as join5 } from "path";
|
|
429
|
+
import { z } from "zod";
|
|
430
|
+
var MANIFEST_FILENAME = ".harness-manifest.json";
|
|
431
|
+
var MANIFEST_VERSION = "6";
|
|
432
|
+
var ManifestSchema = z.object({
|
|
433
|
+
version: z.enum(["4", "5", MANIFEST_VERSION]),
|
|
434
|
+
engines: z.array(z.string()),
|
|
435
|
+
renderedAt: z.string(),
|
|
436
|
+
files: z.array(z.string()),
|
|
437
|
+
harnessVersion: z.string().optional(),
|
|
438
|
+
overridesDir: z.string().optional(),
|
|
439
|
+
fileHashes: z.record(z.string().regex(/^[a-f0-9]{64}$/)).optional(),
|
|
440
|
+
preservedFiles: z.array(z.string()).optional()
|
|
441
|
+
});
|
|
442
|
+
function manifestPath(targetDir) {
|
|
443
|
+
return join5(targetDir, MANIFEST_FILENAME);
|
|
444
|
+
}
|
|
445
|
+
function readManifest(targetDir) {
|
|
446
|
+
assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
|
|
447
|
+
const path = manifestPath(targetDir);
|
|
448
|
+
if (!existsSync4(path)) return null;
|
|
449
|
+
const raw = JSON.parse(readFileSync2(path, "utf8"));
|
|
450
|
+
return ManifestSchema.parse(raw);
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
// src/cli/plan-render.ts
|
|
454
|
+
import { existsSync as existsSync6 } from "fs";
|
|
455
|
+
import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
|
|
456
|
+
import { fileURLToPath } from "url";
|
|
457
|
+
|
|
458
|
+
// src/loader.ts
|
|
459
|
+
import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
|
|
460
|
+
import { join as join6 } from "path";
|
|
461
|
+
import fg4 from "fast-glob";
|
|
462
|
+
import { z as z3 } from "zod";
|
|
463
|
+
|
|
464
|
+
// src/parser/common.ts
|
|
465
|
+
import { readFileSync as readFileSync3 } from "fs";
|
|
466
|
+
import matter2 from "gray-matter";
|
|
467
|
+
|
|
468
|
+
// src/parser/schemas.ts
|
|
469
|
+
import { z as z2 } from "zod";
|
|
470
|
+
|
|
471
|
+
// src/types.ts
|
|
472
|
+
var ENGINES = ["claude-code", "codex-cli", "opencode"];
|
|
473
|
+
var CAPABILITIES = ["multi-step", "slash-command", "inline-exec"];
|
|
474
|
+
var CAPABILITIES_MATRIX = {
|
|
475
|
+
"claude-code": ["multi-step", "slash-command", "inline-exec"],
|
|
476
|
+
"codex-cli": ["multi-step", "slash-command", "inline-exec"],
|
|
477
|
+
opencode: ["multi-step", "slash-command", "inline-exec"]
|
|
478
|
+
};
|
|
479
|
+
var DEGRADED_CAPABILITIES = {
|
|
480
|
+
"codex-cli": ["multi-step"]
|
|
481
|
+
};
|
|
482
|
+
|
|
483
|
+
// src/parser/schemas.ts
|
|
484
|
+
var IdSchema = z2.string().min(1).regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase + digits + hyphens)");
|
|
485
|
+
var SkillFrontmatterSchema = z2.object({
|
|
486
|
+
id: IdSchema,
|
|
487
|
+
description: z2.string().min(1),
|
|
488
|
+
engines: z2.array(z2.enum(ENGINES)).min(1).optional(),
|
|
489
|
+
requires: z2.array(z2.enum(CAPABILITIES)).optional(),
|
|
490
|
+
tags: z2.array(z2.string()).optional()
|
|
491
|
+
}).strict();
|
|
492
|
+
var CmdArgEnumSchema = z2.object({
|
|
493
|
+
name: z2.string().min(1),
|
|
494
|
+
type: z2.literal("enum"),
|
|
495
|
+
values: z2.array(z2.string()).min(1),
|
|
496
|
+
default: z2.string().optional()
|
|
497
|
+
}).strict();
|
|
498
|
+
var CmdArgStringSchema = z2.object({
|
|
499
|
+
name: z2.string().min(1),
|
|
500
|
+
type: z2.literal("string"),
|
|
501
|
+
default: z2.string().optional()
|
|
502
|
+
}).strict();
|
|
503
|
+
var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
504
|
+
var CmdFrontmatterSchema = z2.object({
|
|
505
|
+
id: IdSchema,
|
|
506
|
+
trigger: z2.string().regex(/^\/[a-z][a-z0-9-]*$/, "trigger must be /kebab-case"),
|
|
507
|
+
invokes_skill: IdSchema,
|
|
508
|
+
args: z2.array(CmdArgSchema).optional(),
|
|
509
|
+
description: z2.string().min(1)
|
|
510
|
+
}).strict();
|
|
511
|
+
var Schemas = {
|
|
512
|
+
Skill: SkillFrontmatterSchema,
|
|
513
|
+
Cmd: CmdFrontmatterSchema
|
|
514
|
+
};
|
|
515
|
+
var ParseError = class extends Error {
|
|
516
|
+
constructor(file, issues) {
|
|
517
|
+
const messages = issues.map((i) => ` - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
|
|
518
|
+
super(`Frontmatter validation failed for ${file}:
|
|
519
|
+
${messages}`);
|
|
520
|
+
this.file = file;
|
|
521
|
+
this.issues = issues;
|
|
522
|
+
this.name = "ParseError";
|
|
523
|
+
}
|
|
524
|
+
file;
|
|
525
|
+
issues;
|
|
526
|
+
};
|
|
527
|
+
|
|
528
|
+
// src/parser/common.ts
|
|
529
|
+
function parseWithSchema(filePath, source, schema) {
|
|
530
|
+
const parsed = matter2(source);
|
|
531
|
+
const result = schema.safeParse(parsed.data);
|
|
532
|
+
if (!result.success) {
|
|
533
|
+
throw new ParseError(filePath, result.error.issues);
|
|
534
|
+
}
|
|
535
|
+
return {
|
|
536
|
+
meta: result.data,
|
|
537
|
+
body: parsed.content.trim(),
|
|
538
|
+
sourcePath: filePath
|
|
539
|
+
};
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
// src/parser/cmd.ts
|
|
543
|
+
function parseCmd(filePath, source) {
|
|
544
|
+
return parseWithSchema(filePath, source, Schemas.Cmd);
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
// src/parser/skill.ts
|
|
548
|
+
function parseSkill(filePath, source) {
|
|
549
|
+
return parseWithSchema(filePath, source, Schemas.Skill);
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
// src/util/yaml.ts
|
|
553
|
+
import { parse as yamlParse } from "yaml";
|
|
554
|
+
function parseYAML(source) {
|
|
555
|
+
return yamlParse(source);
|
|
556
|
+
}
|
|
557
|
+
|
|
558
|
+
// src/loader.ts
|
|
559
|
+
var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
|
|
560
|
+
function loadHarness(packageDir, opts = {}) {
|
|
561
|
+
const skillsDir = opts.skillsDir ?? join6(packageDir, "skills");
|
|
562
|
+
const commandsDir = opts.commandsDir ?? join6(packageDir, "commands");
|
|
563
|
+
const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
564
|
+
const cmdFiles = fg4.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
|
|
565
|
+
return {
|
|
566
|
+
skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
|
|
567
|
+
cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
|
|
568
|
+
};
|
|
569
|
+
}
|
|
570
|
+
function loadProjectSkills(targetDir) {
|
|
571
|
+
const skillsDir = join6(targetDir, "docs", "skills");
|
|
572
|
+
if (!existsSync5(skillsDir)) return [];
|
|
573
|
+
const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
574
|
+
return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
|
|
575
|
+
}
|
|
576
|
+
function loadOverrides(worktreeDir) {
|
|
577
|
+
const overridesDir = join6(worktreeDir, ".harness-overrides");
|
|
578
|
+
if (!existsSync5(overridesDir)) return void 0;
|
|
579
|
+
const added = loadHarness(overridesDir, {
|
|
580
|
+
skillsDir: join6(overridesDir, "skills"),
|
|
581
|
+
commandsDir: join6(overridesDir, "commands")
|
|
582
|
+
});
|
|
583
|
+
const disablePath = join6(overridesDir, "disable.yaml");
|
|
584
|
+
let disable = [];
|
|
585
|
+
if (existsSync5(disablePath)) {
|
|
586
|
+
try {
|
|
587
|
+
const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
|
|
588
|
+
if (parsed.success && parsed.data.disable) {
|
|
589
|
+
disable = parsed.data.disable;
|
|
590
|
+
}
|
|
591
|
+
} catch {
|
|
592
|
+
}
|
|
593
|
+
}
|
|
594
|
+
return { add: added, disable };
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
// src/renderers/common.ts
|
|
598
|
+
import { stringify as yamlStringify } from "yaml";
|
|
599
|
+
function checkSkillCapabilities(skill, engine) {
|
|
600
|
+
const blockingWarnings = [];
|
|
601
|
+
const degradedWarnings = [];
|
|
602
|
+
const supported = CAPABILITIES_MATRIX[engine];
|
|
603
|
+
const degraded = DEGRADED_CAPABILITIES[engine] ?? [];
|
|
604
|
+
if (!skill.meta.requires) return { blockingWarnings, degradedWarnings };
|
|
605
|
+
for (const cap of skill.meta.requires) {
|
|
606
|
+
if (!supported.includes(cap)) {
|
|
607
|
+
blockingWarnings.push(
|
|
608
|
+
`skill "${skill.meta.id}" requires "${cap}" not supported by "${engine}" \u2014 skipped`
|
|
609
|
+
);
|
|
610
|
+
} else if (degraded.includes(cap)) {
|
|
611
|
+
degradedWarnings.push(
|
|
612
|
+
`skill "${skill.meta.id}" requires "${cap}" \u2014 supported by "${engine}" with degradation`
|
|
613
|
+
);
|
|
614
|
+
}
|
|
615
|
+
}
|
|
616
|
+
return { blockingWarnings, degradedWarnings };
|
|
617
|
+
}
|
|
618
|
+
function isSkillEngineAllowed(skill, engine) {
|
|
619
|
+
if (!skill.meta.engines) return true;
|
|
620
|
+
return skill.meta.engines.includes(engine);
|
|
621
|
+
}
|
|
622
|
+
function yamlFrontmatter(data) {
|
|
623
|
+
const rendered = yamlStringify(data, { lineWidth: 0 }).trimEnd();
|
|
624
|
+
return `---
|
|
625
|
+
${rendered}
|
|
626
|
+
---
|
|
627
|
+
`;
|
|
628
|
+
}
|
|
629
|
+
function frontmatterDataForSkill(skill) {
|
|
630
|
+
const data = {
|
|
631
|
+
name: skill.meta.id,
|
|
632
|
+
description: skill.meta.description
|
|
633
|
+
};
|
|
634
|
+
if (skill.meta.tags && skill.meta.tags.length > 0) data.tags = skill.meta.tags;
|
|
635
|
+
return data;
|
|
636
|
+
}
|
|
637
|
+
function frontmatterDataForCmd(cmd) {
|
|
638
|
+
const data = {
|
|
639
|
+
id: cmd.meta.id,
|
|
640
|
+
trigger: cmd.meta.trigger,
|
|
641
|
+
description: cmd.meta.description
|
|
642
|
+
};
|
|
643
|
+
if (cmd.meta.args && cmd.meta.args.length > 0) {
|
|
644
|
+
data.args = cmd.meta.args.map((a) => {
|
|
645
|
+
if (a.type === "enum") {
|
|
646
|
+
return a.default !== void 0 ? { name: a.name, type: a.type, values: a.values, default: a.default } : { name: a.name, type: a.type, values: a.values };
|
|
647
|
+
}
|
|
648
|
+
return a.default !== void 0 ? { name: a.name, type: a.type, default: a.default } : { name: a.name, type: a.type };
|
|
649
|
+
});
|
|
650
|
+
}
|
|
651
|
+
return data;
|
|
652
|
+
}
|
|
653
|
+
function buildUmbrellaBody(extras) {
|
|
654
|
+
const triggerBySkill = new Map(
|
|
655
|
+
extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
|
|
656
|
+
);
|
|
657
|
+
const skillLines = extras.availableSkills.map((s) => {
|
|
658
|
+
const trigger = triggerBySkill.get(s.meta.id);
|
|
659
|
+
const label = trigger ? `\`${s.meta.id}\` (\`${trigger}\`)` : `\`${s.meta.id}\``;
|
|
660
|
+
return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
|
|
661
|
+
});
|
|
662
|
+
const sections = [
|
|
663
|
+
"# How we work",
|
|
664
|
+
"",
|
|
665
|
+
"This file describes **how to work in this project**. The **business context** (what the project does, how to run it, which subsystems it contains) lives in `README.md` and `docs/`. Read them first.",
|
|
666
|
+
"",
|
|
667
|
+
"## Project map",
|
|
668
|
+
"",
|
|
669
|
+
"- `README.md` \u2014 pitch, quick start, scripts. Entry point.",
|
|
670
|
+
"- `docs/spec/<subsystem>.md` \u2014 *what* and *why* (tech-agnostic).",
|
|
671
|
+
"- `docs/handbook/<feature>.md` \u2014 *how it actually works* today.",
|
|
672
|
+
"- `docs/decisions/<slug>.md` \u2014 ADRs: structural choices and rejected alternatives.",
|
|
673
|
+
"- `docs/tests/integration-tests.md` & `e2e-tests.md` \u2014 core scenarios.",
|
|
674
|
+
"- `docs/workflow/coding-workflow.md` \u2014 CI, branches, PR, release. How this team works: follow it.",
|
|
675
|
+
...extras.hasProjectSkills ? ["- `docs/skills/*.skill.md` \u2014 the project's domain skills."] : [],
|
|
676
|
+
...extras.hasQualityDoc ? [
|
|
677
|
+
"- `docs/quality/code-quality.md` \u2014 the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code."
|
|
678
|
+
] : [],
|
|
679
|
+
"",
|
|
680
|
+
"## Doc-first",
|
|
681
|
+
"",
|
|
682
|
+
"The order is: **understand the docs \u2192 fill the gaps \u2192 code \u2192 update the docs \u2192 commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers \u2014 not downstream, not after the fact.",
|
|
683
|
+
"",
|
|
684
|
+
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
685
|
+
"- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
|
|
686
|
+
"- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
|
|
687
|
+
"- Suspected code \u2194 doc drift \u2192 `/drift` before moving on.",
|
|
688
|
+
"",
|
|
689
|
+
"## Checks",
|
|
690
|
+
"",
|
|
691
|
+
"Run `npx @vaubaan/harness lint` before you commit; CI runs the same linters on every pull request. Fix what it reports with the skill it suggests.",
|
|
692
|
+
"",
|
|
693
|
+
"The files the harness generates (`AGENTS.md`, `CLAUDE.md`, the `.claude/`, `.agents/` and `.opencode/` folders, `.harness-manifest.json`) are committed. Never edit them by hand: change their source in `docs/` or `.harness-overrides/`, run `npx @vaubaan/harness update .`, and commit the result. The linter fails when a generated file no longer matches its render."
|
|
694
|
+
];
|
|
695
|
+
if (skillLines.length > 0) {
|
|
696
|
+
sections.push("", "## Doc-skills", "", skillLines.join("\n"));
|
|
697
|
+
}
|
|
698
|
+
return `${sections.join("\n")}
|
|
699
|
+
`;
|
|
700
|
+
}
|
|
701
|
+
|
|
702
|
+
// src/renderers/claude-code.ts
|
|
703
|
+
var ENGINE = "claude-code";
|
|
704
|
+
var BASE = ".claude";
|
|
705
|
+
var claudeCodeRenderer = {
|
|
706
|
+
engine: ENGINE,
|
|
707
|
+
renderSkill(skill) {
|
|
708
|
+
if (!isSkillEngineAllowed(skill, ENGINE)) {
|
|
709
|
+
return {
|
|
710
|
+
files: [],
|
|
711
|
+
warnings: [`skill "${skill.meta.id}" excluded from engine "${ENGINE}"`]
|
|
712
|
+
};
|
|
713
|
+
}
|
|
714
|
+
const check = checkSkillCapabilities(skill, ENGINE);
|
|
715
|
+
if (check.blockingWarnings.length > 0) {
|
|
716
|
+
return { files: [], warnings: check.blockingWarnings };
|
|
717
|
+
}
|
|
718
|
+
const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}
|
|
719
|
+
${skill.body}
|
|
720
|
+
`;
|
|
721
|
+
return {
|
|
722
|
+
files: [{ path: `${BASE}/skills/${skill.meta.id}/SKILL.md`, content }],
|
|
723
|
+
warnings: check.degradedWarnings
|
|
724
|
+
};
|
|
725
|
+
},
|
|
726
|
+
renderCmd(cmd) {
|
|
727
|
+
const content = `${yamlFrontmatter(frontmatterDataForCmd(cmd))}
|
|
728
|
+
${cmd.body}
|
|
729
|
+
`;
|
|
730
|
+
return {
|
|
731
|
+
files: [{ path: `${BASE}/commands/${cmd.meta.id}.md`, content }],
|
|
732
|
+
warnings: []
|
|
733
|
+
};
|
|
734
|
+
}
|
|
735
|
+
};
|
|
736
|
+
|
|
737
|
+
// src/renderers/codex-cli.ts
|
|
738
|
+
var ENGINE2 = "codex-cli";
|
|
739
|
+
var SKILLS_BASE = ".agents/skills";
|
|
740
|
+
var codexCliRenderer = {
|
|
741
|
+
engine: ENGINE2,
|
|
742
|
+
renderSkill(skill) {
|
|
743
|
+
if (!isSkillEngineAllowed(skill, ENGINE2)) {
|
|
744
|
+
return {
|
|
745
|
+
files: [],
|
|
746
|
+
warnings: [`skill "${skill.meta.id}" excluded from engine "${ENGINE2}"`]
|
|
747
|
+
};
|
|
748
|
+
}
|
|
749
|
+
const check = checkSkillCapabilities(skill, ENGINE2);
|
|
750
|
+
if (check.blockingWarnings.length > 0) {
|
|
751
|
+
return { files: [], warnings: check.blockingWarnings };
|
|
752
|
+
}
|
|
753
|
+
const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}
|
|
754
|
+
${skill.body}
|
|
755
|
+
`;
|
|
756
|
+
return {
|
|
757
|
+
files: [{ path: `${SKILLS_BASE}/${skill.meta.id}/SKILL.md`, content }],
|
|
758
|
+
warnings: check.degradedWarnings
|
|
759
|
+
};
|
|
760
|
+
},
|
|
761
|
+
// Codex custom prompts are deprecated in favour of skills: nothing to render.
|
|
762
|
+
renderCmd(_cmd) {
|
|
763
|
+
return { files: [], warnings: [] };
|
|
764
|
+
}
|
|
765
|
+
};
|
|
766
|
+
|
|
767
|
+
// src/renderers/opencode.ts
|
|
768
|
+
var ENGINE3 = "opencode";
|
|
769
|
+
var BASE2 = ".opencode";
|
|
770
|
+
var opencodeRenderer = {
|
|
771
|
+
engine: ENGINE3,
|
|
772
|
+
renderSkill(skill) {
|
|
773
|
+
if (!isSkillEngineAllowed(skill, ENGINE3)) {
|
|
774
|
+
return {
|
|
775
|
+
files: [],
|
|
776
|
+
warnings: [`skill "${skill.meta.id}" excluded from engine "${ENGINE3}"`]
|
|
777
|
+
};
|
|
778
|
+
}
|
|
779
|
+
const check = checkSkillCapabilities(skill, ENGINE3);
|
|
780
|
+
if (check.blockingWarnings.length > 0) {
|
|
781
|
+
return { files: [], warnings: check.blockingWarnings };
|
|
782
|
+
}
|
|
783
|
+
const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}
|
|
784
|
+
${skill.body}
|
|
785
|
+
`;
|
|
786
|
+
return {
|
|
787
|
+
files: [{ path: `${BASE2}/skills/${skill.meta.id}/SKILL.md`, content }],
|
|
788
|
+
warnings: check.degradedWarnings
|
|
789
|
+
};
|
|
790
|
+
},
|
|
791
|
+
renderCmd(cmd) {
|
|
792
|
+
const content = `${yamlFrontmatter({ description: cmd.meta.description })}
|
|
793
|
+
${cmd.body}
|
|
794
|
+
`;
|
|
795
|
+
return {
|
|
796
|
+
files: [{ path: `${BASE2}/commands/${cmd.meta.id}.md`, content }],
|
|
797
|
+
warnings: []
|
|
798
|
+
};
|
|
799
|
+
}
|
|
800
|
+
};
|
|
801
|
+
|
|
802
|
+
// src/renderers/index.ts
|
|
803
|
+
var RENDERERS = {
|
|
804
|
+
"claude-code": claudeCodeRenderer,
|
|
805
|
+
"codex-cli": codexCliRenderer,
|
|
806
|
+
opencode: opencodeRenderer
|
|
807
|
+
};
|
|
808
|
+
function getRenderer(engine) {
|
|
809
|
+
return RENDERERS[engine];
|
|
810
|
+
}
|
|
811
|
+
|
|
812
|
+
// src/render.ts
|
|
813
|
+
var RenderError = class extends Error {
|
|
814
|
+
constructor(message) {
|
|
815
|
+
super(message);
|
|
816
|
+
this.name = "RenderError";
|
|
817
|
+
}
|
|
818
|
+
};
|
|
819
|
+
function mergeById(stock, added) {
|
|
820
|
+
const result = /* @__PURE__ */ new Map();
|
|
821
|
+
for (const item of stock) result.set(item.meta.id, item);
|
|
822
|
+
if (added) {
|
|
823
|
+
for (const item of added) result.set(item.meta.id, item);
|
|
824
|
+
}
|
|
825
|
+
return Array.from(result.values());
|
|
826
|
+
}
|
|
827
|
+
function removeByIds(items, disabled) {
|
|
828
|
+
if (disabled.length === 0) return [...items];
|
|
829
|
+
const disabledSet = new Set(disabled);
|
|
830
|
+
return items.filter((item) => !disabledSet.has(item.meta.id));
|
|
831
|
+
}
|
|
832
|
+
function applyOverrides(harness, overrides) {
|
|
833
|
+
const disabled = overrides?.disable ?? [];
|
|
834
|
+
return {
|
|
835
|
+
skills: removeByIds(mergeById(harness.skills, overrides?.add?.skills), disabled),
|
|
836
|
+
cmds: removeByIds(mergeById(harness.cmds, overrides?.add?.cmds), disabled)
|
|
837
|
+
};
|
|
838
|
+
}
|
|
839
|
+
var CLAUDE_MD_STUB = "@AGENTS.md\n";
|
|
840
|
+
function opencodeLast(engines) {
|
|
841
|
+
return [...engines].sort((a, b) => Number(a === "opencode") - Number(b === "opencode"));
|
|
842
|
+
}
|
|
843
|
+
function render(input) {
|
|
844
|
+
const { engines } = input;
|
|
845
|
+
if (engines.length === 0) {
|
|
846
|
+
throw new RenderError("at least one engine must be selected");
|
|
847
|
+
}
|
|
848
|
+
const base = input.projectSkills?.length ? { ...input.harness, skills: mergeById(input.harness.skills, input.projectSkills) } : input.harness;
|
|
849
|
+
const harness = applyOverrides(base, input.overrides);
|
|
850
|
+
const files = [];
|
|
851
|
+
const warnings = [];
|
|
852
|
+
const exposedSkills = /* @__PURE__ */ new Map();
|
|
853
|
+
const exposedCmds = /* @__PURE__ */ new Map();
|
|
854
|
+
for (const engine of opencodeLast(engines)) {
|
|
855
|
+
const renderer = getRenderer(engine);
|
|
856
|
+
const renderedSkillIds = /* @__PURE__ */ new Set();
|
|
857
|
+
for (const skill of harness.skills) {
|
|
858
|
+
const result = renderer.renderSkill(skill);
|
|
859
|
+
warnings.push(...result.warnings);
|
|
860
|
+
if (result.files.length > 0) {
|
|
861
|
+
const alreadyVisible = engine === "opencode" && exposedSkills.has(skill.meta.id);
|
|
862
|
+
if (!alreadyVisible) files.push(...result.files);
|
|
863
|
+
renderedSkillIds.add(skill.meta.id);
|
|
864
|
+
exposedSkills.set(skill.meta.id, skill);
|
|
865
|
+
}
|
|
866
|
+
}
|
|
867
|
+
for (const cmd of harness.cmds) {
|
|
868
|
+
if (!renderedSkillIds.has(cmd.meta.invokes_skill)) continue;
|
|
869
|
+
const result = renderer.renderCmd(cmd);
|
|
870
|
+
warnings.push(...result.warnings);
|
|
871
|
+
if (result.files.length > 0) {
|
|
872
|
+
files.push(...result.files);
|
|
873
|
+
exposedCmds.set(cmd.meta.id, cmd);
|
|
874
|
+
}
|
|
875
|
+
}
|
|
876
|
+
}
|
|
877
|
+
const umbrellaContent = buildUmbrellaBody({
|
|
878
|
+
availableSkills: Array.from(exposedSkills.values()),
|
|
879
|
+
availableCommands: Array.from(exposedCmds.values()),
|
|
880
|
+
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
881
|
+
hasQualityDoc: input.hasQualityDoc === true
|
|
882
|
+
});
|
|
883
|
+
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
884
|
+
if (engines.includes("claude-code")) {
|
|
885
|
+
files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
|
|
886
|
+
}
|
|
887
|
+
return { files, warnings };
|
|
888
|
+
}
|
|
889
|
+
|
|
890
|
+
// src/cli/plan-render.ts
|
|
891
|
+
var QUALITY_DOC_PATH = "docs/quality/code-quality.md";
|
|
892
|
+
function resolveEngineList(requested) {
|
|
893
|
+
if (!requested || requested.length === 0) {
|
|
894
|
+
throw new Error(
|
|
895
|
+
`no engine selected: pass --engines=<list> with one or more of ${ENGINES.join(", ")}`
|
|
896
|
+
);
|
|
897
|
+
}
|
|
898
|
+
const engines = requested.map((e) => {
|
|
899
|
+
if (!ENGINES.includes(e)) {
|
|
900
|
+
throw new Error(`unknown engine: ${e} (expected one of ${ENGINES.join(", ")})`);
|
|
901
|
+
}
|
|
902
|
+
return e;
|
|
903
|
+
});
|
|
904
|
+
return [...new Set(engines)];
|
|
905
|
+
}
|
|
906
|
+
function defaultPackageDir() {
|
|
907
|
+
const here = dirname3(fileURLToPath(import.meta.url));
|
|
908
|
+
if (existsSync6(join7(here, "skills"))) return here;
|
|
909
|
+
return resolve3(here, "..");
|
|
910
|
+
}
|
|
911
|
+
function planInit(args) {
|
|
912
|
+
const engines = resolveEngineList(args.engines);
|
|
913
|
+
const packageDir = args.packageDir ?? defaultPackageDir();
|
|
914
|
+
const harness = loadHarness(packageDir);
|
|
915
|
+
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
916
|
+
const projectSkills = loadProjectSkills(args.targetDir);
|
|
917
|
+
const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
|
|
918
|
+
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
|
|
919
|
+
return { engines, output };
|
|
920
|
+
}
|
|
921
|
+
|
|
922
|
+
// src/linters/generated-fresh.ts
|
|
923
|
+
var FIX = "run `npx @vaubaan/harness update .` and commit the result";
|
|
924
|
+
var generatedFresh = {
|
|
925
|
+
id: "lint:generated-fresh",
|
|
926
|
+
pillars: ["repo-root"],
|
|
927
|
+
defaultSeverity: "error",
|
|
928
|
+
run(repoRoot) {
|
|
929
|
+
const issue = (file, message) => ({
|
|
930
|
+
linter: this.id,
|
|
931
|
+
severity: "error",
|
|
932
|
+
file,
|
|
933
|
+
message
|
|
934
|
+
});
|
|
935
|
+
let manifest;
|
|
936
|
+
try {
|
|
937
|
+
manifest = readManifest(repoRoot);
|
|
938
|
+
} catch (error) {
|
|
939
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
940
|
+
return [issue(".harness-manifest.json", `invalid harness manifest: ${reason}`)];
|
|
941
|
+
}
|
|
942
|
+
if (!manifest) return [];
|
|
943
|
+
const overridesParent = manifest.overridesDir ? resolve4(repoRoot, manifest.overridesDir) : repoRoot;
|
|
944
|
+
const hasOverrides = existsSync7(join8(overridesParent, ".harness-overrides"));
|
|
945
|
+
let rendered;
|
|
946
|
+
try {
|
|
947
|
+
rendered = planInit({
|
|
948
|
+
targetDir: repoRoot,
|
|
949
|
+
engines: manifest.engines,
|
|
950
|
+
overridesDir: hasOverrides ? overridesParent : void 0
|
|
951
|
+
});
|
|
952
|
+
} catch (error) {
|
|
953
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
954
|
+
return [issue(".harness-manifest.json", `cannot render the harness: ${reason}`)];
|
|
955
|
+
}
|
|
956
|
+
const preserved = new Set(manifest.preservedFiles ?? []);
|
|
957
|
+
const issues = [];
|
|
958
|
+
const renderedPaths = /* @__PURE__ */ new Set();
|
|
959
|
+
for (const file of rendered.output.files) {
|
|
960
|
+
if (preserved.has(file.path)) continue;
|
|
961
|
+
renderedPaths.add(file.path);
|
|
962
|
+
const full = join8(repoRoot, file.path);
|
|
963
|
+
if (!existsSync7(full)) {
|
|
964
|
+
issues.push(issue(file.path, `generated file is missing; ${FIX}`));
|
|
965
|
+
} else if (readFileSync5(full, "utf8") !== file.content) {
|
|
966
|
+
issues.push(
|
|
967
|
+
issue(
|
|
968
|
+
file.path,
|
|
969
|
+
`generated file differs from the current render; edit its source in docs/ or .harness-overrides/, then ${FIX}`
|
|
970
|
+
)
|
|
971
|
+
);
|
|
972
|
+
}
|
|
973
|
+
}
|
|
974
|
+
for (const path of manifest.files) {
|
|
975
|
+
if (renderedPaths.has(path) || preserved.has(path) || RELEASED_PATHS.includes(path)) continue;
|
|
976
|
+
if (existsSync7(join8(repoRoot, path))) {
|
|
977
|
+
issues.push(issue(path, `stale generated file, no longer rendered; ${FIX}`));
|
|
978
|
+
}
|
|
979
|
+
}
|
|
980
|
+
return issues;
|
|
981
|
+
}
|
|
982
|
+
};
|
|
983
|
+
|
|
352
984
|
// src/linters/gitignore-harness.ts
|
|
353
985
|
var REQUIRED_GITIGNORE_ENTRIES = [
|
|
354
986
|
".harness-overrides/",
|
|
355
|
-
".
|
|
356
|
-
|
|
987
|
+
".vaubaan/"
|
|
988
|
+
];
|
|
989
|
+
var FORBIDDEN_GITIGNORE_ENTRIES = [
|
|
990
|
+
"AGENTS.md",
|
|
991
|
+
"CLAUDE.md",
|
|
357
992
|
".claude/",
|
|
358
993
|
".codex/",
|
|
359
|
-
".opencode/",
|
|
360
994
|
".agents/",
|
|
361
|
-
".
|
|
362
|
-
"
|
|
363
|
-
"CLAUDE.md",
|
|
364
|
-
".mcp.json"
|
|
995
|
+
".opencode/",
|
|
996
|
+
".harness-manifest.json"
|
|
365
997
|
];
|
|
998
|
+
function gitignoreEntries(text) {
|
|
999
|
+
const entries = /* @__PURE__ */ new Set();
|
|
1000
|
+
for (const raw of text.split("\n")) {
|
|
1001
|
+
const line = raw.trim();
|
|
1002
|
+
if (!line || line.startsWith("#")) continue;
|
|
1003
|
+
entries.add(line.replace(/^\//, "").replace(/\/$/, ""));
|
|
1004
|
+
}
|
|
1005
|
+
return entries;
|
|
1006
|
+
}
|
|
1007
|
+
function normalize(entry) {
|
|
1008
|
+
return entry.replace(/\/$/, "");
|
|
1009
|
+
}
|
|
1010
|
+
function missingGitignoreEntries(text) {
|
|
1011
|
+
const lines = gitignoreEntries(text);
|
|
1012
|
+
return REQUIRED_GITIGNORE_ENTRIES.filter((entry) => !lines.has(normalize(entry)));
|
|
1013
|
+
}
|
|
1014
|
+
function forbiddenGitignoreEntries(text) {
|
|
1015
|
+
const lines = gitignoreEntries(text);
|
|
1016
|
+
return FORBIDDEN_GITIGNORE_ENTRIES.filter((entry) => lines.has(normalize(entry)));
|
|
1017
|
+
}
|
|
366
1018
|
var gitignoreHarness = {
|
|
367
1019
|
id: "lint:gitignore-harness",
|
|
368
1020
|
pillars: ["repo-root"],
|
|
369
1021
|
defaultSeverity: "error",
|
|
370
1022
|
run(repoRoot) {
|
|
371
|
-
const issues = [];
|
|
372
1023
|
if (!fileExists(repoRoot, ".gitignore")) {
|
|
1024
|
+
return [
|
|
1025
|
+
{
|
|
1026
|
+
linter: this.id,
|
|
1027
|
+
severity: "error",
|
|
1028
|
+
file: ".gitignore",
|
|
1029
|
+
message: ".gitignore is missing at repo root"
|
|
1030
|
+
}
|
|
1031
|
+
];
|
|
1032
|
+
}
|
|
1033
|
+
const text = readText(repoRoot, ".gitignore");
|
|
1034
|
+
const issues = [];
|
|
1035
|
+
for (const entry of missingGitignoreEntries(text)) {
|
|
373
1036
|
issues.push({
|
|
374
1037
|
linter: this.id,
|
|
375
1038
|
severity: "error",
|
|
376
1039
|
file: ".gitignore",
|
|
377
|
-
message:
|
|
1040
|
+
message: `.gitignore must contain "${entry}"`
|
|
378
1041
|
});
|
|
379
|
-
return issues;
|
|
380
1042
|
}
|
|
381
|
-
const
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
issues.push({
|
|
389
|
-
linter: this.id,
|
|
390
|
-
severity: "error",
|
|
391
|
-
file: ".gitignore",
|
|
392
|
-
message: `.gitignore must contain "${entry}"`
|
|
393
|
-
});
|
|
394
|
-
}
|
|
1043
|
+
for (const entry of forbiddenGitignoreEntries(text)) {
|
|
1044
|
+
issues.push({
|
|
1045
|
+
linter: this.id,
|
|
1046
|
+
severity: "error",
|
|
1047
|
+
file: ".gitignore",
|
|
1048
|
+
message: `.gitignore must not contain "${entry}": files the harness generates are committed`
|
|
1049
|
+
});
|
|
395
1050
|
}
|
|
396
1051
|
return issues;
|
|
397
1052
|
}
|
|
398
1053
|
};
|
|
399
1054
|
|
|
400
1055
|
// src/linters/orphan-decisions.ts
|
|
401
|
-
import { basename } from "path";
|
|
402
|
-
import
|
|
1056
|
+
import { basename as basename2 } from "path";
|
|
1057
|
+
import fg5 from "fast-glob";
|
|
403
1058
|
var orphanDecisions = {
|
|
404
1059
|
id: "lint:orphan-decisions",
|
|
405
1060
|
pillars: ["decisions"],
|
|
@@ -410,7 +1065,7 @@ var orphanDecisions = {
|
|
|
410
1065
|
const issues = [];
|
|
411
1066
|
const adrs = listMarkdown(repoRoot, "docs/decisions");
|
|
412
1067
|
if (adrs.length === 0) return issues;
|
|
413
|
-
const otherDocs =
|
|
1068
|
+
const otherDocs = fg5.sync("**/*.md", {
|
|
414
1069
|
cwd: repoRoot,
|
|
415
1070
|
absolute: false,
|
|
416
1071
|
ignore: [
|
|
@@ -427,7 +1082,7 @@ var orphanDecisions = {
|
|
|
427
1082
|
});
|
|
428
1083
|
const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
|
|
429
1084
|
for (const adr of adrs) {
|
|
430
|
-
const filename =
|
|
1085
|
+
const filename = basename2(adr);
|
|
431
1086
|
const stem = filename.replace(/\.md$/, "");
|
|
432
1087
|
const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
|
|
433
1088
|
if (!referenced) {
|
|
@@ -603,12 +1258,12 @@ var specTechAgnostic = {
|
|
|
603
1258
|
};
|
|
604
1259
|
|
|
605
1260
|
// src/linters/tracks-drift.ts
|
|
606
|
-
import
|
|
1261
|
+
import fg6 from "fast-glob";
|
|
607
1262
|
var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
608
1263
|
var DEFAULT_DRIFT_THRESHOLD = 10;
|
|
609
1264
|
function expandGlob(repoRoot, pattern) {
|
|
610
1265
|
if (pattern.includes("*")) {
|
|
611
|
-
return
|
|
1266
|
+
return fg6.sync(pattern, { cwd: repoRoot, absolute: false });
|
|
612
1267
|
}
|
|
613
1268
|
return [pattern];
|
|
614
1269
|
}
|
|
@@ -665,7 +1320,8 @@ var ALL_LINTERS = [
|
|
|
665
1320
|
crossLinks,
|
|
666
1321
|
orphanDecisions,
|
|
667
1322
|
gitignoreHarness,
|
|
668
|
-
qualitySchema
|
|
1323
|
+
qualitySchema,
|
|
1324
|
+
generatedFresh
|
|
669
1325
|
];
|
|
670
1326
|
function runLinters(repoRoot, opts = {}) {
|
|
671
1327
|
const config = loadLintConfig(repoRoot);
|