agents-templated 2.1.0 → 2.2.1

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/agents-templated.svg)](https://www.npmjs.com/package/agents-templated)
 [![npm downloads](https://img.shields.io/npm/dm/agents-templated.svg)](https://www.npmjs.com/package/agents-templated)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub stars](https://img.shields.io/github/stars/rickandrew2/agents-projects-templated?style=social)](https://github.com/rickandrew2/agents-templated)
+[![GitHub stars](https://img.shields.io/github/stars/rickandrew2/agents-templated?style=social)](https://github.com/rickandrew2/agents-templated)
 
 > **Agents Templated** is a CLI tool and npm package that instantly scaffolds production-ready project structures with enterprise-grade development patterns, security guidelines, and AI assistant configurations. Designed for developers who want to start projects the right way—with proven OWASP security practices, comprehensive testing strategies (80/15/5 coverage targets), and agent-based architecture patterns—without being locked into specific frameworks. It generates unified configuration files that work seamlessly with Cursor, GitHub Copilot, Claude, and Google Gemini, allowing AI assistants to automatically follow best practices from day one. Whether you're building a Next.js app, Django API, Go microservice, or any custom stack, Agents Templated provides the guardrails and patterns you need while giving you complete freedom to choose your technology.
 
@@ -28,13 +28,13 @@ Agents Templated scaffolds your project with:
 - Deterministic slash-command standard in `AGENTS.MD` and modular contracts in `agents/commands/`
 - Implicit natural-language routing support (`slash-command-auto`) for non-technical prompts
 - New workflow/routing/hardening rule set:
-  - `agents/rules/intent-routing.mdc`
-  - `agents/rules/system-workflow.mdc`
-  - `agents/rules/hardening.mdc`
+  - `.github/instructions/rules/intent-routing.mdc`
+  - `.github/instructions/rules/system-workflow.mdc`
+  - `.github/instructions/rules/hardening.mdc`
 - New baseline skills:
-  - `agents/skills/feature-delivery/`
-  - `agents/skills/bug-triage/`
-  - `agents/skills/app-hardening/`
+  - `.github/skills/feature-delivery/`
+  - `.github/skills/bug-triage/`
+  - `.github/skills/app-hardening/`
 - Release and audit contracts now require hardening evidence when risk profile requires it
 
 ---
@@ -124,7 +124,7 @@ Agents Templated automatically configures compatible wrappers for major AI codin
 | **Claude** | `CLAUDE.md` | ✅ Compatible |
 | **Generic agents** | `AGENTS.MD` | ✅ Compatible |
 
-**Single source of truth:** `instructions/source/core.md` drives generated tool-compatible instruction files.
+**Single source of truth:** `CLAUDE.md` drives generated tool-compatible instruction files.
 
 ---
 
@@ -421,7 +421,7 @@ await agentsTemplated.install('./my-project', {
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
-2. Update relevant rule files in `agents/rules/`
+2. Update relevant rule files in `.github/instructions/rules/`
 3. Keep documentation synchronized with code changes
 4. Follow security and testing patterns
 5. Ensure AI assistant configurations remain compatible

package/bin/cli.js

@@ -10,6 +10,7 @@ const {
   LAYOUT,
   resolveRulesDir,
   resolveSkillsDir,
+  resolveSubagentsDir,
   hasAnyLayout,
   getLegacyMigrationPlan
 } = require('../lib/layout');
@@ -19,7 +20,8 @@ const {
   writeGeneratedInstructions,
   validateInstructionDrift,
   scaffoldSkill,
-  scaffoldRule
+  scaffoldRule,
+  scaffoldSubagent
 } = require('../lib/instructions');
 
 // Resolve the templates directory - works in both dev and installed contexts
@@ -52,6 +54,7 @@ program
   .option('-r, --rules', 'Install agent rules only')
   .option('-s, --skills', 'Install skills only')
   .option('-g, --github', 'Install GitHub Copilot instructions')
+  .option('-S, --subagents', 'Install agent subagents only')
   .option('-p, --preset <name>', 'Use a preset configuration (nextjs, django-react, express-api, fastapi, go-api)')
   .option('-f, --force', 'Overwrite existing files')
   .action(async (options) => {
@@ -121,7 +124,8 @@ program
               { name: 'Documentation files (agent-docs/)', value: 'docs' },
               { name: 'Agent rules (.github/instructions/rules/*.mdc)', value: 'rules' },
               { name: 'Skills (.github/skills/*)', value: 'skills' },
-              { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' }
+              { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
+              { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
             ],
             default: ['all']
           },
@@ -143,6 +147,7 @@ program
         if (options.rules) choices.push('rules');
         if (options.skills) choices.push('skills');
         if (options.github) choices.push('github');
+        if (options.subagents) choices.push('subagents');
       }
 
       const installAll = choices.includes('all');
@@ -185,9 +190,21 @@ program
         await writeGeneratedInstructions(targetDir, templateDir, options.force);
         console.log(chalk.gray('  ✓ Claude (CLAUDE.md — canonical source)'));
         console.log(chalk.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md pointer)'));
+        console.log(chalk.gray('  ✓ Cursor (.cursorrules pointer)'));
         console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD pointer)'));
       }
 
+      // Install agent subagents
+      if (installAll || choices.includes('subagents')) {
+        console.log(chalk.yellow('Installing agent subagents...'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
+        await copyDirectory(
+          path.join(templateDir, '.claude', 'agents'),
+          path.join(targetDir, LAYOUT.canonical.subagentsDir),
+          options.force
+        );
+      }
+
       console.log(chalk.green.bold('\nInstallation complete!\n'));
       console.log(chalk.cyan('Next steps:'));
       console.log(chalk.white('  1. Review CLAUDE.md (canonical AI policy — edit this directly)'));
@@ -240,7 +257,8 @@ program
                 { name: 'Documentation (agent-docs/)', value: 'docs' },
                 { name: 'Agent Rules (security, testing, database, etc.)', value: 'rules' },
                 { name: 'Skills (reusable agent capabilities)', value: 'skills' },
-                { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' }
+                { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
+                { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
               ],
               validate: (answer) => {
                 if (answer.length === 0) {
@@ -276,7 +294,8 @@ program
             { name: 'Documentation (agent-docs/)', value: 'docs', checked: true },
             { name: 'Agent Rules (security, testing, database, etc.)', value: 'rules', checked: true },
             { name: 'Skills (reusable agent capabilities)', value: 'skills', checked: true },
-            { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github', checked: true }
+            { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github', checked: true },
+            { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents', checked: true }
           ],
           validate: (answer) => {
             if (answer.length === 0) {
@@ -301,7 +320,8 @@ program
         docs: componentAnswers.components.includes('docs'),
         rules: componentAnswers.components.includes('rules'),
         skills: componentAnswers.components.includes('skills'),
-        github: componentAnswers.components.includes('github')
+        github: componentAnswers.components.includes('github'),
+        subagents: componentAnswers.components.includes('subagents')
       };
 
       // Install documentation files
@@ -345,6 +365,17 @@ program
         console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD pointer)'));
       }
 
+      // Install agent subagents
+      if (options.subagents) {
+        console.log(chalk.yellow('Installing agent subagents...'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
+        await copyDirectory(
+          path.join(templateDir, '.claude', 'agents'),
+          path.join(targetDir, LAYOUT.canonical.subagentsDir),
+          options.force
+        );
+      }
+
       // Show summary and next steps
       console.log(chalk.green.bold('\n✅ Installation complete!\n'));
       
@@ -375,6 +406,7 @@ program
     console.log(chalk.yellow('rules') + '   - Agent rules (.github/instructions/rules/*.mdc)');
     console.log(chalk.yellow('skills') + '  - Agent skills (.github/skills/*)');
     console.log(chalk.yellow('github') + '  - AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)');
+    console.log(chalk.yellow('subagents') + ' - Agent subagents (.claude/agents/*.md)');
     console.log(chalk.yellow('all') + '     - All components');
     
     console.log(chalk.blue.bold('\n\nAvailable Presets:\n'));
@@ -462,6 +494,15 @@ program
         warnings.push(`⚠ ${LAYOUT.canonical.skillsDir} directory missing - run 'agents-templated init --skills'`);
       }
 
+      // Check subagents
+      const subagentsDir = path.join(targetDir, LAYOUT.canonical.subagentsDir);
+      if (await fs.pathExists(subagentsDir)) {
+        const subagents = (await fs.readdir(subagentsDir)).filter(f => f.endsWith('.md') && f !== 'README.md');
+        passed.push(`✓ ${subagents.length} subagents installed in ${LAYOUT.canonical.subagentsDir}`);
+      } else {
+        warnings.push(`⚠ ${LAYOUT.canonical.subagentsDir} directory missing - run 'agents-templated init --subagents'`);
+      }
+
       // Check instruction pointer files and drift
       const instructionDrift = await validateInstructionDrift(targetDir);
       if (instructionDrift.missingCanonical) {
@@ -613,7 +654,6 @@ async function cleanupLegacyInstructionFiles(targetDir) {
   // Files removed in v2.0.0: orphaned wrappers that contained duplicated policy
   // content and were not managed/validated by the generator.
   const legacyFiles = [
-    '.cursorrules',
     '.github/instructions/AGENTS.md',
     // Pre-v1.2.13 paths
     '.claude/CLAUDE.md'
@@ -630,7 +670,7 @@ async function cleanupLegacyInstructionFiles(targetDir) {
 
 async function updateSelectedComponents(targetDir, templateDir, selectedComponents, overwrite = true) {
   const components = selectedComponents.includes('all')
-    ? ['docs', 'rules', 'skills', 'github']
+    ? ['docs', 'rules', 'skills', 'github', 'subagents']
     : selectedComponents;
 
   if (components.includes('docs')) {
@@ -670,6 +710,16 @@ async function updateSelectedComponents(targetDir, templateDir, selectedComponen
     await cleanupLegacyInstructionFiles(targetDir);
   }
 
+  if (components.includes('subagents')) {
+    console.log(chalk.yellow('Updating agent subagents...'));
+    await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
+    await copyDirectory(
+      path.join(templateDir, '.claude', 'agents'),
+      path.join(targetDir, LAYOUT.canonical.subagentsDir),
+      overwrite
+    );
+  }
+
   if ((components.includes('docs') || components.includes('github')) && !components.includes('github')) {
     await writeGeneratedInstructions(targetDir, templateDir, overwrite);
   }
@@ -704,6 +754,7 @@ program
   .option('-r, --rules', 'Update agent rules only')
   .option('-s, --skills', 'Update skills only')
   .option('-g, --github', 'Update AI agent instruction files only')
+  .option('-S, --subagents', 'Update agent subagents only')
   .option('-c, --check-only', 'Only check for updates, don\'t install')
   .option('-f, --force', 'Force overwrite files during update')
   .action(async (options) => {
@@ -763,6 +814,7 @@ program
         if (options.all || options.rules) selectedComponents.push('rules');
         if (options.all || options.skills) selectedComponents.push('skills');
         if (options.all || options.github) selectedComponents.push('github');
+        if (options.all || options.subagents) selectedComponents.push('subagents');
 
         console.log(chalk.blue('📦 Updating selected components...\n'));
 
@@ -977,6 +1029,22 @@ program
     }
   });
 
+program
+  .command('new-subagent <name>')
+  .description('Scaffold a new subagent in .claude/agents/<name>.md')
+  .action(async (name) => {
+    try {
+      const targetDir = process.cwd();
+      const relPath = await scaffoldSubagent(targetDir, name);
+      console.log(chalk.green(`\n+ ${relPath}\n`));
+      console.log(chalk.gray('Fill in Activation Conditions, Workflow, and Output Format.'));
+      console.log(chalk.gray('Then add it to the Subagent modules table in CLAUDE.md.\n'));
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
 program.parse(process.argv);
 
 // Show help if no command provided

package/index.js

@@ -16,12 +16,13 @@ const { CANONICAL_INSTRUCTION_FILE, writeGeneratedInstructions } = require('./li
  * @param {boolean} options.rules - Install agent rules
  * @param {boolean} options.skills - Install skills
  * @param {boolean} options.github - Install GitHub Copilot instructions
+ * @param {boolean} options.subagents - Install agent subagents
  * @param {boolean} options.force - Overwrite existing files
  * @returns {Promise<void>}
  */
 async function install(targetDir, options = {}) {
   const templateDir = path.join(__dirname, 'templates');
-  const installAll = !options.docs && !options.rules && !options.skills && !options.github;
+  const installAll = !options.docs && !options.rules && !options.skills && !options.github && !options.subagents;
 
   const files = [];
 
@@ -73,6 +74,16 @@ async function install(targetDir, options = {}) {
     await fs.ensureDir(path.join(targetDir, '.github', 'instructions'));
     await writeGeneratedInstructions(targetDir, templateDir, options.force);
   }
+
+  // Agent subagents (.claude/agents/)
+  if (installAll || options.subagents) {
+    await fs.ensureDir(path.join(targetDir, '.claude', 'agents'));
+    await copyDirectory(
+      path.join(templateDir, '.claude', 'agents'),
+      path.join(targetDir, '.claude', 'agents'),
+      options.force
+    );
+  }
 }
 
 async function copyDirectory(sourceDir, targetDir, force = false) {

package/lib/instructions.js

@@ -7,7 +7,8 @@ const CANONICAL_INSTRUCTION_FILE = 'CLAUDE.md';
 // Thin compatibility pointer files — policy lives in CLAUDE.md, not here.
 const POINTER_FILES = {
   agents: 'AGENTS.MD',
-  copilot: '.github/copilot-instructions.md'
+  copilot: '.github/copilot-instructions.md',
+  cursor: '.cursorrules'
 };
 
 function buildAgentsPointer() {
@@ -31,6 +32,17 @@ function buildCopilotPointer() {
   ].join('\n');
 }
 
+function buildCursorPointer() {
+  return [
+    '<!-- Tool profile: cursor-compat -->',
+    '# Cursor Rules',
+    '',
+    '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');
+}
+
 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);
@@ -42,7 +54,8 @@ async function writeGeneratedInstructions(targetDir, templateDir, force = false)
   // Write thin pointer files
   const pointers = {
     [POINTER_FILES.agents]: buildAgentsPointer(),
-    [POINTER_FILES.copilot]: buildCopilotPointer()
+    [POINTER_FILES.copilot]: buildCopilotPointer(),
+    [POINTER_FILES.cursor]: buildCursorPointer()
   };
 
   for (const [relPath, content] of Object.entries(pointers)) {
@@ -63,7 +76,8 @@ async function validateInstructionDrift(targetDir) {
   const driftFiles = [];
   const expectedPointers = {
     [POINTER_FILES.agents]: buildAgentsPointer(),
-    [POINTER_FILES.copilot]: buildCopilotPointer()
+    [POINTER_FILES.copilot]: buildCopilotPointer(),
+    [POINTER_FILES.cursor]: buildCursorPointer()
   };
 
   for (const [relPath, expectedContent] of Object.entries(expectedPointers)) {
@@ -157,11 +171,53 @@ async function scaffoldRule(targetDir, ruleName) {
   return `agents/rules/${ruleName}.mdc`;
 }
 
+async function scaffoldSubagent(targetDir, name) {
+  const subagentFile = path.join(targetDir, '.claude', 'agents', `${name}.md`);
+
+  if (await fs.pathExists(subagentFile)) {
+    throw new Error(`Subagent already exists: .claude/agents/${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 `.claude/agents/${name}.md`;
+}
+
 module.exports = {
   CANONICAL_INSTRUCTION_FILE,
   POINTER_FILES,
   writeGeneratedInstructions,
   validateInstructionDrift,
   scaffoldSkill,
-  scaffoldRule
+  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: '.claude/agents'
   },
   legacy: {
     rulesDirs: ['agents/rules'],
@@ -39,10 +40,17 @@ function resolveSkillsDir(baseDir) {
   return firstExistingPath(baseDir, candidates) || LAYOUT.canonical.skillsDir;
 }
 
+function resolveSubagentsDir(baseDir) {
+  const candidates = [LAYOUT.canonical.subagentsDir, 'agents/subagents'];
+  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),
+    path.join(baseDir, 'agents', 'subagents'),
     ...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 +98,7 @@ module.exports = {
   LAYOUT,
   resolveRulesDir,
   resolveSkillsDir,
+  resolveSubagentsDir,
   hasAnyLayout,
   getLegacyMigrationPlan
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "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/.claude/agents/README.md

@@ -0,0 +1,76 @@
+# Subagents
+
+Subagents are bounded agent processes that your orchestrator (main AI) can delegate tasks to with limited scope. Each subagent is defined as a single Markdown file with YAML frontmatter specifying its tools, model, and activation conditions.
+
+## What Are Subagents?
+
+- **Limited scope** — each subagent has one primary job and restricted tool access
+- **Delegatable** — the orchestrator assigns tasks and subagents execute autonomously
+- **Composable** — subagents work alongside skills; a subagent can invoke skills within its scope
+- **Tool profile: copilot-compat** — YAML frontmatter is read natively by Claude Code; other tools treat the file as plain instructions
+
+## Available Subagents
+
+| Subagent | Model | Purpose |
+|----------|-------|---------|
+| `planner` | opus | Break down features into phased, ordered implementation plans |
+| `architect` | opus | System design, ADRs, scalability trade-off analysis |
+| `tdd-guide` | sonnet | Write tests first — Red-Green-Refactor lifecycle |
+| `code-reviewer` | sonnet | Quality review with CRITICAL/HIGH/MEDIUM/LOW severity |
+| `security-reviewer` | sonnet | OWASP Top 10 scan, secrets detection, auth review |
+| `build-error-resolver` | sonnet | Fix build/type errors with minimal diff, no refactoring |
+| `e2e-runner` | sonnet | Execute Playwright E2E test suites and report results |
+| `refactor-cleaner` | sonnet | Remove dead code, unused deps, orphaned exports |
+| `doc-updater` | haiku | Sync README, API docs, and codemaps after code changes |
+
+## Model Selection Guide
+
+| Model | When to use |
+|-------|------------|
+| `claude-opus-4-5` | Complex reasoning: feature planning, architecture decisions |
+| `claude-sonnet-4-5` | Balanced: code review, security scan, testing, build fixes |
+| `claude-haiku-4-5` | Lightweight: documentation sync, simple transformations |
+
+## Invocation
+
+### Claude Code (native)
+Subagents are invoked automatically based on `description` matching, or explicitly:
+```
+/planner Build a multi-tenant authentication system
+/code-reviewer Review the changes in src/auth/
+```
+
+### Other tools (Copilot, Cursor, Windsurf)
+Reference the subagent file directly in your prompt or instruct your AI to follow the workflow defined in `.claude/agents/<name>.md`.
+
+## File Structure
+
+```
+.claude/agents/
+├── README.md                  ← This file
+├── planner.md
+├── architect.md
+├── tdd-guide.md
+├── code-reviewer.md
+├── security-reviewer.md
+├── build-error-resolver.md
+├── e2e-runner.md
+├── refactor-cleaner.md
+└── doc-updater.md
+```
+
+## Adding a New Subagent
+
+```bash
+agents-templated new-subagent <name>
+```
+
+Then add it to the Reference Index in `CLAUDE.md`.
+
+## Guardrails
+
+All subagents inherit the constraints from `CLAUDE.md`:
+- Security and testing rules are non-overrideable
+- Destructive actions require `CONFIRM-DESTRUCTIVE:<target>`
+- Subagents must stop and report on failure, never silently retry
+- No subagent may expose secrets, credentials, or PII

package/templates/.claude/agents/architect.md

@@ -0,0 +1,106 @@
+---
+name: architect
+description: Use when making significant system design decisions, evaluating architectural trade-offs, or producing Architecture Decision Records (ADRs) for a new or evolving system.
+tools: ["Read", "Grep", "Glob"]
+model: claude-opus-4-5
+---
+
+# Architect
+
+You are a system design agent. Your job is to reason deeply about architectural decisions, evaluate trade-offs, and produce durable Architecture Decision Records (ADRs) — not to write implementation code.
+
+## Activation Conditions
+
+Invoke this subagent when:
+- Designing a new system, service, or major module from scratch
+- Evaluating whether to refactor, replace, or extend existing architecture
+- Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL, etc.)
+- Producing a formal ADR for a significant decision
+- Planning for scalability (10K → 100K → 1M users)
+
+## Workflow
+
+### 1. Understand context
+- Read existing architecture docs, README, and key source files
+- Identify: current stack, team constraints, performance requirements, security posture
+- Clarify the decision trigger: what problem is this architecture solving?
+
+### 2. Identify architectural options
+- Enumerate 2-4 realistic alternatives (including "keep current" where applicable)
+- For each option: describe the approach in 2-3 sentences
+
+### 3. Trade-off analysis
+For each option, evaluate:
+- **Pros**: concrete advantages
+- **Cons**: concrete disadvantages, risks
+- **Cost**: implementation effort, operational overhead
+- **Fit**: how well it matches current constraints
+
+### 4. Scalability projection
+- Describe behavior at current scale, 10× scale, 100× scale
+- Identify the likely bottleneck at each level
+- Recommend the inflection point where architecture should change
+
+### 5. Decision and ADR
+- State the recommended option and primary rationale
+- Produce a formal ADR in the standard format
+
+### 6. Implementation guidance
+- List the highest-priority first steps to realize the architecture
+- Flag dependencies and sequencing constraints
+
+## Output Format
+
+```
+## Context
+{What problem is being solved and why now}
+
+## Options Considered
+
+### Option A: {name}
+{2-3 sentence description}
+- Pros: ...
+- Cons: ...
+- Estimated effort: {Low/Med/High}
+
+### Option B: {name}
+...
+
+## Trade-off Matrix
+| Criterion | Option A | Option B | Option C |
+|-----------|---------|---------|---------|
+| Scalability | ... | ... | ... |
+| Complexity | ... | ... | ... |
+| Security | ... | ... | ... |
+| Ops burden | ... | ... | ... |
+
+## Scalability Projection
+- Current scale (~{N} users/req): {behavior}
+- 10× scale: {behavior, bottleneck}
+- 100× scale: {behavior, bottleneck, recommended change}
+
+## Architecture Decision Record (ADR)
+
+**Title**: {short imperative title}
+**Status**: Proposed
+**Date**: {today}
+
+**Decision**: {one paragraph — what was decided and why}
+
+**Consequences**:
+- Positive: ...
+- Negative: ...
+- Neutral: ...
+
+## First Steps
+1. ...
+2. ...
+```
+
+## Guardrails
+
+- Do not write implementation code — produce architecture artifacts only
+- Every decision that affects auth, data storage, or external APIs must include a security consideration
+- Call out single points of failure explicitly
+- Do not recommend an option without stating its primary downside
+- If the existing architecture is already appropriate, say so clearly — do not engineer for the sake of it