special-agents 0.3.6 → 0.4.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!) The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -2,7 +2,7 @@
 
 29 composable best-practice rule packs, 6 skills, and 4 agent roles for Claude Code and Codex.
 
-The content layer of [Rafi](https://github.com/ttante/foreman). Ships both the authoring source (`content/`) and prebuilt composition logic so it can be used as a library, consumed by `rafi compile`, or extended directly.
+The content layer of [Rafi](https://github.com/ttante/rafi). Ships both the authoring source (`content/`) and prebuilt composition logic so it can be used as a library, consumed by `rafi compile`, or extended directly.
 
 ## Install
 
@@ -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;
 }
 /**