forgedev 1.0.2 → 1.1.3

package/README.md

@@ -6,16 +6,19 @@ Universal, AI-first project scaffolding CLI. Describe what you're building, get
 
 ```bash
 # New project — guided (for beginners)
-npx devforge new my-app
+npx forgedev new my-app
 
 # New project — shorthand
-npx devforge my-app
+npx forgedev my-app
 
 # Add dev guardrails to existing project
-npx devforge init
+npx forgedev init
 
 # Diagnose and optimize existing project
-npx devforge doctor
+npx forgedev doctor
+
+# Check for updates
+npx forgedev update
 ```
 
 ## Four Modes, Four Audiences
@@ -25,7 +28,7 @@ npx devforge doctor
 Describe what you want in plain English. DevForge picks the stack.
 
 ```
-$ npx devforge new my-app
+$ npx forgedev new my-app
 
   🔨 DevForge — Let's build something.
 
@@ -52,7 +55,7 @@ Tell me about what you want to build:
   │
   └── Developer tools:
       • Code quality checks (catches errors automatically)
-      • Guided workflows (type /project:help anytime you're stuck)
+      • Guided workflows (type /workflows anytime you're stuck)
       • Testing templates
 
 ? Sound right? Yes — create it!
@@ -63,7 +66,7 @@ Zero technical jargon. DevForge makes all the decisions. After scaffolding, gene
 ### 2. Developer Mode (developers who know their stack)
 
 ```
-$ npx devforge new my-app
+$ npx forgedev new my-app
 
 ? How would you like to start?
   ⚡ I know my stack — let me pick
@@ -91,7 +94,7 @@ $ npx devforge new my-app
 
 ```
 $ cd my-existing-project
-$ npx devforge init
+$ npx forgedev init
 
   🔨 DevForge — Adding dev guardrails
 
@@ -100,14 +103,18 @@ $ npx devforge init
   Detected: nextjs (typescript) + fastapi (python) + postgresql (prisma) + vitest + playwright + pytest
 
   Installing:
+  ✓ CLAUDE.md — project context + rules
   ✓ .claude/hooks/ — auto-lint, quality gate, file protection
   ✓ .claude/agents/ — code quality, security, spec validator
-  ✓ .claude/commands/ — help, status, next, done, audit, pre-pr
+  ✓ .claude/commands/ — workflows, status, next, done, audit, pre-pr
   ✓ .claude/skills/ — framework-specific knowledge
   ✓ docs/uat/ — acceptance test templates
-  ⊘ CLAUDE.md — exists (tip: run /project:optimize-claude-md to slim it)
 
-  Done. Type /project:help to get started.
+  Done. Your project is now configured for Claude Code.
+
+  Next steps:
+    1. Open Claude Code in this directory: claude
+    2. Type /workflows to see available workflows
 ```
 
 Zero questions. Scans, detects, installs.
@@ -115,7 +122,7 @@ Zero questions. Scans, detects, installs.
 ### 4. Doctor Mode (diagnose & optimize existing projects)
 
 ```
-$ npx devforge doctor
+$ npx forgedev doctor
 
   🔨 DevForge Doctor — Project Health Check
 
@@ -170,14 +177,51 @@ Every project includes:
 
 With Claude Code infrastructure enabled (default):
 
-- **CLAUDE.md** tailored to your stack
-- **Hooks** — auto-lint on edit, quality gate on stop
-- **Skills** — framework-specific knowledge
-- **Agents** — 5-agent verification chain
-- **Commands** — verify-all, audit-spec, audit-wiring, audit-security, pre-pr, run-uat, generate-prd, generate-uat, optimize-claude-md
+- **CLAUDE.md** tailored to your stack (with pitfalls and agents quick-reference)
+- **Hooks** — cross-platform Node.js `.mjs` hooks (auto-lint on edit, quality gate, protected file guard)
+- **17 Agents** — verification, development, review, and orchestration (see below)
+- **20 Commands** — daily workflow, verification, release, development, session management
+- **8 Skills** — framework-specific + universal knowledge
 - **UAT templates** — scenario packs and CSV checklists
 - **Prompt library** — the complete development prompt library
 
+## Agents (17)
+
+Every scaffolded project gets these agents in `.claude/agents/`:
+
+| Agent | Role | Access |
+|-------|------|--------|
+| `architect` | System design, data models, API contracts | Read-only |
+| `build-error-resolver` | Fix build/lint/type errors with minimal changes | Write |
+| `chief-of-staff` | Orchestrate multiple agents for complex tasks | Write |
+| `code-quality-reviewer` | Code quality review | Read-only |
+| `database-reviewer` | Query optimization, schema review, N+1 detection | Read-only |
+| `doc-updater` | Keep docs in sync with code changes | Write |
+| `docs-lookup` | Search framework docs for answers | Read-only |
+| `e2e-runner` | Generate and run Playwright E2E tests | Write |
+| `harness-optimizer` | Audit Claude Code setup, suggest optimizations | Read-only |
+| `loop-operator` | Autonomous improvement loops with stop conditions | Write |
+| `planner` | Create implementation plans before coding | Read-only |
+| `production-readiness` | Production deployment readiness review | Read-only |
+| `refactor-cleaner` | Dead code removal, duplicate elimination | Write |
+| `security-reviewer` | Security audit | Read-only |
+| `spec-validator` | Validate implementation matches specification | Read-only |
+| `tdd-guide` | Enforce RED-GREEN-REFACTOR TDD cycle | Write |
+| `uat-validator` | QA validation of UAT scenarios | Read-only |
+
+## Skills (8)
+
+| Skill | Scope |
+|-------|-------|
+| `nextjs` | Next.js 15 App Router patterns |
+| `fastapi` | FastAPI + SQLAlchemy 2.0 + Pydantic v2 |
+| `playwright` | Playwright E2E testing |
+| `security-web` | Web application security |
+| `security-api` | API security |
+| `ai-prompts` | AI/LLM integration patterns |
+| `git-workflow` | Git branching, commits, PR workflow (universal) |
+| `testing-patterns` | Test pyramid, AAA pattern, mocking (universal) |
+
 ## Development
 
 ```bash
@@ -186,6 +230,7 @@ npm test                           # run unit tests
 node bin/devforge.js test-output   # manual smoke test (guided + developer)
 node bin/devforge.js init          # test init mode (from any project dir)
 node bin/devforge.js doctor        # test doctor mode (from any project dir)
+node bin/devforge.js update        # check for updates
 ```
 
 ## Project Structure
@@ -194,7 +239,7 @@ node bin/devforge.js doctor        # test doctor mode (from any project dir)
 devforge/
 ├── bin/devforge.js              # CLI entry point
 ├── src/
-│   ├── cli.js                   # Command router (new, init, doctor)
+│   ├── cli.js                   # Command router (new, init, doctor, update)
 │   ├── index.js                 # New project orchestrator (guided + developer)
 │   ├── guided.js                # Guided mode (description → stack)
 │   ├── prompts.js               # Interactive prompts (Inquirer.js)
@@ -207,6 +252,8 @@ devforge/
 │   ├── doctor.js                # Doctor mode orchestrator
 │   ├── doctor-checks.js         # Diagnostic check functions
 │   ├── doctor-prompts.js        # Fix prompt generators
+│   ├── update-check.js          # npm registry version check
+│   ├── update.js                # Update command handler
 │   └── utils.js                 # File ops, logging, colors
 ├── templates/                   # Scaffold templates by category
 │   ├── base/                    # Every project gets this
@@ -221,17 +268,66 @@ devforge/
 └── docs/                        # Reference documentation
 ```
 
-## Claude Code Commands
+## Claude Code Commands (20)
+
+After running `npx forgedev init`, these slash commands are available inside Claude Code:
+
+**Daily Workflow:**
+
+| Command | What It Does |
+|---------|-------------|
+| `/workflows` | Lists all available workflows |
+| `/status` | Project dashboard — tests, branch, changes |
+| `/next` | Figures out your next task |
+| `/done` | Verifies task completion |
+
+**Verification:**
 
 | Command | What It Does |
 |---------|-------------|
-| `/project:help` | Asks your situation, gives the exact prompt |
-| `/project:status` | Project dashboard — tests, branch, changes |
-| `/project:next` | Figures out your next task |
-| `/project:done` | Verifies task completion |
-| `/project:generate-prd` | Generates a PRD with Mermaid diagrams |
-| `/project:generate-uat` | Generates UAT scenarios from codebase |
-| `/project:optimize-claude-md` | Proposes splitting an oversized CLAUDE.md |
+| `/verify-all` | Runs lint, type check, tests, then launches reviewers |
+| `/full-audit` | Runs every audit and review agent in a single pass |
+| `/audit-spec` | Validates implementation against a spec/PRD |
+| `/audit-wiring` | Finds dead or unwired features |
+| `/audit-security` | Runs a security audit |
+| `/code-review` | Reviews uncommitted changes for security and quality |
+
+**Release:**
+
+| Command | What It Does |
+|---------|-------------|
+| `/pre-pr` | Runs the complete pre-PR checklist |
+| `/run-uat` | Executes UAT scenarios |
+
+**Development:**
+
+| Command | What It Does |
+|---------|-------------|
+| `/plan` | Invoke planner agent for implementation planning |
+| `/build-fix` | Incrementally fix build/lint/type errors |
+| `/tdd` | Enforce test-driven development cycle |
+| `/generate-prd` | Generates a PRD with Mermaid diagrams |
+| `/generate-uat` | Generates UAT scenarios from codebase |
+| `/optimize-claude-md` | Proposes splitting an oversized CLAUDE.md |
+
+**Session:**
+
+| Command | What It Does |
+|---------|-------------|
+| `/save-session` | Save work context for later resumption |
+| `/resume-session` | Load saved session and continue where you left off |
+
+## Install
+
+```bash
+# Use directly (no install needed)
+npx forgedev new my-app
+
+# Or install globally
+npm install -g forgedev
+```
+
+Package name on npm: [`forgedev`](https://www.npmjs.com/package/forgedev)
 
 ## Roadmap
 

package/bin/devforge.js

@@ -1,4 +1,13 @@
 #!/usr/bin/env node
 import { parseCommand } from '../src/cli.js';
 
-parseCommand(process.argv.slice(2));
+try {
+  await parseCommand(process.argv.slice(2));
+} catch (err) {
+  // Graceful exit on Ctrl+C / prompt cancellation
+  if (err?.name === 'ExitPromptError' || err?.code === 'ERR_USE_AFTER_CLOSE') {
+    console.log('');
+    process.exit(0);
+  }
+  throw err;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedev",
-  "version": "1.0.2",
+  "version": "1.1.3",
   "description": "Universal, AI-first project scaffolding CLI with Claude Code infrastructure",
   "type": "module",
   "bin": {

package/src/claude-configurator.js

@@ -69,7 +69,10 @@ function buildClaudeVars(config) {
   }
 
   // Build skills list for CLAUDE.md reference
-  const skillsList = [];
+  const skillsList = [
+    '- `@.claude/skills/git-workflow/` — Git branching, commits, and PR workflow',
+    '- `@.claude/skills/testing-patterns/` — Test pyramid, AAA pattern, mocking strategies',
+  ];
   if (config.frontend?.framework === 'nextjs') {
     skillsList.push('- `@.claude/skills/nextjs/` — Next.js patterns and conventions');
     skillsList.push('- `@.claude/skills/security-web/` — Frontend security practices');
@@ -112,17 +115,17 @@ function generateClaudeMd(outputDir, config, vars) {
 
 function generateHooks(outputDir, config, options = {}) {
   let hookFile;
-  let scriptFiles = ['guard-protected-files.sh'];
+  let scriptFiles = ['guard-protected-files.mjs'];
 
   if (config.stackId === 'nextjs-fullstack') {
     hookFile = 'typescript.json';
-    scriptFiles.push('autofix-typescript.sh');
+    scriptFiles.push('autofix-typescript.mjs');
   } else if (config.stackId === 'fastapi-backend') {
     hookFile = 'python.json';
-    scriptFiles.push('autofix-python.sh');
+    scriptFiles.push('autofix-python.mjs');
   } else if (config.stackId === 'polyglot-fullstack') {
     hookFile = 'polyglot.json';
-    scriptFiles.push('autofix-polyglot.sh');
+    scriptFiles.push('autofix-polyglot.mjs');
   }
 
   const settingsPath = path.join(outputDir, '.claude', 'settings.json');
@@ -175,7 +178,8 @@ function deepMergeSettings(existing, incoming) {
 }
 
 function generateSkills(outputDir, config) {
-  const skillsToInclude = [];
+  // Universal skills — always included
+  const skillsToInclude = ['git-workflow', 'testing-patterns'];
 
   if (config.frontend?.framework === 'nextjs') {
     skillsToInclude.push('nextjs');
@@ -210,6 +214,18 @@ function generateAgents(outputDir, config, vars) {
     'spec-validator.md',
     'production-readiness.md',
     'uat-validator.md',
+    'build-error-resolver.md',
+    'planner.md',
+    'doc-updater.md',
+    'tdd-guide.md',
+    'refactor-cleaner.md',
+    'e2e-runner.md',
+    'architect.md',
+    'database-reviewer.md',
+    'docs-lookup.md',
+    'chief-of-staff.md',
+    'loop-operator.md',
+    'harness-optimizer.md',
   ];
 
   for (const agent of agents) {
@@ -238,6 +254,13 @@ function generateCommands(outputDir, config, vars) {
     'generate-prd.md',
     'generate-uat.md',
     'optimize-claude-md.md',
+    'plan.md',
+    'build-fix.md',
+    'code-review.md',
+    'tdd.md',
+    'save-session.md',
+    'resume-session.md',
+    'full-audit.md',
   ];
 
   for (const cmd of commands) {

package/src/cli.js

@@ -46,6 +46,12 @@ export async function parseCommand(args) {
     return;
   }
 
+  if (command === 'update') {
+    const { runUpdate } = await import('./update.js');
+    await runUpdate();
+    return;
+  }
+
   // Shorthand: devforge my-app → devforge new my-app
   if (!command.startsWith('-')) {
     const targetDir = path.resolve(process.cwd(), command);
@@ -73,6 +79,7 @@ function showUsage() {
     devforge new <name>     Create a new project
     devforge init           Add dev guardrails to current project
     devforge doctor         Diagnose and optimize current project
+    devforge update         Check for newer version
     devforge <name>         Shorthand for ${chalk.dim('devforge new <name>')}
 
   ${chalk.bold('Options:')}
@@ -105,6 +112,10 @@ function showHelp() {
       flaky tests, dead code, duplicate code, and more.
       Generates Claude Code prompts to fix each issue.
 
+    ${chalk.bold('devforge update')}
+      Check if a newer version of DevForge is available.
+      Shows upgrade instructions if an update exists.
+
   ${chalk.bold('Supported stacks (V1):')}
     - Next.js full-stack (TypeScript + Prisma + PostgreSQL)
     - FastAPI backend (Python + SQLAlchemy + PostgreSQL)

package/src/doctor-prompts.js

@@ -176,6 +176,15 @@ ${fileList}
 
 Extract all prompts into a dedicated prompts file (e.g., src/lib/prompts.ts or prompts/). This makes prompts easier to version, A/B test, and iterate on without changing application code.`;
   },
+
+  DEVFORGE_UPDATE: (issue) => {
+    return `A newer version of DevForge is available.
+
+Run: npm install -g forgedev@latest
+Then re-run: npx forgedev init
+
+This will update your project's agents, commands, skills, and hooks to the latest version.`;
+  },
 };
 
 export function generatePrompt(issue) {
@@ -223,8 +232,6 @@ export function generateReport(issues, projectName) {
   const critical = issues.filter(i => i.severity === 'critical');
   const warnings = issues.filter(i => i.severity === 'warning');
   const info = issues.filter(i => i.severity === 'info');
-  const healthy = []; // Could be populated by passing in good checks
-
   let report = `# DevForge Doctor Report — ${projectName}
 Generated: ${new Date().toISOString().split('T')[0]}
 

package/src/doctor.js

@@ -29,6 +29,25 @@ export async function runDoctor(projectDir) {
   // Run all checks
   const issues = runAllChecks(projectDir, scan);
 
+  // Check for DevForge updates (5s timeout, won't crash on failure)
+  try {
+    const { checkForUpdate } = await import('./update-check.js');
+    const updateResult = await checkForUpdate();
+    if (updateResult?.updateAvailable) {
+      issues.push({
+        severity: 'info',
+        title: `DevForge update available: ${updateResult.current} → ${updateResult.latest}`,
+        impact: 'Newer version may include improved agents, commands, and bug fixes',
+        files: [],
+        autoFixable: false,
+        promptId: 'DEVFORGE_UPDATE',
+        effort: 'quick',
+      });
+    }
+  } catch {
+    // Silently ignore — network issues shouldn't block doctor
+  }
+
   if (issues.length === 0) {
     console.log(chalk.green('  ✓ Your project looks healthy! No issues found.'));
     console.log('');

package/src/index.js

@@ -11,6 +11,13 @@ import { generateUAT } from './uat-generator.js';
 
 export async function runNew(projectName) {
   const safeName = toKebabCase(projectName);
+
+  // Prevent path traversal — project name must not escape cwd
+  if (/[\/\\]/.test(safeName) || safeName.includes('..')) {
+    log.error('Project name must not contain path separators or ".."');
+    process.exit(1);
+  }
+
   const outputDir = path.resolve(process.cwd(), safeName);
 
   if (fs.existsSync(outputDir)) {

package/src/update-check.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+
+const PACKAGE_NAME = 'forgedev';
+
+/**
+ * Compare two semver strings (major.minor.patch).
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+export function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Check npm registry for a newer version of forgedev.
+ * Returns { current, latest, updateAvailable } or null on failure.
+ */
+export async function checkForUpdate() {
+  const pkg = JSON.parse(
+    fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8')
+  );
+  const currentVersion = pkg.version;
+
+  try {
+    const response = await fetch(
+      `https://registry.npmjs.org/${PACKAGE_NAME}/latest`,
+      { signal: AbortSignal.timeout(5000) }
+    );
+    if (!response.ok) return null;
+    const data = await response.json();
+    const latestVersion = data.version;
+
+    // Validate version format before trusting registry response
+    if (!/^\d+\.\d+\.\d+/.test(latestVersion)) return null;
+
+    return {
+      current: currentVersion,
+      latest: latestVersion,
+      updateAvailable: compareVersions(latestVersion, currentVersion) > 0,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/update.js

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { log } from './utils.js';
+import { checkForUpdate } from './update-check.js';
+
+export async function runUpdate() {
+  console.log('');
+  console.log(chalk.bold.cyan('  DevForge') + chalk.dim(' — Checking for updates...'));
+  console.log('');
+
+  const result = await checkForUpdate();
+
+  if (result === null) {
+    log.warn('  Could not reach the npm registry. Check your internet connection.');
+    console.log('');
+    return;
+  }
+
+  if (!result.updateAvailable) {
+    log.success(`  ✓ You're on the latest version (${result.current})`);
+    console.log('');
+    return;
+  }
+
+  log.warn(`  Update available: ${result.current} → ${result.latest}`);
+  console.log('');
+  console.log('  To update:');
+  console.log(`    ${chalk.bold('npm install -g forgedev@latest')}   ${chalk.dim('(if installed globally)')}`);
+  console.log(`    ${chalk.bold('npx forgedev@latest new my-app')}  ${chalk.dim('(one-time use)')}`);
+  console.log('');
+  log.dim('  To update an existing project\'s Claude Code infrastructure:');
+  log.dim('    cd my-project && npx forgedev@latest init');
+  console.log('');
+}

package/templates/auth/jwt-custom/backend/app/core/security.py.template

@@ -1,3 +1,4 @@
+import os
 from datetime import datetime, timedelta, timezone
 
 from jose import JWTError, jwt
@@ -7,7 +8,9 @@ from app.core.config import settings
 
 pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
 
-SECRET_KEY = "change-me-in-production"  # TODO: Move to settings/env
+SECRET_KEY = os.environ.get("JWT_SECRET_KEY")
+if not SECRET_KEY:
+    raise RuntimeError("JWT_SECRET_KEY environment variable is required. Set it in your .env file.")
 ALGORITHM = "HS256"
 ACCESS_TOKEN_EXPIRE_MINUTES = 30
 

package/templates/backend/fastapi/backend/app/core/config.py.template

@@ -6,8 +6,8 @@ class Settings(BaseSettings):
     app_name: str = "{{PROJECT_NAME_PASCAL}}"
     debug: bool = False
 
-    # Database
-    database_url: str = "postgresql+asyncpg://postgres:postgres@localhost:5432/{{PROJECT_NAME_SNAKE}}"
+    # Database — no default: must be set via .env or environment
+    database_url: str
 
     # CORS
     cors_origins: list[str] = ["http://localhost:3000"]

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

@@ -0,0 +1,70 @@
+---
+description: System design specialist for data models, API contracts, service boundaries, and architectural decisions.
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+You are a software architecture specialist. Your job is to design systems that are modular, scalable, and maintainable.
+
+## Architecture Review Process
+
+1. **Current state analysis** — Read existing code to understand what's built
+2. **Requirements gathering** — Clarify functional and non-functional requirements
+3. **Design proposal** — Propose architecture with clear rationale
+4. **Trade-off analysis** — Compare alternatives with pros/cons
+
+## Architectural Principles
+
+- **Modularity** — Each module has a single responsibility and clear boundaries
+- **Scalability** — Design can handle 10x growth without rewriting
+- **Maintainability** — New developers can understand the system in < 1 day
+- **Security** — Defense in depth, principle of least privilege
+- **Performance** — Optimize hot paths, lazy-load cold paths
+
+## Common Patterns
+
+**Frontend**: Component composition, container/presenter, custom hooks, context for global state, code splitting for routes
+
+**Backend**: Repository pattern for data access, service layer for business logic, middleware for cross-cutting concerns, event-driven for async work
+
+**Data**: Normalized schemas, cursor-based pagination, caching strategy (in-memory → Redis → CDN), eventual consistency where appropriate
+
+## Architecture Decision Records (ADRs)
+
+For significant decisions, produce an ADR:
+
+```markdown
+# ADR: [Title]
+
+## Status: Proposed
+
+## Context
+[Why this decision is needed]
+
+## Decision
+[What we chose and why]
+
+## Alternatives Considered
+[What else we looked at and why we rejected it]
+
+## Consequences
+[What changes as a result — positive and negative]
+```
+
+## Red Flags to Identify
+
+- Tight coupling between unrelated modules
+- God objects (one class/file doing everything)
+- Premature optimization before measuring
+- Not-invented-here syndrome (rebuilding existing libraries)
+- Missing error boundaries between services
+- No clear data ownership (multiple services writing the same table)
+
+## Rules
+
+- NEVER write code — only produce designs and recommendations
+- Always consider the simplest solution first
+- Flag when a proposed architecture is over-engineered for the project size
+- Recommend specific libraries/tools, not generic categories

package/templates/claude-code/agents/build-error-resolver.md

@@ -0,0 +1,30 @@
+---
+description: Fix build, lint, and type errors with minimal, targeted changes. No architectural edits.
+---
+
+You are a build error resolution specialist. Your job is to fix build/type/lint errors with the smallest possible changes.
+
+## Workflow
+
+1. **Collect errors** — Run `{{BUILD_COMMAND}}`, `{{LINT_COMMAND}}`, and `{{TYPE_CHECK_COMMAND}}` to capture all errors
+2. **Group by file** — Sort errors by file path, fix in dependency order (imports/types before logic)
+3. **Fix one error at a time** — Read the file, diagnose root cause, apply minimal edit
+4. **Verify** — After each fix, re-run all three commands to confirm the error is gone and no new errors were introduced
+## Common Fix Patterns
+
+| Error Type | Fix |
+|-----------|-----|
+| Missing import | Add the import statement |
+| Type mismatch | Add type annotation or assertion |
+| Undefined variable | Check spelling, add declaration, or fix import |
+| Missing dependency | Suggest install command (`npm install X` or `pip install X`) |
+| Config error | Compare with known working defaults |
+| Circular dependency | Identify the cycle, suggest extraction to shared module |
+
+## Rules
+
+- **DO**: Add type annotations, null checks, fix imports, update configs
+- **DON'T**: Refactor working code, change architecture, rename files, add features
+- Fix must change less than 5% of the file — if more is needed, stop and report
+- If the same error persists after 3 attempts, stop and ask the user
+- If a fix introduces more errors than it resolves, revert and ask the user