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 c0ea70e838
commit 6a66440095
243 files changed
+23698 -1607

No files matched your search

@@ -0,0 +1,224 @@
#!/usr/bin/env node
// agent-files.mjs: find other AI agents' config files and point them at AGENTS.md.
//
// Init and Init Update both end with the same step: detect CLAUDE.md, GEMINI.md,
// .cursorrules, the Copilot instructions and the Cursor / Windsurf rule folders,
// and (only for the ones the user confirms) replace each with a short pointer
// to AGENTS.md. Which files exist, how long they are, the relative path back to
// AGENTS.md and the replacement text are all fixed, so they live here.
import fs from "node:fs";
import path from "node:path";
import { EXIT, fail, out, parseArgs, run, readText, isDir } from "./common.mjs";
const USAGE = `
agent-files.mjs: detect AI agent config files and replace them with AGENTS.md pointers. JSON on stdout.
node agent-files.mjs detect [--root <dir>]
Every config file present, with its line count, whether it has custom
content (more than 10 lines) and the pointer it would get.
node agent-files.mjs apply <id> [<id> ...] [--root <dir>] [--dry-run]
node agent-files.mjs apply --all [--root <dir>] [--dry-run]
Replace the confirmed entries (ids from detect: CLAUDE.md, GEMINI.md,
.cursorrules, .github/copilot-instructions.md, .cursor/rules,
.windsurf/rules). A rules folder loses its .md files (and .mdc, for Cursor) and gets one
reference.md. Only run this for entries the user confirmed.
An entry that is AGENTS.md itself through a symlink or hard link
(detect: linkedToAgents) is refused by id and skipped by --all
("skipped-linked"). A symlink to any other file is removed and replaced,
never written through.
Exit: 0 ok · 2 bad arguments · 3 AGENTS.md missing or an id not present ·
5 refused (an entry linked to AGENTS.md).
`;
// id, title, where the pointer goes, and the relative path back to AGENTS.md.
const TARGETS = [
{ id: "CLAUDE.md", title: "CLAUDE.md", file: "CLAUDE.md", ref: "./AGENTS.md" },
{ id: "GEMINI.md", title: "GEMINI.md", file: "GEMINI.md", ref: "./AGENTS.md" },
{ id: ".cursorrules", title: ".cursorrules", file: ".cursorrules", ref: "./AGENTS.md" },
{ id: ".github/copilot-instructions.md", title: "Copilot Instructions", file: ".github/copilot-instructions.md", ref: "../AGENTS.md" },
{ id: ".cursor/rules", title: "Project Rules", dir: ".cursor/rules", ref: "../../AGENTS.md" },
{ id: ".windsurf/rules", title: "Project Rules", dir: ".windsurf/rules", ref: "../../AGENTS.md" },
];
const CUSTOM_LINES = 10;
// CLAUDE.md gets its own template: Claude Code auto-loads it, so it carries the
// directive that makes AGENTS.md the mandatory first read.
function claudeTemplate() {
return [
"# CLAUDE.md",
"",
"**CRITICAL — MANDATORY FIRST STEP: You MUST read [AGENTS.md](./AGENTS.md) before responding to ANY user message, including simple questions. Do NOT skip this step regardless of how trivial the request appears. No exceptions.**",
"",
"See AGENTS.md for complete project documentation including:",
"- Development commands and setup",
"- Architecture overview",
"- Environment variables",
"- Testing patterns",
"- Deployment guides",
"- Keeping this file current / Failure log",
"- Section details in .agents-docs/",
"",
"This file exists for Claude Code auto-loading. All AI coding agents should reference AGENTS.md.",
"",
].join("\n");
}
function referenceTemplate(title, ref) {
return [
`# ${title}`,
"",
`See [AGENTS.md](${ref}) for complete project documentation including:`,
"- Development commands and setup",
"- Architecture overview",
"- Environment variables",
"- Testing patterns",
"- Deployment guides",
"- Keeping this file current / Failure log",
"- Section details in .agents-docs/",
"",
].join("\n");
}
function templateFor(t) {
return t.id === "CLAUDE.md" ? claudeTemplate() : referenceTemplate(t.title, t.ref);
}
// A CRLF checkout of a pointer file is still the pointer.
function lf(text) {
return text === null ? null : text.replace(/\r\n/g, "\n");
}
const samePath = (a, b) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
// True when p is AGENTS.md itself: a symlink resolving to it, or a hard link to
// the same inode. Writing a pointer through either would replace AGENTS.md.
// Some platforms report ino 0 for every file, so 0 never counts as a match.
function isAgentsFile(p, agents) {
try {
if (samePath(fs.realpathSync.native(p), fs.realpathSync.native(agents))) return true;
const a = fs.statSync(p, { bigint: true });
const b = fs.statSync(agents, { bigint: true });
return a.ino !== 0n && a.ino === b.ino && a.dev === b.dev;
} catch {
return false;
}
}
function lineCount(text) {
if (!text) return 0;
return text.replace(/\r?\n$/, "").split(/\r?\n/).length;
}
function detect(root) {
const agents = path.join(root, "AGENTS.md");
const found = [];
for (const t of TARGETS) {
if (t.file) {
const text = readText(path.join(root, t.file));
if (text === null) continue;
const lines = lineCount(text);
found.push({
id: t.id,
title: t.title,
files: [{ path: t.file, lines }],
lines,
custom: lines > CUSTOM_LINES,
alreadyPointer: lf(text) === templateFor(t),
linkedToAgents: isAgentsFile(path.join(root, t.file), agents),
writes: t.file,
pointsTo: t.ref,
});
} else {
const dir = path.join(root, t.dir);
if (!isDir(dir)) continue;
// Cursor's own rule files are .mdc; leaving them would keep a second source of rules.
const exts = t.id === ".cursor/rules" ? [".md", ".mdc"] : [".md"];
const mds = fs.readdirSync(dir).filter((n) => exts.some((e) => n.toLowerCase().endsWith(e)) && !isDir(path.join(dir, n))).sort();
if (!mds.length) continue;
const files = mds.map((n) => ({ path: `${t.dir}/${n}`, lines: lineCount(readText(path.join(dir, n))) }));
const lines = files.reduce((n, f) => n + f.lines, 0);
found.push({
id: t.id,
title: t.title,
files,
lines,
custom: files.some((f) => f.lines > CUSTOM_LINES),
alreadyPointer: mds.length === 1 && mds[0] === "reference.md" && lf(readText(path.join(dir, "reference.md"))) === templateFor(t),
linkedToAgents: mds.some((n) => isAgentsFile(path.join(dir, n), agents)),
writes: `${t.dir}/reference.md`,
deletes: files.map((f) => f.path).filter((p) => !p.endsWith("/reference.md")),
pointsTo: t.ref,
});
}
}
return found;
}
run(USAGE, async (argv) => {
const args = parseArgs(argv, { booleans: ["dry-run", "all"], values: ["root"] });
const cmd = args._[0];
const root = path.resolve(args.root || ".");
const hasAgents = fs.existsSync(path.join(root, "AGENTS.md"));
if (cmd === "detect") {
const found = detect(root);
out({
ok: true,
root,
hasAgents,
found,
warnings: found.filter((f) => f.custom && !f.alreadyPointer && !f.linkedToAgents).map((f) => `${f.id} has custom content that will be replaced (${f.lines} lines).`),
...(found.length ? {} : { note: "No AI agent config files found: skip this step silently." }),
});
return;
}
if (cmd !== "apply") fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: detect, apply. Run with --help.");
if (!hasAgents) fail(EXIT.NOT_FOUND, "no-agents-md", "AGENTS.md does not exist, so there is nothing to point these files at.", "Create AGENTS.md first.");
const ids = args._.slice(1);
if (!args.all && !ids.length) fail(EXIT.USAGE, "nothing-selected", "Name the entries to replace, or pass --all.", "Use the ids `detect` printed, for the entries the user confirmed.");
const found = detect(root);
const chosen = args.all ? found : ids.map((id) => {
const hit = found.find((f) => f.id === id.replace(/\\/g, "/").replace(/\/$/, ""));
if (!hit) fail(EXIT.NOT_FOUND, "not-present", `"${id}" is not one of the detected entries (${found.map((f) => f.id).join(", ") || "none"}).`, "Run `detect` and use its ids.");
return hit;
});
// Checked before anything is written, so a refusal leaves every file as it was.
const linked = chosen.find((c) => c.linkedToAgents);
if (linked && !args.all) {
fail(EXIT.REFUSED, "linked-to-agents", `${linked.id} is AGENTS.md itself (via a symlink or hard link); replacing it would overwrite AGENTS.md with the pointer.`, `Leave ${linked.id} as it is: it already serves AGENTS.md. Rerun apply without it.`);
}
const actions = [];
for (const entry of chosen) {
if (entry.linkedToAgents) {
actions.push({ action: "skipped-linked", path: entry.writes });
continue;
}
const t = TARGETS.find((x) => x.id === entry.id);
const content = templateFor(t);
for (const del of entry.deletes || []) {
actions.push({ action: "delete", path: del });
if (!args["dry-run"]) fs.rmSync(path.join(root, del), { force: true });
}
const target = path.join(root, entry.writes);
const changed = lf(readText(target)) !== content;
actions.push({ action: changed ? "write" : "unchanged", path: entry.writes });
if (changed && !args["dry-run"]) {
fs.mkdirSync(path.dirname(target), { recursive: true });
// A symlink (or a hard link) to some other file is replaced, not written
// through, so the file it shares content with is left alone.
let st = null;
try {
st = fs.lstatSync(target);
} catch {}
if (st && (st.isSymbolicLink() || st.nlink > 1)) fs.rmSync(target, { force: true });
fs.writeFileSync(target, content);
}
}
out({ ok: true, root, dryRun: !!args["dry-run"], updated: chosen.filter((c) => !c.linkedToAgents).map((c) => c.id), actions });
});