Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-04 12:17:05 -07:00
1 parent 5cbc6edce2
commit 7d54941b75
243 files changed
+23698 -1607

No files matched your search

+157
View File
@@ -0,0 +1,157 @@
#!/usr/bin/env node
// agents-md.mjs: the shape of a project's AGENTS.md, read from disk.
//
// Init and Init Update both start by establishing facts about AGENTS.md: does
// it exist, how long is it, which sections does it have, is it a single file
// or an index over .agents-docs/, which section files exist, which links are
// broken, which section files nothing links to. All of that is mechanical;
// what to write about it is not.
import fs from "node:fs";
import path from "node:path";
import { EXIT, fail, out, parseArgs, run, readText, isDir } from "./common.mjs";
const USAGE = `
agents-md.mjs: inspect AGENTS.md and .agents-docs/. JSON on stdout.
node agents-md.mjs inspect [--root <dir>]
exists, line count against the 500-line budget, structure
(progressive or single-file), every ## section with its line count and
its Details link, the always-inline sections, .agents-docs/ files with
their breadcrumb check, broken links, orphan section files (no link from
AGENTS.md).
node agents-md.mjs filename "<Section Name>"
The detail file for a section: AGENTS-<kebab-case>.md, its link line
and its two header lines.
Exit: 0 ok (check "exists") · 2 bad arguments.
`;
const LIMIT = 500;
const ALWAYS_INLINE = ["Project Overview", "How to Use This File", "Keeping this file current", "Failure log"];
const BREADCRUMB = "> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.";
function kebab(name) {
return name
.normalize("NFKD")
.replace(/[̀-ͯ]/g, "")
.toLowerCase()
.replace(/&/g, " and ")
.replace(/[^a-z0-9]+/g, "-")
.replace(/^-+|-+$/g, "");
}
function lineCount(text) {
return text ? text.replace(/\r?\n$/, "").split(/\r?\n/).length : 0;
}
function sectionsOf(text) {
const lines = text.split(/\r?\n/);
const outList = [];
let inFence = false;
lines.forEach((l, i) => {
if (/^\s*(```|~~~)/.test(l)) inFence = !inFence;
if (inFence) return;
const m = l.match(/^## +(.+?)\s*$/);
if (m) outList.push({ name: m[1].trim(), line: i + 1 });
});
outList.forEach((s, i) => {
const end = i + 1 < outList.length ? outList[i + 1].line - 1 : lines.length;
const body = lines.slice(s.line, end).join("\n");
s.lines = end - s.line + 1;
const link = body.match(/\]\((\.\/)?\.agents-docs\/([^)\s#]+)/);
s.details = link ? `.agents-docs/${link[2]}` : null;
});
return outList;
}
function inspect(root) {
const file = path.join(root, "AGENTS.md");
const text = readText(file);
const docsDir = path.join(root, ".agents-docs");
const hasDocs = isDir(docsDir);
const docFiles = hasDocs
? fs.readdirSync(docsDir).filter((n) => n.toLowerCase().endsWith(".md")).sort().map((n) => {
const t = readText(path.join(docsDir, n)) || "";
const lines = t.split(/\r?\n/);
const h1 = lines.find((l) => /^# /.test(l));
return {
path: `.agents-docs/${n}`,
lines: lineCount(t),
title: h1 ? h1.replace(/^# +/, "").trim() : null,
breadcrumb: lines.slice(0, 6).some((l) => l.trim() === BREADCRUMB || /^> Part of \[AGENTS\.md\]\(\.\.\/AGENTS\.md\)/.test(l.trim())),
namedLikeConvention: /^AGENTS-[a-z0-9]+(-[a-z0-9]+)*\.md$/.test(n),
};
})
: [];
if (text === null) {
return { ok: true, root, exists: false, hasAgentsDocs: hasDocs, agentsDocs: docFiles, otherFiles: ["CLAUDE.md", "README.md", "PROJECT.md", "GEMINI.md", ".cursorrules", ".github/copilot-instructions.md"].filter((f) => fs.existsSync(path.join(root, f))) };
}
const sections = sectionsOf(text);
const linked = new Set();
for (const m of text.matchAll(/\]\((?:\.\/)?(\.agents-docs\/[^)\s#]+)/g)) linked.add(m[1]);
const broken = [...linked].filter((l) => !fs.existsSync(path.join(root, l)));
// A section file nothing in AGENTS.md links to is an orphan, unless another
// section file links to it: that one is reached indirectly, and deleting it
// would break a link, so it is reported apart and never offered for removal.
const fromDocs = new Set();
for (const d of docFiles) {
const t = readText(path.join(root, d.path)) || "";
for (const m of t.matchAll(/\]\((?:\.\/)?([^)\s#]+\.md)/g)) {
const target = path.posix.normalize(path.posix.join(".agents-docs", m[1]));
if (target !== d.path) fromDocs.add(target);
}
}
const unlinked = docFiles.map((d) => d.path).filter((p) => !linked.has(p));
const orphans = unlinked.filter((p) => !fromDocs.has(p));
const indirect = unlinked.filter((p) => fromDocs.has(p));
const inline = ALWAYS_INLINE.map((name) => {
const s = sections.find((x) => x.name.toLowerCase() === name.toLowerCase());
return { name, present: !!s, splitOut: !!(s && s.details) };
});
const count = lineCount(text);
return {
ok: true,
root,
exists: true,
lines: count,
budget: `${count}/${LIMIT}`,
nearLimit: count > LIMIT * 0.9,
overLimit: count > LIMIT,
structure: hasDocs ? "progressive" : "single-file",
sections,
alwaysInline: inline,
hasAgentsDocs: hasDocs,
agentsDocs: docFiles,
brokenLinks: broken,
orphans,
indirect,
problems: [
...broken.map((b) => `AGENTS.md links to ${b}, which does not exist`),
...orphans.map((o) => `${o} has no link from AGENTS.md (orphan: offer to remove it)`),
...inline.filter((s) => s.splitOut).map((s) => `${s.name} must stay inline in AGENTS.md but links out to a section file`),
...docFiles.filter((d) => !d.breadcrumb).map((d) => `${d.path} lacks the "> Part of [AGENTS.md](../AGENTS.md)" breadcrumb`),
...docFiles.filter((d) => !d.namedLikeConvention).map((d) => `${d.path} is not named AGENTS-<kebab-case>.md`),
],
};
}
run(USAGE, async (argv) => {
const args = parseArgs(argv, { values: ["root"] });
const cmd = args._[0];
if (cmd === "inspect") {
out(inspect(path.resolve(args.root || ".")));
return;
}
if (cmd === "filename") {
const name = args._.slice(1).join(" ").trim();
if (!name) fail(EXIT.USAGE, "missing-name", "Give the section name.", 'Example: filename "Development Commands"');
const slug = kebab(name);
if (!slug) fail(EXIT.USAGE, "bad-name", `"${name}" has no letters or digits to name a file from.`, "Use the section's heading text.");
const file = `.agents-docs/AGENTS-${slug}.md`;
out({ ok: true, section: name, file, link: `Details: [${name}](./${file})`, header: [`# ${name}`, BREADCRUMB] });
return;
}
fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: inspect, filename. Run with --help.");
});