forgedev 1.1.3 → 1.2.0

package/docs/prompt-library.md

@@ -0,0 +1,160 @@
+# DevForge Prompt Library
+
+8 workflow guides for developing DevForge. Each workflow includes the exact prompts to use.
+
+---
+
+## Flow 1: Add a New Stack
+
+When you want to add support for a new tech stack (e.g., Hono, React+Vite, Express).
+
+**Step 1: Plan**
+```
+I want to add [stack] support to DevForge. Enter plan mode. Research:
+1. What files/directories are needed for a typical [stack] project
+2. What dependencies go in package.json / requirements.txt
+3. What the recommender decision tree should look like
+Write a plan to docs/plans/add-[stack].md
+```
+
+**Step 2: Templates**
+```
+Following the plan in docs/plans/add-[stack].md, create template files in
+templates/[category]/[stack]/. Use {{VARIABLE_NAME}} for substitution.
+Follow the patterns in existing templates like templates/frontend/nextjs/.
+```
+
+**Step 3: Recommender**
+```
+Update src/recommender.js to route to the new [stack] templates.
+Add the new templateModules paths. Update formatStackSummary.
+```
+
+**Step 4: Test**
+```
+Add tests in tests/recommender.test.js for the new stack routing.
+Run npx vitest run to verify all tests pass.
+```
+
+---
+
+## Flow 2: Create a New Template
+
+When adding individual template files to an existing stack.
+
+```
+I want to add a [template] to the [stack] stack. Create the template file at
+templates/[category]/[stack]/[path]. Use {{VARIABLE_NAME}} placeholders where
+the project name, description, or config values should go. Check
+src/composer.js buildVariables() for available variables.
+```
+
+---
+
+## Flow 3: Fix a Bug
+
+**Step 1: Reproduce**
+```
+There's a bug: [describe]. Write a failing test in tests/ that reproduces it.
+Run npx vitest run to confirm the test fails.
+```
+
+**Step 2: Fix**
+```
+Fix the bug that causes [test name] to fail. Run npx vitest run to confirm
+the fix and that no other tests break.
+```
+
+---
+
+## Flow 4: Refactor
+
+```
+I want to refactor [module/function]. Enter plan mode. First:
+1. Check test coverage for the code being refactored
+2. Add tests for any uncovered behavior
+3. Plan the refactoring steps (each should keep tests green)
+Write a plan to docs/plans/refactor-[module].md
+```
+
+---
+
+## Flow 5: Add a Feature
+
+For features that touch multiple modules (prompts, recommender, composer, configurator).
+
+**Step 1: Plan**
+```
+I want to add [feature] to DevForge. Enter plan mode. Trace through:
+- src/prompts.js — does the user need to be asked anything new?
+- src/recommender.js — does the decision tree change?
+- src/composer.js — are new template variables needed?
+- src/claude-configurator.js — does the generated infrastructure change?
+- src/uat-generator.js — do UAT scenarios need updating?
+Write a plan to docs/plans/[feature].md
+```
+
+**Step 2: Implement**
+```
+Following docs/plans/[feature].md, implement the feature. Work module by module.
+Run npx vitest run after each module change.
+```
+
+---
+
+## Flow 6: Verification
+
+```
+Run /project:verify-all
+```
+
+This launches all 5 agents (code-quality, security, spec-validator, production-readiness, uat-validator) and runs tests.
+
+---
+
+## Flow 7: Pre-PR
+
+```
+Run /project:pre-pr
+```
+
+This runs tests, smoke test, code quality review, security review, and checks for staged secrets.
+
+---
+
+## Flow 8: UAT
+
+```
+Run /project:run-uat
+```
+
+This reads docs/uat/UAT_TEMPLATE.md, maps scenarios to tests, runs them, and updates UAT_CHECKLIST.csv.
+
+---
+
+## Utility Prompts
+
+### "I'm lost"
+```
+Read CLAUDE.md, git log --oneline -10, and git status. Tell me where I am,
+what I was working on, and what I should do next.
+```
+
+### "Is this right?"
+```
+Review my changes (git diff). Check if they follow DevForge patterns:
+ESM imports with .js extensions, chalk for output, path.join for paths,
+{{VARIABLE}} for templates. Flag anything that looks wrong.
+```
+
+### "Before I PR"
+```
+Run /project:pre-pr
+```
+
+### "Explain this code"
+```
+Read [file] and explain what it does, how it fits into the DevForge pipeline
+(prompts → recommender → composer → configurator → uat-generator), and what
+calls it.
+```

package/docs/uat/UAT_CHECKLIST.csv

@@ -0,0 +1,9 @@
+UAT_ID,Scenario,Priority,Automated,Test_File,Status,Last_Run,Notes
+UAT-001,Scaffold Next.js Full-Stack,P0,PARTIAL,tests/composer.test.js,NOT RUN,,Manual smoke test required
+UAT-002,Scaffold FastAPI Backend,P0,PARTIAL,tests/composer.test.js,NOT RUN,,Manual smoke test required
+UAT-003,Scaffold Polyglot Full-Stack,P0,PARTIAL,tests/composer.test.js,NOT RUN,,Manual smoke test required
+UAT-004,Recommender Selects Correct Stack,P0,YES,tests/recommender.test.js,NOT RUN,,
+UAT-005,Template Variable Substitution,P0,YES,tests/composer.test.js,NOT RUN,,
+UAT-006,Claude Code Infrastructure Generated,P1,YES,tests/claude-configurator.test.js,NOT RUN,,
+UAT-007,Invalid Input Handling,P1,NO,,NOT RUN,,Manual test required
+UAT-008,Unsupported Stack Selection,P1,PARTIAL,tests/recommender.test.js,NOT RUN,,

package/docs/uat/UAT_TEMPLATE.md

@@ -0,0 +1,163 @@
+# UAT Scenario Pack: DevForge
+
+## Pre-Conditions
+- [ ] Node.js >= 18 installed
+- [ ] npm available
+- [ ] DevForge dependencies installed (`npm install`)
+- [ ] No existing `test-output/` directory
+
+## Scenarios
+
+### UAT-001: Scaffold Next.js Full-Stack Project — Happy Path
+**Priority:** P0
+**Preconditions:** Clean environment, no test-output/ directory
+**Steps:**
+1. Run `node bin/devforge.js test-output`
+2. Select "Full-stack app"
+3. Select "TypeScript" for language
+4. Select "Yes" for authentication
+5. Select "No" for AI integration
+6. Select "Docker" for deployment
+7. Confirm the recommended stack
+**Expected Result:**
+- `test-output/` directory created
+- Contains `package.json` with Next.js, React, TypeScript, Tailwind, Prisma, NextAuth dependencies
+- Contains `src/app/layout.tsx`, `src/app/page.tsx`
+- Contains `src/app/api/health/route.ts` (health check endpoint)
+- Contains `prisma/schema.prisma`
+- Contains `.claude/` directory with hooks, agents, commands
+- Contains `CLAUDE.md` with Next.js-specific rules
+- Contains `docs/uat/UAT_TEMPLATE.md`
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___
+
+### UAT-002: Scaffold FastAPI Backend Project — Happy Path
+**Priority:** P0
+**Preconditions:** Clean environment, no test-output/ directory
+**Steps:**
+1. Run `node bin/devforge.js test-output`
+2. Select "API / backend service"
+3. Select "Python" for language
+4. Select "Yes" for authentication
+5. Select "No" for AI integration
+6. Select "Docker" for deployment
+7. Confirm the recommended stack
+**Expected Result:**
+- `test-output/` directory created
+- Contains `backend/requirements.txt` with FastAPI, SQLAlchemy, Pydantic
+- Contains `backend/app/main.py` with health endpoint and graceful shutdown
+- Contains `backend/app/api/health.py`
+- Contains `backend/app/core/config.py`, `errors.py`, `retry.py`
+- Contains `backend/tests/` with pytest fixtures
+- Contains `.claude/` directory with Python-specific hooks
+- Contains `CLAUDE.md` with FastAPI-specific rules
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___
+
+### UAT-003: Scaffold Polyglot Full-Stack Project — Happy Path
+**Priority:** P0
+**Preconditions:** Clean environment, no test-output/ directory
+**Steps:**
+1. Run `node bin/devforge.js test-output`
+2. Select "Full-stack app"
+3. Select "TypeScript" and "Python" for language
+4. Select "Yes" for authentication
+5. Select "Yes" for AI integration
+6. Select "Docker" for deployment
+7. Confirm the recommended stack
+**Expected Result:**
+- `test-output/` directory created
+- Contains both `frontend/` and `backend/` directories
+- Contains `docker-compose.yml` at root
+- Contains Next.js frontend and FastAPI backend
+- Contains both Prisma and SQLAlchemy database configs
+- Contains polyglot Claude Code hooks (TypeScript + Python)
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___
+
+### UAT-004: Recommender Selects Correct Stack
+**Priority:** P0
+**Preconditions:** None
+**Steps:**
+1. Run `npx vitest run tests/recommender.test.js`
+2. Verify all test cases pass
+3. Verify: web_app + TypeScript → Next.js full-stack
+4. Verify: api_service + Python → FastAPI backend
+5. Verify: full_stack + TS + Python → polyglot
+6. Verify: unsupported combos return helpful error
+**Expected Result:** All recommender tests pass, all 3 stacks correctly selected
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___
+
+### UAT-005: Template Variable Substitution
+**Priority:** P0
+**Preconditions:** None
+**Steps:**
+1. Run `npx vitest run tests/composer.test.js`
+2. Verify `{{PROJECT_NAME}}` replaced in all .template files
+3. Verify non-.template files copied without modification
+4. Verify .gitkeep files preserved
+5. Verify no `{{` patterns remain in output
+**Expected Result:** All composer tests pass, variables correctly substituted
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___
+
+### UAT-006: Claude Code Infrastructure Generated
+**Priority:** P1
+**Preconditions:** Scaffold a project first
+**Steps:**
+1. Run `npx vitest run tests/claude-configurator.test.js`
+2. Verify `.claude/settings.json` created with correct hooks
+3. Verify CLAUDE.md generated with stack-specific content
+4. Verify agents copied (5 agents)
+5. Verify skills copied (filtered by stack)
+6. Verify commands copied (6 commands)
+**Expected Result:** All claude-configurator tests pass, infrastructure complete
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___
+
+### UAT-007: Invalid Input Handling
+**Priority:** P1
+**Preconditions:** None
+**Steps:**
+1. Run `node bin/devforge.js` (no project name) — should show error
+2. Run `node bin/devforge.js .` (invalid name) — should show error
+3. Create `test-output/` dir, then run `node bin/devforge.js test-output` — should warn about existing dir
+**Expected Result:** Clear error messages, no crashes, exit code 1
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___
+
+### UAT-008: Unsupported Stack Selection
+**Priority:** P1
+**Preconditions:** None
+**Steps:**
+1. Run `node bin/devforge.js test-output`
+2. Select "Mobile app" or "Desktop app"
+3. Observe the recommendation
+**Expected Result:** Displays message that the stack is not yet supported in V1, suggests closest supported option
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedev",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Universal, AI-first project scaffolding CLI with Claude Code infrastructure",
   "type": "module",
   "bin": {
@@ -29,5 +29,13 @@
   },
   "engines": {
     "node": ">=18.0.0"
-  }
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "docs/",
+    "LICENSE",
+    "README.md"
+  ]
 }

package/src/claude-configurator.js

@@ -226,6 +226,7 @@ function generateAgents(outputDir, config, vars) {
     'chief-of-staff.md',
     'loop-operator.md',
     'harness-optimizer.md',
+    'product-strategist.md',
   ];
 
   for (const agent of agents) {

package/src/cli.js

@@ -56,11 +56,11 @@ export async function parseCommand(args) {
   if (!command.startsWith('-')) {
     const targetDir = path.resolve(process.cwd(), command);
     if (fs.existsSync(targetDir)) {
-      console.log('');
+      console.error('');
       log.warn(`"${command}" already exists. Did you mean:`);
-      console.log(`  ${chalk.bold('devforge init')}     Add dev guardrails to current project`);
-      console.log(`  ${chalk.bold('devforge doctor')}   Diagnose and optimize current project`);
-      console.log('');
+      console.error(`  ${chalk.bold('devforge init')}     Add dev guardrails to current project`);
+      console.error(`  ${chalk.bold('devforge doctor')}   Diagnose and optimize current project`);
+      console.error('');
       process.exit(1);
     }
     const { runNew } = await import('./index.js');
@@ -86,7 +86,7 @@ function showUsage() {
     -h, --help              Show this help message
     -v, --version           Show version number
 
-  Run ${chalk.cyan('devforge new --help')} for more details.
+  Run ${chalk.cyan('devforge --help')} for more details.
 `);
 }
 

package/src/index.js

@@ -12,9 +12,9 @@ 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 ".."');
+  // Validate project name — must be a clean kebab-case identifier
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(safeName)) {
+    log.error('Project name must start with a letter or number and contain only lowercase letters, numbers, and hyphens.');
     process.exit(1);
   }
 

package/src/utils.js

@@ -11,7 +11,7 @@ export const ROOT_DIR = path.resolve(__dirname, '..');
 export const log = {
   info: (msg) => console.log(chalk.cyan(msg)),
   success: (msg) => console.log(chalk.green(msg)),
-  warn: (msg) => console.log(chalk.yellow(msg)),
+  warn: (msg) => console.error(chalk.yellow(msg)),
   error: (msg) => console.error(chalk.red(msg)),
   step: (n, total, msg) => console.log(chalk.blue(`[${n}/${total}] ${msg}`)),
   dim: (msg) => console.log(chalk.dim(msg)),

package/templates/base/docs/uat/UAT_CHECKLIST.csv.template

@@ -0,0 +1,2 @@
+UAT_ID,Feature,Priority,Status,Tester,Date,Defect_ID,Notes
+UAT-001,Health Check,P0,NOT RUN,,,,

package/templates/base/docs/uat/UAT_TEMPLATE.md.template

@@ -0,0 +1,22 @@
+# UAT Scenario Pack: {{PROJECT_NAME}}
+
+## Pre-Conditions
+- [ ] Application is deployed to staging
+- [ ] Test accounts are created
+- [ ] Test data is seeded
+
+## Scenarios
+
+### UAT-001: Health Check — Happy Path
+**Priority:** P0
+**Preconditions:** Application is running
+**Steps:**
+1. Send GET request to /health (or /api/health)
+2. Verify response status is 200
+3. Verify response body contains status: "ok"
+**Expected Result:** Health endpoint responds with 200 and status ok
+**Actual Result:** ___
+**Status:** NOT RUN
+**Tester:** ___
+**Date:** ___
+**Notes:** ___

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

@@ -10,16 +10,17 @@ You are a build error resolution specialist. Your job is to fix build/type/lint
 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 |
+| Type mismatch | Add correct type annotation, adjust code to match expected types, or fix the actual type |
 | 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 |
+| Circular dependency | Identify the cycle, report to user with suggested breaking strategies |
 
 ## Rules
 

package/templates/claude-code/agents/code-quality-reviewer.md

@@ -38,4 +38,4 @@ Stack: {{STACK_SUMMARY}}
 - [ ] Functions are reasonably sized (< 50 lines)
 
 ## Output
-For each issue: **File** | **Line** | **Severity** (critical/warning/info) | **Issue** | **Fix**
+For each issue: **File** | **Line** | **Severity** (critical/high/medium/low) | **Issue** | **Fix**

package/templates/claude-code/agents/database-reviewer.md

@@ -46,7 +46,7 @@ You are a database specialist. Your job is to review database code for performan
 | `SELECT *` | Fetches unnecessary data, breaks on schema change | Specify exact columns |
 | OFFSET pagination | Slow on large tables (scans skipped rows) | Use cursor-based pagination |
 | N+1 queries | 1 query per row instead of 1 query for all | Use joins or eager loading |
-| String IDs | Poor index performance | Use UUID or serial |
+| String IDs | Poor index performance | Use sequential identifiers (SERIAL, UUIDv7) |
 | No connection pooling | Exhausts database connections | Use connection pool |
 | `GRANT ALL` | Violates least privilege | Grant specific permissions |
 

package/templates/claude-code/agents/doc-updater.md

@@ -6,7 +6,7 @@ You are a documentation specialist. Your job is to keep project documentation ac
 
 ## Workflow
 
-1. **Detect changes** — Run `git diff --name-only HEAD~1` to see files changed in the last commit
+1. **Detect changes** — Run `git diff --name-only HEAD~1` to see files changed in the last commit (or `git diff --name-only` for uncommitted changes)
 2. **Identify affected docs** — Map code changes to documentation that needs updating
 3. **Update docs** — Edit README, API docs, changelogs, and inline comments
 4. **Verify links** — Check that all referenced files and endpoints still exist

package/templates/claude-code/agents/harness-optimizer.md

@@ -40,6 +40,32 @@ You are a Claude Code harness optimizer. Your job is to audit the project's Clau
 - [ ] No commands that duplicate agent functionality
 - [ ] Commands reference correct tool commands for the project's stack
 
+### Internal Consistency (cross-template validation)
+- [ ] No contradictory guidelines across agents, skills, and CLAUDE.md
+  - Cross-reference DO/DON'T rules — ensure fix suggestions don't violate their own rules
+  - Verify branching/rebase/merge advice is consistent across git-workflow skill and CLAUDE.md
+- [ ] No duplicate guidelines (same advice in multiple places → stale risk)
+- [ ] All severity levels referenced in report outputs are defined with criteria
+- [ ] All process steps referenced in output sections have matching report formats
+- [ ] Hook scripts: path validation uses `cwd + sep` (not bare `startsWith`)
+- [ ] Hook scripts: `cwd` option matches expected filePath prefix (no double-prefix bug)
+- [ ] Settings files: no hardcoded absolute paths or debug artifacts in permissions
+
+### Technical Accuracy (advice matches reality)
+- [ ] Framework-specific advice matches actual framework behavior
+  - Server Components can't use client hooks (useState, useEffect)
+  - Pydantic v2 doesn't reject extra fields by default (needs `extra = "forbid"`)
+  - Playwright: getByRole/getByLabel preferred over CSS selectors
+- [ ] Code examples use valid syntax (JSON with quoted keys, correct API signatures)
+- [ ] Version-specific features match the version declared in CLAUDE.md
+
+### Formatting Integrity (no corrupted templates)
+- [ ] No merged lines (two steps concatenated without newline)
+- [ ] No duplicate content on same line
+- [ ] Markdown tables have correct column counts per row
+- [ ] All files end with a trailing newline
+- [ ] Proper blank lines between sections (## heading preceded by blank line)
+
 ## Output Format
 
 ```

package/templates/claude-code/agents/loop-operator.md

@@ -14,7 +14,8 @@ Execute iterative improvement loops safely: run a sequence of checks → fixes
 2. **Set stop conditions** — Define when to stop (all tests pass, zero lint errors, or max 5 iterations)
 3. **Execute iteration** — Fix one category of issues per iteration
 4. **Checkpoint** — After each iteration, record progress and compare to baseline
-5. **Evaluate** — If no progress across 2 consecutive iterations, stop and report6. **Report** — Show baseline vs final state with concrete numbers
+5. **Evaluate** — If no progress across 2 consecutive iterations, stop and report
+6. **Report** — Show baseline vs final state with concrete numbers
 
 ## Stop Conditions (halt the loop if any are true)
 

package/templates/claude-code/agents/product-strategist.md

@@ -0,0 +1,124 @@
+---
+description: Research competitors via web search, evaluate project maturity against industry leaders, and recommend strategic improvements with competitive context.
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+# Product Strategist
+
+You are a product strategist for {{PROJECT_NAME_PASCAL}}. Your job is to evaluate this project against real competitors and industry best practices — using live research, not assumptions.
+
+## Process
+
+### Phase 1: Understand the Project
+1. Read CLAUDE.md, package.json/pyproject.toml, and project structure
+2. Read product documents if they exist: PRD (`docs/prd/`), user stories (`docs/stories/`), or any spec files
+3. Identify the project's domain, stack, target audience, and stated goals
+4. List the project's current features and capabilities
+
+### Phase 2: Competitive Research (Web Search Required)
+5. **Search for direct competitors** — Use WebSearch to find 5-7 projects/products that solve the same problem
+6. **Search for best-in-class examples** — Find the top-rated or most-starred open source projects in the same domain
+7. **Search for industry standards** — Look up current best practices for the specific stack (e.g., "Next.js 15 production best practices 2026", "FastAPI security checklist 2026")
+8. **Search for user reviews and feedback** — Find reviews, GitHub issues, Reddit threads, or forum discussions about competitors to understand what users love and hate
+9. Document what competitors offer that this project doesn't
+10. Document common user complaints about competitors (opportunities to differentiate)
+
+### Phase 3: Internal Evaluation
+11. Evaluate each category below against what competitors actually do (not abstract ideals)
+12. Rate: AHEAD (exceeds competitors), ON PAR (matches competitors), BEHIND (competitors do this, we don't), N/A
+
+## Evaluation Categories
+
+### Developer Experience
+- [ ] One-command setup (`npm install` or `docker compose up` → working app)
+- [ ] Hot reload in development
+- [ ] Meaningful error messages (not stack traces)
+- [ ] Automated code formatting on save
+- [ ] Pre-commit hooks for quality gates
+
+### API Design
+- [ ] OpenAPI/Swagger documentation auto-generated
+- [ ] Consistent error response format
+- [ ] API versioning strategy
+- [ ] Rate limiting
+- [ ] Pagination for list endpoints
+
+### Testing Strategy
+- [ ] Unit test coverage > 80%
+- [ ] E2E tests for critical user flows
+- [ ] CI runs tests on every PR
+- [ ] Test data factories/fixtures (not hardcoded test data)
+- [ ] Performance/load testing setup
+
+### Security Posture
+- [ ] Dependency vulnerability scanning (npm audit / safety)
+- [ ] Secret scanning in CI
+- [ ] OWASP Top 10 coverage
+- [ ] Content Security Policy headers
+- [ ] Input sanitization beyond basic validation
+
+### Observability
+- [ ] Structured logging (JSON, not plain text)
+- [ ] Request tracing (correlation IDs)
+- [ ] Health check endpoints (shallow + deep)
+- [ ] Error tracking integration (Sentry, etc.)
+- [ ] Performance monitoring
+
+### Deployment & Infrastructure
+- [ ] Containerized (Docker)
+- [ ] CI/CD pipeline
+- [ ] Environment parity (dev ≈ staging ≈ prod)
+- [ ] Database migration strategy
+- [ ] Rollback plan documented
+
+### Documentation
+- [ ] README with quickstart that works in < 5 minutes
+- [ ] API documentation (auto-generated preferred)
+- [ ] Architecture decision records (ADRs) for key decisions
+- [ ] Contributing guide
+- [ ] Changelog
+
+## Output
+
+### Competitive Landscape (5-7 competitors)
+| Competitor | What They Do Well | What Users Complain About | What We Do Better | Key Feature We're Missing |
+|-----------|-------------------|--------------------------|-------------------|--------------------------|
+| [name + link] | [specific feature] | [from reviews/issues] | [our advantage] | [gap] |
+
+### User Sentiment Summary
+Key themes from user reviews and discussions across competitors:
+- **Users love**: [common positive themes]
+- **Users hate**: [common pain points — opportunities for us]
+- **Most requested features**: [what users are asking for that nobody fully delivers]
+
+### Scorecard
+| Category | Rating | Competitor Benchmark | Our Status | Recommendation |
+|----------|--------|---------------------|------------|----------------|
+| [category] | AHEAD/ON PAR/BEHIND | [what competitors do] | [what we do] | [specific action] |
+
+### Strategic Recommendations
+For each finding, present the choice:
+
+**[Feature/Gap Name]**
+- Match: [What to implement to reach parity with competitors]
+- Exceed: [What to implement to go beyond competitors]
+- Skip: [Why it might be OK to skip this — trade-offs]
+- **Recommendation**: [Your informed opinion on which option and why]
+
+### Priority Roadmap
+1. [Highest impact — what to do first, with effort estimate]
+2. [Second priority]
+3. [Third priority]
+
+## Rules
+- Always use WebSearch — never rely solely on your training data for competitive info
+- Cite specific competitors by name with links
+- Be honest: if the project is already ahead, say so
+- Recommendations must be actionable: specific libraries, patterns, or implementations
+- Adapt categories to the actual stack (skip frontend checks for backend-only projects)
+- If the project is a CLI tool, compare against CLI tools, not web apps
+- Present choices, don't dictate — the user decides the strategy
+- Prioritize by impact-to-effort ratio

package/templates/claude-code/agents/security-reviewer.md

@@ -23,6 +23,7 @@ Read-only. Never modify code.
 - [ ] All user input validated before use
 - [ ] SQL injection prevention (parameterized queries/ORM)
 - [ ] XSS prevention (proper escaping/sanitization)
+- [ ] CSRF protection for state-changing operations
 - [ ] File upload validation (type, size, extension)
 
 ### Data Exposure