special-agents 0.1.0

package/content/rules/base/definition-of-done.md

@@ -0,0 +1,21 @@
+---
+name: definition-of-done
+category: base
+description: "What must be true before a change is considered complete."
+condition: always
+template: false
+---
+## Definition Of Done
+
+A change is not done until:
+
+- The requested behavior is implemented.
+- The agent has reviewed this rule file, confirmed the change complies with it, and prepared a concise rule-compliance result for the user, except for items that are not yet applicable during initial project buildout.
+- Relevant tests are added or updated.
+- Relevant tests and quality checks pass, or any inability to run them is reported.
+- API docs are updated when contracts change.
+- Developer, user, admin, business, ticket, and architecture docs are updated where relevant.
+- Ticket status and future follow-ups are updated.
+- New environment variables, migrations, dependencies, and operational steps are documented.
+- The final response explains what changed, what tests ran, and any remaining risks.
+

package/content/rules/base/git-safety.md

@@ -0,0 +1,16 @@
+---
+name: git-safety
+category: base
+description: "Protect user changes and avoid destructive git operations."
+condition: always
+template: false
+---
+## Git And Workspace Safety
+
+- Before editing, inspect the repository state when practical and avoid overwriting user changes.
+- Treat uncommitted changes as user-owned unless the agent made them in the current task.
+- Never discard, reset, overwrite, or revert user changes unless the user explicitly asks.
+- Do not run destructive git commands such as hard reset, forced checkout, branch deletion, or history rewriting unless the user explicitly asks.
+- Do not commit, push, tag, merge, rebase, or open pull requests unless the user asks.
+- Keep changes scoped to the requested work. If a cleanup or refactor is useful but not required, note it as follow-up work.
+

package/content/rules/base/response-expectations.md

@@ -0,0 +1,18 @@
+---
+name: response-expectations
+category: base
+description: "What every final response should include."
+condition: always
+template: false
+---
+## Agent Response Expectations
+
+- Be concise and concrete.
+- In final responses, include:
+  - Code changes made.
+  - Tests/checks run and whether they passed.
+  - Documentation updated.
+  - Rule compliance check result, including any rules not yet applicable during initial buildout.
+  - Tests changed, explained simply, when applicable.
+  - Follow-up tickets added, when applicable.
+- Do not overwhelm the user with implementation noise unless they ask for it.

package/content/rules/domain/accessibility.md

@@ -0,0 +1,14 @@
+---
+name: accessibility
+category: domain
+description: "Accessible, resilient UI and product quality."
+condition: frontend
+template: false
+---
+## Accessibility, UX, And Product Quality
+
+- Build accessible UI by default: semantic markup, keyboard navigation, focus states, labels, contrast, and screen-reader-friendly structure.
+- Keep user workflows complete, understandable, and resilient to loading, empty, error, and permission states.
+- Do not ship user-facing changes without updating relevant user/admin docs.
+- Preserve existing design system conventions unless the task calls for a design change.
+

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

@@ -0,0 +1,21 @@
+---
+name: ai-cost
+category: domain
+description: "AI cost tracking and the correction/learning loop."
+condition: ai
+template: false
+---
+## 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`.
+- 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.
+- 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

@@ -0,0 +1,25 @@
+---
+name: ai-evals
+category: domain
+description: "Quality gates, confidence, evals, and examples for AI."
+condition: ai
+template: false
+---
+## AI Quality, Confidence, And Evals
+
+- Always plan AI generation workflows for high-confidence outputs, not just plausible outputs.
+- Define quality gates, confidence scoring, QA checks, and acceptance thresholds for AI-generated results.
+- Assume the project will include custom QA steps for important AI generations.
+- When an AI generation is important or user-facing, include tests, evals, review workflows, or human approval steps that match the risk level.
+- For prompts used in AI generation steps, QA steps, correction steps, and other relevant AI uses, instruct the model to check its work three times by default.
+- Make the number of model self-checks configurable.
+- Make extra model self-checking toggleable so it can be disabled when cost, latency, or workflow needs require it.
+- During planning, consult the user about where work-checking prompts should be used, how many checks are appropriate, and when extra checks may be turned off.
+- When using AI generation, start with at least one correct or top-quality example, and prefer many high-quality examples.
+- Use correct/high-quality examples during AI generation where they improve quality.
+- During planning, consult the user on which AI generation stages should use examples.
+- Build the ability to toggle the use of correct/high-quality examples at AI generation steps where practical.
+- Track AI failures, correction rates, confidence levels, approval outcomes, and quality trends.
+- Keep AI eval suites, golden examples, adversarial cases, and regression results updated in `docs/ai-evals.md`.
+- Promote prompt 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

@@ -0,0 +1,16 @@
+---
+name: ai-governance
+category: domain
+description: "Model/provider and dataset governance."
+condition: ai
+template: false
+---
+## AI Model And Dataset Governance
+
+- Document approved AI models/providers, the reason each is used, fallback models, and model-change approval rules.
+- Treat model changes as product changes. Run relevant evals and document quality, cost, latency, and safety impact before promoting a new model.
+- 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`.
+

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

@@ -0,0 +1,19 @@
+---
+name: ai-reproducibility
+category: domain
+description: "Replayability, prompt versioning, and prompt tuning."
+condition: ai
+template: false
+---
+## AI Reproducibility, Replayability, And Prompt Tuning
+
+- For anything involving AI, include reproducibility and replayability by default.
+- Record enough information to replay meaningful AI generations: prompt version, rendered prompt, input data references, model/provider, parameters, tool calls, retrieval context, output, validation results, cost, latency, timestamps, and user/admin decisions.
+- Do not store sensitive prompt, input, or output data for replay or training unless privacy, consent, retention, and access controls are documented and approved.
+- Version prompts and keep a prompt change history.
+- Treat prompts as product logic: review them, test them, document their purpose, and connect changes to eval results.
+- Maintain eval sets with golden examples, edge cases, failure cases, and adversarial cases.
+- Prefer structured prompt inputs and structured model outputs where practical.
+- Support prompt rollback when a prompt change reduces quality.
+- Track prompt experiments, model changes, temperature/parameter changes, example changes, and their measured impact.
+

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

@@ -0,0 +1,19 @@
+---
+name: ai-safety
+category: domain
+description: "Adversarial safety and abuse protection for AI features."
+condition: ai
+template: false
+---
+## AI And LLM Safety
+
+- For anything using LLMs or AI generation, include adversarial safety planning and protection against nefarious use.
+- During planning for AI features, consult the user on enterprise-level AI safety practices appropriate for the app.
+- Protect against prompt injection, jailbreak attempts, data exfiltration, tool misuse, unsafe generated actions, and hidden instructions in user-supplied content.
+- Treat model output as untrusted. Validate, constrain, and review AI output before it affects users, data, money, permissions, external systems, or business-critical workflows.
+- Use content safety checks, allow/deny rules, scoped tools, permission boundaries, and human review where risk warrants it.
+- 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`.
+

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

@@ -0,0 +1,17 @@
+---
+name: data-governance
+category: domain
+description: "Data classification, retention, consent, and PII handling."
+condition: always
+template: false
+---
+## Data Governance
+
+- Classify data by sensitivity, including public, internal, confidential, PII, credentials/secrets, regulated data, and training/eval data.
+- Collect and retain the minimum data needed for the product, operations, safety, and legal requirements.
+- Document data retention, deletion, export, backup, and recovery expectations.
+- 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`.
+

package/content/rules/domain/observability.md

@@ -0,0 +1,18 @@
+---
+name: observability
+category: domain
+description: "Logging, metrics, dashboards, runbooks, and AI observability."
+condition: always
+template: false
+---
+## Observability And Operations
+
+- Add useful logging, monitoring, metrics, alerts, and health checks for production-relevant services.
+- Plan for Grafana-compatible dashboards or an equivalent observability dashboard stack unless the project chooses another monitoring platform.
+- 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.
+- 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/robustness.md

@@ -0,0 +1,21 @@
+---
+name: robustness
+category: domain
+description: "Resilient workflows, transactions, health checks, backups."
+condition: always
+template: false
+---
+## Robustness And Reliability
+
+- Design important workflows to handle loading, empty, error, timeout, retry, and partial-failure states.
+- Use transactions for multi-step database writes that must succeed or fail together.
+- Make background jobs idempotent where practical so retries do not duplicate side effects.
+- Add timeouts, retries with backoff, and circuit-breaker-style protections around external services where appropriate.
+- Use feature flags or staged rollout controls for risky releases where practical.
+- Validate configuration at startup and fail with clear errors when required settings are missing.
+- Use database constraints and application-level validation for important invariants.
+- Add health checks for services and readiness checks for dependencies.
+- Preserve backward compatibility for public APIs unless a breaking change is intentional and documented.
+- Plan for backups, automated or scheduled restore testing, migrations, and rollback paths for production data.
+- Maintain a release checklist covering migrations, environment variables, generated docs, monitoring, smoke tests, rollback steps, and user/admin documentation.
+

package/content/rules/domain/scalability.md

@@ -0,0 +1,18 @@
+---
+name: scalability
+category: domain
+description: "Scaling strategy across server, cloud, AI, frontend, and data."
+condition: always
+template: false
+---
+## Scalability And Performance
+
+- Plan for scalability across the server, cloud infrastructure, AI/model usage, frontend, databases, and total app architecture.
+- Keep services stateless where practical so they can scale horizontally.
+- Use pagination, filtering, caching, batching, queues, background jobs, and rate limits where they reduce load or improve user experience.
+- Design database schemas, indexes, constraints, and query patterns with expected growth in mind.
+- 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`.
+

package/content/rules/domain/security.md

@@ -0,0 +1,28 @@
+---
+name: security
+category: domain
+description: "Security, privacy, and compliance baseline."
+condition: always
+template: false
+---
+## Security, Privacy, And Compliance
+
+- Never commit secrets, credentials, tokens, private keys, or real user data.
+- Use environment variables or secret managers for sensitive configuration.
+- Apply least privilege to permissions, tokens, database access, and admin workflows.
+- Require authentication and authorization checks on server-side boundaries, not only in the UI.
+- Validate and sanitize user input.
+- Use parameterized queries or trusted ORM/query-builder APIs. Do not build SQL with string concatenation.
+- Keep dependencies current and remove unused dependencies.
+- Scan dependencies for known vulnerabilities and address meaningful findings.
+- Use secure defaults for cookies, sessions, CORS, headers, rate limits, password handling, and token expiration.
+- Store passwords only with proven password hashing such as Argon2 or bcrypt. Never store plain-text passwords.
+- Encrypt sensitive data in transit and at rest where appropriate.
+- Protect against common web risks such as injection, XSS, CSRF, auth bypass, insecure direct object references, and unsafe file handling.
+- Add audit logs for sensitive admin, billing, auth, permission, and data export actions.
+- Document sensitive data flows, auth assumptions, and privacy-relevant behavior.
+- Add threat-model notes for meaningful auth, billing, admin, AI/provider, and sensitive user-data workflows.
+- Add rate limiting and abuse protection for public APIs, login/signup flows, expensive operations, and AI/vendor-backed calls.
+- Maintain a security document with the auth model, permission model, threat model, abuse controls, dependency/security scanning, incident response, and known risks.
+- Ask before adding analytics, tracking, paid services, or external data sharing.
+

package/content/rules/packs.index.yaml

@@ -0,0 +1,177 @@
+# Generated by scripts/shard.ts — registry of rule packs in source order.
+packs:
+  - name: core
+    category: base
+    path: base/core.md
+    condition: always
+    template: false
+    order: 1000
+  - name: git-safety
+    category: base
+    path: base/git-safety.md
+    condition: always
+    template: false
+    order: 2000
+  - name: stack
+    category: templated
+    path: templated/stack.md
+    condition: always
+    template: true
+    order: 3000
+  - name: project-docs
+    category: process
+    path: process/project-docs.md
+    condition: always
+    template: false
+    order: 4000
+  - name: tickets
+    category: process
+    path: process/tickets.md
+    condition: always
+    template: false
+    supersededByForeman: true
+    order: 5000
+  - name: tdd
+    category: process
+    path: process/tdd.md
+    condition: always
+    template: false
+    order: 6000
+  - name: testing
+    category: process
+    path: process/testing.md
+    condition: always
+    template: false
+    order: 7000
+  - name: ci
+    category: process
+    path: process/ci.md
+    condition: always
+    template: false
+    order: 8000
+  - name: dependencies
+    category: process
+    path: process/dependencies.md
+    condition: always
+    template: false
+    order: 9000
+  - name: code-quality
+    category: base
+    path: base/code-quality.md
+    condition: always
+    template: false
+    order: 10000
+  - name: api-docs
+    category: process
+    path: process/api-docs.md
+    condition: always
+    template: false
+    order: 11000
+  - name: scalability
+    category: domain
+    path: domain/scalability.md
+    condition: always
+    template: false
+    order: 12000
+  - name: infra
+    category: templated
+    path: templated/infra.md
+    condition: cloud
+    template: true
+    order: 13000
+  - name: database
+    category: templated
+    path: templated/database.md
+    condition: always
+    template: true
+    order: 14000
+  - name: data-governance
+    category: domain
+    path: domain/data-governance.md
+    condition: always
+    template: false
+    order: 15000
+  - name: security
+    category: domain
+    path: domain/security.md
+    condition: always
+    template: false
+    order: 16000
+  - name: ai-safety
+    category: domain
+    path: domain/ai-safety.md
+    condition: ai
+    template: false
+    order: 17000
+  - name: ai-governance
+    category: domain
+    path: domain/ai-governance.md
+    condition: ai
+    template: false
+    order: 18000
+  - name: robustness
+    category: domain
+    path: domain/robustness.md
+    condition: always
+    template: false
+    order: 19000
+  - name: ai-evals
+    category: domain
+    path: domain/ai-evals.md
+    condition: ai
+    template: false
+    order: 20000
+  - name: ai-reproducibility
+    category: domain
+    path: domain/ai-reproducibility.md
+    condition: ai
+    template: false
+    order: 21000
+  - name: ai-cost
+    category: domain
+    path: domain/ai-cost.md
+    condition: ai
+    template: false
+    order: 22000
+  - name: release
+    category: process
+    path: process/release.md
+    condition: always
+    template: false
+    order: 23000
+  - name: accessibility
+    category: domain
+    path: domain/accessibility.md
+    condition: frontend
+    template: false
+    order: 24000
+  - name: observability
+    category: domain
+    path: domain/observability.md
+    condition: always
+    template: false
+    order: 25000
+  - name: business-docs
+    category: process
+    path: process/business-docs.md
+    condition: always
+    template: false
+    order: 26000
+  - name: architecture
+    category: process
+    path: process/architecture.md
+    condition: always
+    template: false
+    order: 27000
+  - name: definition-of-done
+    category: base
+    path: base/definition-of-done.md
+    condition: always
+    template: false
+    order: 28000
+  - name: response-expectations
+    category: base
+    path: base/response-expectations.md
+    condition: always
+    template: false
+    order: 29000

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

@@ -0,0 +1,16 @@
+---
+name: api-docs
+category: process
+description: "Machine-readable API docs and contract tests."
+condition: always
+template: false
+---
+## API And Contract Documentation
+
+- Maintain machine-readable API docs for every public or internal API surface that other clients consume.
+- Prefer OpenAPI/Swagger for HTTP APIs.
+- Prefer JSDoc/Typedoc for TypeScript libraries and generated references where useful.
+- Prefer docstrings plus generated references for Python APIs where useful.
+- Update API docs, examples, request/response schemas, error shapes, auth requirements, and version notes when API behavior changes.
+- Add or update contract tests for public API changes.
+

package/content/rules/process/architecture.md

@@ -0,0 +1,14 @@
+---
+name: architecture
+category: process
+description: "Architecture digest and ADR/decision-history discipline."
+condition: always
+template: false
+---
+## 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.
+- ADRs should be short: context, decision, alternatives considered, consequences, date.
+

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

@@ -0,0 +1,13 @@
+---
+name: business-docs
+category: process
+description: "Keep business assumptions, costs, and risks current."
+condition: always
+template: false
+---
+## 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.
+- 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/ci.md

@@ -0,0 +1,18 @@
+---
+name: ci
+category: process
+description: "Repeatable scripts and CI aligned with local verification."
+condition: always
+template: false
+---
+## Automation And CI
+
+- Prefer repeatable project scripts over one-off commands.
+- Keep CI aligned with the local verification commands agents are expected to run.
+- Add or update CI checks when adding new test types, generated API docs, database migrations, security checks, or build steps.
+- For AI features, add or update prompt/eval regression checks where practical.
+- Include dependency vulnerability scanning and secret scanning in CI where practical.
+- Include license checks, SBOM generation, and container image scanning for production applications where practical.
+- Generated artifacts should be reproducible and documented with the command that updates them.
+- Do not bypass failing CI without documenting the reason and the follow-up ticket.
+

package/content/rules/process/dependencies.md

@@ -0,0 +1,17 @@
+---
+name: dependencies
+category: process
+description: "Dependency, license, SBOM, and vulnerability governance."
+condition: always
+template: false
+---
+## Dependency And Supply Chain Governance
+
+- Do not add major dependencies, paid services, or vendor lock-in without a clear reason and user approval when the decision has meaningful cost, security, licensing, or maintenance impact.
+- Prefer existing dependencies and standard library capabilities before adding new packages.
+- Keep lockfiles committed and reproducible.
+- Check dependency licenses before adding packages to production applications.
+- Generate and maintain a software bill of materials for production applications where practical.
+- Scan dependencies and container images for known vulnerabilities and address meaningful findings.
+- Remove unused dependencies, stale packages, and abandoned integrations when discovered during relevant work.
+

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

@@ -0,0 +1,35 @@
+---
+name: project-docs
+category: process
+description: "The standard set of project documents to create and maintain."
+condition: always
+template: false
+---
+## 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.
+- `CHANGELOG.md`: notable user-facing, API, migration, and operational changes.
+- `.env.example`: documented environment variables with safe placeholder values.
+
+When app behavior changes, update the affected docs in the same change.
+

package/content/rules/process/release.md

@@ -0,0 +1,16 @@
+---
+name: release
+category: process
+description: "Changelog, semver, release checklist, and post-release notes."
+condition: always
+template: false
+---
+## 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.
+- 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/tdd.md

@@ -0,0 +1,16 @@
+---
+name: tdd
+category: process
+description: "Test-driven development discipline: identify behavior, write tests first, then minimal code."
+condition: always
+template: false
+---
+## Test-Driven Development
+
+- Always use test-driven development for application code changes wherever practical.
+- Start by identifying the expected behavior and acceptance criteria.
+- For new behavior or bug fixes, write or update tests first when practical, then implement the minimal code needed to pass, then refactor.
+- Cover business logic, API contracts, permissions, data access, validation, error handling, and critical UI workflows.
+- For UI work, include component tests, integration tests, or end-to-end tests where they provide meaningful confidence.
+- If TDD is not practical for a specific change, explain why briefly and still add the best reasonable coverage.
+

package/content/rules/process/testing.md

@@ -0,0 +1,28 @@
+---
+name: testing
+category: process
+description: "Discover and run the repo's quality commands; verification order."
+condition: always
+template: false
+---
+## Testing And Verification
+
+- Always discover and use the repository's existing test, lint, typecheck, build, migration, and formatting commands.
+- If standard quality commands do not exist yet, add or propose them before the project grows around inconsistent tooling.
+- Run relevant tests during development, then run the full practical verification suite before considering work complete.
+- If tests fail, fix the code so they pass unless the test expectations are clearly obsolete.
+- If test requirements may have changed and the correct behavior is unclear, ask the user before rewriting the tests.
+- When tests are updated, explain what changed and why in simple, concise language.
+- Do not claim tests passed unless they were actually run and passed.
+- If a command cannot be run, report the command, the reason, and the remaining risk.
+
+Preferred verification order when available:
+
+1. Targeted tests for the changed behavior.
+2. Typecheck/static analysis.
+3. Lint/format checks.
+4. Full test suite.
+5. Build.
+6. Database migration validation.
+7. End-to-end or smoke tests for user-facing changes.
+