special-agents 0.3.6 → 0.4.0

package/dist/content.d.ts

@@ -7,6 +7,7 @@ export declare function parseRulePack(raw: string): RulePack;
 export interface Defaults {
     stack: Record<string, string>;
     flags: Record<string, boolean>;
+    docsRoot?: string;
 }
 /** Read content/defaults.yaml. */
 export declare function loadDefaults(): Defaults;

package/dist/content.js

@@ -27,7 +27,8 @@ export function parseRulePack(raw) {
 }
 /** Read content/defaults.yaml. */
 export function loadDefaults() {
-    return parseYaml(readFileSync(join(CONTENT_DIR, "defaults.yaml"), "utf8"));
+    const defaults = parseYaml(readFileSync(join(CONTENT_DIR, "defaults.yaml"), "utf8"));
+    return { ...defaults, docsRoot: defaults.docsRoot ?? "docs" };
 }
 /** The flattened-rules-doc preamble (everything before the first section). */
 export function loadPreamble() {

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "special-agents",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Rafi library: composable best-practice rules, skills, and agents for Claude Code and Codex.",
+  "license": "Apache-2.0",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ttante/rafi.git",
+    "directory": "packages/special-agents"
+  },
+  "bugs": {
+    "url": "https://github.com/ttante/rafi/issues"
+  },
+  "homepage": "https://github.com/ttante/rafi/tree/main/packages/special-agents#readme",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -14,27 +24,25 @@
   "files": [
     "dist",
     "content",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts"
+  },
   "engines": {
     "node": ">=20"
   },
-  "bundledDependencies": [
-    "rafi-spec"
-  ],
   "dependencies": {
+    "rafi-spec": "0.4.0",
     "ajv": "^8.20.0",
-    "yaml": "^2.5.1",
-    "rafi-spec": "0.0.0"
+    "yaml": "^2.5.1"
   },
   "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"
   }
-}
+}

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

@@ -1,4 +0,0 @@
-/** 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

@@ -1,4 +0,0 @@
-/** 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

@@ -1,245 +0,0 @@
-/**
- * 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", "agent_files", "agents", "skills"];
-    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";
-                };
-            };
-        };
-        readonly agent_files: {
-            readonly type: "object";
-            readonly additionalProperties: false;
-            readonly required: readonly ["mode", "codex", "claude"];
-            readonly properties: {
-                readonly mode: {
-                    readonly enum: readonly ["append", "update", "overwrite"];
-                };
-                readonly codex: {
-                    readonly type: "string";
-                    readonly minLength: 1;
-                };
-                readonly claude: {
-                    readonly type: "string";
-                    readonly minLength: 1;
-                };
-            };
-        };
-        readonly agents: {
-            readonly type: "object";
-            readonly additionalProperties: {
-                readonly type: "object";
-                readonly additionalProperties: false;
-                readonly required: readonly ["artifact_source", "claude", "codex"];
-                readonly properties: {
-                    readonly artifact_source: {
-                        readonly enum: readonly ["rafi", "existing"];
-                    };
-                    readonly claude: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                    };
-                    readonly codex: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                    };
-                };
-            };
-        };
-        readonly skills: {
-            readonly type: "object";
-            readonly additionalProperties: {
-                readonly type: "object";
-                readonly additionalProperties: false;
-                readonly required: readonly ["artifact_source", "claude", "codex"];
-                readonly properties: {
-                    readonly artifact_source: {
-                        readonly enum: readonly ["rafi", "existing"];
-                    };
-                    readonly claude: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                    };
-                    readonly codex: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                    };
-                };
-            };
-        };
-    };
-};

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

@@ -1,121 +0,0 @@
-/**
- * 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" }])),
-});
-const runtimeArtifactPaths = {
-    type: "object",
-    additionalProperties: false,
-    required: ["artifact_source", "claude", "codex"],
-    properties: {
-        artifact_source: { enum: ["rafi", "existing"] },
-        claude: { type: "string", minLength: 1 },
-        codex: { type: "string", minLength: 1 },
-    },
-};
-const artifactPathMap = {
-    type: "object",
-    additionalProperties: runtimeArtifactPaths,
-};
-export const projectConfigSchema = {
-    $id: "rafi/projectConfig",
-    type: "object",
-    additionalProperties: false,
-    required: ["appName", "timezone", "stack", "flags", "harness", "agent_files", "agents", "skills"],
-    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" },
-            },
-        },
-        agent_files: {
-            type: "object",
-            additionalProperties: false,
-            required: ["mode", "codex", "claude"],
-            properties: {
-                mode: { enum: ["append", "update", "overwrite"] },
-                codex: { type: "string", minLength: 1 },
-                claude: { type: "string", minLength: 1 },
-            },
-        },
-        agents: artifactPathMap,
-        skills: artifactPathMap,
-    },
-};

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

@@ -1,129 +0,0 @@
-/**
- * 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;
-}
-/** How Rafi should handle existing root instruction files. */
-export type AgentFileMode = "append" | "update" | "overwrite";
-/** Root instruction files used by Codex and Claude. */
-export interface AgentFilesConfig {
-    mode: AgentFileMode;
-    codex: string;
-    claude: string;
-}
-/** Per-runtime paths for a skill or agent artifact. */
-export type ArtifactSource = "rafi" | "existing";
-export interface RuntimeArtifactConfig {
-    artifact_source: ArtifactSource;
-    claude: string;
-    codex: string;
-}
-/**
- * The committed `rafi-config.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;
-    agent_files: AgentFilesConfig;
-    agents: Record<string, RuntimeArtifactConfig>;
-    skills: Record<string, RuntimeArtifactConfig>;
-}

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

@@ -1,6 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-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

@@ -1,40 +0,0 @@
-/** 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("; ")}`);
-}