fullstack-agentic-flow 2.0.0

package/dist/src/cli/commands/init.js

@@ -0,0 +1,103 @@
+import { ClaudeMdMode, parseClaudeMdMode } from '../../domain/claude-md-mode.js';
+import { InvalidOptionError } from '../../domain/errors.js';
+import { PipelineConfig } from '../../domain/pipeline-config.js';
+import { ALL_RUNTIMES, parseRuntimes } from '../../domain/runtime.js';
+import { ALL_TOOL_IDS, StepLocation, parseToolIds } from '../../domain/tool.js';
+import { ALL_TOPOLOGIES, describeTopology, parseTopology } from '../../domain/topology.js';
+import { ApplyOptions } from '../../install/applier.js';
+import { detectStack } from '../../install/detect.js';
+import { TOOL_CATALOG } from '../../registry/tools.js';
+import { onPath, runShell } from '../../io/shell.js';
+import { printApplyReport } from '../report.js';
+import { installFiles, packageVersion } from './shared.js';
+async function askUntilValid(prompter, output, question, fallback, parse) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const answer = await prompter.ask(question);
+        try {
+            return parse(answer === '' ? fallback : answer);
+        }
+        catch (error) {
+            if (!(error instanceof InvalidOptionError))
+                throw error;
+            output.warn(error.message);
+        }
+    }
+    throw new InvalidOptionError('answer', 'three invalid attempts', ['a valid value']);
+}
+async function chooseTopology(args, prompter, output) {
+    if (args.topology !== null)
+        return parseTopology(args.topology);
+    if (args.yes) {
+        throw new InvalidOptionError('--topology', '(missing)', ALL_TOPOLOGIES);
+    }
+    output.info('Topologies:');
+    for (const topology of ALL_TOPOLOGIES)
+        output.info(`  ${topology.padEnd(15)} ${describeTopology(topology)}`);
+    return askUntilValid(prompter, output, `Topology? [${ALL_TOPOLOGIES.join('|')}]`, '', parseTopology);
+}
+async function chooseRuntimes(args, prompter, output) {
+    if (args.runtime !== null)
+        return parseRuntimes(args.runtime);
+    if (args.yes)
+        return ALL_RUNTIMES;
+    return askUntilValid(prompter, output, `Runtimes? comma list of ${ALL_RUNTIMES.join(',')} [default: both]`, ALL_RUNTIMES.join(','), parseRuntimes);
+}
+async function chooseTools(args, prompter, output) {
+    if (args.tools !== null)
+        return parseToolIds(args.tools);
+    if (args.yes)
+        return ALL_TOOL_IDS;
+    output.info('Tools:');
+    for (const tool of TOOL_CATALOG.all())
+        output.info(`  ${tool.id.padEnd(18)} ${tool.purpose}`);
+    return askUntilValid(prompter, output, 'Tools? all | none | comma list [default: all]', 'all', parseToolIds);
+}
+function runToolSteps(config, target, output) {
+    for (const tool of TOOL_CATALOG.forIds(config.tools)) {
+        for (const runtime of config.runtimes) {
+            for (const step of tool.stepsFor(runtime)) {
+                if (step.location === StepLocation.AgentUi) {
+                    output.info(`[${tool.name}] do this yourself: ${step.command}`);
+                    continue;
+                }
+                const missing = step.requires.filter((binary) => !onPath(binary));
+                if (missing.length > 0) {
+                    output.warn(`[${tool.name}] skipped "${step.command}" — not on PATH: ${missing.join(', ')}`);
+                    continue;
+                }
+                output.info(`[${tool.name}] $ ${step.command}`);
+                const result = runShell(step.command, target);
+                if (!result.succeeded)
+                    output.warn(`[${tool.name}] exited ${result.exitCode}; see .ai-agents/SETUP.md`);
+            }
+        }
+    }
+}
+export async function runInit(args, prompter, output) {
+    const detected = await detectStack(args.target);
+    output.info(`Target: ${args.target}`);
+    output.info(`Detected: ${detected.evidence}${detected.isGitRepository ? '' : ' (not a git repository yet)'}`);
+    const topology = await chooseTopology(args, prompter, output);
+    const runtimes = await chooseRuntimes(args, prompter, output);
+    const tools = await chooseTools(args, prompter, output);
+    const config = new PipelineConfig(packageVersion(), topology, runtimes, tools, detected.mapping, new Date().toISOString());
+    const claudeMd = args.claudeMd === null ? ClaudeMdMode.Import : parseClaudeMdMode(args.claudeMd);
+    const report = await installFiles(args.target, config, new ApplyOptions(args.force, args.dryRun), claudeMd);
+    printApplyReport(report, output);
+    if (args.dryRun)
+        return 0;
+    const shellSteps = TOOL_CATALOG.forIds(tools).some((tool) => runtimes.some((runtime) => tool.stepsFor(runtime).length > 0));
+    let runSteps = args.runTools;
+    if (!runSteps && !args.yes && shellSteps) {
+        const answer = await prompter.ask('Run the shell install steps for these tools now? [y/N]');
+        runSteps = /^y(es)?$/i.test(answer);
+    }
+    if (runSteps)
+        runToolSteps(config, args.target, output);
+    output.info('');
+    output.info('Installed. Next:');
+    output.info('  1. Review .ai-agents/SETUP.md for any tool steps still to do');
+    output.info('  2. Empty repo → /scaffold then /bootstrap.  Existing code → /bootstrap');
+    output.info('  3. Commit .ai-agents/, .claude/ and/or .agents/, CLAUDE.md/AGENTS.md');
+    return 0;
+}

package/dist/src/cli/commands/shared.js

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACKAGE_ROOT, PAYLOAD_DIR } from '../../io/paths.js';
+import { InstallManifest } from '../../install/manifest.js';
+import { applyPlan } from '../../install/applier.js';
+import { buildPlan } from '../../install/planner.js';
+export function packageVersion() {
+    const raw = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+    const version = typeof raw === 'object' && raw !== null ? raw.version : undefined;
+    return typeof version === 'string' ? version : '0.0.0';
+}
+export async function installFiles(target, config, options, claudeMd) {
+    const plan = await buildPlan(PAYLOAD_DIR, config, target, claudeMd);
+    const legacy = await InstallManifest.loadFile(join(PAYLOAD_DIR, 'legacy', 'v1-checksums.json'));
+    const { report, manifest } = await applyPlan(target, plan, await InstallManifest.load(target, legacy), options);
+    if (!options.dryRun) {
+        await manifest.withVersion(config.pipelineVersion).save(target);
+    }
+    return report;
+}

package/dist/src/cli/commands/tools.js

@@ -0,0 +1,21 @@
+import { ALL_RUNTIMES } from '../../domain/runtime.js';
+import { TOOL_CATALOG } from '../../registry/tools.js';
+import { parseRuntimes } from '../../domain/runtime.js';
+export function runTools(args, output) {
+    const runtimes = args.runtime === null ? ALL_RUNTIMES : parseRuntimes(args.runtime);
+    for (const tool of TOOL_CATALOG.all()) {
+        output.info(`${tool.name}  (${tool.source}, ${tool.role})`);
+        output.info(`  ${tool.purpose}`);
+        for (const runtime of runtimes) {
+            const support = tool.supportFor(runtime);
+            if (support === null)
+                continue;
+            for (const step of support.steps)
+                output.info(`  [${runtime}] ${step.command}${step.verified ? '' : '   (unverified)'}`);
+            if (support.caveat.length > 0)
+                output.info(`  [${runtime}] note: ${support.caveat}`);
+        }
+        output.info('');
+    }
+    return 0;
+}

package/dist/src/cli/commands/update.js

@@ -0,0 +1,21 @@
+import { join } from 'node:path';
+import { ClaudeMdMode, parseClaudeMdMode } from '../../domain/claude-md-mode.js';
+import { PipelineConfig } from '../../domain/pipeline-config.js';
+import { ApplyOptions } from '../../install/applier.js';
+import { readTextOrNull } from '../../io/fs.js';
+import { printApplyReport } from '../report.js';
+import { installFiles, packageVersion } from './shared.js';
+export async function runUpdate(args, output) {
+    const text = await readTextOrNull(join(args.target, '.ai-agents', 'pipeline.config.json'));
+    if (text === null) {
+        output.error('No .ai-agents/pipeline.config.json here. Run `npx fullstack-agentic-flow init` first.');
+        return 1;
+    }
+    const previous = PipelineConfig.parse(text);
+    const config = new PipelineConfig(packageVersion(), previous.topology, previous.runtimes, previous.tools, previous.mapping, previous.installedAt);
+    output.info(`Updating ${args.target} from pipeline ${previous.pipelineVersion} to ${config.pipelineVersion}.`);
+    const claudeMd = args.claudeMd === null ? ClaudeMdMode.Import : parseClaudeMdMode(args.claudeMd);
+    const report = await installFiles(args.target, config, new ApplyOptions(args.force, args.dryRun), claudeMd);
+    printApplyReport(report, output);
+    return 0;
+}

package/dist/src/cli/main.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from './run.js';
+import { ConsoleOutput } from './output.js';
+import { TerminalPrompter } from './prompter.js';
+const code = await runCli(process.argv.slice(2), new TerminalPrompter(), new ConsoleOutput());
+process.exitCode = code;

package/dist/src/cli/output.js

@@ -0,0 +1,11 @@
+export class ConsoleOutput {
+    info(line) {
+        console.log(line);
+    }
+    warn(line) {
+        console.warn(`! ${line}`);
+    }
+    error(line) {
+        console.error(`✗ ${line}`);
+    }
+}

package/dist/src/cli/prompter.js

@@ -0,0 +1,13 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+export class TerminalPrompter {
+    async ask(question) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            return (await rl.question(`${question} `)).trim();
+        }
+        finally {
+            rl.close();
+        }
+    }
+}

package/dist/src/cli/report.js

@@ -0,0 +1,13 @@
+import { OutcomeKind } from '../install/applier.js';
+export function printApplyReport(report, output) {
+    output.info(`Files: ${report.count(OutcomeKind.Created)} created, ${report.count(OutcomeKind.Updated)} updated, ` +
+        `${report.count(OutcomeKind.Unchanged)} unchanged, ${report.count(OutcomeKind.SeedKept)} kept, ` +
+        `${report.count(OutcomeKind.Conflict)} conflicts` +
+        (report.count(OutcomeKind.Planned) > 0 ? `, ${report.count(OutcomeKind.Planned)} planned (dry run — nothing written).` : '.'));
+    for (const conflict of report.ofKind(OutcomeKind.Conflict)) {
+        output.warn(`${conflict.relativePath} — ${conflict.note}; new version written to ${conflict.relativePath}.incoming. Merge it, or re-run with --force.`);
+    }
+    for (const path of report.obsoletePresent) {
+        output.warn(`${path} is from pipeline v1 and was renamed or removed in v2 — delete it once you have merged anything you need.`);
+    }
+}

package/dist/src/cli/run.js

@@ -0,0 +1,48 @@
+import { InvalidOptionError } from '../domain/errors.js';
+import { CliArgs, USAGE } from './args.js';
+import { runDoctor } from './commands/doctor.js';
+import { runInit } from './commands/init.js';
+import { packageVersion } from './commands/shared.js';
+import { runTools } from './commands/tools.js';
+import { runUpdate } from './commands/update.js';
+/** Exit codes: 0 ok, 1 check or operation failed, 2 usage error. */
+export async function runCli(argv, prompter, output) {
+    let args;
+    try {
+        args = CliArgs.parse(argv);
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        output.info(USAGE);
+        return 2;
+    }
+    try {
+        switch (args.command) {
+            case 'init':
+                return await runInit(args, prompter, output);
+            case 'update':
+                return await runUpdate(args, output);
+            case 'doctor':
+                return await runDoctor(args, output);
+            case 'tools':
+                return runTools(args, output);
+            case 'version':
+                output.info(packageVersion());
+                return 0;
+            case 'help':
+                output.info(USAGE);
+                return 0;
+            default:
+                output.error(`Unknown command: ${args.command}`);
+                output.info(USAGE);
+                return 2;
+        }
+    }
+    catch (error) {
+        if (error instanceof InvalidOptionError) {
+            output.error(error.message);
+            return 2;
+        }
+        throw error;
+    }
+}

package/dist/src/domain/canon-mapping.js

@@ -0,0 +1,26 @@
+import { parseEnum } from './enum-parse.js';
+/** Which framework mapping of canon/backend-canon.md §7 a repository uses. */
+export var CanonMapping;
+(function (CanonMapping) {
+    CanonMapping["Laravel"] = "laravel";
+    CanonMapping["NestJs"] = "nestjs";
+    CanonMapping["Express"] = "express";
+    CanonMapping["Django"] = "django";
+    CanonMapping["FastApi"] = "fastapi";
+    CanonMapping["Spring"] = "spring";
+    CanonMapping["Go"] = "go";
+    CanonMapping["Custom"] = "custom";
+})(CanonMapping || (CanonMapping = {}));
+export const ALL_CANON_MAPPINGS = [
+    CanonMapping.Laravel,
+    CanonMapping.NestJs,
+    CanonMapping.Express,
+    CanonMapping.Django,
+    CanonMapping.FastApi,
+    CanonMapping.Spring,
+    CanonMapping.Go,
+    CanonMapping.Custom,
+];
+export function parseCanonMapping(value) {
+    return parseEnum('canon mapping', value, ALL_CANON_MAPPINGS);
+}

package/dist/src/domain/claude-md-mode.js

@@ -0,0 +1,17 @@
+import { parseEnum } from './enum-parse.js';
+/**
+ * The pipeline section lives in AGENTS.md, which Codex reads directly and
+ * Claude Code reads only when the repository has no CLAUDE.md. This decides
+ * how Claude Code reaches it.
+ */
+export var ClaudeMdMode;
+(function (ClaudeMdMode) {
+    /** Keep a CLAUDE.md whose managed section is a single `@AGENTS.md` import. */
+    ClaudeMdMode["Import"] = "import";
+    /** Write no CLAUDE.md. Claude Code reads AGENTS.md directly (v2.1.277+). */
+    ClaudeMdMode["None"] = "none";
+})(ClaudeMdMode || (ClaudeMdMode = {}));
+export const ALL_CLAUDE_MD_MODES = [ClaudeMdMode.Import, ClaudeMdMode.None];
+export function parseClaudeMdMode(value) {
+    return parseEnum('claude-md', value, ALL_CLAUDE_MD_MODES);
+}

package/dist/src/domain/enum-parse.js

@@ -0,0 +1,9 @@
+import { InvalidOptionError } from './errors.js';
+/** Parse edge for string enums (typed-data T5): the only place a raw string becomes an enum. */
+export function parseEnum(option, value, allowed) {
+    const match = allowed.find((candidate) => candidate === value.trim());
+    if (match === undefined) {
+        throw new InvalidOptionError(option, value, allowed);
+    }
+    return match;
+}

package/dist/src/domain/errors.js

@@ -0,0 +1,13 @@
+/** A user-supplied option (flag, prompt answer, config value) was not valid. */
+export class InvalidOptionError extends Error {
+    option;
+    value;
+    allowed;
+    constructor(option, value, allowed) {
+        super(`Invalid ${option}: "${value}". Expected one of: ${allowed.join(', ')}.`);
+        this.option = option;
+        this.value = value;
+        this.allowed = allowed;
+        this.name = 'InvalidOptionError';
+    }
+}

package/dist/src/domain/pipeline-config.js

@@ -0,0 +1,58 @@
+import { InvalidOptionError } from './errors.js';
+import { parseTopology } from './topology.js';
+import { parseRuntimes } from './runtime.js';
+import { parseToolIds } from './tool.js';
+import { parseCanonMapping } from './canon-mapping.js';
+/** `.ai-agents/pipeline.config.json` — what was installed, read by every agent. */
+export class PipelineConfig {
+    pipelineVersion;
+    topology;
+    runtimes;
+    tools;
+    mapping;
+    installedAt;
+    constructor(pipelineVersion, topology, runtimes, tools, 
+    /** Null until detected or chosen; /scaffold or /bootstrap records it in §5.0. */
+    mapping, installedAt) {
+        this.pipelineVersion = pipelineVersion;
+        this.topology = topology;
+        this.runtimes = runtimes;
+        this.tools = tools;
+        this.mapping = mapping;
+        this.installedAt = installedAt;
+    }
+    toJson() {
+        return `${JSON.stringify({
+            pipelineVersion: this.pipelineVersion,
+            topology: this.topology,
+            runtimes: this.runtimes,
+            tools: this.tools,
+            canonMapping: this.mapping,
+            installedAt: this.installedAt,
+        }, null, 2)}\n`;
+    }
+    /** Parse edge (typed-data T5): JSON text in, named type out, or a precise error. */
+    static parse(json) {
+        const raw = JSON.parse(json);
+        if (typeof raw !== 'object' || raw === null) {
+            throw new InvalidOptionError('pipeline.config.json', json.slice(0, 40), ['a JSON object']);
+        }
+        const field = (name) => raw[name];
+        const text = (name) => {
+            const value = field(name);
+            if (typeof value !== 'string') {
+                throw new InvalidOptionError(`pipeline.config.json ${name}`, String(value), ['a string']);
+            }
+            return value;
+        };
+        const list = (name) => {
+            const value = field(name);
+            if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+                throw new InvalidOptionError(`pipeline.config.json ${name}`, String(value), ['a list of strings']);
+            }
+            return value.join(',');
+        };
+        const mapping = field('canonMapping');
+        return new PipelineConfig(text('pipelineVersion'), parseTopology(text('topology')), parseRuntimes(list('runtimes')), parseToolIds(list('tools')), typeof mapping === 'string' ? parseCanonMapping(mapping) : null, text('installedAt'));
+    }
+}

package/dist/src/domain/runtime.js

@@ -0,0 +1,19 @@
+import { InvalidOptionError } from './errors.js';
+import { parseEnum } from './enum-parse.js';
+export var Runtime;
+(function (Runtime) {
+    Runtime["ClaudeCode"] = "claude-code";
+    Runtime["Codex"] = "codex";
+})(Runtime || (Runtime = {}));
+export const ALL_RUNTIMES = [Runtime.ClaudeCode, Runtime.Codex];
+export function parseRuntimes(csv) {
+    const parts = csv
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (parts.length === 0) {
+        throw new InvalidOptionError('runtime', csv, ALL_RUNTIMES);
+    }
+    const parsed = parts.map((part) => parseEnum('runtime', part, ALL_RUNTIMES));
+    return ALL_RUNTIMES.filter((runtime) => parsed.includes(runtime));
+}

package/dist/src/domain/tool.js

@@ -0,0 +1,129 @@
+import { parseEnum } from './enum-parse.js';
+export var ToolId;
+(function (ToolId) {
+    ToolId["FindSkills"] = "find-skills";
+    ToolId["Superpowers"] = "superpowers";
+    ToolId["ClaudeMem"] = "claude-mem";
+    ToolId["Impeccable"] = "impeccable";
+    ToolId["TaskObserver"] = "task-observer";
+    ToolId["Ponytail"] = "ponytail";
+    ToolId["Headroom"] = "headroom";
+    ToolId["CodeReviewGraph"] = "code-review-graph";
+    ToolId["Graphify"] = "graphify";
+})(ToolId || (ToolId = {}));
+export const ALL_TOOL_IDS = [
+    ToolId.FindSkills,
+    ToolId.Superpowers,
+    ToolId.ClaudeMem,
+    ToolId.Impeccable,
+    ToolId.TaskObserver,
+    ToolId.Ponytail,
+    ToolId.Headroom,
+    ToolId.CodeReviewGraph,
+    ToolId.Graphify,
+];
+export function parseToolIds(csv) {
+    const value = csv.trim();
+    if (value === 'all')
+        return ALL_TOOL_IDS;
+    if (value === 'none' || value === '')
+        return [];
+    const parsed = value.split(',').map((part) => parseEnum('tool', part, ALL_TOOL_IDS));
+    return ALL_TOOL_IDS.filter((id) => parsed.includes(id));
+}
+/** Where an install step has to be run. */
+export var StepLocation;
+(function (StepLocation) {
+    /** A shell command the installer can run (with consent). */
+    StepLocation["Shell"] = "shell";
+    /** Must be done inside the agent's own UI (slash command, plugin menu). */
+    StepLocation["AgentUi"] = "agent-ui";
+})(StepLocation || (StepLocation = {}));
+export class InstallStep {
+    description;
+    command;
+    location;
+    requires;
+    verified;
+    constructor(description, command, location, 
+    /** Binaries that must exist before the command can run, e.g. `uv`, `npx`. */
+    requires, 
+    /** False when the command is our best reading of the tool's docs rather than copied from them. */
+    verified) {
+        this.description = description;
+        this.command = command;
+        this.location = location;
+        this.requires = requires;
+        this.verified = verified;
+    }
+}
+export var ProbeKind;
+(function (ProbeKind) {
+    ProbeKind["Binary"] = "binary";
+    /** Any of the paths exists. `~` expands to the home directory; relative paths resolve against the repo. */
+    ProbeKind["AnyPath"] = "any-path";
+})(ProbeKind || (ProbeKind = {}));
+export class ToolProbe {
+    kind;
+    targets;
+    constructor(kind, targets) {
+        this.kind = kind;
+        this.targets = targets;
+    }
+}
+export var ToolRole;
+(function (ToolRole) {
+    ToolRole["Skill"] = "skill";
+    ToolRole["Plugin"] = "plugin";
+    ToolRole["Proxy"] = "proxy";
+    ToolRole["CodeGraph"] = "code-graph";
+})(ToolRole || (ToolRole = {}));
+export class RuntimeSupport {
+    runtime;
+    steps;
+    probe;
+    caveat;
+    constructor(runtime, steps, probe, 
+    /** Non-empty when support on this runtime is partial or community-maintained. */
+    caveat) {
+        this.runtime = runtime;
+        this.steps = steps;
+        this.probe = probe;
+        this.caveat = caveat;
+    }
+}
+export class ExternalTool {
+    id;
+    name;
+    source;
+    role;
+    purpose;
+    usedBy;
+    support;
+    ignorePaths;
+    usage;
+    constructor(id, name, source, role, purpose, usedBy, support, 
+    /** Lines added to .gitignore when this tool is installed. */
+    ignorePaths, 
+    /** How to use it day to day, for SETUP.md. */
+    usage) {
+        this.id = id;
+        this.name = name;
+        this.source = source;
+        this.role = role;
+        this.purpose = purpose;
+        this.usedBy = usedBy;
+        this.support = support;
+        this.ignorePaths = ignorePaths;
+        this.usage = usage;
+    }
+    supports(runtime) {
+        return this.support.some((entry) => entry.runtime === runtime);
+    }
+    supportFor(runtime) {
+        return this.support.find((entry) => entry.runtime === runtime) ?? null;
+    }
+    stepsFor(runtime) {
+        return this.supportFor(runtime)?.steps ?? [];
+    }
+}

package/dist/src/domain/topology.js

@@ -0,0 +1,39 @@
+import { parseEnum } from './enum-parse.js';
+export var Topology;
+(function (Topology) {
+    /** Server-rendered: controllers hand typed view models to views/pages. */
+    Topology["Mvc"] = "mvc";
+    /** Backend API and frontend in one repository. */
+    Topology["UnifiedApi"] = "unified-api";
+    /** Backend only; consumers live in other repositories. */
+    Topology["SplitBackend"] = "split-backend";
+    /** Frontend only (any framework); the API lives in another repository. */
+    Topology["SplitFrontend"] = "split-frontend";
+})(Topology || (Topology = {}));
+export const ALL_TOPOLOGIES = [
+    Topology.Mvc,
+    Topology.UnifiedApi,
+    Topology.SplitBackend,
+    Topology.SplitFrontend,
+];
+export function parseTopology(value) {
+    return parseEnum('topology', value, ALL_TOPOLOGIES);
+}
+export function describeTopology(topology) {
+    switch (topology) {
+        case Topology.Mvc:
+            return 'MVC — server-rendered pages; the seam is a typed view model per screen';
+        case Topology.UnifiedApi:
+            return 'Unified API — backend + frontend in one repo over REST/GraphQL/RPC';
+        case Topology.SplitBackend:
+            return 'Split backend — API only; contracts exported to consumer repos';
+        case Topology.SplitFrontend:
+            return 'Split frontend — UI only (any framework); contracts imported from the API repo';
+    }
+}
+export function isSplit(topology) {
+    return topology === Topology.SplitBackend || topology === Topology.SplitFrontend;
+}
+export function hasUi(topology) {
+    return topology !== Topology.SplitBackend;
+}

package/dist/src/install/adapters.js

@@ -0,0 +1,39 @@
+const yamlSafe = (text) => text.replace(/\n/g, ' ').replace(/:\s/g, ' — ');
+/** `.claude/commands/{slug}.md` */
+export function renderClaudeCommand(command, body) {
+    return `---\ndescription: ${yamlSafe(command.description)}\n---\n\n${body.replace(/\n+$/, '')}\n`;
+}
+/** `.agents/skills/flow-{slug}/SKILL.md` — Codex has no slash-command files; skills trigger on description. */
+export function renderCodexSkill(command, body) {
+    const description = yamlSafe(`${command.description}. Use when the user types /${command.slug} or $flow-${command.slug}, or is ${command.triggers}.`);
+    return `---\nname: flow-${command.slug}\ndescription: ${description}\n---\n\n# /${command.slug}\n\n${body.replace(/\n+$/, '')}\n`;
+}
+/** `.claude/agents/{name}.md` — a pointer; the instructions live in .ai-agents/agents/. */
+export function renderClaudeSubagent(agent) {
+    const prerequisite = agent.requiresContext
+        ? [
+            'Read `.ai-agents/architecture-context.md` first so you understand this',
+            "repository's topology, canon mapping, conventions, and rules.",
+            '',
+            'If `architecture-context.md` is missing or still contains `{PLACEHOLDER}`',
+            'text, stop and tell the user to run `/bootstrap` first.',
+        ].join('\n')
+        : [
+            'You do NOT require `.ai-agents/architecture-context.md` to exist. You run',
+            'before it can be written, or you are the agent that writes it.',
+        ].join('\n');
+    return [
+        '---',
+        `name: ${agent.name}`,
+        `description: ${yamlSafe(agent.description)}`,
+        '---',
+        '',
+        prerequisite,
+        '',
+        `Then read \`.ai-agents/agents/${agent.agentFile}\` and follow it exactly. That file`,
+        'is the source of truth for this agent — do not improvise beyond it.',
+        '',
+        'Precedence, skills, and fallbacks: `.ai-agents/toolchain.md`.',
+        '',
+    ].join('\n');
+}