special-agents 0.3.7 → 0.4.0

package/README.md

@@ -40,7 +40,7 @@ emitCompiledBundles("./my-repo", {
 
 ## Rule packs
 
-29 packs across four categories. Conditional packs are only included when the matching flag is on.
+30 packs across four categories. Conditional packs are only included when the matching flag is on.
 
 | Category | Packs | Condition |
 |---|---|---|

package/content/docs/features.md

@@ -35,7 +35,6 @@ Use this document to track what the app does, who can use each feature, and what
 
 ## Future Ideas
 
-Add future ideas to `docs/tickets.md`; summarize only major themes here.
+Add future ideas to `{{docsRoot}}/tickets.md`; summarize only major themes here.
 
 - `<idea/theme>`
-

package/content/rules/domain/ai-cost.md

@@ -3,19 +3,19 @@ name: ai-cost
 category: domain
 description: "AI cost tracking and the correction/learning loop."
 condition: ai
-template: false
+template: true
 ---
 ## AI Cost Tracking And Learning Loop
 
 - Include cost tracking throughout AI usage.
 - Track cost per task for AI generations, including tokens, model/provider, retries, tool calls, retrieval, latency, and final success/failure status where available.
 - Track other app operations that may create significant cost early or at scale, including cloud resources, queues, storage, external APIs, email/SMS, analytics, and heavy database workloads.
-- Keep AI cost tracking and optimization notes updated in `docs/ai-costs.md`.
+- Keep AI cost tracking and optimization notes updated in `{{docsRoot}}/ai-costs.md`.
 - Record results of AI generation steps when appropriate so the project can learn from successes and failures.
 - Plan a correction workflow for failed generations: generate suggested corrections, run QA on corrections, and record approved corrections with the failed generation.
 - Auto-approve corrections only when correction and QA confidence are both very high and the risk level allows it.
 - Require admin approval for lower-confidence, high-risk, or ambiguous corrections.
 - Preserve approved corrections and failed generations in a structured format that could support future fine-tuning, evals, or custom model training.
-- Document the journey toward custom model training in `docs/ai.md`, including data requirements, quality thresholds, privacy constraints, retention rules, estimated cost, and when training is worth it.
+- Document the journey toward custom model training in `{{docsRoot}}/ai.md`, including data requirements, quality thresholds, privacy constraints, retention rules, estimated cost, and when training is worth it.
 - During planning, consult the user about the AI learning-loop and custom-training approach. If the full setup would be too cumbersome or data-heavy, recommend a lighter approach.
 

package/content/rules/domain/ai-evals.md

@@ -3,7 +3,7 @@ name: ai-evals
 category: domain
 description: "Quality gates, confidence, evals, and examples for AI."
 condition: ai
-template: false
+template: true
 ---
 ## AI Quality, Confidence, And Evals
 
@@ -28,7 +28,7 @@ template: false
 
 ### Eval Suites
 
-- Keep AI eval suites, golden examples, adversarial cases, and regression results updated in `docs/ai-evals.md`.
+- Keep AI eval suites, golden examples, adversarial cases, and regression results updated in `{{docsRoot}}/ai-evals.md`.
 - Maintain eval sets that cover: correct common cases, edge cases, known failure modes, adversarial inputs, and cases drawn from corrected production failures.
 - Track AI failures, correction rates, confidence levels, approval outcomes, and quality trends.
 - Promote prompt, parameter, or model changes only when required eval suites meet documented thresholds, or document the explicit user-approved reason for accepting the risk.

package/content/rules/domain/ai-governance.md

@@ -3,7 +3,7 @@ name: ai-governance
 category: domain
 description: "Model/provider and dataset governance."
 condition: ai
-template: false
+template: true
 ---
 ## AI Model And Dataset Governance
 
@@ -12,5 +12,5 @@ template: false
 - Document dataset sources, consent, labeling process, quality thresholds, retention, access controls, and whether data may be used for evals, fine-tuning, or custom model training.
 - Keep training/eval datasets versioned where practical.
 - Do not use customer/user data for model training unless the data policy, consent, retention, security, and approval requirements are documented.
-- Document model and dataset governance in `docs/ai.md` and `docs/data-governance.md`.
+- Document model and dataset governance in `{{docsRoot}}/ai.md` and `{{docsRoot}}/data-governance.md`.
 

package/content/rules/domain/ai-safety.md

@@ -3,7 +3,7 @@ name: ai-safety
 category: domain
 description: "Adversarial safety and abuse protection for AI features."
 condition: ai
-template: false
+template: true
 ---
 ## AI And LLM Safety
 
@@ -15,5 +15,5 @@ template: false
 - Add AI abuse monitoring for suspicious prompts, repeated failures, high-cost usage, policy violations, and unusual generation patterns.
 - Red-team AI features with prompt injection, jailbreak, data leakage, unsafe action, tool misuse, and cost-abuse cases before high-risk releases.
 - Maintain an AI incident plan for harmful, wrong, private, expensive, abusive, or policy-violating outputs.
-- Document AI safety controls, known risks, and escalation paths in `docs/ai.md` and `docs/operations.md`.
+- Document AI safety controls, known risks, and escalation paths in `{{docsRoot}}/ai.md` and `{{docsRoot}}/operations.md`.
 

package/content/rules/domain/data-governance.md

@@ -3,7 +3,7 @@ name: data-governance
 category: domain
 description: "Data classification, retention, consent, and PII handling."
 condition: always
-template: false
+template: true
 ---
 ## Data Governance
 
@@ -13,5 +13,5 @@ template: false
 - Document consent requirements for user data, analytics, AI replay logs, eval datasets, and future model training.
 - Use access controls for sensitive data and audit access where risk warrants it.
 - Redact or tokenize PII and secrets before storing prompts, outputs, logs, traces, eval cases, or replay data unless explicitly approved and protected.
-- Keep data-governance rules current in `docs/data-governance.md`.
+- Keep data-governance rules current in `{{docsRoot}}/data-governance.md`.
 

package/content/rules/domain/observability.md

@@ -3,7 +3,7 @@ name: observability
 category: domain
 description: "Logging, metrics, dashboards, runbooks, and AI observability."
 condition: always
-template: false
+template: true
 ---
 ## Observability And Operations
 
@@ -12,7 +12,7 @@ template: false
 - Build visible status tracking for key workflows so users, admins, and operators can understand progress, failures, retries, and completion state.
 - Add detailed observability for AI generation flows, including generation stages, model calls, retries, validation results, confidence, cost, latency, and approval status.
 - Avoid logging secrets or sensitive user data.
-- Document operational risks, runbooks, cost drivers, and monitoring expectations in `docs/operations.md`, `docs/business.md`, or `docs/architecture.md` as appropriate.
+- Document operational risks, runbooks, cost drivers, and monitoring expectations in `{{docsRoot}}/operations.md`, `{{docsRoot}}/business.md`, or `{{docsRoot}}/architecture.md` as appropriate.
 - Maintain runbooks for common production failures and manual recovery steps.
 - For new background jobs, queues, cron tasks, or integrations, document retry behavior, failure modes, and manual recovery steps.
 

package/content/rules/domain/scalability.md

@@ -3,7 +3,7 @@ name: scalability
 category: domain
 description: "Scaling strategy across server, cloud, AI, frontend, and data."
 condition: always
-template: false
+template: true
 ---
 ## Scalability And Performance
 
@@ -14,5 +14,5 @@ template: false
 - For frontend work, watch bundle size, rendering cost, loading states, network waterfalls, and mobile performance.
 - For cloud infrastructure, document scaling assumptions, capacity limits, deployment topology, regions, managed services, and expected bottlenecks.
 - For AI/model usage, plan for provider limits, latency, concurrency, queueing, fallback behavior, cost controls, and model upgrade paths.
-- Document meaningful scalability assumptions and known limits in `docs/scalability.md`.
+- Document meaningful scalability assumptions and known limits in `{{docsRoot}}/scalability.md`.
 

package/content/rules/packs.index.yaml

@@ -22,13 +22,13 @@ packs:
     category: process
     path: process/project-docs.md
     condition: always
-    template: false
+    template: true
     order: 4000
   - name: tickets
     category: process
     path: process/tickets.md
     condition: always
-    template: false
+    template: true
     supersededByForeman: true
     order: 5000
   - name: tdd
@@ -71,7 +71,7 @@ packs:
     category: domain
     path: domain/scalability.md
     condition: always
-    template: false
+    template: true
     order: 12000
   - name: infra
     category: templated
@@ -89,7 +89,7 @@ packs:
     category: domain
     path: domain/data-governance.md
     condition: always
-    template: false
+    template: true
     order: 15000
   - name: security
     category: domain
@@ -101,13 +101,13 @@ packs:
     category: domain
     path: domain/ai-safety.md
     condition: ai
-    template: false
+    template: true
     order: 17000
   - name: ai-governance
     category: domain
     path: domain/ai-governance.md
     condition: ai
-    template: false
+    template: true
     order: 18000
   - name: robustness
     category: domain
@@ -119,7 +119,7 @@ packs:
     category: domain
     path: domain/ai-evals.md
     condition: ai
-    template: false
+    template: true
     order: 20000
   - name: ai-reproducibility
     category: domain
@@ -131,7 +131,7 @@ packs:
     category: domain
     path: domain/ai-cost.md
     condition: ai
-    template: false
+    template: true
     order: 22000
   - name: ai-batch-testing
     category: domain
@@ -143,7 +143,7 @@ packs:
     category: process
     path: process/release.md
     condition: always
-    template: false
+    template: true
     order: 24000
   - name: accessibility
     category: domain
@@ -155,19 +155,19 @@ packs:
     category: domain
     path: domain/observability.md
     condition: always
-    template: false
+    template: true
     order: 26000
   - name: business-docs
     category: process
     path: process/business-docs.md
     condition: always
-    template: false
+    template: true
     order: 27000
   - name: architecture
     category: process
     path: process/architecture.md
     condition: always
-    template: false
+    template: true
     order: 28000
   - name: definition-of-done
     category: base

package/content/rules/process/architecture.md

@@ -3,12 +3,12 @@ name: architecture
 category: process
 description: "Architecture digest and ADR/decision-history discipline."
 condition: always
-template: false
+template: true
 ---
 ## Architecture And Decisions
 
-- Keep `docs/architecture.md` as a digest of how the app works now.
-- Add ADRs in `docs/decisions/` for choices that will matter later, including stack changes, major dependencies, database design, auth model, billing model, hosting, integrations, and AI/provider choices.
-- Keep `docs/decisions/README.md` updated as the decision-making history index.
+- Keep `{{docsRoot}}/architecture.md` as a digest of how the app works now.
+- Add ADRs in `{{docsRoot}}/decisions/` for choices that will matter later, including stack changes, major dependencies, database design, auth model, billing model, hosting, integrations, and AI/provider choices.
+- Keep `{{docsRoot}}/decisions/README.md` updated as the decision-making history index.
 - ADRs should be short: context, decision, alternatives considered, consequences, date.
 

package/content/rules/process/business-docs.md

@@ -3,11 +3,11 @@ name: business-docs
 category: process
 description: "Keep business assumptions, costs, and risks current."
 condition: always
-template: false
+template: true
 ---
 ## Business Documentation
 
-- Keep `docs/business.md` current with product assumptions, cost drivers, vendor/service pricing notes, revenue/pricing ideas, operational risks, and open business questions.
+- Keep `{{docsRoot}}/business.md` current with product assumptions, cost drivers, vendor/service pricing notes, revenue/pricing ideas, operational risks, and open business questions.
 - When a change affects cost, pricing, packaging, user roles, admin effort, compliance, support load, AI/model usage, or operational complexity, update the business docs.
 - If exact pricing or costs require current external information, verify them before documenting.
 

package/content/rules/process/project-docs.md

@@ -3,31 +3,31 @@ name: project-docs
 category: process
 description: "The standard set of project documents to create and maintain."
 condition: always
-template: false
+template: true
 ---
 ## Standard Project Documents
 
 Create and maintain these documents unless the repository has equivalent files:
 
 - `README.md`: developer install, setup, environment variables, run, test, build, and deploy basics.
-- `docs/architecture.md`: architecture digest, major modules, data flow, integrations, infrastructure, and tradeoffs.
-- `docs/features.md`: feature digest, user-facing capabilities, roles, permissions, and important workflows.
-- `docs/api.md` or generated API docs: API overview and links to OpenAPI, Swagger, JSDoc, Typedoc, or equivalent generated references.
-- `docs/users.md`: normal user documentation.
-- `docs/admins.md`: admin/operator documentation.
-- `docs/business.md`: business-level notes, feature rationale, pricing/costs, vendor costs, risk areas, operational concerns, and things to watch.
-- `docs/operations.md`: deployment notes, monitoring, runbooks, incident response, backups, and recovery steps.
-- `docs/security.md`: security model, threat model, auth, permissions, secrets, abuse controls, and incident response.
-- `docs/data-governance.md`: data classification, PII handling, retention, deletion/export, consent, and training-data rules.
-- `docs/local-cloud.md`: local runtime, cloud runtime, parity expectations, environment differences, and deployment notes.
-- `docs/scalability.md`: scaling strategy for server, cloud, AI/model usage, frontend, databases, and overall architecture.
-- `docs/ai.md`: AI workflows, model/provider choices, prompts, evals, safety controls, cost tracking, replayability, and training-data strategy when the app uses AI.
-- `docs/ai-evals.md`: AI eval suites, golden examples, adversarial cases, quality gates, and prompt/model regression results.
-- `docs/ai-costs.md`: AI cost tracking, cost per task, provider/model costs, high-cost workflows, and optimization notes.
-- `docs/tickets.md`: ticket log, roadmap, backlog, status, acceptance criteria, and future ideas.
-- `docs/decisions/`: ADRs and decision history for meaningful architecture, product, data, vendor, AI, or cost decisions.
-- `docs/decisions/README.md`: decision-making history index with links to ADRs and a short status summary.
-- `docs/release-checklist.md`: release readiness, versioning, migrations, rollback, smoke tests, and post-release checks.
+- `{{docsRoot}}/architecture.md`: architecture digest, major modules, data flow, integrations, infrastructure, and tradeoffs.
+- `{{docsRoot}}/features.md`: feature digest, user-facing capabilities, roles, permissions, and important workflows.
+- `{{docsRoot}}/api.md` or generated API docs: API overview and links to OpenAPI, Swagger, JSDoc, Typedoc, or equivalent generated references.
+- `{{docsRoot}}/users.md`: normal user documentation.
+- `{{docsRoot}}/admins.md`: admin/operator documentation.
+- `{{docsRoot}}/business.md`: business-level notes, feature rationale, pricing/costs, vendor costs, risk areas, operational concerns, and things to watch.
+- `{{docsRoot}}/operations.md`: deployment notes, monitoring, runbooks, incident response, backups, and recovery steps.
+- `{{docsRoot}}/security.md`: security model, threat model, auth, permissions, secrets, abuse controls, and incident response.
+- `{{docsRoot}}/data-governance.md`: data classification, PII handling, retention, deletion/export, consent, and training-data rules.
+- `{{docsRoot}}/local-cloud.md`: local runtime, cloud runtime, parity expectations, environment differences, and deployment notes.
+- `{{docsRoot}}/scalability.md`: scaling strategy for server, cloud, AI/model usage, frontend, databases, and overall architecture.
+- `{{docsRoot}}/ai.md`: AI workflows, model/provider choices, prompts, evals, safety controls, cost tracking, replayability, and training-data strategy when the app uses AI.
+- `{{docsRoot}}/ai-evals.md`: AI eval suites, golden examples, adversarial cases, quality gates, and prompt/model regression results.
+- `{{docsRoot}}/ai-costs.md`: AI cost tracking, cost per task, provider/model costs, high-cost workflows, and optimization notes.
+- `{{docsRoot}}/tickets.md`: ticket log, roadmap, backlog, status, acceptance criteria, and future ideas.
+- `{{docsRoot}}/decisions/`: ADRs and decision history for meaningful architecture, product, data, vendor, AI, or cost decisions.
+- `{{docsRoot}}/decisions/README.md`: decision-making history index with links to ADRs and a short status summary.
+- `{{docsRoot}}/release-checklist.md`: release readiness, versioning, migrations, rollback, smoke tests, and post-release checks.
 - `CHANGELOG.md`: notable user-facing, API, migration, and operational changes.
 - `.env.example`: documented environment variables with safe placeholder values.
 

package/content/rules/process/release.md

@@ -3,14 +3,14 @@ name: release
 category: process
 description: "Changelog, semver, release checklist, and post-release notes."
 condition: always
-template: false
+template: true
 ---
 ## Release, Versioning, And Change Management
 
 - Maintain `CHANGELOG.md` for notable user-facing, API, migration, security, AI/model, and operational changes.
 - Use semantic versioning where it applies to published apps, APIs, packages, SDKs, or user-visible releases.
 - Document breaking changes, deprecations, migration steps, rollback steps, and user/admin impact.
-- Use `docs/release-checklist.md` before releases that affect users, production data, public APIs, infrastructure, billing, auth, or AI behavior.
+- Use `{{docsRoot}}/release-checklist.md` before releases that affect users, production data, public APIs, infrastructure, billing, auth, or AI behavior.
 - Include smoke tests, monitoring checks, migration checks, environment-variable checks, documentation updates, and rollback readiness in release planning.
 - After release, document incidents, regressions, follow-up work, and any release-process improvements.
 

package/content/rules/process/tickets.md

@@ -3,12 +3,12 @@ name: tickets
 category: process
 description: "Ticket log expectations when no external tracker is configured."
 condition: always
-template: false
+template: true
 supersededByForeman: true
 ---
 ## Ticket Tracking
 
-- Maintain `docs/tickets.md` as the source of truth if no external tracker is configured.
+- Maintain `{{docsRoot}}/tickets.md` as the source of truth if no external tracker is configured.
 - Break work into epics, stories, and implementation tickets where useful.
 - Every ticket should include: ID, title, status, priority, user/business value, acceptance criteria, implementation notes, test expectations, and links to related docs or code when available.
 - Valid statuses: `Backlog`, `Ready`, `In Progress`, `Blocked`, `In Review`, `Done`, `Won't Do`.

package/content/rules/templated/database.md

@@ -12,5 +12,5 @@ template: true
 - Keep migrations reviewable and, where practical, reversible.
 - Update seed data, fixtures, and `.env.example` when schema or setup requirements change.
 - Validate data at system boundaries and before persistence.
-- Document important entities and relationships in `docs/architecture.md`.
+- Document important entities and relationships in `{{docsRoot}}/architecture.md`.
 

package/content/rules/templated/infra.md

@@ -13,6 +13,6 @@ template: true
 - Keep `.env.example`, setup docs, seed data, and local database instructions current.
 - Define cloud infrastructure with Infrastructure as Code such as AWS CDK, Terraform, Pulumi, or CloudFormation unless there is a documented reason not to.
 - Avoid manual cloud console changes for durable infrastructure. If manual changes are unavoidable, document them and add follow-up work to codify them.
-- Document {{cloud}} account/region assumptions, IAM model, networking, secrets, storage, databases, queues, observability, and deployment flow in `docs/local-cloud.md`, `docs/architecture.md`, or `docs/operations.md`.
+- Document {{cloud}} account/region assumptions, IAM model, networking, secrets, storage, databases, queues, observability, and deployment flow in `{{docsRoot}}/local-cloud.md`, `{{docsRoot}}/architecture.md`, or `{{docsRoot}}/operations.md`.
 - Consult the user when local/cloud runtime expectations, hosting constraints, or infrastructure ownership are unclear.
 

package/dist/compile.d.ts

@@ -53,7 +53,7 @@ export declare function buildConditionsHeader(flags: {
     usesAI: boolean;
     hasFrontend: boolean;
     runsInCloud: boolean;
-}): string;
+}, docsRoot?: string): string;
 /**
  * Write `<targetDir>/AGENTS.md` — the flattened Codex rules document.
  * Format: one-line conditions header + preamble + all packs rendered with defaults.

package/dist/compile.js

@@ -19,7 +19,10 @@ 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 });
+    return render(pack.body, {
+        vars: { ...defaults.stack, docsRoot: defaults.docsRoot ?? "docs" },
+        flags: defaults.flags,
+    });
 }
 /**
  * The full flattened rules doc: preamble + all packs (index order), rendered.
@@ -61,10 +64,11 @@ export function getAgent(role, opts = {}) {
  * are active. Written at the top of `AGENTS.md` and `CLAUDE.md` so the choice
  * is never invisible.
  */
-export function buildConditionsHeader(flags) {
+export function buildConditionsHeader(flags, docsRoot = "docs") {
     return (`# rafi: ai=${flags.usesAI ? "on" : "off"}` +
         ` frontend=${flags.hasFrontend ? "on" : "off"}` +
-        ` cloud=${flags.runsInCloud ? "on" : "off"}\n`);
+        ` cloud=${flags.runsInCloud ? "on" : "off"}` +
+        ` docs=${docsRoot}\n`);
 }
 /**
  * Write `<targetDir>/AGENTS.md` — the flattened Codex rules document.
@@ -81,12 +85,12 @@ export function emitClaudeMd(targetDir, opts = {}) {
 }
 export function renderAgentsMd(opts = {}) {
     const defaults = opts.defaults ?? loadDefaults();
-    const header = buildConditionsHeader(defaults.flags);
+    const header = buildConditionsHeader(defaults.flags, defaults.docsRoot ?? "docs");
     return header + composeRulesMarkdown({ defaults });
 }
 export function renderClaudeMd(opts = {}) {
     const defaults = opts.defaults ?? loadDefaults();
-    const header = buildConditionsHeader(defaults.flags);
+    const header = buildConditionsHeader(defaults.flags, defaults.docsRoot ?? "docs");
     return header + "@AGENTS.md\n\n" + CUSTOM_ARTIFACTS_NOTE;
 }
 /**

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,6 +1,6 @@
 {
   "name": "special-agents",
-  "version": "0.3.7",
+  "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",
@@ -36,7 +36,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "rafi-spec": "0.3.7",
+    "rafi-spec": "0.4.0",
     "ajv": "^8.20.0",
     "yaml": "^2.5.1"
   },