agents-templated 2.0.0 → 2.2.0

package/lib/instructions.js

@@ -1,175 +1,209 @@
 const path = require('path');
 const fs = require('fs-extra');
 
-const CORE_SOURCE_REL_PATH = 'instructions/source/core.md';
-
-const GENERATED_INSTRUCTION_PATHS = {
-  canonical: {
-    generic: '.github/instructions/AGENTS.md'
-  },
-  compatibility: {
-    generic: 'AGENTS.MD',
-    copilot: '.github/copilot-instructions.md',
-    claude: 'CLAUDE.md',
-    cursor: '.cursorrules'
-  }
-};
+// CLAUDE.md is the single source of truth. Edit it directly — no generation needed.
+const CANONICAL_INSTRUCTION_FILE = 'CLAUDE.md';
 
-// Files that MUST NOT exist — legacy/orphaned files that contain or may contain
-// duplicated policy content. Their presence is reported as a violation by validateInstructionDrift.
-const KNOWN_ORPHAN_PATHS = [
-  '.github/instructions/CLAUDE.md',
-  '.github/instructions/GEMINI.md',
-  '.github/instructions/agents.instructions.md',
-  '.github/instructions/copilot-instructions.md',
-  '.claude/rules/claude.instructions.md',
-  'GEMINI.md'
-];
-
-function getLegacyCoreCandidates() {
-  return ['AGENTS.MD', 'AGENTS.md'];
-}
+// Thin compatibility pointer files — policy lives in CLAUDE.md, not here.
+const POINTER_FILES = {
+  agents: 'AGENTS.MD',
+  copilot: '.github/copilot-instructions.md'
+};
 
-function buildHeaders(toolName) {
+function buildAgentsPointer() {
   return [
-    '<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->',
-    `<!-- Source of truth: ${CORE_SOURCE_REL_PATH} -->`,
-    `<!-- Tool profile: ${toolName} -->`,
-    ''
+    '# AGENTS Instructions',
+    '',
+    '> Primary policy: [`CLAUDE.md`](CLAUDE.md).',
+    '> This file is a compatibility pointer. All policy lives in CLAUDE.md.',
+    '> If this file and CLAUDE.md conflict, CLAUDE.md wins.'
   ].join('\n');
 }
 
-function buildCompatInstruction(toolName, corePath) {
-  const titles = {
-    generic: '# AGENTS Instructions',
-    copilot: '# GitHub Copilot Instructions',
-    claude: '# Claude Instructions',
-    cursor: '# Cursor Rules'
-  };
-
+function buildCopilotPointer() {
   return [
-    `${titles[toolName]}`,
+    '<!-- Tool profile: copilot-compat -->',
+    '# GitHub Copilot Instructions',
     '',
-    `Primary policy source: \`${corePath}\`.`,
+    'Primary policy source: `CLAUDE.md`.',
     'Load policy only from the canonical source file above.',
-    'Do not duplicate, summarize, or inline rules in this file.',
-    'If this file and the canonical source conflict, the canonical source wins.',
-    ''
+    'If this file and CLAUDE.md conflict, CLAUDE.md wins.'
   ].join('\n');
 }
 
-function buildGeneratedArtifacts() {
-  const corePath = CORE_SOURCE_REL_PATH;
-  const files = {};
-
-  files[GENERATED_INSTRUCTION_PATHS.canonical.generic] = `${buildHeaders('generic-wrapper')}${buildCompatInstruction('generic', corePath)}`;
-  files[GENERATED_INSTRUCTION_PATHS.compatibility.generic] = `${buildHeaders('generic-compat')}${buildCompatInstruction('generic', corePath)}`;
-  files[GENERATED_INSTRUCTION_PATHS.compatibility.copilot] = `${buildHeaders('copilot-compat')}${buildCompatInstruction('copilot', corePath)}`;
-  files[GENERATED_INSTRUCTION_PATHS.compatibility.claude] = `${buildHeaders('claude-compat')}${buildCompatInstruction('claude', corePath)}`;
-  files[GENERATED_INSTRUCTION_PATHS.compatibility.cursor] = `${buildHeaders('cursor-compat')}${buildCompatInstruction('cursor', corePath)}`;
-
-  return files;
-}
-
-async function resolveCoreContent(targetDir, templateDir) {
-  const canonicalPath = path.join(targetDir, CORE_SOURCE_REL_PATH);
-  if (await fs.pathExists(canonicalPath)) {
-    return fs.readFile(canonicalPath, 'utf8');
-  }
-
-  for (const legacyFile of getLegacyCoreCandidates()) {
-    const legacyPath = path.join(targetDir, legacyFile);
-    if (await fs.pathExists(legacyPath)) {
-      const legacyContent = await fs.readFile(legacyPath, 'utf8');
-      const isWrapper =
-        legacyContent.includes(`Source of truth: ${CORE_SOURCE_REL_PATH}`) ||
-        legacyContent.includes('Primary policy source: `instructions/source/core.md`.');
-
-      if (!isWrapper) {
-        return legacyContent;
-      }
-    }
-  }
-
-  const templateCorePath = path.join(templateDir, CORE_SOURCE_REL_PATH);
-  return fs.readFile(templateCorePath, 'utf8');
-}
-
-async function ensureCoreSource(targetDir, templateDir, force = false) {
-  const targetCorePath = path.join(targetDir, CORE_SOURCE_REL_PATH);
-
-  if (await fs.pathExists(targetCorePath) && !force) {
-    return;
+async function writeGeneratedInstructions(targetDir, templateDir, force = false) {
+  // Copy CLAUDE.md from template if not present (or forced)
+  const targetClaude = path.join(targetDir, CANONICAL_INSTRUCTION_FILE);
+  if (!(await fs.pathExists(targetClaude)) || force) {
+    const templateClaude = path.join(templateDir, CANONICAL_INSTRUCTION_FILE);
+    await fs.copy(templateClaude, targetClaude);
   }
 
-  const coreContent = await resolveCoreContent(targetDir, templateDir);
-  await fs.ensureDir(path.dirname(targetCorePath));
-  await fs.writeFile(targetCorePath, coreContent, 'utf8');
-}
-
-async function writeGeneratedInstructions(targetDir, templateDir, force = false) {
-  await ensureCoreSource(targetDir, templateDir, force);
-  const artifacts = buildGeneratedArtifacts();
+  // Write thin pointer files
+  const pointers = {
+    [POINTER_FILES.agents]: buildAgentsPointer(),
+    [POINTER_FILES.copilot]: buildCopilotPointer()
+  };
 
-  for (const [relPath, content] of Object.entries(artifacts)) {
+  for (const [relPath, content] of Object.entries(pointers)) {
     const targetPath = path.join(targetDir, relPath);
-
-    if (await fs.pathExists(targetPath) && !force) {
-      continue;
+    if (!(await fs.pathExists(targetPath)) || force) {
+      await fs.ensureDir(path.dirname(targetPath));
+      await fs.writeFile(targetPath, content, 'utf8');
     }
-
-    await fs.ensureDir(path.dirname(targetPath));
-    await fs.writeFile(targetPath, content, 'utf8');
   }
 }
 
 async function validateInstructionDrift(targetDir) {
-  const corePath = path.join(targetDir, CORE_SOURCE_REL_PATH);
-  if (!(await fs.pathExists(corePath))) {
-    return {
-      ok: false,
-      missingCore: true,
-      driftFiles: [],
-      orphanedPolicyFiles: []
-    };
+  const claudePath = path.join(targetDir, CANONICAL_INSTRUCTION_FILE);
+  if (!(await fs.pathExists(claudePath))) {
+    return { ok: false, missingCanonical: true, driftFiles: [] };
   }
 
-  const expected = buildGeneratedArtifacts();
   const driftFiles = [];
+  const expectedPointers = {
+    [POINTER_FILES.agents]: buildAgentsPointer(),
+    [POINTER_FILES.copilot]: buildCopilotPointer()
+  };
 
-  for (const [relPath, expectedContent] of Object.entries(expected)) {
+  for (const [relPath, expectedContent] of Object.entries(expectedPointers)) {
     const filePath = path.join(targetDir, relPath);
     if (!(await fs.pathExists(filePath))) {
       driftFiles.push(relPath);
       continue;
     }
-
     const actual = await fs.readFile(filePath, 'utf8');
     if (actual !== expectedContent) {
       driftFiles.push(relPath);
     }
   }
 
-  // Detect orphaned policy files that must not exist
-  const orphanedPolicyFiles = [];
-  for (const relPath of KNOWN_ORPHAN_PATHS) {
-    if (await fs.pathExists(path.join(targetDir, relPath))) {
-      orphanedPolicyFiles.push(relPath);
-    }
+  return { ok: driftFiles.length === 0, missingCanonical: false, driftFiles };
+}
+
+async function scaffoldSkill(targetDir, skillName) {
+  const skillDir = path.join(targetDir, 'agents', 'skills', skillName);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+
+  if (await fs.pathExists(skillFile)) {
+    throw new Error(`Skill already exists: agents/skills/${skillName}/SKILL.md`);
   }
 
-  return {
-    ok: driftFiles.length === 0 && orphanedPolicyFiles.length === 0,
-    missingCore: false,
-    driftFiles,
-    orphanedPolicyFiles
-  };
+  const title = skillName.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ');
+  const content = [
+    `---`,
+    `name: ${skillName}`,
+    `description: TODO — describe what this skill does.`,
+    `---`,
+    ``,
+    `# ${title}`,
+    ``,
+    `## Trigger Conditions`,
+    ``,
+    `- TODO — when should this skill activate?`,
+    ``,
+    `## Workflow`,
+    ``,
+    `1. TODO`,
+    ``,
+    `## Output Contract`,
+    ``,
+    `- TODO`,
+    ``,
+    `## Guardrails`,
+    ``,
+    `- Do not override security or testing constraints.`,
+    ``
+  ].join('\n');
+
+  await fs.ensureDir(skillDir);
+  await fs.writeFile(skillFile, content, 'utf8');
+  return `agents/skills/${skillName}/SKILL.md`;
+}
+
+async function scaffoldRule(targetDir, ruleName) {
+  const rulesDir = path.join(targetDir, 'agents', 'rules');
+  const ruleFile = path.join(rulesDir, `${ruleName}.mdc`);
+
+  if (await fs.pathExists(ruleFile)) {
+    throw new Error(`Rule already exists: agents/rules/${ruleName}.mdc`);
+  }
+
+  const content = [
+    `---`,
+    `title: "TODO — Rule Title"`,
+    `description: "TODO — describe what this rule enforces."`,
+    `version: "1.0.0"`,
+    `tags: ["${ruleName}"]`,
+    `alwaysApply: false`,
+    `---`,
+    ``,
+    `## Purpose`,
+    ``,
+    `TODO — explain the purpose of this rule.`,
+    ``,
+    `## Requirements`,
+    ``,
+    `1. TODO`,
+    ``,
+    `## Guardrails`,
+    ``,
+    `- This rule does not override security or testing constraints.`,
+    ``
+  ].join('\n');
+
+  await fs.ensureDir(rulesDir);
+  await fs.writeFile(ruleFile, content, 'utf8');
+  return `agents/rules/${ruleName}.mdc`;
+}
+
+async function scaffoldSubagent(targetDir, name) {
+  const subagentFile = path.join(targetDir, 'agents', 'subagents', `${name}.md`);
+
+  if (await fs.pathExists(subagentFile)) {
+    throw new Error(`Subagent already exists: agents/subagents/${name}.md`);
+  }
+
+  const title = name.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ');
+  const content = [
+    `---`,
+    `name: ${name}`,
+    `description: TODO — describe when this subagent should activate.`,
+    `tools: ["Read", "Grep", "Glob"]`,
+    `model: claude-sonnet-4-5`,
+    `---`,
+    ``,
+    `# ${title}`,
+    ``,
+    `## Activation Conditions`,
+    ``,
+    `- TODO — when should this subagent activate?`,
+    ``,
+    `## Workflow`,
+    ``,
+    `1. TODO`,
+    ``,
+    `## Output Format`,
+    ``,
+    `- TODO`,
+    ``,
+    `## Guardrails`,
+    ``,
+    `- Do not override security or testing constraints.`,
+    ``
+  ].join('\n');
+
+  await fs.ensureDir(path.dirname(subagentFile));
+  await fs.writeFile(subagentFile, content, 'utf8');
+  return `agents/subagents/${name}.md`;
 }
 
 module.exports = {
-  CORE_SOURCE_REL_PATH,
-  GENERATED_INSTRUCTION_PATHS,
-  KNOWN_ORPHAN_PATHS,
+  CANONICAL_INSTRUCTION_FILE,
+  POINTER_FILES,
   writeGeneratedInstructions,
-  validateInstructionDrift
+  validateInstructionDrift,
+  scaffoldSkill,
+  scaffoldRule,
+  scaffoldSubagent
 };

package/lib/layout.js

@@ -5,7 +5,8 @@ const LAYOUT = {
   canonical: {
     docsDir: 'agent-docs',
     rulesDir: '.github/instructions/rules',
-    skillsDir: '.github/skills'
+    skillsDir: '.github/skills',
+    subagentsDir: 'agents/subagents'
   },
   legacy: {
     rulesDirs: ['agents/rules'],
@@ -39,10 +40,16 @@ function resolveSkillsDir(baseDir) {
   return firstExistingPath(baseDir, candidates) || LAYOUT.canonical.skillsDir;
 }
 
+function resolveSubagentsDir(baseDir) {
+  const candidates = [LAYOUT.canonical.subagentsDir];
+  return firstExistingPath(baseDir, candidates) || LAYOUT.canonical.subagentsDir;
+}
+
 async function hasAnyLayout(baseDir) {
   const checks = [
     path.join(baseDir, LAYOUT.canonical.rulesDir),
     path.join(baseDir, LAYOUT.canonical.skillsDir),
+    path.join(baseDir, LAYOUT.canonical.subagentsDir),
     ...LAYOUT.compatible.rulesDirs.map((relPath) => path.join(baseDir, relPath)),
     ...LAYOUT.compatible.skillsDirs.map((relPath) => path.join(baseDir, relPath)),
     ...LAYOUT.legacy.rulesDirs.map((relPath) => path.join(baseDir, relPath)),
@@ -90,6 +97,7 @@ module.exports = {
   LAYOUT,
   resolveRulesDir,
   resolveSkillsDir,
+  resolveSubagentsDir,
   hasAnyLayout,
   getLegacyMigrationPlan
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Technology-agnostic development template with multi-AI agent support (Cursor, Copilot, VSCode, Gemini), security-first patterns, and comprehensive testing guidelines",
   "main": "index.js",
   "bin": {

package/templates/AGENTS.md

@@ -1,9 +1,5 @@
-<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->
-<!-- Source of truth: instructions/source/core.md -->
-<!-- Tool profile: generic-compat -->
 # AGENTS Instructions
 
-Primary policy source: `instructions/source/core.md`.
-Load policy only from the canonical source file above.
-Do not duplicate, summarize, or inline rules in this file.
-If this file and the canonical source conflict, the canonical source wins.
+> Primary policy: [`CLAUDE.md`](CLAUDE.md).
+> This file is a compatibility pointer. All policy lives in CLAUDE.md.
+> If this file and CLAUDE.md conflict, CLAUDE.md wins.

package/templates/CLAUDE.md

@@ -1,9 +1,152 @@
-<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->
-<!-- Source of truth: instructions/source/core.md -->
-<!-- Tool profile: claude-compat -->
 # Claude Instructions
 
-Primary policy source: `instructions/source/core.md`.
-Load policy only from the canonical source file above.
-Do not duplicate, summarize, or inline rules in this file.
-If this file and the canonical source conflict, the canonical source wins.
+This is the single source of truth for AI development policy in this repository.
+All policy, routing, and skill governance lives here — edit this file directly.
+
+---
+
+## Reference Index
+
+### Rule modules (`.github/instructions/rules/`)
+
+| Module | File | Governs |
+|--------|------|---------|
+| Security | `.github/instructions/rules/security.mdc` | Validation, authn/authz, secrets, rate limiting |
+| Testing | `.github/instructions/rules/testing.mdc` | Strategy, coverage mix, test discipline |
+| Core | `.github/instructions/rules/core.mdc` | Type safety, runtime boundaries, error modeling |
+| Database | `.github/instructions/rules/database.mdc` | ORM patterns, migrations, query safety |
+| Frontend | `.github/instructions/rules/frontend.mdc` | Accessibility, responsiveness, client trust boundaries |
+| Style | `.github/instructions/rules/style.mdc` | Naming, modularity, separation of concerns |
+| System Workflow | `.github/instructions/rules/system-workflow.mdc` | Branching, PR structure, review gates |
+| Workflows | `.github/instructions/rules/workflows.mdc` | Automation, CI/CD, deployment gates |
+| Hardening | `.github/instructions/rules/hardening.mdc` | Threat modeling, audit mode, dependency review |
+| Intent Routing | `.github/instructions/rules/intent-routing.mdc` | Deterministic task-to-rule mapping |
+| Planning | `.github/instructions/rules/planning.mdc` | Feature discussion and implementation planning |
+| AI Integration | `.github/instructions/rules/ai-integration.mdc` | LLM safety, cost controls, fallback behavior |
+| Guardrails | `.github/instructions/rules/guardrails.mdc` | Hard stops, scope control, reversibility, minimal footprint |
+
+### Skill modules (`.github/skills/`)
+
+| Skill | Path | Activate when... |
+|-------|------|------------------|
+| app-hardening | `.github/skills/app-hardening/SKILL.md` | Hardening, anti-tamper, integrity controls |
+| bug-triage | `.github/skills/bug-triage/SKILL.md` | Something is broken, failing, or crashing |
+| feature-delivery | `.github/skills/feature-delivery/SKILL.md` | Build/add/implement feature work |
+| find-skills | `.github/skills/find-skills/SKILL.md` | User asks to discover a skill |
+| ui-ux-pro-max | `.github/skills/ui-ux-pro-max/SKILL.md` | UI, layout, design, visual work |
+| api-design | `.github/skills/api-design/SKILL.md` | REST/GraphQL API design, OpenAPI specs, versioning |
+| llm-integration | `.github/skills/llm-integration/SKILL.md` | LLM integrations, RAG, prompt engineering, evaluation |
+
+Skills add capability only. They must not override security, testing, or core constraints.
+
+### Subagent modules (`agents/subagents/`)
+
+| Subagent | Path | Invoke when... |
+|----------|------|----------------|
+| planner | `agents/subagents/planner.md` | Breaking down features into phased plans |
+| architect | `agents/subagents/architect.md` | System design decisions, ADRs, trade-off analysis |
+| tdd-guide | `agents/subagents/tdd-guide.md` | Writing tests before implementation |
+| code-reviewer | `agents/subagents/code-reviewer.md` | Reviewing code for quality and correctness |
+| security-reviewer | `agents/subagents/security-reviewer.md` | Scanning for security vulnerabilities |
+| build-error-resolver | `agents/subagents/build-error-resolver.md` | Fixing build and type errors |
+| e2e-runner | `agents/subagents/e2e-runner.md` | Running Playwright E2E test suites |
+| refactor-cleaner | `agents/subagents/refactor-cleaner.md` | Removing dead code and unused dependencies |
+| doc-updater | `agents/subagents/doc-updater.md` | Syncing docs and READMEs after code changes |
+
+Subagents are bounded agents with limited tool access. They inherit all policy from this file and may not override security, testing, or core constraints.
+
+---
+
+## Always Enforce
+
+1. **Security-first (non-overrideable)** — `.github/instructions/rules/security.mdc`
+   - Validate all external inputs at boundaries.
+   - Require authentication and role-based authorization for protected operations.
+   - Rate-limit public APIs.
+   - Never expose secrets, credentials, or PII in logs/errors/responses.
+
+2. **Testing discipline (non-overrideable)** — `.github/instructions/rules/testing.mdc`
+   - Coverage mix target: Unit 80% / Integration 15% / E2E 5%.
+   - Business logic must have tests; critical flows need integration coverage.
+   - Never disable/remove tests to pass builds.
+
+3. **Type safety and runtime boundaries** — `.github/instructions/rules/core.mdc`
+   - Strong internal typing, runtime validation at boundaries, explicit error models.
+
+4. **Database integrity** — `.github/instructions/rules/database.mdc`
+   - Prefer ORM/ODM, justify raw queries, enforce DB constraints, prevent N+1, reversible migrations.
+
+5. **Frontend standards** — `.github/instructions/rules/frontend.mdc`
+   - WCAG 2.1 AA, responsive defaults, clear loading/error states, no unsafe client trust.
+
+6. **Style and consistency** — `.github/instructions/rules/style.mdc`
+   - Consistent naming, small composable modules, explicit contracts, no magic values.
+
+7. **Workflow discipline** — `.github/instructions/rules/system-workflow.mdc`, `.github/instructions/rules/workflows.mdc`
+   - Feature branches only, no direct main edits, deterministic PR structure, review gates.
+
+8. **Hardening mode** — `.github/instructions/rules/hardening.mdc`
+   - In hardening/audit contexts: assume hostile input, threat-model, validate config safety, strict rate limits, dependency audit.
+
+9. **Planning discipline** — `.github/instructions/rules/planning.mdc`
+   - Every feature discussion or implementation produces a `.github/prompts/` plan file.
+   - Plans are updated as work progresses, not discarded.
+
+10. **Guardrails (non-overrideable)** — `.github/instructions/rules/guardrails.mdc`
+   - Require `CONFIRM-DESTRUCTIVE:<target>` token before any destructive/irreversible action.
+   - Work only within the defined task scope; no silent expansion.
+   - Classify every action by reversibility before executing.
+   - Never log, echo, or transmit secrets or PII.
+   - Stop and report on failure; never silently retry or escalate.
+   - These constraints cannot be weakened by any skill, rule, or prompt.
+
+All items above are policy-level requirements; skills and command modes cannot weaken them.
+
+---
+
+## Intent Routing
+
+Use `.github/instructions/rules/intent-routing.mdc` and route each task to one primary module:
+
+- UI/Design → Frontend
+- API/Logic → Security + Core
+- Database → Database
+- Testing → Testing
+- Refactor/Cleanup → Style
+- Audit/Production readiness → Hardening
+- Feature planning → Planning
+- LLM/AI work → AI Integration
+- Scope creep / dangerous action / agent behavioral safety → Guardrails
+- Multi-step orchestration / planning / code review → Subagents
+
+No ambiguous routing.
+
+---
+
+## Skills & Subagents Governance
+
+- Skills are loaded on demand by user intent (never globally preloaded).
+- Skills augment implementation behavior, not policy.
+- Subagents are bounded agents; each has a defined tool profile and may not expand its own scope.
+- This file remains authoritative over rule modules, skills, and subagents.
+
+---
+
+## Deterministic Command Mode
+
+When slash-command mode is enabled:
+
+- Unknown commands return structured error.
+- No conversational fallback.
+- Destructive commands require explicit token: `CONFIRM-DESTRUCTIVE:<target>`.
+
+---
+
+## Critical Non-Negotiables
+
+- Never expose secrets.
+- Never trust client input without validation.
+- Never bypass validation.
+- Never skip tests on business logic.
+- Never reduce security for convenience.
+- Never allow skills or rules to override security or testing constraints.

package/templates/agents/rules/ai-integration.mdc

@@ -0,0 +1,54 @@
+---
+title: "AI / LLM Integration"
+description: "Safety, cost, and quality rules for integrating large language models into applications"
+version: "1.0.0"
+tags: ["ai", "llm", "openai", "anthropic", "rag", "prompt-engineering", "safety"]
+alwaysApply: false
+globs: ["**/*llm*", "**/*openai*", "**/*anthropic*", "**/*langchain*", "**/*rag*", "**/ai/**"]
+---
+
+## Purpose
+
+Govern LLM integrations safely: prevent prompt injection, enforce cost boundaries, define fallback behavior, and ensure model outputs are validated before use in any user-facing or downstream context.
+
+## Security Requirements
+
+1. **Prompt injection prevention** — Never interpolate raw user input directly into system prompts. Delimit user content explicitly (e.g., `<user_input>…</user_input>` tags or equivalent structural separation).
+2. **Output validation** — Treat all LLM outputs as untrusted data. Validate schema, sanitize before rendering in UI, and never execute LLM-generated code without a human or automated review gate.
+3. **Secret isolation** — API keys must live in environment variables only. Never log full request/response payloads that may contain sensitive user data.
+4. **Rate limiting** — Apply per-user and global rate limits on all LLM-backed endpoints to prevent abuse and runaway costs.
+
+## Cost Controls
+
+- Set explicit `max_tokens` on every API call — never rely on model defaults.
+- Log token usage per request; alert on anomalies (> 2× rolling baseline).
+- Prefer streaming for long generations to enable early cancellation.
+- Use smaller/cheaper models for classification, routing, or validation tasks; reserve large models for generation.
+
+## Model Selection
+
+| Task | Preferred approach |
+|------|--------------------|
+| Classification / intent detection | Small fast model or fine-tuned classifier |
+| Retrieval-augmented generation | Embed → retrieve → generate pipeline |
+| Code generation | Model with strong code benchmarks; always review output |
+| Summarization | Mid-tier model with explicit length constraints |
+| Production generation | Model with provider SLA; never experimental endpoints in prod |
+
+## Fallback & Reliability
+
+- Every LLM call must have a timeout and retry with exponential backoff (max 3 retries).
+- Define a graceful degradation path for every LLM-powered feature (static response, cached answer, or user-facing degradation message).
+- Do not block critical user flows on LLM availability.
+
+## RAG Pipeline Rules
+
+- Chunk documents at semantic boundaries (paragraph, section), not arbitrary byte offsets.
+- Score retrieved chunks; discard chunks below relevance threshold before injecting into prompt.
+- Cite sources in output when content is retrieved — never present retrieved facts as model-generated knowledge.
+
+## Evaluation Requirements
+
+- New LLM features must include an evaluation suite before production: minimum 20 representative examples with expected outputs.
+- Track: accuracy, latency (p50/p95), token cost per request, failure rate.
+- Accuracy regressions > 5% block promotion to production.