special-agents 0.3.5 → 0.3.6

package/content/defaults.yaml

@@ -1,6 +1,6 @@
 # Default stack values + flags. These reproduce the original hardcoded rules.md
 # guidance: rendering the templated packs with these defaults equals the source.
-# `rafi create` writes a project.yaml that overrides these per project.
+# `rafi create` writes a rafi-config.yaml that overrides these per project.
 stack:
   frontend: "React with TypeScript"
   backend: "Python and Node.js"

package/content/preamble.md

@@ -11,3 +11,4 @@ For Claude Code, create a repository-root `CLAUDE.md` that imports the same rule
 
 Keep durable process rules in this file. Put detailed project facts in the project documents named below, not in the agent rules.
 
+Custom Rafi skills or agents can replace the defaults by setting `artifact_source: existing` and editing their paths in `rafi-config.yaml`.

package/dist/compile.d.ts

@@ -1,6 +1,7 @@
 import { type Defaults, type LoadedPack } from "./content.js";
 import { type ConditionFlags, type ResolvableManifest } from "./resolve.js";
 import type { AgentManifest, AgentRole, EffortLevel } from "rafi-spec";
+export declare const CUSTOM_ARTIFACTS_NOTE = "Custom Rafi skills or agents can replace the defaults by setting `artifact_source: existing` and editing their paths in `rafi-config.yaml`.\n";
 export interface CompileOptions {
     /** Stack/flags to render with. Defaults to the bundled `defaults.yaml`. */
     defaults?: Defaults;
@@ -62,9 +63,13 @@ export declare function emitAgentsMd(targetDir: string, opts?: CompileOptions):
  * Write `<targetDir>/CLAUDE.md` — the lean Claude entrypoint that imports `AGENTS.md`.
  */
 export declare function emitClaudeMd(targetDir: string, opts?: CompileOptions): void;
+export declare function renderAgentsMd(opts?: CompileOptions): string;
+export declare function renderClaudeMd(opts?: CompileOptions): string;
 export interface EmitOptions extends AgentComposeOptions {
     /** Roles to emit. Defaults to all four. */
     roles?: AgentRole[];
+    /** Map generic skill names in role manifests to the installed runtime skill names. */
+    skillNames?: Record<string, string>;
 }
 /**
  * Write `.rafi/compiled/<role>/system.md` + `meta.json` for each role.
@@ -77,3 +82,16 @@ export declare function emitCompiledBundles(targetDir: string, opts?: EmitOption
  * composed system text.
  */
 export declare function emitClaudeAgents(targetDir: string, opts?: EmitOptions): void;
+export interface EmitMappedOptions extends EmitOptions {
+    paths?: Record<string, string>;
+    force?: boolean;
+}
+export declare function emitMappedClaudeAgents(targetDir: string, opts?: EmitMappedOptions): void;
+export declare function emitCodexAgents(targetDir: string, opts?: EmitMappedOptions): void;
+export interface EmitSkillsOptions {
+    /** Generic skill name -> runtime-specific path. */
+    paths?: Record<string, string>;
+    names?: string[];
+    force?: boolean;
+}
+export declare function emitSkills(targetDir: string, opts?: EmitSkillsOptions): void;

package/dist/compile.js

@@ -9,12 +9,14 @@
  *
  * Per-role and lean-Claude emission build on this and the resolver (see resolve.ts).
  */
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { cpSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { render } from "./template.js";
 import { loadAllPacks, loadDefaults, loadPack, loadPacksIndex, loadPreamble, } from "./content.js";
 import { resolveAgentPacks } from "./resolve.js";
 import { loadAgent, AGENT_ROLES } from "./agents.js";
+import { loadAllSkills, SKILLS_DIR } from "./skills.js";
+export const CUSTOM_ARTIFACTS_NOTE = "Custom Rafi skills or agents can replace the defaults by setting `artifact_source: existing` and editing their paths in `rafi-config.yaml`.\n";
 /** Render one pack body, substituting `{{vars}}` and resolving `{{#if flag}}` blocks. */
 export function renderPackBody(pack, defaults) {
     return render(pack.body, { vars: defaults.stack, flags: defaults.flags });
@@ -69,17 +71,23 @@ export function buildConditionsHeader(flags) {
  * Format: one-line conditions header + preamble + all packs rendered with defaults.
  */
 export function emitAgentsMd(targetDir, opts = {}) {
-    const defaults = opts.defaults ?? loadDefaults();
-    const header = buildConditionsHeader(defaults.flags);
-    writeFileSync(join(targetDir, "AGENTS.md"), header + composeRulesMarkdown({ defaults }), "utf8");
+    writeFileSync(join(targetDir, "AGENTS.md"), renderAgentsMd(opts), "utf8");
 }
 /**
  * Write `<targetDir>/CLAUDE.md` — the lean Claude entrypoint that imports `AGENTS.md`.
  */
 export function emitClaudeMd(targetDir, opts = {}) {
+    writeFileSync(join(targetDir, "CLAUDE.md"), renderClaudeMd(opts), "utf8");
+}
+export function renderAgentsMd(opts = {}) {
+    const defaults = opts.defaults ?? loadDefaults();
+    const header = buildConditionsHeader(defaults.flags);
+    return header + composeRulesMarkdown({ defaults });
+}
+export function renderClaudeMd(opts = {}) {
     const defaults = opts.defaults ?? loadDefaults();
     const header = buildConditionsHeader(defaults.flags);
-    writeFileSync(join(targetDir, "CLAUDE.md"), header + "@AGENTS.md\n", "utf8");
+    return header + "@AGENTS.md\n\n" + CUSTOM_ARTIFACTS_NOTE;
 }
 /**
  * Write `.rafi/compiled/<role>/system.md` + `meta.json` for each role.
@@ -92,7 +100,8 @@ export function emitCompiledBundles(targetDir, opts = {}) {
         const dir = join(targetDir, ".rafi", "compiled", role);
         mkdirSync(dir, { recursive: true });
         writeFileSync(join(dir, "system.md"), bundle.system, "utf8");
-        const meta = { skills: bundle.skills, model: bundle.model, effort: bundle.effort };
+        const skills = bundle.skills.map((skill) => opts.skillNames?.[skill] ?? skill);
+        const meta = { skills, model: bundle.model, effort: bundle.effort };
         writeFileSync(join(dir, "meta.json"), JSON.stringify(meta, null, 2) + "\n", "utf8");
     }
 }
@@ -111,3 +120,65 @@ export function emitClaudeAgents(targetDir, opts = {}) {
         writeFileSync(join(agentsDir, `${role}.md`), frontMatter + bundle.system, "utf8");
     }
 }
+export function emitMappedClaudeAgents(targetDir, opts = {}) {
+    const roles = opts.roles ?? AGENT_ROLES;
+    for (const role of roles) {
+        const bundle = getAgent(role, opts);
+        const path = join(targetDir, opts.paths?.[role] ?? `./.claude/agents/${role}.md`);
+        if (!opts.force && fileExists(path))
+            continue;
+        mkdirSync(dirname(path), { recursive: true });
+        const name = artifactNameFromPath(path, role);
+        const frontMatter = `---\nname: ${name}\ndescription: ${bundle.manifest.description}\n---\n\n`;
+        writeFileSync(path, frontMatter + bundle.system, "utf8");
+    }
+}
+export function emitCodexAgents(targetDir, opts = {}) {
+    const roles = opts.roles ?? AGENT_ROLES;
+    for (const role of roles) {
+        const bundle = getAgent(role, opts);
+        const path = join(targetDir, opts.paths?.[role] ?? `./.codex/agents/${role}.toml`);
+        if (!opts.force && fileExists(path))
+            continue;
+        mkdirSync(dirname(path), { recursive: true });
+        const name = artifactNameFromPath(path, role);
+        const toml = `name = ${JSON.stringify(name)}\n` +
+            `description = ${JSON.stringify(bundle.manifest.description)}\n` +
+            `developer_instructions = ${JSON.stringify(bundle.system)}\n`;
+        writeFileSync(path, toml, "utf8");
+    }
+}
+export function emitSkills(targetDir, opts = {}) {
+    for (const skill of loadAllSkills()) {
+        if (opts.names && !opts.names.includes(skill.name))
+            continue;
+        const path = join(targetDir, opts.paths?.[skill.name] ?? `./.agents/skills/${skill.name}/SKILL.md`);
+        if (!opts.force && fileExists(path))
+            continue;
+        const dir = dirname(path);
+        mkdirSync(dirname(dir), { recursive: true });
+        cpSync(join(SKILLS_DIR, skill.name), dir, { recursive: true });
+        const installedName = artifactNameFromPath(path, skill.name);
+        if (installedName !== skill.name) {
+            const raw = readFileSync(join(SKILLS_DIR, skill.name, "SKILL.md"), "utf8");
+            writeFileSync(path, raw.replace(/^name:\s*.+$/m, `name: ${installedName}`), "utf8");
+        }
+    }
+}
+function artifactNameFromPath(path, fallback) {
+    const file = path.split(/[\\/]/).pop() ?? fallback;
+    if (file === "SKILL.md") {
+        const parent = path.split(/[\\/]/).at(-2);
+        return parent && parent.length > 0 ? parent : fallback;
+    }
+    return file.replace(/\.(md|toml)$/i, "") || fallback;
+}
+function fileExists(path) {
+    try {
+        readFileSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -6,7 +6,7 @@
 export * from "rafi-spec";
 export { render, type TemplateContext } from "./template.js";
 export { CONTENT_DIR, DOCS_DIR, parseRulePack, loadDefaults, loadDocsIndex, loadPreamble, loadPacksIndex, loadPack, loadAllPacks, packFilesOnDisk, type Defaults, type PackIndexEntry, type LoadedPack, type DocIndexEntry, } from "./content.js";
-export { composeRulesMarkdown, composeAgentSystem, getAgent, buildConditionsHeader, emitAgentsMd, emitClaudeMd, emitCompiledBundles, emitClaudeAgents, renderPackBody, type CompileOptions, type AgentComposeOptions, type ComposedAgent, type EmitOptions, } from "./compile.js";
+export { composeRulesMarkdown, composeAgentSystem, getAgent, buildConditionsHeader, CUSTOM_ARTIFACTS_NOTE, renderAgentsMd, renderClaudeMd, emitAgentsMd, emitClaudeMd, emitCompiledBundles, emitClaudeAgents, emitMappedClaudeAgents, emitCodexAgents, emitSkills, renderPackBody, type CompileOptions, type AgentComposeOptions, type ComposedAgent, type EmitOptions, type EmitMappedOptions, type EmitSkillsOptions, } from "./compile.js";
 export { resolvePackRefs, resolveAgentPacks, type ConditionFlags, type ResolveContext, type ResolvableManifest, } from "./resolve.js";
 export { SKILLS_DIR, parseSkillManifest, loadSkill, loadAllSkills, skillNames, } from "./skills.js";
 export { AGENTS_DIR, AGENT_ROLES, parseAgentManifest, loadAgent, loadAllAgents, } from "./agents.js";

package/dist/index.js

@@ -6,7 +6,7 @@
 export * from "rafi-spec";
 export { render } from "./template.js";
 export { CONTENT_DIR, DOCS_DIR, parseRulePack, loadDefaults, loadDocsIndex, loadPreamble, loadPacksIndex, loadPack, loadAllPacks, packFilesOnDisk, } from "./content.js";
-export { composeRulesMarkdown, composeAgentSystem, getAgent, buildConditionsHeader, emitAgentsMd, emitClaudeMd, emitCompiledBundles, emitClaudeAgents, renderPackBody, } from "./compile.js";
+export { composeRulesMarkdown, composeAgentSystem, getAgent, buildConditionsHeader, CUSTOM_ARTIFACTS_NOTE, renderAgentsMd, renderClaudeMd, emitAgentsMd, emitClaudeMd, emitCompiledBundles, emitClaudeAgents, emitMappedClaudeAgents, emitCodexAgents, emitSkills, renderPackBody, } from "./compile.js";
 export { resolvePackRefs, resolveAgentPacks, } from "./resolve.js";
 export { SKILLS_DIR, parseSkillManifest, loadSkill, loadAllSkills, skillNames, } from "./skills.js";
 export { AGENTS_DIR, AGENT_ROLES, parseAgentManifest, loadAgent, loadAllAgents, } from "./agents.js";

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

@@ -133,7 +133,7 @@ export declare const projectConfigSchema: {
     readonly $id: "rafi/projectConfig";
     readonly type: "object";
     readonly additionalProperties: false;
-    readonly required: readonly ["appName", "timezone", "stack", "flags", "harness"];
+    readonly required: readonly ["appName", "timezone", "stack", "flags", "harness", "agent_files", "agents", "skills"];
     readonly properties: {
         readonly appName: {
             readonly type: "string";
@@ -181,5 +181,65 @@ export declare const projectConfigSchema: {
                 };
             };
         };
+        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

@@ -68,11 +68,25 @@ const boolRecord = (keys) => ({
     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"],
+    required: ["appName", "timezone", "stack", "flags", "harness", "agent_files", "agents", "skills"],
     properties: {
         appName: { type: "string", minLength: 1 },
         timezone: { type: "string", minLength: 1 },
@@ -91,5 +105,17 @@ export const projectConfigSchema = {
                 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

@@ -98,8 +98,23 @@ 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 `project.yaml` in a target repo. Skipping the walkthrough uses
+ * 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 {
@@ -108,4 +123,7 @@ export interface ProjectConfig {
     stack: ProjectStack;
     flags: ProjectFlags;
     harness: HarnessConfig;
+    agent_files: AgentFilesConfig;
+    agents: Record<string, RuntimeArtifactConfig>;
+    skills: Record<string, RuntimeArtifactConfig>;
 }

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

@@ -75,11 +75,27 @@ const boolRecord = (keys: string[]) => ({
   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 },
+  },
+} as const;
+
+const artifactPathMap = {
+  type: "object",
+  additionalProperties: runtimeArtifactPaths,
+} as const;
+
 export const projectConfigSchema = {
   $id: "rafi/projectConfig",
   type: "object",
   additionalProperties: false,
-  required: ["appName", "timezone", "stack", "flags", "harness"],
+  required: ["appName", "timezone", "stack", "flags", "harness", "agent_files", "agents", "skills"],
   properties: {
     appName: { type: "string", minLength: 1 },
     timezone: { type: "string", minLength: 1 },
@@ -98,5 +114,17 @@ export const projectConfigSchema = {
         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,
   },
 } as const;

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

@@ -121,8 +121,27 @@ export interface HarnessConfig {
   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 `project.yaml` in a target repo. Skipping the walkthrough uses
+ * 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 {
@@ -131,4 +150,7 @@ export interface ProjectConfig {
   stack: ProjectStack;
   flags: ProjectFlags;
   harness: HarnessConfig;
+  agent_files: AgentFilesConfig;
+  agents: Record<string, RuntimeArtifactConfig>;
+  skills: Record<string, RuntimeArtifactConfig>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "special-agents",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Rafi library: composable best-practice rules, skills, and agents for Claude Code and Codex.",
   "type": "module",
   "main": "./dist/index.js",