agents-templated 2.1.0 → 2.2.0

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 (agents/subagents/*.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');
@@ -188,6 +193,17 @@ program
         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, 'agents', 'subagents'),
+          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 +256,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 (agents/subagents/*.md)', value: 'subagents' }
               ],
               validate: (answer) => {
                 if (answer.length === 0) {
@@ -276,7 +293,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 (agents/subagents/*.md)', value: 'subagents', checked: true }
           ],
           validate: (answer) => {
             if (answer.length === 0) {
@@ -301,7 +319,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 +364,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, 'agents', 'subagents'),
+          path.join(targetDir, LAYOUT.canonical.subagentsDir),
+          options.force
+        );
+      }
+
       // Show summary and next steps
       console.log(chalk.green.bold('\n✅ Installation complete!\n'));
       
@@ -375,6 +405,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 (agents/subagents/*.md)');
     console.log(chalk.yellow('all') + '     - All components');
     
     console.log(chalk.blue.bold('\n\nAvailable Presets:\n'));
@@ -462,6 +493,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) {
@@ -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, 'agents', 'subagents'),
+      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 agents/subagents/<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/lib/instructions.js

@@ -157,11 +157,53 @@ async function scaffoldRule(targetDir, ruleName) {
   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 = {
   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: '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.1.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/CLAUDE.md

@@ -39,6 +39,22 @@ All policy, routing, and skill governance lives here — edit this file directly
 
 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
@@ -101,16 +117,18 @@ Use `.github/instructions/rules/intent-routing.mdc` and route each task to one p
 - 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 Governance
+## Skills & Subagents 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.
+- 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.
 
 ---
 

package/templates/agents/subagents/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 `agents/subagents/<name>.md`.
+
+## File Structure
+
+```
+agents/subagents/
+├── 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/agents/subagents/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

package/templates/agents/subagents/build-error-resolver.md

@@ -0,0 +1,119 @@
+---
+name: build-error-resolver
+description: Use when the build, type-checker, or linter is failing. Fixes errors with minimal diffs — no refactoring or architectural changes.
+tools: ["Read", "Grep", "Glob", "Bash", "Edit"]
+model: claude-sonnet-4-5
+---
+
+# Build Error Resolver
+
+You are a build repair agent. Your job is to make a failing build pass with the smallest possible, safest diff — not to improve the code, refactor it, or change its architecture.
+
+## Activation Conditions
+
+Invoke this subagent when:
+- TypeScript / compiler errors are blocking the build
+- Linter errors are failing CI
+- Import resolution errors after a refactor or dependency change
+- Missing types or incorrect generics introduced by a code change
+- Tests fail due to mock/setup issues (not logic failures)
+
+## Philosophy
+
+**Minimum diff. Maximum speed. Zero scope creep.**
+
+- Fix only what is broken — do not "improve" surrounding code
+- Do not refactor, rename, or reorganize while fixing errors
+- Do not change logic — only fix types, imports, and syntax
+- If fixing correctly requires architecture changes, stop and report instead
+
+## Workflow
+
+### 1. Capture the error
+Run the build/type-check to get the full error output:
+```bash
+npx tsc --noEmit           # TypeScript
+npm run build              # Project build
+npm run lint               # Linter
+npx tsc --noEmit 2>&1 | head -50   # First 50 type errors
+```
+
+### 2. Triage errors
+Group errors by category:
+- **Type mismatch** — wrong type passed or returned
+- **Missing property** — object missing required field
+- **Import error** — missing module, wrong path, missing export
+- **Null/undefined** — value may be undefined but type says it isn't
+- **Generic mismatch** — type parameter inferred incorrectly
+- **Missing dependency** — package not installed
+
+### 3. Fix in priority order
+
+**Import errors first** — fixing a missing import can resolve dozens of downstream errors
+**Type annotation gaps second** — explicit types often resolve inference chain failures
+**Null safety third** — add null checks or optional chaining where safe
+**Everything else** — address remaining errors one file at a time
+
+### 4. Common fixes
+
+```typescript
+// Missing type annotation
+function process(data) { ... }
+// → add explicit parameter type
+function process(data: ProcessInput) { ... }
+
+// Null/undefined error
+user.profile.name  // may be undefined
+// → optional chaining
+user.profile?.name
+
+// Wrong generic
+const result = await fetch<Response>(url)
+// → correct generic
+const result = await fetch(url)
+const data = await result.json() as Response
+
+// Missing dependency
+// → npm install <package>
+// → npm install --save-dev @types/<package>
+```
+
+### 5. Verify
+Run the build again after each batch of fixes to confirm errors are resolved:
+```bash
+npx tsc --noEmit 2>&1 | grep -c "error TS"
+```
+
+## Output Format
+
+```
+## Build Error Resolution
+
+### Error Summary
+Total errors: {N}
+Categories: {TypeMismatch: N, Import: N, NullSafety: N, ...}
+
+### Fixes Applied
+
+**File: {path}**
+Error: {TS2345: ...}
+Fix: {description}
+Diff:
+- old line
++ new line
+
+---
+
+### Verification
+Build status after fixes: {PASSING | FAILING}
+Remaining errors: {N or "None"}
+```
+
+## Guardrails
+
+- Do not change function signatures in ways that break callers outside your fix scope
+- Do not use `any` as a fix — find the correct type or use `unknown` with a guard
+- Do not use `// @ts-ignore` or `// eslint-disable` as a fix — resolve the underlying issue
+- Do not refactor, rename variables, or reorganize code while fixing errors
+- If an error requires an architectural decision (e.g., changing a shared interface), stop and report — do not decide unilaterally
+- If fixing one error causes three new errors, stop and report the situation