special-agents 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# special-agents
+
+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.
+
+## Install
+
+```sh
+npm install special-agents
+```
+
+## Usage
+
+```ts
+import { getAgent, getSkill, emitCompiledBundles } from "special-agents";
+
+// Get a composed role bundle (system prompt + skills list)
+const { system, skills } = getAgent("builder");
+// system → assembled prompt with all applicable rule packs rendered
+// skills → ["tdd", "improve-codebase-architecture"]
+
+// Write compiled role bundles + AGENTS.md + CLAUDE.md to a target repo
+emitCompiledBundles("./my-repo", {
+  defaults: {
+    stack: { frontend: "React", backend: "Node.js", database: "PostgreSQL", cloud: "AWS", packageManager: "pnpm" },
+    flags:  { usesAI: false, hasFrontend: true, runsInCloud: true },
+  },
+});
+```
+
+## Roles
+
+| Role | Description |
+|---|---|
+| `builder` | Implements one ticket/step per turn |
+| `qa` | Reviews and verifies completed work |
+| `planner` | Produces the project plan and ticket list |
+| `ticket-maker` | Converts requirements into structured tickets |
+
+## Rule packs
+
+29 packs across four categories. Conditional packs are only included when the matching flag is on.
+
+| Category | Packs | Condition |
+|---|---|---|
+| base | core, git-safety, code-quality, definition-of-done, response-expectations | always |
+| process | testing, tdd, ci, tickets, api-docs, release, dependencies, architecture, project-docs, business-docs | always |
+| domain | security, robustness, scalability, observability, data-governance | always |
+| domain | accessibility | `hasFrontend` |
+| domain | ai-safety, ai-governance, ai-evals, ai-reproducibility, ai-cost | `usesAI` |
+| templated | stack, database, infra | always / `runsInCloud` |
+
+## Content structure
+
+```
+content/
+  rules/         rule packs (base/, process/, domain/, templated/)
+  skills/        SKILL.md units (tdd, grill-me, improve-codebase-architecture, ...)
+  agents/        role manifests (builder, qa, planner, ticket-maker .yaml)
+  docs/          starter doc templates for new repos
+  defaults.yaml  default stack values
+```
+
+## Part of Rafi
+
+- **`special-agents`** — this library
+- **`ai-foreman`** — runtime that drives agents through a ticket loop
+- **`@rafi-ai/cli`** — CLI for `rafi create` and `rafi compile`

package/content/agents/builder.yaml

@@ -0,0 +1,25 @@
+name: builder
+description: Implements one ticket or step per turn, test-first, to a senior standard.
+role: builder
+packs:
+  - base/*
+  - process/tdd
+  - process/testing
+  - process/api-docs
+  - domain/security
+  - domain/robustness
+  - templated/*
+skills:
+  - tdd
+  - improve-codebase-architecture
+conditionalPacks:
+  ai:
+    - domain/ai-safety
+    - domain/ai-evals
+    - domain/ai-cost
+    - domain/ai-reproducibility
+    - domain/ai-governance
+  frontend:
+    - domain/accessibility
+model: null
+effort: null

package/content/agents/planner.yaml

@@ -0,0 +1,13 @@
+name: planner
+description: Plans the next N tickets or steps before any implementation. Outputs an ordered list, implements nothing.
+role: planner
+packs:
+  - base/*
+  - process/architecture
+  - process/tickets
+  - process/project-docs
+skills:
+  - write-a-prd
+  - prd-to-issues
+model: null
+effort: null

package/content/agents/qa.yaml

@@ -0,0 +1,16 @@
+name: qa
+description: Reviews the just-completed ticket or step for accuracy, tests, and security. Skeptical, not a rubber stamp.
+role: qa
+packs:
+  - base/*
+  - process/tdd
+  - process/testing
+  - domain/security
+skills:
+  - grill-me
+  - tdd
+conditionalPacks:
+  frontend:
+    - domain/accessibility
+model: null
+effort: null

package/content/agents/ticket-maker.yaml

@@ -0,0 +1,11 @@
+name: ticket-maker
+description: Populates the ticket backlog with well-formed tickets (ID, value, acceptance criteria, test expectations); asks the user for format/style preferences.
+role: ticket-maker
+packs:
+  - base/*
+  - process/tickets
+  - process/project-docs
+  - process/architecture
+skills: []
+model: null
+effort: null

package/content/defaults.yaml

@@ -0,0 +1,13 @@
+# Default stack values + flags. These reproduce the original hardcoded rules.md
+# guidance: rendering the templated packs with these defaults equals the source.
+# `rafi create` writes a project.yaml that overrides these per project.
+stack:
+  frontend: "React with TypeScript"
+  backend: "Node.js, Python, or both, based on the project needs"
+  database: "PostgreSQL"
+  cloud: "AWS"
+  packageManager: "pnpm"
+flags:
+  hasFrontend: true
+  usesAI: false
+  runsInCloud: true

package/content/docs/README.md

@@ -0,0 +1,42 @@
+# Starter Documentation Templates
+
+Copy these files into new app repos when bootstrapping AI-agent-friendly project documentation.
+
+## Baseline Templates
+
+Use these for most application repos:
+
+- `architecture.md`: system overview, modules, integrations, tradeoffs, and architecture digest.
+- `features.md`: user-facing capabilities, roles, permissions, and workflows.
+- `api.md`: API documentation index and contract notes.
+- `users.md`: normal user documentation.
+- `admins.md`: admin/operator documentation.
+- `business.md`: costs, pricing, product assumptions, risks, and business notes.
+- `operations.md`: deployment, monitoring, incidents, backups, and runbooks.
+- `security.md`: auth, permissions, threat model, secrets, abuse controls, and incident response.
+- `data-governance.md`: PII, consent, retention, exports, deletion, and training/eval data rules.
+- `local-cloud.md`: local and cloud runtime paths, parity, and environment differences.
+- `scalability.md`: scaling plan for server, cloud, frontend, databases, AI/model usage, and architecture.
+- `tickets.md`: ticket log, roadmap, backlog, status, acceptance criteria, and future ideas.
+- `release-checklist.md`: release readiness, smoke tests, migrations, rollback, and post-release checks.
+- `decisions/README.md`: ADR index and decision history.
+- `decisions/0000-template.md`: reusable ADR template.
+
+## AI Templates
+
+Use these when the app includes LLMs, AI generation, model calls, AI-assisted decisions, or future model-training plans:
+
+- `ai.md`: AI workflows, models, prompts, safety controls, replayability, and training-data strategy.
+- `ai-evals.md`: eval suites, golden examples, adversarial cases, quality gates, and regression results.
+- `ai-costs.md`: AI cost per task, provider/model spend, high-cost workflows, and optimization notes.
+
+## Usage
+
+The easiest path is the `rafi` CLI:
+
+```sh
+rafi create /path/to/new-repo
+```
+
+By default, `rafi create` skips doc files that already exist. Use `--force` to overwrite existing files.
+

package/content/docs/admins.md

@@ -0,0 +1,46 @@
+# Admin And Operator Guide
+
+Use this document for admin, support, and operator workflows.
+
+## Audience
+
+- Admin roles:
+- Operator roles:
+- Last reviewed:
+
+## Admin Capabilities
+
+| Capability | Role Required | Risk Level | Audit Logged? | Notes |
+|---|---|---|---|---|
+| `<capability>` | `<role>` | `<low/medium/high>` | `<yes/no>` | `<notes>` |
+
+## Common Admin Workflows
+
+### `<Workflow Name>`
+
+- Goal:
+- Required role:
+- Steps:
+- Verification:
+- Rollback/recovery:
+
+## User And Permission Management
+
+- Invite users:
+- Change roles:
+- Disable users:
+- Review access:
+
+## Operational Tasks
+
+- Data export:
+- Billing/support actions:
+- Background job actions:
+- Manual recovery steps:
+
+## Audit And Compliance
+
+- Audit log location:
+- Sensitive actions:
+- Review cadence:
+

package/content/docs/ai-costs.md

@@ -0,0 +1,38 @@
+# AI Cost Tracking
+
+Use this document to track AI cost per task, model/provider spend, high-cost workflows, and cost optimization notes.
+
+## Cost Strategy
+
+- Cost owner:
+- Monthly budget target:
+- Alert threshold:
+- Primary cost drivers:
+- Last reviewed:
+
+## Cost Per AI Task
+
+| Task | Workflow | Provider | Model | Avg Input Tokens | Avg Output Tokens | Avg Retries | Avg Cost | Target Cost | Notes |
+|---|---|---|---|---:|---:|---:|---:|---:|---|
+| `<task>` | `<workflow>` | `<provider>` | `<model>` | `<tokens>` | `<tokens>` | `<count>` | `<cost>` | `<cost>` | `<notes>` |
+
+## High-Cost App Operations
+
+Track non-AI costs that may become significant early or at scale.
+
+| Operation | Cost Source | Cost Driver | Current Estimate | Scale Risk | Mitigation |
+|---|---|---|---:|---|---|
+| `<operation>` | `<cloud/api/storage/email/sms/db/etc>` | `<driver>` | `<estimate>` | `<low/medium/high>` | `<plan>` |
+
+## Cost Events
+
+| Date | Event | Impact | Root Cause | Fix | Follow-Up Ticket |
+|---|---|---|---|---|---|
+| `<date>` | `<event>` | `<cost impact>` | `<cause>` | `<fix>` | `<ticket>` |
+
+## Optimization Ideas
+
+| Idea | Area | Expected Savings | Risk | Status | Ticket |
+|---|---|---:|---|---|---|
+| `<idea>` | `<workflow>` | `<estimate>` | `<risk>` | `<status>` | `<ticket>` |
+

package/content/docs/ai-evals.md

@@ -0,0 +1,55 @@
+# AI Eval Log
+
+Use this document to track AI quality gates, eval sets, golden examples, adversarial cases, and prompt/model regression results.
+
+## Eval Strategy
+
+- Primary AI workflows covered:
+- Quality goals:
+- Minimum passing threshold:
+- Human review requirements:
+- Regression policy:
+- Prompt/model promotion policy:
+- Last reviewed:
+
+## Eval Suites
+
+| Eval Suite | Workflow | Purpose | Cases | Passing Threshold | Owner | Status |
+|---|---|---|---:|---|---|---|
+| `<suite>` | `<workflow>` | `<purpose>` | `<count>` | `<threshold>` | `<owner>` | `<planned/live>` |
+
+## Golden Examples
+
+Golden examples are correct or top-quality examples that represent desired output.
+
+| Example ID | Workflow | Input Summary | Expected Output Summary | Why It Matters | Status |
+|---|---|---|---|---|---|
+| `<example-id>` | `<workflow>` | `<input>` | `<output>` | `<reason>` | `<active>` |
+
+## Edge And Failure Cases
+
+| Case ID | Workflow | Scenario | Expected Handling | Risk | Status |
+|---|---|---|---|---|---|
+| `<case-id>` | `<workflow>` | `<scenario>` | `<behavior>` | `<low/medium/high>` | `<active>` |
+
+## Adversarial Cases
+
+| Case ID | Attack Type | Input Summary | Expected Defense | Status |
+|---|---|---|---|---|
+| `<case-id>` | `<prompt injection/jailbreak/data exfiltration/tool misuse>` | `<input>` | `<defense>` | `<active>` |
+
+## Eval Runs
+
+| Date | Change Tested | Model/Prompt Version | Suite | Score | Result | Notes | Follow-Up Ticket |
+|---|---|---|---|---:|---|---|---|
+| `<date>` | `<change>` | `<version>` | `<suite>` | `<score>` | `<pass/fail>` | `<notes>` | `<ticket>` |
+
+## Promotion Decisions
+
+| Date | Prompt/Model Change | Eval Result | Decision | Approver | Rollback Plan |
+|---|---|---|---|---|---|
+| `<date>` | `<change>` | `<result>` | `<promote/hold/rollback>` | `<approver>` | `<plan>` |
+
+## Regression Notes
+
+- `<date>`: `<what regressed, why, and what changed next>`

package/content/docs/ai.md

@@ -0,0 +1,141 @@
+# AI System Plan
+
+Use this document for apps that include LLMs, AI generation, model calls, AI-assisted decisions, or future model-training plans.
+
+## Current Status
+
+- AI enabled: `<yes/no>`
+- Primary AI use cases: `<summary>`
+- Current model/provider stack: `<models/providers>`
+- Current risk level: `<low/medium/high>`
+- Last reviewed: `<date>`
+
+## AI Workflows
+
+| Workflow | User/admin value | Trigger | Inputs | Outputs | Human review? | Status |
+|---|---|---|---|---|---|---|
+| `<workflow>` | `<value>` | `<event>` | `<data>` | `<result>` | `<yes/no>` | `<planned/live>` |
+
+## Model And Provider Choices
+
+| Use case | Provider | Model | Why this model | Alternatives considered | Fallback | Owner |
+|---|---|---|---|---|---|---|
+| `<use case>` | `<provider>` | `<model>` | `<reason>` | `<options>` | `<fallback>` | `<owner>` |
+
+## Model Governance
+
+- Approved providers/models:
+- Model-change approval rules:
+- Fallback model rules:
+- Required evals before promotion:
+- Cost/latency thresholds:
+- Safety thresholds:
+- Rollback process:
+
+## Prompt Inventory
+
+| Prompt ID | Version | Purpose | Owner | Eval coverage | Last changed | Rollback version |
+|---|---|---|---|---|---|---|
+| `<prompt-id>` | `<v1>` | `<purpose>` | `<owner>` | `<eval link>` | `<date>` | `<version>` |
+
+## Safety Controls
+
+Document how the app prevents unsafe or abusive AI behavior.
+
+- Prompt injection protection:
+- Jailbreak protection:
+- Data exfiltration protection:
+- Tool-use boundaries:
+- Human review requirements:
+- Content safety checks:
+- Abuse monitoring:
+- Escalation path:
+
+## Red-Team Testing
+
+| Scenario | Attack Type | Expected Defense | Eval/Test Link | Status |
+|---|---|---|---|---|
+| `<scenario>` | `<prompt injection/jailbreak/data leakage/tool misuse/cost abuse>` | `<defense>` | `<link>` | `<status>` |
+
+## AI Incident Response
+
+- Harmful output response:
+- Wrong/low-quality output response:
+- Private data exposure response:
+- High-cost/abusive usage response:
+- Policy-violating output response:
+- Owner/escalation path:
+
+## Quality And Confidence
+
+- Definition of high-quality output:
+- Required confidence signals:
+- Model self-checking default: `3 checks`
+- Model self-checking configurable count:
+- Model self-checking toggle:
+- AI steps that use self-checking:
+- AI steps where self-checking is disabled and why:
+- QA checks:
+- Auto-approval threshold:
+- Admin approval threshold:
+- Rejection criteria:
+- Known weak spots:
+
+## Reproducibility And Replayability
+
+Record enough information to replay important generations without storing sensitive data unnecessarily.
+
+- Prompt version:
+- Rendered prompt storage policy:
+- Input data reference policy:
+- Model/provider and parameters:
+- Retrieval context:
+- Tool calls:
+- Output:
+- Validation results:
+- Cost:
+- Latency:
+- User/admin decision:
+- Retention policy:
+
+## Learning Loop
+
+Use this section to describe how failed generations become future improvements.
+
+- Failed-generation capture:
+- Correction generation:
+- QA review:
+- Auto-approval rules:
+- Admin approval rules:
+- Approved correction storage:
+- Eval updates:
+- Prompt updates:
+- Product changes:
+
+## Dataset Governance
+
+- Dataset sources:
+- Consent requirements:
+- Labeling process:
+- Quality thresholds:
+- Access controls:
+- Retention rules:
+- PII redaction/tokenization:
+- Allowed use for evals:
+- Allowed use for fine-tuning/custom training:
+- Versioning strategy:
+
+## Future Custom Model Training
+
+- Why custom training may be useful:
+- Data needed:
+- Data quality threshold:
+- Privacy and consent constraints:
+- Retention rules:
+- Estimated cost:
+- When training is worth it:
+- Lighter alternative if full training is too heavy:
+
+## Open Questions
+
+- `<question>`

package/content/docs/api.md

@@ -0,0 +1,51 @@
+# API Documentation
+
+Use this document to summarize API contracts and link to generated API references.
+
+## API Overview
+
+- API type: `<HTTP/library/events/etc>`
+- Base URL:
+- Auth model:
+- Versioning strategy:
+- Generated docs:
+- Last reviewed:
+
+## Contract Sources
+
+| Contract | Source | Generated? | Command | Notes |
+|---|---|---|---|---|
+| `<OpenAPI/Typedoc/etc>` | `<path>` | `<yes/no>` | `<command>` | `<notes>` |
+
+## Authentication And Authorization
+
+- Authentication:
+- Authorization:
+- Token/session behavior:
+- Rate limits:
+- Error behavior:
+
+## Endpoints Or Public Interfaces
+
+| Method/Interface | Path/Name | Purpose | Auth | Request | Response | Errors |
+|---|---|---|---|---|---|---|
+| `<method>` | `<path>` | `<purpose>` | `<auth>` | `<schema>` | `<schema>` | `<errors>` |
+
+## Error Format
+
+```json
+{
+  "error": {
+    "code": "<code>",
+    "message": "<safe message>",
+    "requestId": "<request id>"
+  }
+}
+```
+
+## Breaking Changes And Deprecations
+
+| Change | Version/Date | Migration Path | Owner |
+|---|---|---|---|
+| `<change>` | `<version/date>` | `<steps>` | `<owner>` |
+

package/content/docs/architecture.md

@@ -0,0 +1,61 @@
+# Architecture Digest
+
+Use this document to explain how the app works now. Keep it current as the architecture changes.
+
+## Overview
+
+- Product purpose:
+- Primary users:
+- Core workflows:
+- Architecture status:
+- Last reviewed:
+
+## System Diagram
+
+Describe or link to the current system diagram.
+
+```text
+<client> -> <api> -> <database/services>
+```
+
+## Runtime Components
+
+| Component | Responsibility | Runtime | Owner | Notes |
+|---|---|---|---|---|
+| `<component>` | `<responsibility>` | `<node/python/etc>` | `<owner>` | `<notes>` |
+
+## Data Flow
+
+| Flow | Source | Destination | Data | Security/Privacy Notes |
+|---|---|---|---|---|
+| `<flow>` | `<source>` | `<destination>` | `<data>` | `<notes>` |
+
+## Integrations
+
+| Integration | Purpose | Direction | Auth | Failure Handling | Owner |
+|---|---|---|---|---|---|
+| `<service>` | `<purpose>` | `<inbound/outbound>` | `<auth>` | `<handling>` | `<owner>` |
+
+## Infrastructure
+
+- Local runtime:
+- Cloud runtime:
+- Default cloud provider:
+- Deployment approach:
+- Secrets:
+- Observability:
+
+## Key Tradeoffs
+
+| Decision | Tradeoff | Link |
+|---|---|---|
+| `<decision>` | `<tradeoff>` | `<ADR/link>` |
+
+## Known Limits
+
+- `<limit>`
+
+## Open Questions
+
+- `<question>`
+

package/content/docs/business.md

@@ -0,0 +1,49 @@
+# Business Notes
+
+Use this document to track product, pricing, cost, packaging, operational, and business-risk context.
+
+## Business Summary
+
+- Product:
+- Target users/customers:
+- Value proposition:
+- Business model:
+- Last reviewed:
+
+## Features And Rationale
+
+| Feature | Business Reason | User Value | Status | Notes |
+|---|---|---|---|---|
+| `<feature>` | `<reason>` | `<value>` | `<status>` | `<notes>` |
+
+## Pricing And Packaging
+
+| Plan/Package | Target User | Price | Limits | Notes |
+|---|---|---:|---|---|
+| `<plan>` | `<user>` | `<price>` | `<limits>` | `<notes>` |
+
+## Cost Drivers
+
+| Cost Driver | Source | Current Estimate | Scale Risk | Mitigation |
+|---|---|---:|---|---|
+| `<cost>` | `<vendor/service>` | `<estimate>` | `<low/medium/high>` | `<plan>` |
+
+## Operational Concerns
+
+- Support load:
+- Admin effort:
+- Compliance:
+- Vendor risk:
+- AI/model cost:
+- Reliability risk:
+
+## Things To Watch
+
+- `<watch item>`
+
+## Open Business Questions
+
+| Question | Why It Matters | Owner | Status |
+|---|---|---|---|
+| `<question>` | `<impact>` | `<owner>` | `<status>` |
+