@baldurpan/create-ai-workflow 0.2.0

package/dist/cli.js

@@ -0,0 +1,109 @@
+import path from 'node:path';
+import { check } from "./commands/check.js";
+import { install } from "./commands/install.js";
+import { standardsAdd } from "./commands/standards-add.js";
+import { update } from "./commands/update.js";
+import { bold, cyan, dim, info, UserError } from "./log.js";
+import { packageVersion } from "./paths.js";
+const USAGE = `${bold('create-ai-workflow')} — overlay a tiered planning workflow onto an existing repository
+
+${bold('Usage')}
+  npx @baldurpan/create-ai-workflow                      install into this repository
+  npm  create @baldurpan/ai-workflow                     the same thing, shorter
+  npx @baldurpan/create-ai-workflow update               replace the tool-owned files with this version
+  npx @baldurpan/create-ai-workflow standards add <url>  swap context/standards/ for a git repository
+  npx @baldurpan/create-ai-workflow check                report structural breakage; never writes
+
+${bold('Options')}
+  --dir <path>        act on this directory instead of the working directory
+  --dry-run           ${dim('update:')} print the plan and change nothing
+  --force             ${dim('update:')} back up edited files (.bak) and take ours
+  --generate-index    ${dim('standards add:')} build a conditional-loading table without asking
+  --version, --help
+
+${bold('What it installs')}
+  context/            the workflow's documents. Tool-owned files are replaced on update; your
+                      roadmap, plans, findings, stack, verify and executors never are.
+  .claude/            seven skills and two subagent definitions, for Claude Code.
+  .agents/            the same seven skills, for Codex and anything else reading that tree.
+  AGENTS.md           a delimited block, merged into whatever is already there.
+  CLAUDE.md           a single ${cyan('@AGENTS.md')} line, and only if the file does not exist.
+
+Nothing is committed. Review the diff, then run ${cyan('/onboard')} in your agent.
+`;
+export function parseArgs(argv) {
+    const args = {
+        command: '',
+        rest: [],
+        dir: process.cwd(),
+        dryRun: false,
+        force: false,
+        generateIndex: false,
+        help: false,
+        version: false,
+    };
+    const positional = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--dir':
+                i += 1;
+                args.dir = path.resolve(argv[i] ?? '.');
+                break;
+            case '--dry-run':
+                args.dryRun = true;
+                break;
+            case '--force':
+                args.force = true;
+                break;
+            case '--generate-index':
+                args.generateIndex = true;
+                break;
+            case '--help':
+            case '-h':
+                args.help = true;
+                break;
+            case '--version':
+            case '-v':
+                args.version = true;
+                break;
+            default:
+                if (arg.startsWith('-'))
+                    throw new UserError(`unknown option ${arg}`);
+                positional.push(arg);
+        }
+    }
+    args.command = positional[0] ?? 'install';
+    args.rest = positional.slice(1);
+    return args;
+}
+export async function main(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        info(USAGE);
+        return 0;
+    }
+    if (args.version) {
+        info(packageVersion());
+        return 0;
+    }
+    switch (args.command) {
+        case 'install':
+            return install(args.dir);
+        case 'update':
+            return update(args.dir, { dryRun: args.dryRun, force: args.force });
+        case 'check':
+            return check(args.dir);
+        case 'standards': {
+            const [sub, url] = args.rest;
+            if (sub !== 'add') {
+                throw new UserError('the only standards subcommand is `standards add <git-url>`');
+            }
+            if (!url)
+                throw new UserError('`standards add` needs a git URL');
+            return standardsAdd(args.dir, url, { generateIndex: args.generateIndex });
+        }
+        default:
+            throw new UserError(`unknown command \`${args.command}\`. Run with --help for the four it knows.`);
+    }
+}

package/dist/commands/check.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { runChecks } from "../check/rules.js";
+import { CONTEXT_DIR } from "../layout.js";
+import { bold, dim, green, info, red, UserError, yellow } from "../log.js";
+import { exists } from "../paths.js";
+/**
+ * Reports structural breakage and nothing else. It never writes — there is no `--fix`, because the moment
+ * it can repair a ledger, a program's edit competes with a hand edit. Nothing depends on it: delete it and
+ * every workflow answer is unchanged.
+ */
+export function check(root) {
+    if (!exists(path.join(root, CONTEXT_DIR))) {
+        throw new UserError(`no ${CONTEXT_DIR}/ in ${root} — nothing to check.\n` +
+            '  Run `npx @baldurpan/create-ai-workflow` to install the overlay.');
+    }
+    const problems = runChecks(root);
+    const errors = problems.filter((p) => p.level === 'error');
+    const notes = problems.filter((p) => p.level === 'note');
+    if (problems.length === 0) {
+        info(`${green('ok')} roadmap, plans, history and findings are structurally sound`);
+        return 0;
+    }
+    for (const problem of problems) {
+        const marker = problem.level === 'error' ? red('error') : yellow('note ');
+        const where = problem.line ? `${problem.file}:${problem.line}` : problem.file;
+        info(`${marker} ${bold(where)}`);
+        info(`      ${problem.message}`);
+        info(`      ${dim(problem.rule)}`);
+        info();
+    }
+    const parts = [];
+    if (errors.length)
+        parts.push(`${errors.length} error${errors.length === 1 ? '' : 's'}`);
+    if (notes.length)
+        parts.push(`${notes.length} note${notes.length === 1 ? '' : 's'}`);
+    info(parts.join(', '));
+    if (errors.length === 0) {
+        info(dim('Notes do not fail the check — nothing here is structurally broken.'));
+    }
+    return errors.length > 0 ? 1 : 0;
+}

package/dist/commands/install.js

@@ -0,0 +1,76 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { apply as applyBlock, BlockConflictError } from "../agents-block.js";
+import { ADAPTER_SKILL_DIRS, AGENTS_BLOCK_KEY, CONTEXT_DIR, DEFAULT_ADAPTERS, STUB_DIRS, STUBS, agentsBlockBody, managedFiles, readTemplate, renderManaged, } from "../layout.js";
+import { bold, cyan, dim, green, info, UserError, warn } from "../log.js";
+import { SCHEMA_VERSION, writeManifest } from "../manifest.js";
+import { exists, hash, packageVersion } from "../paths.js";
+const CLAUDE_MD_IMPORT = '@AGENTS.md';
+function write(root, dest, content) {
+    const full = path.join(root, dest);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, content, 'utf8');
+}
+export function install(root) {
+    if (exists(path.join(root, CONTEXT_DIR))) {
+        throw new UserError(`${CONTEXT_DIR}/ already exists in ${root}.\n` +
+            '  This tool overlays onto a repository that does not have one; it does not merge into an\n' +
+            '  existing directory. If this is an earlier install, run `update` instead. If it is yours,\n' +
+            '  move it aside first.');
+    }
+    const adapters = DEFAULT_ADAPTERS;
+    const manifest = {
+        schemaVersion: SCHEMA_VERSION,
+        version: packageVersion(),
+        adapters: [...adapters],
+        managedFiles: {},
+    };
+    info(bold('Installing the ai-workflow overlay'));
+    info();
+    const managed = managedFiles(adapters);
+    for (const file of managed) {
+        const content = renderManaged(file);
+        write(root, file.dest, content);
+        manifest.managedFiles[file.dest] = hash(content);
+    }
+    info(`${green('+')} ${managed.length} tool-owned files ${dim('(replaced on update)')}`);
+    info(dim(`    the seven skills go to ${adapters.map((a) => `${ADAPTER_SKILL_DIRS[a]}/`).join(' and ')} — ` +
+        'one body, one directory per host, neither hand-edited'));
+    for (const stub of STUBS) {
+        write(root, stub.dest, readTemplate(stub.source));
+    }
+    for (const dir of STUB_DIRS) {
+        write(root, `${dir}/.gitkeep`, '');
+    }
+    info(`${green('+')} ${STUBS.length} project-owned stubs and ${STUB_DIRS.length} directories ` +
+        `${dim('(yours — the updater cannot reach them)')}`);
+    const agentsPath = path.join(root, 'AGENTS.md');
+    const body = agentsBlockBody();
+    const before = exists(agentsPath) ? readFileSync(agentsPath, 'utf8') : null;
+    try {
+        writeFileSync(agentsPath, applyBlock(before, body), 'utf8');
+    }
+    catch (error) {
+        if (error instanceof BlockConflictError)
+            throw new UserError(error.message);
+        throw error;
+    }
+    manifest.managedFiles[AGENTS_BLOCK_KEY] = hash(body);
+    info(`${green(before === null ? '+' : '~')} AGENTS.md ${dim('— the delimited block only')}`);
+    const claudeMdPath = path.join(root, 'CLAUDE.md');
+    if (!exists(claudeMdPath)) {
+        writeFileSync(claudeMdPath, `# CLAUDE.md\n\n${CLAUDE_MD_IMPORT}\n\nThe import above is this project's agent-neutral instruction set, expanded into context at launch.\n**Everything that is not Claude-Code-specific belongs there, not here.**\n`, 'utf8');
+        info(`${green('+')} CLAUDE.md ${dim(`— one ${CLAUDE_MD_IMPORT} line. Yours from here on.`)}`);
+    }
+    else if (!readFileSync(claudeMdPath, 'utf8').includes(CLAUDE_MD_IMPORT)) {
+        warn(`CLAUDE.md exists without an ${CLAUDE_MD_IMPORT} import — left untouched.\n` +
+            `  Add the single line ${cyan(CLAUDE_MD_IMPORT)} to it so the block above reaches Claude Code.`);
+    }
+    writeManifest(root, manifest);
+    info();
+    info(bold('Next'));
+    info(`  1. Review the diff. ${dim('Nothing was committed — that is deliberate.')}`);
+    info(`  2. Run ${cyan('/onboard')} in your agent to fill in verify.md, executors.md and stack.md.`);
+    info(`  3. ${cyan('/roadmap "some idea"')} starts the loop.`);
+    return 0;
+}

package/dist/commands/standards-add.js

@@ -0,0 +1,145 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, cpSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseTables } from "../check/markdown.js";
+import { STANDARDS_PREFIX } from "../layout.js";
+import { bold, cyan, dim, green, info, UserError, warn } from "../log.js";
+import { readManifest, writeManifest } from "../manifest.js";
+import { exists, walk } from "../paths.js";
+const INDEX_HEADER = ['If the task involves…', 'Load…'];
+function git(args, cwd) {
+    try {
+        return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch (error) {
+        const message = error.stderr ?? error.message;
+        throw new UserError(`git ${args[0]} failed:\n  ${message.trim()}`);
+    }
+}
+/**
+ * The conditional-loading table is the interface, not the files behind it — agents read that table and pull
+ * exactly what it names. A tree whose README has no usable table is a tree the skills cannot navigate.
+ */
+export function findIndexTable(readme, root) {
+    for (const table of parseTables(readme)) {
+        if (table.header.length < 2 || table.rows.length < 2)
+            continue;
+        const targets = table.rows.flatMap((row) => [...(row.cells[1] ?? '').matchAll(/\]\(([^)\s#]+)/g)].map((m) => m[1]));
+        if (targets.length < 2)
+            continue;
+        const missing = targets.filter((t) => !/^[a-z]+:/i.test(t) && !existsSync(path.join(root, t)));
+        return { rows: table.rows.length, missing: [...new Set(missing)] };
+    }
+    return null;
+}
+export function generateIndexTable(root) {
+    const files = walk(root).filter((rel) => rel.endsWith('.md') && path.dirname(rel) !== '.');
+    const byDir = new Map();
+    for (const rel of files) {
+        const dir = rel.split(path.sep)[0];
+        byDir.set(dir, [...(byDir.get(dir) ?? []), rel.split(path.sep).join('/')]);
+    }
+    const lines = [
+        '## Conditional loading',
+        '',
+        '**Generated from this tree\'s directory structure at install time.** It is a starting point, not a',
+        'considered index — rewrite the left column to say what each group is actually *for*, because that is',
+        'the column agents match against.',
+        '',
+        `| ${INDEX_HEADER.join(' | ')} |`,
+        '|---|---|',
+    ];
+    for (const [dir, paths] of [...byDir].sort(([a], [b]) => (a < b ? -1 : 1))) {
+        const links = paths.map((p) => `[\`${p}\`](${p})`).join(', ');
+        lines.push(`| ${dir} | ${links} |`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+async function confirm(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function standardsAdd(root, url, options) {
+    const manifest = readManifest(root);
+    const destination = path.join(root, STANDARDS_PREFIX.replace(/\/$/, ''));
+    const scratch = mkdtempSync(path.join(tmpdir(), 'ai-workflow-standards-'));
+    try {
+        info(`${dim('cloning')} ${url}`);
+        git(['clone', '--depth', '1', '--quiet', url, scratch]);
+        const ref = git(['rev-parse', 'HEAD'], scratch).trim();
+        const readmePath = path.join(scratch, 'README.md');
+        if (!exists(readmePath)) {
+            throw new UserError('that repository has no README.md.\n' +
+                `  The skills say "consult the conditional loading table in ${STANDARDS_PREFIX}README.md";\n` +
+                '  without that file there is nothing for an agent to traverse. Refusing to install it.');
+        }
+        const readme = readFileSync(readmePath, 'utf8');
+        const table = findIndexTable(readme, scratch);
+        let generated = null;
+        if (table === null) {
+            info();
+            warn('that README has no conditional-loading table.');
+            info(dim('  Agents read that table and load exactly what it names. Without one, the standards are'));
+            info(dim('  present but unreachable, and every task loads nothing or everything.'));
+            info();
+            const ok = options.generateIndex || (await confirm('Generate one from the directory structure?'));
+            if (!ok) {
+                throw new UserError('refusing to install a standards tree the skills cannot navigate.\n' +
+                    '  Add a conditional-loading table to that repo\'s README.md, or re-run with --generate-index.');
+            }
+            generated = generateIndexTable(scratch);
+        }
+        else if (table.missing.length > 0) {
+            warn(`the conditional-loading table names ${table.missing.length} file${table.missing.length === 1 ? '' : 's'} that ` +
+                'do not exist in that repository:');
+            for (const missing of table.missing.slice(0, 10))
+                info(`    ${missing}`);
+            if (table.missing.length > 10)
+                info(dim(`    …and ${table.missing.length - 10} more`));
+            info(dim('  Installed anyway — those rows will simply never resolve.'));
+        }
+        else {
+            info(`${green('ok')} conditional-loading table found — ${table.rows} rows, every target resolves`);
+        }
+        rmSync(path.join(scratch, '.git'), { recursive: true, force: true });
+        if (generated) {
+            writeFileSync(readmePath, `${readme.replace(/\s+$/, '')}\n\n${generated}`, 'utf8');
+        }
+        writeFileSync(path.join(scratch, '.source'), `# Origin of this standards tree. Project-owned: \`update\` does not reach it.\n` +
+            `origin=${url}\nref=${ref}\nvendored=${new Date().toISOString()}\n`, 'utf8');
+        rmSync(destination, { recursive: true, force: true });
+        cpSync(scratch, destination, { recursive: true });
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    // Whatever lands is project-owned from this point — it drops out of the manifest, so `update` can never
+    // clobber it.
+    let dropped = 0;
+    for (const key of Object.keys(manifest.managedFiles)) {
+        if (key.startsWith(STANDARDS_PREFIX)) {
+            delete manifest.managedFiles[key];
+            dropped += 1;
+        }
+    }
+    writeManifest(root, manifest);
+    info();
+    info(`${green('done')} ${STANDARDS_PREFIX} replaced from ${bold(url)}`);
+    if (dropped > 0) {
+        info(dim(`  ${dropped} entries dropped from the manifest — this tree is yours now, and updates`));
+        info(dim('  will never overwrite it.'));
+    }
+    info(`  Review the diff, then check that ${cyan(`${STANDARDS_PREFIX}README.md`)} reads as an index an agent`);
+    info('  would actually follow. Nothing was committed.');
+    return 0;
+}

package/dist/commands/update.js

@@ -0,0 +1,214 @@
+import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { apply as applyBlock, BlockConflictError, inspect } from "../agents-block.js";
+import { AGENTS_BLOCK_KEY, DEFAULT_ADAPTERS, STANDARDS_PREFIX, agentsBlockBody, managedFiles, renderManaged, } from "../layout.js";
+import { bold, cyan, dim, green, info, red, UserError, warn, yellow } from "../log.js";
+import { readManifest, writeManifest } from "../manifest.js";
+import { exists, hash, packageVersion } from "../paths.js";
+const LABEL = {
+    replace: green('update '),
+    restore: green('restore'),
+    add: green('add    '),
+    unchanged: dim('same   '),
+    conflict: red('CONFLICT'),
+    remove: yellow('remove '),
+    adopt: yellow('adopt  '),
+};
+function readIfExists(file) {
+    return exists(file) ? readFileSync(file, 'utf8') : null;
+}
+function sourceRef(text) {
+    return text ? (/^ref=(.+)$/m.exec(text)?.[1]?.trim() ?? null) : null;
+}
+export function update(root, options) {
+    const manifest = readManifest(root);
+    // Adapters reconcile to what this version ships rather than to what the install recorded. An install
+    // made before a tree existed is the only way that tree ever arrives, and a tree this version has
+    // dropped falls through to the no-longer-shipped branch below and is removed. Both are reported.
+    const adapters = DEFAULT_ADAPTERS;
+    const gained = adapters.filter((a) => !manifest.adapters.includes(a));
+    const dropped = manifest.adapters.filter((a) => !adapters.includes(a));
+    const files = managedFiles(adapters);
+    const byDest = new Map(files.map((f) => [f.dest, f]));
+    // The standards tree is tool-owned only while it is ours and unmodified. One edited file makes the whole
+    // tree the project's — half-managed is worse than either, because the README's conditional table and the
+    // files it names have to agree.
+    const standardsInManifest = Object.keys(manifest.managedFiles).filter((p) => p.startsWith(STANDARDS_PREFIX));
+    const standardsEdited = standardsInManifest.some((dest) => {
+        const onDisk = readIfExists(path.join(root, dest));
+        return onDisk === null ? false : hash(onDisk) !== manifest.managedFiles[dest];
+    });
+    const standardsAdopted = standardsInManifest.length === 0 || standardsEdited;
+    const steps = [];
+    for (const file of files) {
+        if (file.dest.startsWith(STANDARDS_PREFIX) && standardsAdopted)
+            continue;
+        const recorded = manifest.managedFiles[file.dest];
+        const target = renderManaged(file);
+        const onDisk = readIfExists(path.join(root, file.dest));
+        if (onDisk === null) {
+            steps.push(recorded === undefined
+                ? { dest: file.dest, action: 'add', note: 'new in this version' }
+                : { dest: file.dest, action: 'restore' });
+        }
+        else if (recorded === undefined) {
+            steps.push({
+                dest: file.dest,
+                action: 'conflict',
+                note: 'exists but is not in the manifest — this tool did not write it',
+            });
+        }
+        else if (hash(onDisk) === recorded) {
+            steps.push({ dest: file.dest, action: hash(target) === recorded ? 'unchanged' : 'replace' });
+        }
+        else {
+            steps.push({ dest: file.dest, action: 'conflict', note: 'edited since it was installed' });
+        }
+    }
+    if (standardsAdopted && standardsInManifest.length > 0) {
+        steps.push({
+            dest: `${STANDARDS_PREFIX}*`,
+            action: 'adopt',
+            note: 'edited — the whole standards tree becomes project-owned and drops out of the manifest',
+        });
+    }
+    // Anything the manifest still lists that this version no longer ships.
+    for (const dest of Object.keys(manifest.managedFiles)) {
+        if (dest === AGENTS_BLOCK_KEY || byDest.has(dest))
+            continue;
+        if (dest.startsWith(STANDARDS_PREFIX) && standardsAdopted)
+            continue;
+        const onDisk = readIfExists(path.join(root, dest));
+        if (onDisk === null)
+            continue;
+        steps.push(hash(onDisk) === manifest.managedFiles[dest]
+            ? { dest, action: 'remove', note: 'no longer shipped' }
+            : { dest, action: 'conflict', note: 'no longer shipped, and edited — left in place' });
+    }
+    // The AGENTS.md block.
+    const agentsPath = path.join(root, 'AGENTS.md');
+    const agentsText = readIfExists(agentsPath);
+    const body = agentsBlockBody();
+    const state = inspect(agentsText);
+    const recordedBlock = manifest.managedFiles[AGENTS_BLOCK_KEY];
+    let blockStep;
+    if (state.kind === 'duplicate' || state.kind === 'malformed') {
+        blockStep = { dest: AGENTS_BLOCK_KEY, action: 'conflict', note: describeBad(state) };
+    }
+    else if (state.kind === 'no-file' || state.kind === 'no-markers') {
+        blockStep = { dest: AGENTS_BLOCK_KEY, action: 'restore' };
+    }
+    else if (hash(state.body) === recordedBlock) {
+        blockStep = {
+            dest: AGENTS_BLOCK_KEY,
+            action: hash(body) === recordedBlock ? 'unchanged' : 'replace',
+        };
+    }
+    else {
+        blockStep = { dest: AGENTS_BLOCK_KEY, action: 'conflict', note: 'edited since it was installed' };
+    }
+    steps.push(blockStep);
+    // Report.
+    info(bold(`ai-workflow ${manifest.version} → ${packageVersion()}`));
+    info(dim(gained.length || dropped.length
+        ? `adapters: ${manifest.adapters.join(', ')} → ${adapters.join(', ')}`
+        : `adapters: ${adapters.join(', ')}`));
+    info();
+    const conflicts = steps.filter((s) => s.action === 'conflict');
+    const changing = steps.filter((s) => s.action !== 'unchanged');
+    if (changing.length === 0) {
+        info(green('Everything tool-owned is already up to date.'));
+    }
+    for (const step of changing) {
+        info(`  ${LABEL[step.action]} ${step.dest}${step.note ? dim(`  — ${step.note}`) : ''}`);
+    }
+    const same = steps.length - changing.length;
+    if (same > 0)
+        info(dim(`  ${same} file${same === 1 ? '' : 's'} already current`));
+    info();
+    info(bold('Ownership'));
+    info(`  ${green('replaced by update')}  ${dim('the tool-owned files above — every one is in the manifest')}`);
+    info(`  ${cyan('yours, untouched')}    ${dim('context/stack.md, verify.md, executors.md, roadmap.md,')}`);
+    info(`                      ${dim('history.md, findings.md, drafts/, plans/, archive/, CLAUDE.md,')}`);
+    info(`                      ${dim('and anything else you have added under context/')}`);
+    info(dim('  A project-owned file is not in the manifest, so no code path here reaches it.'));
+    const installedRef = sourceRef(readIfExists(path.join(root, `${STANDARDS_PREFIX}.source`)));
+    const bundledRef = sourceRef(renderManagedSourceMarker(files));
+    if (installedRef && bundledRef && installedRef !== bundledRef && !standardsAdopted) {
+        info();
+        info(`${yellow('!')} the bundled standards moved: ${dim(installedRef.slice(0, 8))} → ${dim(bundledRef.slice(0, 8))}`);
+    }
+    if (options.dryRun) {
+        info();
+        info(dim('--dry-run: nothing was written.'));
+        return conflicts.length > 0 && !options.force ? 1 : 0;
+    }
+    if (conflicts.length > 0 && !options.force) {
+        info();
+        throw new UserError(`${conflicts.length} conflict${conflicts.length === 1 ? '' : 's'} — nothing was written.\n` +
+            '  Each file above was edited after this tool wrote it. Re-run with --force to back up the\n' +
+            '  edited copy alongside it (.bak) and take ours, or move your version aside first.');
+    }
+    // Apply.
+    let written = 0;
+    for (const step of steps) {
+        if (step.dest === AGENTS_BLOCK_KEY)
+            continue;
+        if (step.action === 'unchanged' || step.action === 'adopt')
+            continue;
+        const full = path.join(root, step.dest);
+        if (step.action === 'remove') {
+            rmSync(full, { force: true });
+            delete manifest.managedFiles[step.dest];
+            written += 1;
+            continue;
+        }
+        if (step.action === 'conflict') {
+            if (!byDest.has(step.dest))
+                continue; // no longer shipped and edited — leave it alone
+            copyFileSync(full, `${full}.bak`);
+        }
+        const file = byDest.get(step.dest);
+        if (!file)
+            continue;
+        const content = renderManaged(file);
+        mkdirSync(path.dirname(full), { recursive: true });
+        writeFileSync(full, content, 'utf8');
+        manifest.managedFiles[step.dest] = hash(content);
+        written += 1;
+    }
+    if (standardsAdopted) {
+        for (const dest of standardsInManifest)
+            delete manifest.managedFiles[dest];
+    }
+    if (blockStep.action !== 'unchanged') {
+        if (blockStep.action === 'conflict' && agentsText !== null) {
+            copyFileSync(agentsPath, `${agentsPath}.bak`);
+        }
+        try {
+            writeFileSync(agentsPath, applyBlock(agentsText, body), 'utf8');
+        }
+        catch (error) {
+            if (error instanceof BlockConflictError)
+                throw new UserError(error.message);
+            throw error;
+        }
+        manifest.managedFiles[AGENTS_BLOCK_KEY] = hash(body);
+        written += 1;
+    }
+    manifest.version = packageVersion();
+    manifest.adapters = [...adapters];
+    writeManifest(root, manifest);
+    info();
+    info(`${green('done')} ${written} file${written === 1 ? '' : 's'} written. Review the diff — nothing was committed.`);
+    return 0;
+}
+function describeBad(state) {
+    return state.kind === 'duplicate'
+        ? `${state.count} ai-workflow blocks in AGENTS.md — delete the extra one`
+        : `${state.reason} — fix the markers by hand`;
+}
+function renderManagedSourceMarker(files) {
+    const marker = files.find((f) => f.dest === `${STANDARDS_PREFIX}.source`);
+    return marker ? renderManaged(marker) : null;
+}