special-agents 0.1.0

package/content/docs/data-governance.md

@@ -0,0 +1,67 @@
+# Data Governance
+
+Use this document to define how the app classifies, stores, uses, deletes, exports, and protects data.
+
+## Data Owners
+
+- Product owner:
+- Engineering owner:
+- Security/privacy owner:
+- Last reviewed:
+
+## Data Classification
+
+| Classification | Examples | Storage Rules | Access Rules | Retention |
+|---|---|---|---|---|
+| Public | `<examples>` | `<rules>` | `<rules>` | `<retention>` |
+| Internal | `<examples>` | `<rules>` | `<rules>` | `<retention>` |
+| Confidential | `<examples>` | `<rules>` | `<rules>` | `<retention>` |
+| PII | `<examples>` | `<rules>` | `<rules>` | `<retention>` |
+| Secrets | `<examples>` | `<rules>` | `<rules>` | `<retention>` |
+| Training/Eval Data | `<examples>` | `<rules>` | `<rules>` | `<retention>` |
+
+## Data Inventory
+
+| Data Type | Source | Purpose | Stored Where | Sensitive? | Retention | Deletion/Export |
+|---|---|---|---|---|---|---|
+| `<data>` | `<source>` | `<purpose>` | `<store>` | `<yes/no>` | `<period>` | `<process>` |
+
+## Consent And Usage
+
+- User consent requirements:
+- Analytics/tracking consent:
+- AI replay/eval usage:
+- Model training usage:
+- External sharing:
+
+## Retention, Deletion, And Export
+
+- Retention policy:
+- Deletion process:
+- Export process:
+- Backup retention:
+- Legal/compliance holds:
+
+## AI Data Rules
+
+- Prompt/input storage:
+- Output storage:
+- Replay logs:
+- Eval datasets:
+- Correction datasets:
+- Fine-tuning/custom training data:
+- Dataset source approval:
+- Labeling process:
+- Dataset versioning:
+- Consent for training:
+- PII redaction/tokenization:
+
+## Access Controls
+
+| Data | Who Can Access | Approval Needed? | Audit Logged? |
+|---|---|---|---|
+| `<data>` | `<roles>` | `<yes/no>` | `<yes/no>` |
+
+## Open Risks
+
+- `<risk>`

package/content/docs/decisions/0000-template.md

@@ -0,0 +1,29 @@
+# ADR 0000: `<Decision Title>`
+
+- Status: `<Proposed/Accepted/Superseded/Rejected/Deprecated>`
+- Date: `<YYYY-MM-DD>`
+- Owner: `<name/team>`
+- Related tickets/docs: `<links>`
+
+## Context
+
+What problem are we solving, and why does the decision matter?
+
+## Decision
+
+What did we decide?
+
+## Alternatives Considered
+
+| Option | Pros | Cons | Reason Not Chosen |
+|---|---|---|---|
+| `<option>` | `<pros>` | `<cons>` | `<reason>` |
+
+## Consequences
+
+What becomes easier, harder, cheaper, more expensive, safer, riskier, or more constrained because of this decision?
+
+## Follow-Up
+
+- `<ticket or action>`
+

package/content/docs/decisions/README.md

@@ -0,0 +1,30 @@
+# Decision History
+
+Use this index to track architecture decision records and other meaningful project decisions.
+
+## Decision Process
+
+- Record decisions that affect architecture, product behavior, data, vendors, cloud, AI/model choices, cost, security, compliance, or operations.
+- Keep each ADR short: context, decision, alternatives considered, consequences, date, and status.
+- Update this index whenever an ADR is added or superseded.
+
+## Status Values
+
+- `Proposed`
+- `Accepted`
+- `Superseded`
+- `Rejected`
+- `Deprecated`
+
+## Decision Index
+
+| ID | Title | Status | Date | Owner | Link |
+|---|---|---|---|---|---|
+| `0000` | ADR template | `Template` | `<date>` | `<owner>` | [`0000-template.md`](./0000-template.md) |
+
+## Open Decision Questions
+
+| Question | Why It Matters | Needed By | Owner | Status |
+|---|---|---|---|---|
+| `<question>` | `<impact>` | `<date>` | `<owner>` | `<status>` |
+

package/content/docs/docs.index.yaml

@@ -0,0 +1,25 @@
+# Starter documentation templates. `rafi create` copies these into a target repo's
+# docs/ folder, honoring `gate` against the project flags (see ProjectFlags).
+#   gate: always   -> always copied
+#   gate: ai       -> copied only when flags.usesAI
+#   gate: frontend -> copied only when flags.hasFrontend
+docs:
+  - { path: README.md, gate: always }
+  - { path: architecture.md, gate: always }
+  - { path: features.md, gate: always }
+  - { path: api.md, gate: always }
+  - { path: users.md, gate: always }
+  - { path: admins.md, gate: always }
+  - { path: business.md, gate: always }
+  - { path: operations.md, gate: always }
+  - { path: security.md, gate: always }
+  - { path: data-governance.md, gate: always }
+  - { path: local-cloud.md, gate: always }
+  - { path: scalability.md, gate: always }
+  - { path: tickets.md, gate: always }
+  - { path: release-checklist.md, gate: always }
+  - { path: decisions/README.md, gate: always }
+  - { path: decisions/0000-template.md, gate: always }
+  - { path: ai.md, gate: ai }
+  - { path: ai-evals.md, gate: ai }
+  - { path: ai-costs.md, gate: ai }

package/content/docs/features.md

@@ -0,0 +1,41 @@
+# Feature Digest
+
+Use this document to track what the app does, who can use each feature, and what workflows matter.
+
+## Product Summary
+
+- Product purpose:
+- Primary user value:
+- Current release stage:
+- Last reviewed:
+
+## User Roles
+
+| Role | Description | Permissions | Notes |
+|---|---|---|---|
+| `<role>` | `<description>` | `<permissions>` | `<notes>` |
+
+## Features
+
+| Feature | Users/Roles | Status | Business Value | Docs | Tickets |
+|---|---|---|---|---|---|
+| `<feature>` | `<roles>` | `<planned/live>` | `<value>` | `<link>` | `<ticket>` |
+
+## Core Workflows
+
+| Workflow | Actor | Start | End | Happy Path | Failure/Edge States |
+|---|---|---|---|---|---|
+| `<workflow>` | `<role>` | `<start>` | `<end>` | `<steps>` | `<states>` |
+
+## Permissions Matrix
+
+| Capability | Normal User | Admin | Other Roles |
+|---|---|---|---|
+| `<capability>` | `<yes/no>` | `<yes/no>` | `<notes>` |
+
+## Future Ideas
+
+Add future ideas to `docs/tickets.md`; summarize only major themes here.
+
+- `<idea/theme>`
+

package/content/docs/local-cloud.md

@@ -0,0 +1,58 @@
+# Local And Cloud Runtime
+
+Use this document to keep local development and cloud deployment expectations clear.
+
+## Runtime Summary
+
+- Local runtime supported: `<yes/no>`
+- Cloud runtime supported: `<yes/no>`
+- Default cloud provider:
+- Infrastructure as Code tool:
+- Last reviewed:
+
+## Local Development
+
+- Setup command:
+- Run command:
+- Test command:
+- Required services:
+- Seed data:
+- Local URLs:
+- Local secrets process:
+
+## Cloud Runtime
+
+- Provider/account:
+- Region(s):
+- Services:
+- Deployment command/process:
+- Secrets:
+- Domains:
+- Monitoring:
+- Rollback:
+
+## Parity Matrix
+
+| Capability | Local | Cloud | Difference | Reason |
+|---|---|---|---|---|
+| `<capability>` | `<behavior>` | `<behavior>` | `<difference>` | `<reason>` |
+
+## Infrastructure As Code
+
+- Tool:
+- Entrypoint:
+- State management:
+- Environments:
+- Manual steps:
+- Known gaps:
+
+## Environment Variables
+
+| Variable | Local | Cloud | Required? | Notes |
+|---|---|---|---|---|
+| `<VAR>` | `<value/source>` | `<secret/source>` | `<yes/no>` | `<notes>` |
+
+## Open Questions
+
+- `<question>`
+

package/content/docs/operations.md

@@ -0,0 +1,69 @@
+# Operations Guide
+
+Use this document for deployment, monitoring, incident response, backups, and production operations.
+
+## Operational Summary
+
+- Environments:
+- Deployment owner:
+- Monitoring owner:
+- Support path:
+- Last reviewed:
+
+## Environments
+
+| Environment | Purpose | URL/Access | Data | Notes |
+|---|---|---|---|---|
+| Local | Development | `<url>` | `<local/seed>` | `<notes>` |
+| Staging | Pre-production | `<url>` | `<data>` | `<notes>` |
+| Production | Live users | `<url>` | `<data>` | `<notes>` |
+
+## Deployments
+
+- Deployment command/process:
+- Required checks:
+- Migration process:
+- Rollback process:
+- Post-deploy smoke tests:
+
+## Monitoring And Alerts
+
+| Signal | Tool/Dashboard | Alert Threshold | Owner | Runbook |
+|---|---|---|---|---|
+| `<signal>` | `<tool>` | `<threshold>` | `<owner>` | `<link>` |
+
+## Runbooks
+
+### `<Incident Or Task>`
+
+- Symptoms:
+- Severity:
+- First checks:
+- Recovery steps:
+- Escalation:
+- Follow-up:
+
+## Backups And Restore
+
+- Backup scope:
+- Backup cadence:
+- Restore test cadence:
+- Restore steps:
+- Retention:
+
+## Incident Response
+
+- Severity levels:
+- Communication path:
+- Incident commander:
+- Customer communication:
+- Postmortem requirements:
+
+## AI Operations
+
+- AI provider dashboards:
+- Cost alerts:
+- Abuse monitoring:
+- Eval/regression checks:
+- AI incident response:
+

package/content/docs/release-checklist.md

@@ -0,0 +1,56 @@
+# Release Checklist
+
+Use this checklist before releases that affect users, production data, public APIs, infrastructure, billing, auth, or AI behavior.
+
+## Release Summary
+
+- Release name/version:
+- Release owner:
+- Target date:
+- Risk level:
+- Rollback owner:
+
+## Pre-Release
+
+- [ ] Requested behavior is complete.
+- [ ] Relevant tickets are updated.
+- [ ] Relevant tests pass.
+- [ ] Typecheck/static analysis passes.
+- [ ] Lint/format checks pass.
+- [ ] Build passes.
+- [ ] Database migrations are reviewed and tested.
+- [ ] API docs are updated.
+- [ ] User/admin docs are updated.
+- [ ] Architecture/business/operations docs are updated where relevant.
+- [ ] Security, data-governance, and privacy impacts are reviewed.
+- [ ] AI evals pass where relevant.
+- [ ] AI/model cost impact is reviewed where relevant.
+- [ ] Environment variables and secrets are documented.
+- [ ] Monitoring dashboards and alerts are ready.
+- [ ] Rollback path is documented and practical.
+
+## Deployment
+
+- [ ] Deployment started:
+- [ ] Migration completed:
+- [ ] Smoke tests completed:
+- [ ] Monitoring checked:
+- [ ] Error logs checked:
+- [ ] User/admin impact confirmed:
+
+## Post-Release
+
+- [ ] Changelog updated.
+- [ ] Tickets marked complete.
+- [ ] Follow-up work logged.
+- [ ] Incidents/regressions documented.
+- [ ] Release process improvements logged.
+
+## Rollback Plan
+
+- Trigger:
+- Steps:
+- Data considerations:
+- Communication:
+- Verification:
+

package/content/docs/scalability.md

@@ -0,0 +1,81 @@
+# Scalability Plan
+
+Use this document to describe how the app should scale locally, in cloud environments, and across major system areas.
+
+## Current Status
+
+- Expected users:
+- Expected data size:
+- Expected request volume:
+- Expected AI/model volume:
+- Expected cost constraints:
+- Last reviewed:
+
+## Local And Cloud Runtime
+
+Unless the project says otherwise, the app should run both locally and in the cloud.
+
+| Environment | Runtime Path | Dependencies | Data Strategy | Known Gaps |
+|---|---|---|---|---|
+| Local development | `<command/docker/etc>` | `<services>` | `<seed/local db>` | `<gaps>` |
+| Cloud | `<provider/services>` | `<services>` | `<managed db/storage>` | `<gaps>` |
+
+## Server Scaling
+
+- Stateless services:
+- Horizontal scaling plan:
+- Background job strategy:
+- Queueing strategy:
+- Rate limiting:
+- Caching:
+- Bottlenecks:
+
+## Cloud Scaling
+
+- Default cloud provider:
+- Infrastructure as Code tool:
+- Regions:
+- Managed services:
+- Deployment topology:
+- Autoscaling assumptions:
+- Capacity limits:
+- Failover expectations:
+
+## Frontend Scaling
+
+- Bundle-size strategy:
+- Rendering/performance risks:
+- Loading-state strategy:
+- Mobile performance:
+- Caching:
+- Network request strategy:
+
+## Database Scaling
+
+- Schema growth assumptions:
+- Index strategy:
+- Query risk areas:
+- Read/write volume:
+- Connection management:
+- Migration strategy:
+- Archival/retention strategy:
+
+## AI And Model Scaling
+
+- Provider limits:
+- Latency expectations:
+- Concurrency strategy:
+- Queueing/fallback behavior:
+- Cost controls:
+- Model upgrade path:
+- Eval impact of model changes:
+
+## Total Architecture Scaling
+
+| Area | Current Limit | Scale Trigger | Planned Response | Owner |
+|---|---|---|---|---|
+| `<area>` | `<limit>` | `<trigger>` | `<response>` | `<owner>` |
+
+## Open Risks
+
+- `<risk>`

package/content/docs/security.md

@@ -0,0 +1,82 @@
+# Security Plan
+
+Use this document to track the app's security model, threat model, controls, and incident response.
+
+## Security Summary
+
+- Security owner:
+- Risk level:
+- Auth model:
+- Permission model:
+- Last reviewed:
+
+## Authentication And Authorization
+
+- Authentication method:
+- Session/token behavior:
+- Password policy:
+- MFA:
+- Role/permission model:
+- Server-side enforcement points:
+
+## Secrets Management
+
+- Secret storage:
+- Local development secrets:
+- Cloud secrets:
+- Rotation process:
+- Emergency revocation:
+
+## Threat Model
+
+| Area | Threat | Impact | Mitigation | Status |
+|---|---|---|---|---|
+| `<area>` | `<threat>` | `<impact>` | `<mitigation>` | `<status>` |
+
+## Abuse Controls
+
+- Rate limiting:
+- Signup/login protection:
+- API abuse protection:
+- AI abuse protection:
+- Admin action controls:
+
+## AI Security Controls
+
+- Prompt injection protection:
+- Jailbreak protection:
+- Data leakage protection:
+- Tool-use restrictions:
+- Cost-abuse protection:
+- Human review requirements:
+- AI incident escalation:
+
+## Security Checks
+
+| Check | Tool/Process | Frequency | Owner | Notes |
+|---|---|---|---|---|
+| Dependency scanning | `<tool>` | `<frequency>` | `<owner>` | `<notes>` |
+| Secret scanning | `<tool>` | `<frequency>` | `<owner>` | `<notes>` |
+| Container scanning | `<tool>` | `<frequency>` | `<owner>` | `<notes>` |
+| License checks | `<tool>` | `<frequency>` | `<owner>` | `<notes>` |
+| SBOM generation | `<tool>` | `<frequency>` | `<owner>` | `<notes>` |
+
+## Sensitive Actions And Audit Logs
+
+| Action | Actor | Audit Fields | Alert? | Notes |
+|---|---|---|---|---|
+| `<action>` | `<actor>` | `<fields>` | `<yes/no>` | `<notes>` |
+
+## Security Incident Response
+
+- Severity levels:
+- First response steps:
+- Containment:
+- Eradication:
+- Recovery:
+- User/customer communication:
+- Post-incident review:
+
+## Known Risks
+
+- `<risk>`

package/content/docs/tickets.md

@@ -0,0 +1,45 @@
+# Ticket Log
+
+Use this document as the source of truth when no external issue tracker is configured.
+
+## Status Values
+
+- `Backlog`
+- `Ready`
+- `In Progress`
+- `Blocked`
+- `In Review`
+- `Done`
+- `Won't Do`
+
+## Priority Values
+
+- `P0`: urgent production/user/business risk
+- `P1`: important near-term work
+- `P2`: useful planned work
+- `P3`: future idea or low urgency
+
+## Epics
+
+| Epic ID | Title | Status | Business Value | Notes |
+|---|---|---|---|---|
+| `E-001` | `<title>` | `Backlog` | `<value>` | `<notes>` |
+
+## Stories And Tickets
+
+| ID | Epic | Title | Status | Priority | User/Business Value | Acceptance Criteria | Test Expectations | Notes |
+|---|---|---|---|---|---|---|---|---|
+| `T-001` | `E-001` | `<title>` | `Backlog` | `P2` | `<value>` | `<criteria>` | `<tests>` | `<notes>` |
+
+## Follow-Ups And Future Ideas
+
+| ID | Source | Idea | Value | Risk/Cost | Status |
+|---|---|---|---|---|---|
+| `F-001` | `<source>` | `<idea>` | `<value>` | `<risk/cost>` | `Backlog` |
+
+## Completed Work
+
+| ID | Completed Date | Summary | Links |
+|---|---|---|---|
+| `<ticket>` | `<date>` | `<summary>` | `<links>` |
+

package/content/docs/users.md

@@ -0,0 +1,43 @@
+# User Guide
+
+Use this document for normal user-facing documentation.
+
+## Audience
+
+- Primary users:
+- Assumed skill level:
+- Last reviewed:
+
+## Getting Started
+
+1. `<step>`
+2. `<step>`
+3. `<step>`
+
+## Common Workflows
+
+### `<Workflow Name>`
+
+- Goal:
+- Steps:
+- Expected result:
+- Common issues:
+
+## Account And Settings
+
+- Sign in:
+- Profile/settings:
+- Notifications:
+- Data export/deletion:
+
+## Errors And Troubleshooting
+
+| Problem | What It Means | What To Do |
+|---|---|---|
+| `<problem>` | `<meaning>` | `<action>` |
+
+## Support
+
+- Support path:
+- What information to include:
+

package/content/preamble.md

@@ -0,0 +1,13 @@
+# App-Level AI Agent Rules
+
+Use this file as the canonical project instruction source for AI coding agents.
+
+For Codex, copy this content into the repository root as `AGENTS.md`.
+For Claude Code, create a repository-root `CLAUDE.md` that imports the same rules:
+
+```md
+@AGENTS.md
+```
+
+Keep durable process rules in this file. Put detailed project facts in the project documents named below, not in the agent rules.
+

package/content/rules/base/code-quality.md

@@ -0,0 +1,20 @@
+---
+name: code-quality
+category: base
+description: "Clarity, focused modules, explicit errors, stable interfaces."
+condition: always
+template: false
+---
+## Code Quality
+
+- Optimize for clarity over cleverness.
+- Keep functions and modules focused. Extract helpers when they reduce real duplication or clarify complex logic.
+- Avoid oversized files and modules. Split by responsibility when a file becomes difficult to scan or safely change.
+- Use explicit names for variables, functions, components, files, and tests.
+- Add clarifying comments for non-obvious business rules, tradeoffs, edge cases, algorithms, or integration constraints.
+- Avoid comments that merely restate the code.
+- Prefer typed, structured data and schema validation at boundaries.
+- Handle errors explicitly with useful messages and safe failure modes.
+- Keep public interfaces stable unless the task requires a breaking change.
+- Do not add production dependencies without a clear reason. Prefer existing dependencies and standard library capabilities.
+

package/content/rules/base/core.md

@@ -0,0 +1,17 @@
+---
+name: core
+category: base
+description: "Senior-level working agreement and change discipline."
+condition: always
+template: false
+---
+## Core Working Agreement
+
+- Work like a senior or staff-level engineer: keep code simple, readable, well-factored, testable, and easy for another developer to maintain.
+- Do not make changes outside the user's instructions unless they are required to complete the requested work correctly.
+- Prefer small, reviewable changes with clear boundaries. Avoid unrelated refactors unless they are required for the requested change.
+- Follow existing project conventions before introducing new patterns.
+- Make reasonable implementation choices, but ask the user when a decision changes product behavior, cost, security posture, data model, or public API contracts.
+- If you notice unrelated room for improvement, make a note of it and report it when the work is done instead of changing it silently.
+- Never hide uncertainty. If assumptions matter, state them briefly and verify them where practical.
+