special-agents 0.1.0

package/dist/template.js

@@ -0,0 +1,34 @@
+/**
+ * The Rafi templating engine — deliberately tiny (§3 of PLAN.md).
+ *
+ * Two directives only:
+ *   - `{{key}}`                  → substituted from {@link TemplateContext.vars}
+ *   - `{{#if flag}}…{{/if}}`     → body kept when the flag is true, else the whole
+ *                                  block (markers + body) is removed
+ *
+ * No nesting, no expressions, no helpers. An unknown var or flag is a hard error
+ * rather than a silent blank, so a typo can never quietly drop guidance from a
+ * composed agent. Conditional blocks are resolved first, so vars that live only
+ * inside a dropped block are never required to exist.
+ */
+const IF_BLOCK = /\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+const VAR = /\{\{\s*(\w+)\s*\}\}/g;
+/** Render a template string against the given context. Throws on unknown var/flag. */
+export function render(template, ctx) {
+    // 1) Resolve conditional blocks. Body is kept verbatim (and re-scanned for vars
+    //    in step 2) when the flag is true; the entire block is dropped when false.
+    const withConditionals = template.replace(IF_BLOCK, (_match, flag, body) => {
+        if (!(flag in ctx.flags)) {
+            throw new Error(`unknown flag in {{#if}}: ${flag}`);
+        }
+        return ctx.flags[flag] ? body : "";
+    });
+    // 2) Substitute remaining {{var}} occurrences. Anything left now is real text
+    //    the author expected to fill, so an unknown key is an error.
+    return withConditionals.replace(VAR, (_match, key) => {
+        if (!(key in ctx.vars)) {
+            throw new Error(`unknown placeholder: {{${key}}}`);
+        }
+        return ctx.vars[key];
+    });
+}

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;