special-agents 0.1.0

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

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

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

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "special-agents",
+  "version": "0.1.0",
+  "description": "Rafi library: composable best-practice rules, skills, and agents for Claude Code and Codex.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "content",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bundledDependencies": [
+    "rafi-spec"
+  ],
+  "dependencies": {
+    "yaml": "^2.5.1",
+    "rafi-spec": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts"
+  }
+}