special-agents 0.1.0

package/content/skills/write-a-prd/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: write-a-prd
+description: Generate a PRD from the client brief and write it as a local markdown file in issues/. Use when the user wants to turn a client request into a structured PRD.
+---
+
+This skill will be invoked when the user wants to create a PRD. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Interview the user relentlessly about every aspect of this plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+
+4. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation.
+
+A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes.
+
+Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.
+
+5. Once you have a complete understanding of the problem and solution, use the template below to write the PRD. The PRD should be written as a local markdown file at `issues/prd.md`. Create the `issues/` directory if it doesn't exist. Do NOT submit a GitHub issue or call any external service.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>

package/dist/agents.d.ts

@@ -0,0 +1,11 @@
+import { type AgentManifest, type AgentRole } from "rafi-spec";
+/** Absolute path to the bundled `content/agents/` directory. */
+export declare const AGENTS_DIR: string;
+/** The roles Rafi ships, each mapping to an ai-foreman turn-type/command. */
+export declare const AGENT_ROLES: AgentRole[];
+/** Parse an agent-manifest YAML string into a validated AgentManifest. */
+export declare function parseAgentManifest(raw: string): AgentManifest;
+/** Load a single role manifest by name (the file stem under content/agents). */
+export declare function loadAgent(name: string): AgentManifest;
+/** Load every shipped role manifest (in {@link AGENT_ROLES} order). */
+export declare function loadAllAgents(): AgentManifest[];

package/dist/agents.js

@@ -0,0 +1,31 @@
+/**
+ * Agent (role) manifest loader. Reads `content/agents/<role>.yaml` — the named
+ * compositions of packs + skills that the runtime loads per turn-type. A pure
+ * `parseAgentManifest` is split from the filesystem helpers.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { assertAgentManifest } from "rafi-spec";
+import { CONTENT_DIR } from "./content.js";
+/** Absolute path to the bundled `content/agents/` directory. */
+export const AGENTS_DIR = join(CONTENT_DIR, "agents");
+/** The roles Rafi ships, each mapping to an ai-foreman turn-type/command. */
+export const AGENT_ROLES = ["builder", "qa", "planner", "ticket-maker"];
+/** Parse an agent-manifest YAML string into a validated AgentManifest. */
+export function parseAgentManifest(raw) {
+    const data = parseYaml(raw);
+    assertAgentManifest(data); // throws "Invalid agent manifest: …"
+    return data;
+}
+/** Load a single role manifest by name (the file stem under content/agents). */
+export function loadAgent(name) {
+    const path = join(AGENTS_DIR, `${name}.yaml`);
+    if (!existsSync(path))
+        throw new Error(`unknown agent: ${name}`);
+    return parseAgentManifest(readFileSync(path, "utf8"));
+}
+/** Load every shipped role manifest (in {@link AGENT_ROLES} order). */
+export function loadAllAgents() {
+    return AGENT_ROLES.map((role) => loadAgent(role));
+}

package/dist/compile.d.ts

@@ -0,0 +1,79 @@
+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 interface CompileOptions {
+    /** Stack/flags to render with. Defaults to the bundled `defaults.yaml`. */
+    defaults?: Defaults;
+}
+/** Render one pack body, substituting `{{vars}}` and resolving `{{#if flag}}` blocks. */
+export declare function renderPackBody(pack: Pick<LoadedPack, "body">, defaults: Defaults): string;
+/**
+ * The full flattened rules doc: preamble + all packs (index order), rendered.
+ * Includes every pack regardless of condition — this is the canonical "everything"
+ * document; role/flag filtering is the resolver's job.
+ */
+export declare function composeRulesMarkdown(opts?: CompileOptions): string;
+/** Options controlling how a role's packs are resolved and rendered. */
+export interface AgentComposeOptions {
+    /** Stack/flags to render with. Defaults to the bundled `defaults.yaml`. */
+    defaults?: Defaults;
+    /** Which conditional pack groups to include (ai/frontend/cloud/backend). */
+    conditions?: ConditionFlags;
+    /** Drop `supersededByForeman` packs (the foreman tracker owns them). */
+    foremanActive?: boolean;
+}
+/**
+ * Render a role's system text: its resolved packs (listed + enabled conditionals,
+ * deduped, in manifest order) concatenated and rendered with the defaults. Unlike
+ * {@link composeRulesMarkdown} there is no preamble — this is appended to the
+ * harness's own system prompt, not used as a standalone rules doc.
+ */
+export declare function composeAgentSystem(manifest: ResolvableManifest, opts?: AgentComposeOptions): string;
+/** A composed role bundle, ready for the runtime to load. */
+export interface ComposedAgent {
+    manifest: AgentManifest;
+    /** The rendered role system text (pack bodies). */
+    system: string;
+    /** Skill names the role preloads. */
+    skills: string[];
+    /** Model override, or null to inherit the runtime's `--model`. */
+    model: string | null;
+    /** Effort override, or null to inherit the runtime's `--effort`. */
+    effort: EffortLevel | null;
+}
+/** Load a role manifest and compose its full bundle (system text + metadata). */
+export declare function getAgent(role: string, opts?: AgentComposeOptions): ComposedAgent;
+/**
+ * Build the generated header comment that records which conditional pack groups
+ * are active. Written at the top of `AGENTS.md` and `CLAUDE.md` so the choice
+ * is never invisible.
+ */
+export declare function buildConditionsHeader(flags: {
+    usesAI: boolean;
+    hasFrontend: boolean;
+    runsInCloud: boolean;
+}): string;
+/**
+ * Write `<targetDir>/AGENTS.md` — the flattened Codex rules document.
+ * Format: one-line conditions header + preamble + all packs rendered with defaults.
+ */
+export declare function emitAgentsMd(targetDir: string, opts?: CompileOptions): void;
+/**
+ * Write `<targetDir>/CLAUDE.md` — the lean Claude entrypoint that imports `AGENTS.md`.
+ */
+export declare function emitClaudeMd(targetDir: string, opts?: CompileOptions): void;
+export interface EmitOptions extends AgentComposeOptions {
+    /** Roles to emit. Defaults to all four. */
+    roles?: AgentRole[];
+}
+/**
+ * Write `.rafi/compiled/<role>/system.md` + `meta.json` for each role.
+ * Foreman's `roles.ts` reads these at runtime to load the composed bundle.
+ */
+export declare function emitCompiledBundles(targetDir: string, opts?: EmitOptions): void;
+/**
+ * Write lean Claude subagent files to `<targetDir>/.claude/agents/<role>.md`.
+ * Each file has YAML front-matter (name, description) followed by the role's
+ * composed system text.
+ */
+export declare function emitClaudeAgents(targetDir: string, opts?: EmitOptions): void;

package/dist/compile.js

@@ -0,0 +1,113 @@
+/**
+ * Composition — assembles harness artifacts from the bundled packs.
+ *
+ * `composeRulesMarkdown` produces the flattened rules document (Codex's `AGENTS.md`
+ * form): the preamble followed by every pack in index order, with templated packs
+ * rendered against the stack/flags. Because each pack body is a contiguous slice of
+ * the source between headings, concatenating them after the preamble reproduces the
+ * canonical rules doc byte-for-byte — the Phase 3 golden gate.
+ *
+ * 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 { 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";
+/** 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 });
+}
+/**
+ * The full flattened rules doc: preamble + all packs (index order), rendered.
+ * Includes every pack regardless of condition — this is the canonical "everything"
+ * document; role/flag filtering is the resolver's job.
+ */
+export function composeRulesMarkdown(opts = {}) {
+    const defaults = opts.defaults ?? loadDefaults();
+    const body = loadAllPacks()
+        .map((pack) => renderPackBody(pack, defaults))
+        .join("");
+    return loadPreamble() + body;
+}
+/**
+ * Render a role's system text: its resolved packs (listed + enabled conditionals,
+ * deduped, in manifest order) concatenated and rendered with the defaults. Unlike
+ * {@link composeRulesMarkdown} there is no preamble — this is appended to the
+ * harness's own system prompt, not used as a standalone rules doc.
+ */
+export function composeAgentSystem(manifest, opts = {}) {
+    const defaults = opts.defaults ?? loadDefaults();
+    const index = loadPacksIndex();
+    const entries = resolveAgentPacks(manifest, { conditions: opts.conditions ?? {}, foremanActive: opts.foremanActive }, index);
+    return entries.map((e) => renderPackBody(loadPack(e.path), defaults)).join("");
+}
+/** Load a role manifest and compose its full bundle (system text + metadata). */
+export function getAgent(role, opts = {}) {
+    const manifest = loadAgent(role);
+    return {
+        manifest,
+        system: composeAgentSystem(manifest, opts),
+        skills: manifest.skills,
+        model: manifest.model ?? null,
+        effort: manifest.effort ?? null,
+    };
+}
+/**
+ * Build the generated header comment that records which conditional pack groups
+ * are active. Written at the top of `AGENTS.md` and `CLAUDE.md` so the choice
+ * is never invisible.
+ */
+export function buildConditionsHeader(flags) {
+    return (`# rafi: ai=${flags.usesAI ? "on" : "off"}` +
+        ` frontend=${flags.hasFrontend ? "on" : "off"}` +
+        ` cloud=${flags.runsInCloud ? "on" : "off"}\n`);
+}
+/**
+ * Write `<targetDir>/AGENTS.md` — the flattened Codex rules document.
+ * 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");
+}
+/**
+ * Write `<targetDir>/CLAUDE.md` — the lean Claude entrypoint that imports `AGENTS.md`.
+ */
+export function emitClaudeMd(targetDir, opts = {}) {
+    const defaults = opts.defaults ?? loadDefaults();
+    const header = buildConditionsHeader(defaults.flags);
+    writeFileSync(join(targetDir, "CLAUDE.md"), header + "@AGENTS.md\n", "utf8");
+}
+/**
+ * Write `.rafi/compiled/<role>/system.md` + `meta.json` for each role.
+ * Foreman's `roles.ts` reads these at runtime to load the composed bundle.
+ */
+export function emitCompiledBundles(targetDir, opts = {}) {
+    const roles = opts.roles ?? AGENT_ROLES;
+    for (const role of roles) {
+        const bundle = getAgent(role, 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 };
+        writeFileSync(join(dir, "meta.json"), JSON.stringify(meta, null, 2) + "\n", "utf8");
+    }
+}
+/**
+ * Write lean Claude subagent files to `<targetDir>/.claude/agents/<role>.md`.
+ * Each file has YAML front-matter (name, description) followed by the role's
+ * composed system text.
+ */
+export function emitClaudeAgents(targetDir, opts = {}) {
+    const roles = opts.roles ?? AGENT_ROLES;
+    const agentsDir = join(targetDir, ".claude", "agents");
+    mkdirSync(agentsDir, { recursive: true });
+    for (const role of roles) {
+        const bundle = getAgent(role, opts);
+        const frontMatter = `---\nname: ${bundle.manifest.name}\ndescription: ${bundle.manifest.description}\n---\n\n`;
+        writeFileSync(join(agentsDir, `${role}.md`), frontMatter + bundle.system, "utf8");
+    }
+}

package/dist/content.d.ts

@@ -0,0 +1,49 @@
+import { type RulePack } from "rafi-spec";
+/** Absolute path to the bundled `content/` directory. */
+export declare const CONTENT_DIR: string;
+/** Parse a rule-pack markdown string into its validated front-matter + body. */
+export declare function parseRulePack(raw: string): RulePack;
+/** Default stack strings + flags (content/defaults.yaml). */
+export interface Defaults {
+    stack: Record<string, string>;
+    flags: Record<string, boolean>;
+}
+/** Read content/defaults.yaml. */
+export declare function loadDefaults(): Defaults;
+/** The flattened-rules-doc preamble (everything before the first section). */
+export declare function loadPreamble(): string;
+/** One row of content/rules/packs.index.yaml. */
+export interface PackIndexEntry {
+    name: string;
+    category: string;
+    path: string;
+    condition: string;
+    template: boolean;
+    supersededByForeman?: boolean;
+    order: number;
+}
+/** Read the pack registry, sorted by its `order` field. */
+export declare function loadPacksIndex(): PackIndexEntry[];
+/** A loaded pack: its parsed content plus where it sits in the registry. */
+export interface LoadedPack extends RulePack {
+    /** Path relative to content/rules (e.g. `base/core.md`). */
+    path: string;
+    order: number;
+}
+/** Load a single pack file by its path relative to content/rules. */
+export declare function loadPack(relPath: string): RulePack;
+/** Load every pack listed in the index, in index order. */
+export declare function loadAllPacks(): LoadedPack[];
+/** Absolute path to the bundled `content/docs/` directory. */
+export declare const DOCS_DIR: string;
+/** One entry from content/docs/docs.index.yaml. */
+export interface DocIndexEntry {
+    /** Path relative to content/docs/ (and will be placed under targetDir/docs/). */
+    path: string;
+    /** Copy gate: always | ai | frontend. */
+    gate: "always" | "ai" | "frontend";
+}
+/** Read content/docs/docs.index.yaml. */
+export declare function loadDocsIndex(): DocIndexEntry[];
+/** Names of the pack files physically present under content/rules (for drift checks). */
+export declare function packFilesOnDisk(): string[];

package/dist/content.js

@@ -0,0 +1,73 @@
+/**
+ * Loads the bundled authoring content (rule packs, their index, and the default
+ * stack/flags) that the composition step consumes.
+ *
+ * `parseRulePack` is a pure string→RulePack transform (front-matter split + schema
+ * validation) kept separate from the filesystem helpers so the parse rules are
+ * unit-testable. `CONTENT_DIR` resolves the same whether this module runs from
+ * `src/` (tsx/tests) or `dist/` (published) because `content/` ships alongside both.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { assertRulePack } from "rafi-spec";
+/** Absolute path to the bundled `content/` directory. */
+export const CONTENT_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "content");
+const RULES_DIR = join(CONTENT_DIR, "rules");
+const FRONT_MATTER = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+/** Parse a rule-pack markdown string into its validated front-matter + body. */
+export function parseRulePack(raw) {
+    const m = raw.match(FRONT_MATTER);
+    if (!m)
+        throw new Error("rule pack is missing front-matter");
+    const fm = parseYaml(m[1]);
+    assertRulePack(fm); // throws "Invalid rule pack: …" on schema failure
+    return { ...fm, body: m[2] };
+}
+/** Read content/defaults.yaml. */
+export function loadDefaults() {
+    return parseYaml(readFileSync(join(CONTENT_DIR, "defaults.yaml"), "utf8"));
+}
+/** The flattened-rules-doc preamble (everything before the first section). */
+export function loadPreamble() {
+    return readFileSync(join(CONTENT_DIR, "preamble.md"), "utf8");
+}
+/** Read the pack registry, sorted by its `order` field. */
+export function loadPacksIndex() {
+    const parsed = parseYaml(readFileSync(join(RULES_DIR, "packs.index.yaml"), "utf8"));
+    return [...parsed.packs].sort((a, b) => a.order - b.order);
+}
+/** Load a single pack file by its path relative to content/rules. */
+export function loadPack(relPath) {
+    return parseRulePack(readFileSync(join(RULES_DIR, relPath), "utf8"));
+}
+/** Load every pack listed in the index, in index order. */
+export function loadAllPacks() {
+    return loadPacksIndex().map((entry) => ({
+        ...loadPack(entry.path),
+        path: entry.path,
+        order: entry.order,
+    }));
+}
+/** Absolute path to the bundled `content/docs/` directory. */
+export const DOCS_DIR = join(CONTENT_DIR, "docs");
+/** Read content/docs/docs.index.yaml. */
+export function loadDocsIndex() {
+    const parsed = parseYaml(readFileSync(join(DOCS_DIR, "docs.index.yaml"), "utf8"));
+    return parsed.docs;
+}
+/** Names of the pack files physically present under content/rules (for drift checks). */
+export function packFilesOnDisk() {
+    const out = [];
+    const walk = (dir, prefix) => {
+        for (const ent of readdirSync(dir, { withFileTypes: true })) {
+            if (ent.isDirectory())
+                walk(join(dir, ent.name), `${prefix}${ent.name}/`);
+            else if (ent.name.endsWith(".md"))
+                out.push(`${prefix}${ent.name}`);
+        }
+    };
+    walk(RULES_DIR, "");
+    return out.sort();
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * special-agents — the Rafi library. Re-exports the neutral schema, the templating
+ * engine, and the content loaders. The higher-level composition API (getAgent,
+ * getSkill, compile) is layered on these in the rest of Phase 3.
+ */
+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 { 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

@@ -0,0 +1,12 @@
+/**
+ * special-agents — the Rafi library. Re-exports the neutral schema, the templating
+ * engine, and the content loaders. The higher-level composition API (getAgent,
+ * getSkill, compile) is layered on these in the rest of Phase 3.
+ */
+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 { 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/dist/resolve.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pack resolution — turns a role manifest's pack references into an ordered, deduped
+ * list of concrete index entries.
+ *
+ * Reference forms (all `<category>/<name>` or `<category>/*`, matching the manifest
+ * and index layout):
+ *   - `base/core`     → the single pack with that category + name
+ *   - `base/*`        → every pack in that category, in index order
+ *
+ * Resolution is decoupled from `ProjectConfig`: the caller maps project flags onto
+ * the generic {@link ConditionFlags} (ai/frontend/cloud/backend) that gate the
+ * manifest's `conditionalPacks`. Order follows appearance — listed packs first (globs
+ * expanded in index order), then conditional groups in a fixed order — deduped by
+ * first occurrence so authoring intent is preserved deterministically.
+ */
+import type { ConditionalPacks } from "rafi-spec";
+import type { PackIndexEntry } from "./content.js";
+/** Flags that gate `conditionalPacks`. The caller maps project flags onto these. */
+export interface ConditionFlags {
+    ai?: boolean;
+    frontend?: boolean;
+    cloud?: boolean;
+    backend?: boolean;
+}
+export interface ResolveContext {
+    /** Which conditional pack groups to include. */
+    conditions: ConditionFlags;
+    /** When true, packs marked `supersededByForeman` are dropped (foreman owns them). */
+    foremanActive?: boolean;
+}
+/**
+ * Expand and flatten a list of pack refs into ordered, deduped index entries.
+ * Globs expand in index order; duplicates keep their first occurrence.
+ */
+export declare function resolvePackRefs(refs: string[], index: PackIndexEntry[]): PackIndexEntry[];
+/** A manifest's pack-bearing fields (the subset the resolver needs). */
+export interface ResolvableManifest {
+    packs: string[];
+    conditionalPacks?: ConditionalPacks;
+}
+/**
+ * Resolve a role's full pack set: listed `packs` first, then each enabled conditional
+ * group (in {@link CONDITION_ORDER}), deduped by first occurrence. With
+ * `foremanActive`, packs marked `supersededByForeman` are removed.
+ */
+export declare function resolveAgentPacks(manifest: ResolvableManifest, ctx: ResolveContext, index: PackIndexEntry[]): PackIndexEntry[];

package/dist/resolve.js

@@ -0,0 +1,54 @@
+/** Fixed order in which conditional groups are appended after the listed packs. */
+const CONDITION_ORDER = ["ai", "frontend", "cloud", "backend"];
+/** Resolve one ref (`cat/name` or `cat/*`) to its index entries. Throws if unresolved. */
+function resolveOneRef(ref, index) {
+    const slash = ref.indexOf("/");
+    if (slash === -1)
+        throw new Error(`malformed pack ref (expected category/name): ${ref}`);
+    const category = ref.slice(0, slash);
+    const rest = ref.slice(slash + 1);
+    if (rest === "*") {
+        const matches = index.filter((e) => e.category === category);
+        if (matches.length === 0)
+            throw new Error(`no packs match glob: ${ref}`);
+        return matches;
+    }
+    const match = index.find((e) => e.category === category && e.name === rest);
+    if (!match)
+        throw new Error(`unknown pack ref: ${ref}`);
+    return [match];
+}
+/**
+ * Expand and flatten a list of pack refs into ordered, deduped index entries.
+ * Globs expand in index order; duplicates keep their first occurrence.
+ */
+export function resolvePackRefs(refs, index) {
+    const out = [];
+    const seen = new Set();
+    for (const ref of refs) {
+        for (const entry of resolveOneRef(ref, index)) {
+            if (seen.has(entry.name))
+                continue;
+            seen.add(entry.name);
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/**
+ * Resolve a role's full pack set: listed `packs` first, then each enabled conditional
+ * group (in {@link CONDITION_ORDER}), deduped by first occurrence. With
+ * `foremanActive`, packs marked `supersededByForeman` are removed.
+ */
+export function resolveAgentPacks(manifest, ctx, index) {
+    const refs = [...manifest.packs];
+    const conditional = manifest.conditionalPacks ?? {};
+    for (const key of CONDITION_ORDER) {
+        if (ctx.conditions[key])
+            refs.push(...(conditional[key] ?? []));
+    }
+    let resolved = resolvePackRefs(refs, index);
+    if (ctx.foremanActive)
+        resolved = resolved.filter((e) => !e.supersededByForeman);
+    return resolved;
+}

package/dist/skills.d.ts

@@ -0,0 +1,11 @@
+import { type SkillManifest } from "rafi-spec";
+/** Absolute path to the bundled `content/skills/` directory. */
+export declare const SKILLS_DIR: string;
+/** Parse a SKILL.md string into its validated front-matter + body. */
+export declare function parseSkillManifest(raw: string): SkillManifest;
+/** Directory names of every bundled skill, sorted. */
+export declare function skillNames(): string[];
+/** Load a single skill by its directory name. */
+export declare function loadSkill(name: string): SkillManifest;
+/** Load every bundled skill, in directory-name order. */
+export declare function loadAllSkills(): SkillManifest[];

package/dist/skills.js

@@ -0,0 +1,45 @@
+/**
+ * Skill loader. Reads `content/skills/<name>/SKILL.md` units — the standard
+ * Anthropic format plus the optional Rafi `pins` / `codexPriority` fields. A pure
+ * `parseSkillManifest` (string → SkillManifest) is split from the directory walk so
+ * the parse rules are unit-tested without disk.
+ */
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { assertSkillManifest } from "rafi-spec";
+import { CONTENT_DIR } from "./content.js";
+/** Absolute path to the bundled `content/skills/` directory. */
+export const SKILLS_DIR = join(CONTENT_DIR, "skills");
+const FRONT_MATTER = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+/** Parse a SKILL.md string into its validated front-matter + body. */
+export function parseSkillManifest(raw) {
+    const m = raw.match(FRONT_MATTER);
+    if (!m)
+        throw new Error("skill is missing front-matter");
+    const fm = parseYaml(m[1]);
+    assertSkillManifest(fm); // throws "Invalid skill manifest: …"
+    return { ...fm, body: m[2] };
+}
+/** Directory names of every bundled skill, sorted. */
+export function skillNames() {
+    return readdirSync(SKILLS_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(join(SKILLS_DIR, e.name, "SKILL.md")))
+        .map((e) => e.name)
+        .sort();
+}
+/** Load a single skill by its directory name. */
+export function loadSkill(name) {
+    const path = join(SKILLS_DIR, name, "SKILL.md");
+    if (!existsSync(path))
+        throw new Error(`unknown skill: ${name}`);
+    const skill = parseSkillManifest(readFileSync(path, "utf8"));
+    if (skill.name !== name) {
+        throw new Error(`skill ${name}: manifest name "${skill.name}" does not match its directory`);
+    }
+    return skill;
+}
+/** Load every bundled skill, in directory-name order. */
+export function loadAllSkills() {
+    return skillNames().map(loadSkill);
+}

package/dist/template.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+/** Values available to the engine for one render. */
+export interface TemplateContext {
+    /** `{{key}}` substitutions (e.g. the resolved `stack.*` strings). */
+    vars: Record<string, string>;
+    /** Booleans gating `{{#if flag}}…{{/if}}` blocks (e.g. `hasFrontend`). */
+    flags: Record<string, boolean>;
+}
+/** Render a template string against the given context. Throws on unknown var/flag. */
+export declare function render(template: string, ctx: TemplateContext): string;