@rafi-ai/cli 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @rafi-ai/cli
+
+Scaffold and compile AI agent configs for your repo.
+
+`rafi create` reads your stack, assembles best-practice rule packs, and writes the files Claude Code and Codex read — AGENTS.md, CLAUDE.md, subagents, and starter docs — all in one command.
+
+## Install
+
+```sh
+npm install -g @rafi-ai/cli
+```
+
+## Use
+
+```sh
+rafi create ./my-repo             # interactive walkthrough
+rafi create ./my-repo --defaults  # skip walkthrough, use built-in defaults
+rafi compile ./my-repo            # re-render from an existing project.yaml
+```
+
+## Commands
+
+### `rafi create <project>`
+
+Runs the walkthrough (or `--defaults` to skip it), writes `project.yaml`, and compiles all configs.
+
+```sh
+rafi create ./my-repo
+rafi create ./my-repo --defaults  # built-in defaults; byte-equivalent to the bundled rule set
+rafi create ./my-repo --force     # overwrite existing doc files
+```
+
+The walkthrough collects your stack (frontend, backend, database, cloud, package manager) and three boolean flags: `usesAI`, `hasFrontend`, `runsInCloud`. These gate which rule packs are included. Answers are saved to `project.yaml`.
+
+### `rafi compile <project>`
+
+Re-renders all configs from an existing `project.yaml`. Run this after editing the config or upgrading `special-agents`.
+
+```sh
+rafi compile ./my-repo
+rafi compile ./my-repo --force
+```
+
+## What gets written
+
+```
+<project>/
+  AGENTS.md                        Codex flat rules doc
+  CLAUDE.md                        Claude Code entrypoint (@AGENTS.md import)
+  project.yaml                     stack config (commit this)
+  .claude/agents/<role>.md         Claude subagent files (builder, qa, planner, ticket-maker)
+  .rafi/compiled/<role>/system.md  role system text — read by ai-foreman at runtime
+  .rafi/compiled/<role>/meta.json  skills + model config
+  docs/                            starter doc templates (flag-gated by stack)
+```
+
+## Part of Rafi
+
+- **`special-agents`** — library (rules + skills + agents + composition)
+- **`ai-foreman`** — runtime that drives agents through a ticket loop
+- **`@rafi-ai/cli`** — this CLI

package/dist/compiler.d.ts

@@ -0,0 +1,19 @@
+import { type Defaults } from "special-agents";
+import type { ProjectConfig } from "rafi-spec";
+import { type CopyDocsOptions } from "./docs.js";
+export interface CompileProjectOptions extends CopyDocsOptions {
+    /** Skip doc copying entirely (useful in tests that don't need docs). */
+    skipDocs?: boolean;
+}
+/** Map a ProjectConfig to the Defaults shape special-agents compile functions expect. */
+export declare function projectConfigToDefaults(config: ProjectConfig): Defaults;
+/**
+ * Full compile: write AGENTS.md, CLAUDE.md, lean Claude agents,
+ * compiled role bundles, and (optionally) starter docs to `targetDir`.
+ */
+export declare function compile(targetDir: string, config: ProjectConfig, opts?: CompileProjectOptions): void;
+/**
+ * Write `project.yaml` to `<targetDir>/project.yaml`. Creates the directory
+ * if it does not exist.
+ */
+export declare function writeProjectYaml(targetDir: string, config: ProjectConfig): void;

package/dist/compiler.js

@@ -0,0 +1,47 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { emitAgentsMd, emitClaudeMd, emitClaudeAgents, emitCompiledBundles, } from "special-agents";
+import { copyDocs } from "./docs.js";
+/** Map a ProjectConfig to the Defaults shape special-agents compile functions expect. */
+export function projectConfigToDefaults(config) {
+    return {
+        stack: config.stack,
+        flags: config.flags,
+    };
+}
+/** Map ProjectFlags to the ConditionFlags shape (for role-specific compilation). */
+function flagsToConditions(flags) {
+    return {
+        ai: flags.usesAI,
+        frontend: flags.hasFrontend,
+        cloud: flags.runsInCloud,
+    };
+}
+/**
+ * Full compile: write AGENTS.md, CLAUDE.md, lean Claude agents,
+ * compiled role bundles, and (optionally) starter docs to `targetDir`.
+ */
+export function compile(targetDir, config, opts = {}) {
+    const defaults = projectConfigToDefaults(config);
+    const conditions = flagsToConditions(config.flags);
+    // Flat Codex doc + lean Claude entrypoint
+    emitAgentsMd(targetDir, { defaults });
+    emitClaudeMd(targetDir, { defaults });
+    // Lean Claude subagent files (role-filtered)
+    emitClaudeAgents(targetDir, { defaults, conditions });
+    // Compiled role bundles for foreman (role-filtered)
+    emitCompiledBundles(targetDir, { defaults, conditions });
+    // Starter docs (flag-gated)
+    if (!opts.skipDocs) {
+        copyDocs(targetDir, config.flags, { force: opts.force });
+    }
+}
+/**
+ * Write `project.yaml` to `<targetDir>/project.yaml`. Creates the directory
+ * if it does not exist.
+ */
+export function writeProjectYaml(targetDir, config) {
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, "project.yaml"), stringify(config), "utf8");
+}

package/dist/docs.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectFlags } from "rafi-spec";
+export interface CopyDocsOptions {
+    force?: boolean;
+}
+/**
+ * Copy starter doc templates from special-agents into `<targetDir>/docs/`,
+ * respecting gate flags. Returns the list of paths actually written.
+ */
+export declare function copyDocs(targetDir: string, flags: ProjectFlags, opts?: CopyDocsOptions): string[];

package/dist/docs.js

@@ -0,0 +1,25 @@
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DOCS_DIR, loadDocsIndex } from "special-agents";
+/**
+ * Copy starter doc templates from special-agents into `<targetDir>/docs/`,
+ * respecting gate flags. Returns the list of paths actually written.
+ */
+export function copyDocs(targetDir, flags, opts = {}) {
+    const entries = loadDocsIndex();
+    const written = [];
+    for (const entry of entries) {
+        const include = entry.gate === "always" ||
+            (entry.gate === "ai" && flags.usesAI) ||
+            (entry.gate === "frontend" && flags.hasFrontend);
+        if (!include)
+            continue;
+        const dest = join(targetDir, "docs", entry.path);
+        if (!opts.force && existsSync(dest))
+            continue;
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(join(DOCS_DIR, entry.path), dest);
+        written.push(entry.path);
+    }
+    return written;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { resolve, join } from "node:path";
+import { existsSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { assertProjectConfig } from "rafi-spec";
+import { compile, writeProjectYaml } from "./compiler.js";
+import { buildProjectConfig, defaultAnswers } from "./project.js";
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))?.version;
+const program = new Command();
+program
+    .name("rafi")
+    .description("Scaffold and compile Rafi AI framework configs for a target repo.")
+    .version(PACKAGE_VERSION);
+program
+    .command("compile")
+    .description("Re-render .claude/, AGENTS.md, and role bundles from an existing project.yaml.")
+    .argument("<project>", "path to the target repo")
+    .option("--force", "overwrite existing doc files")
+    .action((project, opts) => {
+    const targetDir = resolve(project);
+    const configPath = join(targetDir, "project.yaml");
+    if (!existsSync(configPath)) {
+        console.error(`rafi: project.yaml not found at ${configPath}`);
+        process.exit(1);
+    }
+    const raw = parseYaml(readFileSync(configPath, "utf8"));
+    assertProjectConfig(raw);
+    compile(targetDir, raw, { force: opts.force });
+    console.log(`rafi: compiled ${targetDir}`);
+});
+program
+    .command("create")
+    .description("Run the walkthrough, write project.yaml, and compile the target repo.")
+    .argument("<project>", "path to the target repo")
+    .option("--defaults", "skip walkthrough and use built-in defaults")
+    .option("--force", "overwrite existing doc files")
+    .action(async (project, opts) => {
+    const targetDir = resolve(project);
+    let answers = defaultAnswers();
+    if (!opts.defaults) {
+        // Interactive walkthrough — requires Node >=20 for @clack/prompts
+        const { intro, outro, text, confirm, select, isCancel } = await import("@clack/prompts");
+        intro("rafi create — configure your AI framework");
+        const appName = await text({ message: "App name:", defaultValue: answers.appName });
+        if (isCancel(appName))
+            process.exit(0);
+        const timezone = await text({ message: "Timezone:", defaultValue: answers.timezone });
+        if (isCancel(timezone))
+            process.exit(0);
+        const frontendRaw = await text({
+            message: `Frontend stack (Enter "${answers.frontend}" to keep default, type "No UI" for no frontend):`,
+            defaultValue: answers.frontend,
+        });
+        if (isCancel(frontendRaw))
+            process.exit(0);
+        const backend = await text({ message: "Backend stack:", defaultValue: answers.backend });
+        if (isCancel(backend))
+            process.exit(0);
+        const database = await text({ message: "Database:", defaultValue: answers.database });
+        if (isCancel(database))
+            process.exit(0);
+        const cloudRaw = await text({
+            message: `Cloud provider (type "Local only" for no cloud):`,
+            defaultValue: answers.cloud,
+        });
+        if (isCancel(cloudRaw))
+            process.exit(0);
+        const packageManager = await text({ message: "Package manager:", defaultValue: answers.packageManager });
+        if (isCancel(packageManager))
+            process.exit(0);
+        const usesAI = await confirm({ message: "Will this app call LLMs / do AI generation?", initialValue: false });
+        if (isCancel(usesAI))
+            process.exit(0);
+        answers = {
+            appName: String(appName),
+            timezone: String(timezone),
+            frontend: String(frontendRaw),
+            backend: String(backend),
+            database: String(database),
+            cloud: String(cloudRaw),
+            packageManager: String(packageManager),
+            usesAI: Boolean(usesAI),
+            targets: ["claude", "codex"],
+            qa: true,
+        };
+        outro("Configuration collected — compiling...");
+    }
+    const config = buildProjectConfig(answers);
+    writeProjectYaml(targetDir, config);
+    compile(targetDir, config, { force: opts.force });
+    const aiStatus = config.flags.usesAI ? "on" : "off";
+    console.log(`rafi: compiled ${targetDir}`);
+    console.log(`rafi: AI rules: ${aiStatus === "off" ? "excluded — re-run \`rafi compile\` after setting usesAI: true to add them" : "included"}`);
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(`rafi: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/project.d.ts

@@ -0,0 +1,19 @@
+import type { ProjectConfig, HarnessTarget } from "rafi-spec";
+export declare const NO_UI = "No UI";
+export declare const LOCAL_ONLY = "Local only";
+export interface WalkthroughAnswers {
+    appName: string;
+    timezone: string;
+    frontend: string;
+    backend: string;
+    database: string;
+    cloud: string;
+    packageManager: string;
+    usesAI: boolean;
+    targets: HarnessTarget[];
+    qa: boolean;
+}
+/** Default answers — equivalent to running with `--defaults`. */
+export declare function defaultAnswers(): WalkthroughAnswers;
+/** Map walkthrough answers to a validated ProjectConfig. */
+export declare function buildProjectConfig(answers: WalkthroughAnswers): ProjectConfig;

package/dist/project.js

@@ -0,0 +1,44 @@
+import { loadDefaults } from "special-agents";
+export const NO_UI = "No UI";
+export const LOCAL_ONLY = "Local only";
+/** Default answers — equivalent to running with `--defaults`. */
+export function defaultAnswers() {
+    const d = loadDefaults();
+    return {
+        appName: "My App",
+        timezone: "UTC",
+        frontend: d.stack.frontend,
+        backend: d.stack.backend,
+        database: d.stack.database,
+        cloud: d.stack.cloud,
+        packageManager: d.stack.packageManager,
+        usesAI: Boolean(d.flags.usesAI),
+        targets: ["claude", "codex"],
+        qa: true,
+    };
+}
+/** Map walkthrough answers to a validated ProjectConfig. */
+export function buildProjectConfig(answers) {
+    const hasFrontend = answers.frontend !== NO_UI;
+    const runsInCloud = answers.cloud !== LOCAL_ONLY;
+    return {
+        appName: answers.appName,
+        timezone: answers.timezone,
+        stack: {
+            frontend: hasFrontend ? answers.frontend : "",
+            backend: answers.backend,
+            database: answers.database,
+            cloud: runsInCloud ? answers.cloud : "",
+            packageManager: answers.packageManager,
+        },
+        flags: {
+            hasFrontend,
+            usesAI: answers.usesAI,
+            runsInCloud,
+        },
+        harness: {
+            targets: answers.targets,
+            qa: answers.qa,
+        },
+    };
+}

package/node_modules/rafi-spec/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** Rafi neutral schema — public surface. */
+export * from "./types.js";
+export { rulePackSchema, skillManifestSchema, agentManifestSchema, projectConfigSchema, } from "./schemas.js";
+export { type ValidationResult, validateRulePack, validateSkillManifest, validateAgentManifest, validateProjectConfig, assertRulePack, assertSkillManifest, assertAgentManifest, assertProjectConfig, } from "./validate.js";

package/node_modules/rafi-spec/dist/index.js

@@ -0,0 +1,4 @@
+/** Rafi neutral schema — public surface. */
+export * from "./types.js";
+export { rulePackSchema, skillManifestSchema, agentManifestSchema, projectConfigSchema, } from "./schemas.js";
+export { validateRulePack, validateSkillManifest, validateAgentManifest, validateProjectConfig, assertRulePack, assertSkillManifest, assertAgentManifest, assertProjectConfig, } from "./validate.js";

package/node_modules/rafi-spec/dist/schemas.d.ts

@@ -0,0 +1,185 @@
+/**
+ * JSON Schemas (draft-07) for the neutral types in {@link ./types}. Kept in lockstep
+ * with those interfaces; validated by {@link ./validate}.
+ */
+export declare const rulePackSchema: {
+    readonly $id: "rafi/rulePack";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["name", "category", "description", "condition", "template"];
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+            readonly pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$";
+        };
+        readonly category: {
+            readonly enum: readonly ["base", "process", "domain", "templated"];
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly condition: {
+            readonly enum: readonly ["always", "frontend", "ai", "cloud", "backend"];
+        };
+        readonly template: {
+            readonly type: "boolean";
+        };
+        readonly supersededByForeman: {
+            readonly type: "boolean";
+        };
+        readonly body: {
+            readonly type: "string";
+        };
+    };
+};
+export declare const skillManifestSchema: {
+    readonly $id: "rafi/skillManifest";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["name", "description"];
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+            readonly pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly pins: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly codexPriority: {
+            readonly enum: readonly ["inline", "reference"];
+        };
+        readonly body: {
+            readonly type: "string";
+        };
+    };
+};
+export declare const agentManifestSchema: {
+    readonly $id: "rafi/agentManifest";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["name", "description", "role", "packs", "skills"];
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+            readonly pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly role: {
+            readonly enum: readonly ["builder", "qa", "planner", "ticket-maker"];
+        };
+        readonly packs: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly skills: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly conditionalPacks: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly ai: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly frontend: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly cloud: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly backend: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly model: {
+            readonly type: readonly ["string", "null"];
+        };
+        readonly effort: {
+            readonly type: readonly ["string", "null"];
+            readonly enum: readonly ["low", "medium", "high", "xhigh", null];
+        };
+    };
+};
+export declare const projectConfigSchema: {
+    readonly $id: "rafi/projectConfig";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["appName", "timezone", "stack", "flags", "harness"];
+    readonly properties: {
+        readonly appName: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly timezone: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly stack: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                [k: string]: {
+                    type: string;
+                    minLength: number;
+                };
+            };
+        };
+        readonly flags: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                [k: string]: {
+                    type: string;
+                };
+            };
+        };
+        readonly harness: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["targets", "qa"];
+            readonly properties: {
+                readonly targets: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly enum: readonly ["claude", "codex"];
+                    };
+                };
+                readonly qa: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+    };
+};

package/node_modules/rafi-spec/dist/schemas.js

@@ -0,0 +1,95 @@
+/**
+ * JSON Schemas (draft-07) for the neutral types in {@link ./types}. Kept in lockstep
+ * with those interfaces; validated by {@link ./validate}.
+ */
+const KEBAB = "^[a-z0-9]+(?:-[a-z0-9]+)*$";
+export const rulePackSchema = {
+    $id: "rafi/rulePack",
+    type: "object",
+    additionalProperties: false,
+    required: ["name", "category", "description", "condition", "template"],
+    properties: {
+        name: { type: "string", pattern: KEBAB },
+        category: { enum: ["base", "process", "domain", "templated"] },
+        description: { type: "string", minLength: 1 },
+        condition: { enum: ["always", "frontend", "ai", "cloud", "backend"] },
+        template: { type: "boolean" },
+        supersededByForeman: { type: "boolean" },
+        body: { type: "string" },
+    },
+};
+export const skillManifestSchema = {
+    $id: "rafi/skillManifest",
+    type: "object",
+    additionalProperties: false,
+    required: ["name", "description"],
+    properties: {
+        name: { type: "string", pattern: KEBAB },
+        description: { type: "string", minLength: 1 },
+        pins: { type: "array", items: { type: "string" } },
+        codexPriority: { enum: ["inline", "reference"] },
+        body: { type: "string" },
+    },
+};
+export const agentManifestSchema = {
+    $id: "rafi/agentManifest",
+    type: "object",
+    additionalProperties: false,
+    required: ["name", "description", "role", "packs", "skills"],
+    properties: {
+        name: { type: "string", pattern: KEBAB },
+        description: { type: "string", minLength: 1 },
+        role: { enum: ["builder", "qa", "planner", "ticket-maker"] },
+        packs: { type: "array", items: { type: "string" } },
+        skills: { type: "array", items: { type: "string" } },
+        conditionalPacks: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                ai: { type: "array", items: { type: "string" } },
+                frontend: { type: "array", items: { type: "string" } },
+                cloud: { type: "array", items: { type: "string" } },
+                backend: { type: "array", items: { type: "string" } },
+            },
+        },
+        model: { type: ["string", "null"] },
+        effort: { type: ["string", "null"], enum: ["low", "medium", "high", "xhigh", null] },
+    },
+};
+const stringRecord = (keys) => ({
+    type: "object",
+    additionalProperties: false,
+    required: keys,
+    properties: Object.fromEntries(keys.map((k) => [k, { type: "string", minLength: 1 }])),
+});
+const boolRecord = (keys) => ({
+    type: "object",
+    additionalProperties: false,
+    required: keys,
+    properties: Object.fromEntries(keys.map((k) => [k, { type: "boolean" }])),
+});
+export const projectConfigSchema = {
+    $id: "rafi/projectConfig",
+    type: "object",
+    additionalProperties: false,
+    required: ["appName", "timezone", "stack", "flags", "harness"],
+    properties: {
+        appName: { type: "string", minLength: 1 },
+        timezone: { type: "string", minLength: 1 },
+        stack: stringRecord(["frontend", "backend", "database", "cloud", "packageManager"]),
+        flags: boolRecord(["hasFrontend", "usesAI", "runsInCloud"]),
+        harness: {
+            type: "object",
+            additionalProperties: false,
+            required: ["targets", "qa"],
+            properties: {
+                targets: {
+                    type: "array",
+                    minItems: 1,
+                    items: { enum: ["claude", "codex"] },
+                },
+                qa: { type: "boolean" },
+            },
+        },
+    },
+};

package/node_modules/rafi-spec/dist/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Rafi neutral schema — the shapes that the `special-agents` library and the
+ * `ai-foreman` runtime must agree on. Authoring inputs (rule packs, skills,
+ * agent manifests) and the per-project configuration that drives composition.
+ */
+/** Which category a rule pack belongs to (drives default load behavior). */
+export type PackCategory = "base" | "process" | "domain" | "templated";
+/**
+ * When a pack applies. `always` packs load for every project; the others load
+ * only when the matching project flag is on (see {@link ProjectFlags}).
+ */
+export type PackCondition = "always" | "frontend" | "ai" | "cloud" | "backend";
+/** The YAML front-matter carried by each rule pack markdown file. */
+export interface RulePackFrontmatter {
+    /** Unique, kebab-case identifier (e.g. `security`). */
+    name: string;
+    category: PackCategory;
+    /** One-line summary used in indexes and pack pickers. */
+    description: string;
+    condition: PackCondition;
+    /** True when the body contains `{{placeholders}}` / `{{#if}}` directives. */
+    template: boolean;
+    /** When true, the pack is omitted while the foreman ticket tracker is active. */
+    supersededByForeman?: boolean;
+}
+/** A fully loaded rule pack: its front-matter plus the markdown body. */
+export interface RulePack extends RulePackFrontmatter {
+    /** The rule text (bullets) below the front-matter. */
+    body: string;
+}
+/** How a skill should be treated when flattening for Codex (which can't lazy-load). */
+export type CodexPriority = "inline" | "reference";
+/**
+ * A skill manifest. Keeps the existing Anthropic `SKILL.md` format and adds two
+ * optional composition fields that non-Rafi tools can safely ignore.
+ */
+export interface SkillManifest {
+    /** Unique, kebab-case identifier matching the skill directory name. */
+    name: string;
+    /** One-line trigger description (the cheap progressive-disclosure index). */
+    description: string;
+    /** Rule packs this skill wants loaded alongside it. */
+    pins?: string[];
+    /** Whether Codex flattening should inline this skill's body or just reference it. */
+    codexPriority?: CodexPriority;
+    /** The skill body (instructions). Optional in metadata-only contexts. */
+    body?: string;
+}
+/** The role an agent fills, mapped to an ai-foreman turn-type or command. */
+export type AgentRole = "builder" | "qa" | "planner" | "ticket-maker";
+/** Reasoning effort levels accepted by the builders. */
+export type EffortLevel = "low" | "medium" | "high" | "xhigh";
+/** Packs added to a role only when the matching project flag is on. */
+export interface ConditionalPacks {
+    ai?: string[];
+    frontend?: string[];
+    cloud?: string[];
+    backend?: string[];
+}
+/**
+ * A role manifest: a named composition of rule packs + skills that the runtime
+ * loads for a given turn-type.
+ */
+export interface AgentManifest {
+    /** Unique, kebab-case identifier (usually equals {@link role}). */
+    name: string;
+    description: string;
+    role: AgentRole;
+    /** Pack references; globs like `base/*` are allowed and expanded at compile time. */
+    packs: string[];
+    /** Skill names this role preloads. */
+    skills: string[];
+    /** Extra packs gated on project flags. */
+    conditionalPacks?: ConditionalPacks;
+    /** Model override; null inherits the runtime's `--model`. */
+    model?: string | null;
+    /** Effort override; null inherits the runtime's `--effort`. */
+    effort?: EffortLevel | null;
+}
+/** Which harness targets to emit native config for. */
+export type HarnessTarget = "claude" | "codex";
+/** The stack choices collected by `rafi create` (free-text strings). */
+export interface ProjectStack {
+    frontend: string;
+    backend: string;
+    database: string;
+    cloud: string;
+    packageManager: string;
+}
+/** Boolean flags that gate conditional packs and docs. */
+export interface ProjectFlags {
+    hasFrontend: boolean;
+    usesAI: boolean;
+    runsInCloud: boolean;
+}
+/** Harness emission + QA preferences. */
+export interface HarnessConfig {
+    targets: HarnessTarget[];
+    qa: boolean;
+}
+/**
+ * The committed `project.yaml` in a target repo. Skipping the walkthrough uses
+ * the library defaults, which reproduce today's hardcoded guidance.
+ */
+export interface ProjectConfig {
+    appName: string;
+    timezone: string;
+    stack: ProjectStack;
+    flags: ProjectFlags;
+    harness: HarnessConfig;
+}

package/node_modules/rafi-spec/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Rafi neutral schema — the shapes that the `special-agents` library and the
+ * `ai-foreman` runtime must agree on. Authoring inputs (rule packs, skills,
+ * agent manifests) and the per-project configuration that drives composition.
+ */
+export {};

package/node_modules/rafi-spec/dist/validate.d.ts

@@ -0,0 +1,16 @@
+import type { RulePackFrontmatter, SkillManifest, AgentManifest, ProjectConfig } from "./types.js";
+/** Outcome of validating a value against one of the neutral schemas. */
+export interface ValidationResult {
+    valid: boolean;
+    /** Human-readable messages; empty when valid. */
+    errors: string[];
+}
+export declare const validateRulePack: (d: unknown) => ValidationResult;
+export declare const validateSkillManifest: (d: unknown) => ValidationResult;
+export declare const validateAgentManifest: (d: unknown) => ValidationResult;
+export declare const validateProjectConfig: (d: unknown) => ValidationResult;
+/** Validate and narrow, throwing on failure. */
+export declare function assertRulePack(d: unknown): asserts d is RulePackFrontmatter;
+export declare function assertSkillManifest(d: unknown): asserts d is SkillManifest;
+export declare function assertAgentManifest(d: unknown): asserts d is AgentManifest;
+export declare function assertProjectConfig(d: unknown): asserts d is ProjectConfig;

package/node_modules/rafi-spec/dist/validate.js

@@ -0,0 +1,40 @@
+/** ajv-backed validation for the neutral schemas. */
+import { Ajv } from "ajv";
+import { rulePackSchema, skillManifestSchema, agentManifestSchema, projectConfigSchema, } from "./schemas.js";
+const ajv = new Ajv({ allErrors: true, allowUnionTypes: true });
+function run(fn, data) {
+    const valid = fn(data);
+    if (valid)
+        return { valid: true, errors: [] };
+    const errors = (fn.errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message ?? "is invalid"}`.trim());
+    return { valid: false, errors };
+}
+const vRulePack = ajv.compile(rulePackSchema);
+const vSkill = ajv.compile(skillManifestSchema);
+const vAgent = ajv.compile(agentManifestSchema);
+const vProject = ajv.compile(projectConfigSchema);
+export const validateRulePack = (d) => run(vRulePack, d);
+export const validateSkillManifest = (d) => run(vSkill, d);
+export const validateAgentManifest = (d) => run(vAgent, d);
+export const validateProjectConfig = (d) => run(vProject, d);
+/** Validate and narrow, throwing on failure. */
+export function assertRulePack(d) {
+    const r = validateRulePack(d);
+    if (!r.valid)
+        throw new Error(`Invalid rule pack: ${r.errors.join("; ")}`);
+}
+export function assertSkillManifest(d) {
+    const r = validateSkillManifest(d);
+    if (!r.valid)
+        throw new Error(`Invalid skill manifest: ${r.errors.join("; ")}`);
+}
+export function assertAgentManifest(d) {
+    const r = validateAgentManifest(d);
+    if (!r.valid)
+        throw new Error(`Invalid agent manifest: ${r.errors.join("; ")}`);
+}
+export function assertProjectConfig(d) {
+    const r = validateProjectConfig(d);
+    if (!r.valid)
+        throw new Error(`Invalid project config: ${r.errors.join("; ")}`);
+}

package/node_modules/rafi-spec/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "rafi-spec",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Rafi neutral schema: rule packs, skills, agents, and project config shapes shared by special-agents and ai-foreman.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/node_modules/rafi-spec/src/index.ts

@@ -0,0 +1,19 @@
+/** Rafi neutral schema — public surface. */
+export * from "./types.js";
+export {
+  rulePackSchema,
+  skillManifestSchema,
+  agentManifestSchema,
+  projectConfigSchema,
+} from "./schemas.js";
+export {
+  type ValidationResult,
+  validateRulePack,
+  validateSkillManifest,
+  validateAgentManifest,
+  validateProjectConfig,
+  assertRulePack,
+  assertSkillManifest,
+  assertAgentManifest,
+  assertProjectConfig,
+} from "./validate.js";

package/node_modules/rafi-spec/src/schemas.ts

@@ -0,0 +1,102 @@
+/**
+ * JSON Schemas (draft-07) for the neutral types in {@link ./types}. Kept in lockstep
+ * with those interfaces; validated by {@link ./validate}.
+ */
+
+const KEBAB = "^[a-z0-9]+(?:-[a-z0-9]+)*$";
+
+export const rulePackSchema = {
+  $id: "rafi/rulePack",
+  type: "object",
+  additionalProperties: false,
+  required: ["name", "category", "description", "condition", "template"],
+  properties: {
+    name: { type: "string", pattern: KEBAB },
+    category: { enum: ["base", "process", "domain", "templated"] },
+    description: { type: "string", minLength: 1 },
+    condition: { enum: ["always", "frontend", "ai", "cloud", "backend"] },
+    template: { type: "boolean" },
+    supersededByForeman: { type: "boolean" },
+    body: { type: "string" },
+  },
+} as const;
+
+export const skillManifestSchema = {
+  $id: "rafi/skillManifest",
+  type: "object",
+  additionalProperties: false,
+  required: ["name", "description"],
+  properties: {
+    name: { type: "string", pattern: KEBAB },
+    description: { type: "string", minLength: 1 },
+    pins: { type: "array", items: { type: "string" } },
+    codexPriority: { enum: ["inline", "reference"] },
+    body: { type: "string" },
+  },
+} as const;
+
+export const agentManifestSchema = {
+  $id: "rafi/agentManifest",
+  type: "object",
+  additionalProperties: false,
+  required: ["name", "description", "role", "packs", "skills"],
+  properties: {
+    name: { type: "string", pattern: KEBAB },
+    description: { type: "string", minLength: 1 },
+    role: { enum: ["builder", "qa", "planner", "ticket-maker"] },
+    packs: { type: "array", items: { type: "string" } },
+    skills: { type: "array", items: { type: "string" } },
+    conditionalPacks: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        ai: { type: "array", items: { type: "string" } },
+        frontend: { type: "array", items: { type: "string" } },
+        cloud: { type: "array", items: { type: "string" } },
+        backend: { type: "array", items: { type: "string" } },
+      },
+    },
+    model: { type: ["string", "null"] },
+    effort: { type: ["string", "null"], enum: ["low", "medium", "high", "xhigh", null] },
+  },
+} as const;
+
+const stringRecord = (keys: string[]) => ({
+  type: "object",
+  additionalProperties: false,
+  required: keys,
+  properties: Object.fromEntries(keys.map((k) => [k, { type: "string", minLength: 1 }])),
+});
+
+const boolRecord = (keys: string[]) => ({
+  type: "object",
+  additionalProperties: false,
+  required: keys,
+  properties: Object.fromEntries(keys.map((k) => [k, { type: "boolean" }])),
+});
+
+export const projectConfigSchema = {
+  $id: "rafi/projectConfig",
+  type: "object",
+  additionalProperties: false,
+  required: ["appName", "timezone", "stack", "flags", "harness"],
+  properties: {
+    appName: { type: "string", minLength: 1 },
+    timezone: { type: "string", minLength: 1 },
+    stack: stringRecord(["frontend", "backend", "database", "cloud", "packageManager"]),
+    flags: boolRecord(["hasFrontend", "usesAI", "runsInCloud"]),
+    harness: {
+      type: "object",
+      additionalProperties: false,
+      required: ["targets", "qa"],
+      properties: {
+        targets: {
+          type: "array",
+          minItems: 1,
+          items: { enum: ["claude", "codex"] },
+        },
+        qa: { type: "boolean" },
+      },
+    },
+  },
+} as const;

package/node_modules/rafi-spec/src/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Rafi neutral schema — the shapes that the `special-agents` library and the
+ * `ai-foreman` runtime must agree on. Authoring inputs (rule packs, skills,
+ * agent manifests) and the per-project configuration that drives composition.
+ */
+
+// ───────────────────────────── Rule packs ─────────────────────────────
+
+/** Which category a rule pack belongs to (drives default load behavior). */
+export type PackCategory = "base" | "process" | "domain" | "templated";
+
+/**
+ * When a pack applies. `always` packs load for every project; the others load
+ * only when the matching project flag is on (see {@link ProjectFlags}).
+ */
+export type PackCondition = "always" | "frontend" | "ai" | "cloud" | "backend";
+
+/** The YAML front-matter carried by each rule pack markdown file. */
+export interface RulePackFrontmatter {
+  /** Unique, kebab-case identifier (e.g. `security`). */
+  name: string;
+  category: PackCategory;
+  /** One-line summary used in indexes and pack pickers. */
+  description: string;
+  condition: PackCondition;
+  /** True when the body contains `{{placeholders}}` / `{{#if}}` directives. */
+  template: boolean;
+  /** When true, the pack is omitted while the foreman ticket tracker is active. */
+  supersededByForeman?: boolean;
+}
+
+/** A fully loaded rule pack: its front-matter plus the markdown body. */
+export interface RulePack extends RulePackFrontmatter {
+  /** The rule text (bullets) below the front-matter. */
+  body: string;
+}
+
+// ───────────────────────────── Skills ─────────────────────────────
+
+/** How a skill should be treated when flattening for Codex (which can't lazy-load). */
+export type CodexPriority = "inline" | "reference";
+
+/**
+ * A skill manifest. Keeps the existing Anthropic `SKILL.md` format and adds two
+ * optional composition fields that non-Rafi tools can safely ignore.
+ */
+export interface SkillManifest {
+  /** Unique, kebab-case identifier matching the skill directory name. */
+  name: string;
+  /** One-line trigger description (the cheap progressive-disclosure index). */
+  description: string;
+  /** Rule packs this skill wants loaded alongside it. */
+  pins?: string[];
+  /** Whether Codex flattening should inline this skill's body or just reference it. */
+  codexPriority?: CodexPriority;
+  /** The skill body (instructions). Optional in metadata-only contexts. */
+  body?: string;
+}
+
+// ───────────────────────────── Agents (roles) ─────────────────────────────
+
+/** The role an agent fills, mapped to an ai-foreman turn-type or command. */
+export type AgentRole = "builder" | "qa" | "planner" | "ticket-maker";
+
+/** Reasoning effort levels accepted by the builders. */
+export type EffortLevel = "low" | "medium" | "high" | "xhigh";
+
+/** Packs added to a role only when the matching project flag is on. */
+export interface ConditionalPacks {
+  ai?: string[];
+  frontend?: string[];
+  cloud?: string[];
+  backend?: string[];
+}
+
+/**
+ * A role manifest: a named composition of rule packs + skills that the runtime
+ * loads for a given turn-type.
+ */
+export interface AgentManifest {
+  /** Unique, kebab-case identifier (usually equals {@link role}). */
+  name: string;
+  description: string;
+  role: AgentRole;
+  /** Pack references; globs like `base/*` are allowed and expanded at compile time. */
+  packs: string[];
+  /** Skill names this role preloads. */
+  skills: string[];
+  /** Extra packs gated on project flags. */
+  conditionalPacks?: ConditionalPacks;
+  /** Model override; null inherits the runtime's `--model`. */
+  model?: string | null;
+  /** Effort override; null inherits the runtime's `--effort`. */
+  effort?: EffortLevel | null;
+}
+
+// ───────────────────────────── Project config ─────────────────────────────
+
+/** Which harness targets to emit native config for. */
+export type HarnessTarget = "claude" | "codex";
+
+/** The stack choices collected by `rafi create` (free-text strings). */
+export interface ProjectStack {
+  frontend: string;
+  backend: string;
+  database: string;
+  cloud: string;
+  packageManager: string;
+}
+
+/** Boolean flags that gate conditional packs and docs. */
+export interface ProjectFlags {
+  hasFrontend: boolean;
+  usesAI: boolean;
+  runsInCloud: boolean;
+}
+
+/** Harness emission + QA preferences. */
+export interface HarnessConfig {
+  targets: HarnessTarget[];
+  qa: boolean;
+}
+
+/**
+ * The committed `project.yaml` in a target repo. Skipping the walkthrough uses
+ * the library defaults, which reproduce today's hardcoded guidance.
+ */
+export interface ProjectConfig {
+  appName: string;
+  timezone: string;
+  stack: ProjectStack;
+  flags: ProjectFlags;
+  harness: HarnessConfig;
+}

package/node_modules/rafi-spec/src/validate.ts

@@ -0,0 +1,60 @@
+/** ajv-backed validation for the neutral schemas. */
+import { Ajv, type ValidateFunction } from "ajv";
+import {
+  rulePackSchema,
+  skillManifestSchema,
+  agentManifestSchema,
+  projectConfigSchema,
+} from "./schemas.js";
+import type {
+  RulePackFrontmatter,
+  SkillManifest,
+  AgentManifest,
+  ProjectConfig,
+} from "./types.js";
+
+const ajv = new Ajv({ allErrors: true, allowUnionTypes: true });
+
+/** Outcome of validating a value against one of the neutral schemas. */
+export interface ValidationResult {
+  valid: boolean;
+  /** Human-readable messages; empty when valid. */
+  errors: string[];
+}
+
+function run(fn: ValidateFunction, data: unknown): ValidationResult {
+  const valid = fn(data) as boolean;
+  if (valid) return { valid: true, errors: [] };
+  const errors = (fn.errors ?? []).map(
+    (e) => `${e.instancePath || "(root)"} ${e.message ?? "is invalid"}`.trim(),
+  );
+  return { valid: false, errors };
+}
+
+const vRulePack = ajv.compile(rulePackSchema);
+const vSkill = ajv.compile(skillManifestSchema);
+const vAgent = ajv.compile(agentManifestSchema);
+const vProject = ajv.compile(projectConfigSchema);
+
+export const validateRulePack = (d: unknown): ValidationResult => run(vRulePack, d);
+export const validateSkillManifest = (d: unknown): ValidationResult => run(vSkill, d);
+export const validateAgentManifest = (d: unknown): ValidationResult => run(vAgent, d);
+export const validateProjectConfig = (d: unknown): ValidationResult => run(vProject, d);
+
+/** Validate and narrow, throwing on failure. */
+export function assertRulePack(d: unknown): asserts d is RulePackFrontmatter {
+  const r = validateRulePack(d);
+  if (!r.valid) throw new Error(`Invalid rule pack: ${r.errors.join("; ")}`);
+}
+export function assertSkillManifest(d: unknown): asserts d is SkillManifest {
+  const r = validateSkillManifest(d);
+  if (!r.valid) throw new Error(`Invalid skill manifest: ${r.errors.join("; ")}`);
+}
+export function assertAgentManifest(d: unknown): asserts d is AgentManifest {
+  const r = validateAgentManifest(d);
+  if (!r.valid) throw new Error(`Invalid agent manifest: ${r.errors.join("; ")}`);
+}
+export function assertProjectConfig(d: unknown): asserts d is ProjectConfig {
+  const r = validateProjectConfig(d);
+  if (!r.valid) throw new Error(`Invalid project config: ${r.errors.join("; ")}`);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@rafi-ai/cli",
+  "version": "0.1.0",
+  "description": "Rafi CLI — scaffold and compile AI framework configs for a target repo.",
+  "type": "module",
+  "bin": {
+    "rafi": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bundledDependencies": [
+    "rafi-spec"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "commander": "^12.1.0",
+    "yaml": "^2.5.1",
+    "special-agents": "0.1.0",
+    "rafi-spec": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts"
+  }
+}