agents-templated 1.2.12 → 2.1.0

package/lib/instructions.js

@@ -1,145 +1,167 @@
 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/CLAUDE.md'
-  }
-};
+// CLAUDE.md is the single source of truth. Edit it directly — no generation needed.
+const CANONICAL_INSTRUCTION_FILE = 'CLAUDE.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'
-  };
-
+function buildCopilotPointer() {
   return [
-    `${titles[toolName]}`,
+    '<!-- Tool profile: copilot-compat -->',
+    '# GitHub Copilot Instructions',
     '',
-    `Primary policy source: \`${corePath}\`.`,
-    'Minimal compatibility stub to reduce duplicated prompt tokens.',
-    'Load rules from the canonical source file above.',
-    ''
+    'Primary policy source: `CLAUDE.md`.',
+    'Load policy only from the canonical source file above.',
+    'If this file and CLAUDE.md conflict, CLAUDE.md wins.'
   ].join('\n');
 }
 
-function buildGeneratedArtifacts(coreContent) {
-  const corePath = CORE_SOURCE_REL_PATH;
-  const files = {};
-
-  files[GENERATED_INSTRUCTION_PATHS.canonical.generic] = `${buildHeaders('generic')}${coreContent.trim()}\n`;
-  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)}`;
-
-  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)) {
-      return fs.readFile(legacyPath, 'utf8');
-    }
-  }
-
-  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 corePath = path.join(targetDir, CORE_SOURCE_REL_PATH);
-  const coreContent = await fs.readFile(corePath, 'utf8');
-  const artifacts = buildGeneratedArtifacts(coreContent);
+  // 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: []
-    };
+  const claudePath = path.join(targetDir, CANONICAL_INSTRUCTION_FILE);
+  if (!(await fs.pathExists(claudePath))) {
+    return { ok: false, missingCanonical: true, driftFiles: [] };
   }
 
-  const coreContent = await fs.readFile(corePath, 'utf8');
-  const expected = buildGeneratedArtifacts(coreContent);
   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);
     }
   }
 
-  return {
-    ok: driftFiles.length === 0,
-    missingCore: false,
-    driftFiles
-  };
+  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`);
+  }
+
+  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`;
 }
 
 module.exports = {
-  CORE_SOURCE_REL_PATH,
-  GENERATED_INSTRUCTION_PATHS,
+  CANONICAL_INSTRUCTION_FILE,
+  POINTER_FILES,
   writeGeneratedInstructions,
-  validateInstructionDrift
+  validateInstructionDrift,
+  scaffoldSkill,
+  scaffoldRule
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "1.2.12",
+  "version": "2.1.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/.cursorrules

@@ -1,70 +1,9 @@
-# Cursor Rules - Technology-Agnostic Development Template
-# This is a flexible development template that adapts to any technology stack with enterprise-grade patterns.
-# Detailed rules are in agents/rules/*.mdc files - refer to those for implementation patterns.
-
-## Developer Identity & Communication
-- AI assistant should provide clear, step-by-step solutions with actionable examples
-- Focus on security, performance, and maintainability in all recommendations
-- Adapt patterns to the chosen technology stack
-
-## Core Principles
-- **Security-first development**: Always validate inputs, authenticate users, implement appropriate rate limiting
-- **Type safety**: Use strong typing systems available in chosen language/framework
-- **Performance optimization**: Monitor resource usage, implement caching, optimize assets
-- **Testing strategy**: Comprehensive testing at unit, integration, and E2E levels
-- **Accessibility**: WCAG 2.1 AA compliance for all user-facing interfaces
-- **Documentation**: Keep project documentation updated and comprehensive
-
-## Architecture Principles
-- **Technology-agnostic**: This template adapts to your chosen stack
-- **Security patterns**: Input validation, authentication, authorization, rate limiting
-- **Performance patterns**: Caching, lazy loading, bundle optimization
-- **Testing patterns**: Unit (80%), Integration (15%), E2E (5%) coverage target
-- **Feature-oriented structure**: Group by domain/feature, not just technical layer
-
-## Security Requirements (CRITICAL)
-- **Input validation**: All user inputs MUST be validated with appropriate schema validation
-- **Authentication**: Implement secure authentication flows with session management
-- **Rate limiting**: Public endpoints MUST have rate limiting protection
-- **Authorization**: Role-based access control with proper middleware
-- **Error handling**: Never expose sensitive data in error responses
-- **Database access**: Use ORM/ODM patterns, avoid raw queries unless performance-critical
-
-## Code Quality Standards
-- **Type Safety**: Use strict typing, avoid loose type usage
-- **Performance**: Monitor bundle/binary size, implement lazy loading patterns
-- **Accessibility**: WCAG 2.1 AA compliance for user-facing components
-- **Testing**: All business logic and user flows must have appropriate tests
-- **Documentation**: Keep README, agent-docs/ARCHITECTURE.md, and AGENTS.md updated
-
-## Technology Stack Adaptation
-Choose your stack and apply these patterns consistently:
-
-### Frontend Options
-- **React/Next.js/Vue/Svelte**: Component-based with proper state management
-- **Angular**: Component + service architecture with TypeScript
-- **Traditional**: Server-side rendering with progressive enhancement
-
-### Backend Options  
-- **Node.js**: Express, Fastify, or framework API routes
-- **Python**: Django, FastAPI, Flask with proper ORM patterns
-- **Other**: Adapt patterns to your chosen backend technology
-
-### Database Options
-- **SQL**: PostgreSQL, MySQL with ORM (Prisma, TypeORM, SQLAlchemy)
-- **NoSQL**: MongoDB, DynamoDB with ODM patterns
-- **Cloud**: Supabase, Firebase, managed database services
-
-## Agent Delegation (See AGENTS.md for details)
-- **UI/Design work** → FrontendAgent
-- **API/Business logic** → BackendAgent  
-- **Database/Schema** → DatabaseAgent
-- **Testing implementation** → TestAgent
-- **Security reviews** → SecurityAgent
-- **Code quality** → ReviewerAgent
-
-## Usage Instructions
-1. Choose your technology stack
-2. Adapt the patterns in agents/rules/*.mdc to your chosen technologies
-3. Update this .cursorrules file with stack-specific details
-4. Begin development following the established patterns
+<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->
+<!-- Source of truth: instructions/source/core.md -->
+<!-- Tool profile: cursor-compat -->
+# Cursor Rules
+
+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.

package/templates/.github/copilot-instructions.md

@@ -1,64 +1,9 @@
+<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->
+<!-- Source of truth: instructions/source/core.md -->
+<!-- Tool profile: copilot-compat -->
 # GitHub Copilot Instructions
 
-This project follows enterprise-grade, technology-agnostic development patterns.
-
-## Quick Start
-
-- **AI Guide**: See `AGENTS.md` for comprehensive instructions
-- **Architecture**: See `agent-docs/ARCHITECTURE.md` for project guidelines
-- **Custom Skills**: See `agents/skills/` directory for domain-specific extensions
-- **Detailed Rules**: See `agents/rules/*.mdc` files
-
-## Always Apply
-
-1. **Security-first**: Validate inputs, authenticate endpoints, rate limit public APIs
-   - Reference: `agents/rules/security.mdc`
-
-2. **Testing**: Unit (80%), Integration (15%), E2E (5%) coverage
-   - Reference: `agents/rules/testing.mdc`
-
-3. **Type Safety**: Strong typing with runtime validation at boundaries
-   - Reference: `agents/rules/core.mdc`
-
-## Agent Delegation
-
-When implementing features, follow agent patterns from `AGENTS.MD`:
-- **UI/Design** → FrontendAgent patterns (`agents/rules/frontend.mdc`)
-- **API/Logic** → BackendAgent patterns (`agents/rules/security.mdc`)
-- **Database** → DatabaseAgent patterns (`agents/rules/database.mdc`)
-- **Testing** → TestAgent patterns (`agents/rules/testing.mdc`)
-- **Security** → SecurityAgent patterns (`agents/rules/security.mdc`)
-
-## Deterministic Slash Commands
-
-- Slash command protocol is defined in `AGENTS.MD` under `Deterministic Slash Command System Standard`.
-- Modular command contracts are stored in `agents/commands/`.
-- Command mode is strict: unknown or malformed slash commands must return structured error output and stop.
-- No conversational fallback is allowed once slash-command mode is entered.
-- Destructive actions require explicit confirmation token format: `CONFIRM-DESTRUCTIVE:<target>`.
-
-## Critical Rules
-
-- Validate ALL user inputs with schema validation
-- Authenticate and authorize protected endpoints
-- Rate limit public endpoints
-- Write tests for all business logic
-- Ensure WCAG 2.1 AA accessibility compliance
-- Use ORM/ODM patterns, avoid raw queries
-- Never expose sensitive data in errors/logs
-
-## Reference Files
-
-- `AGENTS.MD` - Primary AI assistant guide
-- `agent-docs/ARCHITECTURE.md` - Architecture and technology stack guidance
-- `agents/commands/` - Deterministic slash command contracts
-- `agents/rules/core.mdc` - Core principles
-- `agents/rules/security.mdc` - Security patterns (CRITICAL)
-- `agents/rules/testing.mdc` - Testing strategy (CRITICAL)
-- `agents/rules/frontend.mdc` - Frontend patterns
-- `agents/rules/database.mdc` - Database patterns
-- `agents/rules/style.mdc` - Code style guidelines
-
----
-
-**Note**: This is technology-agnostic. Adapt patterns to your chosen stack while maintaining security and quality standards.
+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.

package/templates/AGENTS.md

@@ -0,0 +1,5 @@
+# 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.

package/templates/CLAUDE.md

@@ -1,65 +1,134 @@
-# Claude AI Instructions
+# Claude Instructions
 
-This project uses enterprise-grade, technology-agnostic development patterns for Claude AI assistance.
+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.
 
-## Quick Start
+---
+
+## 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.
+
+---
+
+## Always Enforce
 
-- **AI Guide**: See `AGENTS.MD` for comprehensive instructions
-- **Architecture**: See `agent-docs/ARCHITECTURE.md` for project guidelines
-- **Custom Skills**: See `agents/skills/` directory for domain-specific extensions
-- **Detailed Rules**: See `agents/rules/*.mdc` files
+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.
 
-## Always Apply
+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.
 
-1. **Security-first**: Validate inputs, authenticate endpoints, rate limit public APIs
-   - Reference: `agents/rules/security.mdc`
+3. **Type safety and runtime boundaries** — `.github/instructions/rules/core.mdc`
+   - Strong internal typing, runtime validation at boundaries, explicit error models.
 
-2. **Testing**: Unit (80%), Integration (15%), E2E (5%) coverage
-   - Reference: `agents/rules/testing.mdc`
+4. **Database integrity** — `.github/instructions/rules/database.mdc`
+   - Prefer ORM/ODM, justify raw queries, enforce DB constraints, prevent N+1, reversible migrations.
 
-3. **Type Safety**: Strong typing with runtime validation at boundaries
-   - Reference: `agents/rules/core.mdc`
+5. **Frontend standards** — `.github/instructions/rules/frontend.mdc`
+   - WCAG 2.1 AA, responsive defaults, clear loading/error states, no unsafe client trust.
 
-## Agent Delegation
+6. **Style and consistency** — `.github/instructions/rules/style.mdc`
+   - Consistent naming, small composable modules, explicit contracts, no magic values.
 
-When implementing features, reference `AGENTS.MD`:
-- **UI/Design** → FrontendAgent patterns (`agents/rules/frontend.mdc`)
-- **API/Logic** → BackendAgent patterns (`agents/rules/security.mdc`)
-- **Database** → DatabaseAgent patterns (`agents/rules/database.mdc`)
-- **Testing** → TestAgent patterns (`agents/rules/testing.mdc`)
-- **Security** → SecurityAgent patterns (`agents/rules/security.mdc`)
+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.
 
-## Deterministic Slash Commands
+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.
 
-- Slash command protocol is defined in `AGENTS.MD` under `Deterministic Slash Command System Standard`.
-- Modular command contracts are stored in `agents/commands/`.
-- Command mode is strict: unknown or malformed slash commands must return structured error output and stop.
-- No conversational fallback is allowed once slash-command mode is entered.
-- Destructive actions require explicit confirmation token format: `CONFIRM-DESTRUCTIVE:<target>`.
+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.
 
-## Critical Rules
+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.
 
-- Validate ALL user inputs with schema validation
-- Authenticate and authorize protected endpoints
-- Rate limit public endpoints
-- Write tests for all business logic
-- Ensure WCAG 2.1 AA accessibility compliance
-- Use ORM/ODM patterns, avoid raw queries
-- Never expose sensitive data in errors/logs
+All items above are policy-level requirements; skills and command modes cannot weaken them.
 
-## Reference Files
+---
+
+## Intent Routing
+
+Use `.github/instructions/rules/intent-routing.mdc` and route each task to one primary module:
 
-- `AGENTS.MD` - Primary AI assistant guide
-- `agent-docs/ARCHITECTURE.md` - Architecture and technology stack guidance
-- `AGENTS.MD` - AI assistant guide and patterns
-- `agents/commands/` - Deterministic slash command contracts
-- `agents/rules/core.mdc` - Core principles
-- `agents/rules/security.mdc` - Security patterns (CRITICAL)
-- `agents/rules/testing.mdc` - Testing strategy (CRITICAL)
-- `agents/rules/frontend.mdc` - Frontend patterns
-- `agents/rules/database.mdc` - Database patterns
-- `agents/rules/style.mdc` - Code style guidelines
+- 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
+
+No ambiguous routing.
 
 ---
 
-**Note**: This is technology-agnostic. Adapt patterns to your chosen stack while maintaining security and quality standards.
+## Skills Governance
+
+- Skills are loaded on demand by user intent (never globally preloaded).
+- Skills augment implementation behavior, not policy.
+- This file remains authoritative over rule modules and skills.
+
+---
+
+## 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.