forgedev 1.0.2 → 1.1.3

package/templates/claude-code/commands/code-review.md

@@ -0,0 +1,44 @@
+Review uncommitted changes for security issues and code quality.
+
+## Step 1: Get Changed Files
+
+```bash
+git diff --name-only HEAD
+```
+
+## Step 2: Review Each File
+
+For each changed file, check:
+
+**Security (CRITICAL):**
+- Hardcoded credentials, API keys, tokens
+- SQL injection vulnerabilities
+- XSS vulnerabilities
+- Missing input validation
+- Path traversal risks
+
+**Code Quality (HIGH):**
+- Functions > 50 lines
+- Files > 800 lines
+- Nesting depth > 4 levels
+- Missing error handling
+- console.log / print statements left in
+- TODO/FIXME comments without tracking
+
+**Best Practices (MEDIUM):**
+- Missing tests for new code
+- Mutation of shared state (use immutable patterns)
+- Missing accessibility attributes (a11y)
+
+## Step 3: Generate Report
+
+For each issue found:
+- **Severity**: CRITICAL, HIGH, MEDIUM
+- **File**: path and line number
+- **Issue**: what's wrong
+- **Fix**: how to fix it
+## Step 4: Verdict
+
+- If CRITICAL issues found → block commit, list required fixes
+- If only MEDIUM/LOW → approve with suggestions
+- Never approve code with security vulnerabilities

package/templates/claude-code/commands/full-audit.md

@@ -0,0 +1,60 @@
+Run every audit and review agent in a single pass. Use this when you want a comprehensive project health check.
+
+## Step 1: Build + Lint + Tests
+
+1. Run lint: `{{LINT_COMMAND}}`
+2. Run type check: `{{TYPE_CHECK_COMMAND}}`
+3. Run tests: `{{TEST_COMMAND}}`
+
+If any step fails, report the failures but continue with the remaining audits.
+
+## Step 2: Code Review (changed files)
+
+1. Get changed files: `git diff --name-only HEAD`
+2. For each changed file, check for:
+   - Hardcoded credentials, API keys, tokens
+   - SQL injection, XSS, path traversal
+   - Functions > 50 lines, files > 800 lines
+   - Missing error handling, console.log left in
+   - Missing tests for new code
+
+## Step 3: Launch Review Agents
+
+Run these agents in sequence on the full codebase:
+
+1. **code-quality-reviewer** — code patterns, duplication, naming
+2. **security-reviewer** — vulnerabilities, secrets, unsafe operations
+3. **production-readiness** — deployment readiness, error handling, health checks
+4. **database-reviewer** — query performance, N+1, schema issues (skip if no database)
+
+## Step 4: Structural Audits
+
+1. **Wiring audit** — verify all API endpoints are connected between frontend and backend
+2. **Spec audit** — if `docs/` contains a spec/PRD, validate implementation coverage
+
+## Step 5: Claude Code Setup
+
+1. **harness-optimizer** — check if .claude/ setup follows best practices
+
+## Step 6: Summary Report
+
+Compile all findings into a single report grouped by severity:
+
+```
+CRITICAL (must fix before merge):
+  - [list]
+
+HIGH (fix soon):
+  - [list]
+
+MEDIUM (improve when possible):
+  - [list]
+
+LOW (nice to have):
+  - [list]
+
+PASSED:
+  - [list of checks that found no issues]
+```
+
+Include total counts: X critical, Y high, Z medium, W low.

package/templates/claude-code/commands/plan.md

@@ -0,0 +1,21 @@
+Invoke the **planner** agent to create a comprehensive implementation plan before writing any code.
+
+## Process
+
+1. Ask the user what they want to build (or use the description they provided)
+2. Launch the `planner` agent with the feature description
+3. The planner will analyze the codebase, break down the work into phases, and identify risks
+4. Present the plan and WAIT for user confirmation before proceeding
+
+## Important
+
+- NEVER write code until the user explicitly confirms the plan
+- If the user wants modifications, update the plan and re-present
+- After approval, suggest using `/tdd` to implement with test-driven development
+
+## Integration
+
+After planning, use these commands:
+- `/tdd` — implement with test-driven development
+- `/build-fix` — fix any build errors that come up
+- `/code-review` — review the completed implementation

package/templates/claude-code/commands/resume-session.md

@@ -0,0 +1,50 @@
+Load a saved session file and orient before doing any work.
+
+## Process
+
+1. **Find the session file** — Check `docs/sessions/` for the most recent `*-session.md` file
+2. **Read the entire file** — Do not summarize yet
+3. **Present a briefing** in this format:
+
+```
+SESSION LOADED: [file path]
+════════════════════════════════════════════════
+
+PROJECT: [project name / topic]
+
+WHAT WE'RE BUILDING:
+[2-3 sentence summary in your own words]
+
+CURRENT STATE:
+✅ Working: [count] items confirmed
+🔄 In Progress: [list files in progress]
+🗒️ Not Started: [list planned but untouched]
+
+WHAT NOT TO RETRY:
+[list every failed approach with its reason]
+
+OPEN QUESTIONS / BLOCKERS:
+[list any blockers]
+
+NEXT STEP:
+[exact next step from the file]
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+4. **WAIT for the user** — Do NOT start working automatically
+
+## Edge Cases
+
+- **No session files found** — Tell the user to run `/save-session` first
+- **Session references deleted files** — Note "⚠️ file.ts referenced but not found on disk"
+- **Session is > 7 days old** — Note "⚠️ This session is N days old, things may have changed"
+- **Empty or malformed file** — Report and suggest creating a new session
+
+## Rules
+
+- Never modify the session file — it's a read-only historical record
+- Never skip the "What Not To Retry" section — it's the most important
+- Always wait for the user before starting work
+- If the next step is defined and the user says "continue" — proceed with that exact step

package/templates/claude-code/commands/save-session.md

@@ -0,0 +1,69 @@
+Save the current session state so work can be resumed in a future conversation.
+
+## Process
+
+1. **Gather context** — Review what was discussed, built, and decided this session
+2. **Create folder** — `mkdir -p docs/sessions` (or `~/.claude/sessions/`)
+3. **Write session file** — `docs/sessions/YYYY-MM-DD-session.md`
+4. **Show to user** — Display contents and ask for corrections
+
+## Session File Format
+
+```markdown
+# Session: YYYY-MM-DD
+
+**Project:** [project name]
+**Topic:** [one-line summary]
+
+---
+
+## What We Are Building
+[1-3 paragraphs with enough context for someone with zero memory of this session]
+
+---
+
+## What WORKED (with evidence)
+- **[thing]** — confirmed by: [specific evidence like "tests pass", "200 response"]
+
+---
+
+## What Did NOT Work (and why)
+- **[approach]** — failed because: [exact reason / error message]
+
+---
+
+## What Has NOT Been Tried Yet
+- [approach worth exploring]
+
+---
+
+## Current State of Files
+
+| File | Status | Notes |
+|------|--------|-------|
+| `path/file.ts` | ✅ Complete | [what it does] |
+| `path/file.ts` | 🔄 In Progress | [what's left] |
+| `path/file.ts` | 🗒️ Not Started | [planned] |
+
+---
+
+## Decisions Made
+- **[decision]** — reason: [why]
+
+---
+
+## Blockers & Open Questions
+- [blocker or unanswered question]
+
+---
+
+## Exact Next Step
+[The single most important thing to do when resuming]
+```
+
+## Rules
+
+- Write every section honestly — "Nothing yet" is better than skipping a section
+- The "What Did NOT Work" section is the most critical — prevents retrying failed approaches
+- Each session gets its own file — never append to previous sessions
+- Wait for user confirmation before closing

package/templates/claude-code/commands/tdd.md

@@ -0,0 +1,80 @@
+Enforce test-driven development: write failing tests FIRST, then implement.
+
+## TDD Cycle
+
+```
+RED → GREEN → REFACTOR → REPEAT
+```
+
+1. **RED** — Write a failing test (because the code doesn't exist yet)
+2. **GREEN** — Write the minimum code to make the test pass
+3. **REFACTOR** — Improve the code while keeping tests green
+4. **REPEAT** — Next scenario
+
+## Process
+
+1. Ask the user what feature to implement
+2. Launch the `tdd-guide` agent
+3. Define types/interfaces first
+4. Write failing tests covering: happy path, edge cases, error cases
+5. Run `{{TEST_COMMAND}}` — verify tests FAIL for the right reason
+6. Implement minimal code to pass
+7. Run `{{TEST_COMMAND}}` — verify tests PASS
+8. Refactor if needed, keeping tests green
+9. Check coverage — target 80%+ minimum
+
+## Example
+
+```
+User: /tdd I need a function to validate email addresses
+
+Step 1 — SCAFFOLD:
+  Create types/interfaces for input and output
+
+Step 2 — RED (write failing tests):
+  - "should accept valid email: user@example.com"
+  - "should reject email without @"
+  - "should reject email without domain"
+  - "should reject empty string"
+  - "should handle unicode characters"
+
+Step 3 — Run tests → all FAIL (expected, no implementation yet)
+
+Step 4 — GREEN (implement minimal code):
+  Write just enough to pass all tests
+
+Step 5 — Run tests → all PASS
+
+Step 6 — REFACTOR:
+  Extract constants, improve naming, add JSDoc
+
+Step 7 — Run tests → still PASS
+
+Step 8 — Check coverage → 100%
+```
+
+## Rules
+
+- NEVER write implementation before tests
+- NEVER skip running tests after changes
+- Each test should test ONE behavior
+- Use descriptive names: "should return 404 when user not found"
+- Test behavior, not implementation details
+- Don't mock what you're testing
+
+## Coverage Targets
+
+- 80% minimum for all code
+- 100% required for: financial calculations, auth logic, security-critical code
+
+## Test Types to Include
+
+- **Unit**: happy path, edge cases (null, empty, max), error conditions, boundary values
+- **Integration**: API endpoints, database operations, auth flows
+- **E2E**: use `/e2e` command for full user journey tests
+
+## After TDD
+
+- `/build-fix` — if build errors come up
+- `/code-review` — review the implementation
+- `/done` — verify the task is complete

package/templates/claude-code/commands/workflows.md

@@ -2,13 +2,20 @@ Show the developer what workflows are available.
 
 ## Available Workflows
 
-### Daily Development
+### Development
+- `/plan` — Create an implementation plan before writing code
+- `/tdd` — Write failing tests first, then implement (test-driven development)
+- `/build-fix` — Fix build, lint, and type errors incrementally
+- `/code-review` — Review uncommitted changes for security and quality
+
+### Daily
 - `/status` — Run all checks and show a project dashboard
 - `/next` — Figure out what to work on next
 - `/done` — Verify the current task is complete before moving on
 
 ### Verification
 - `/verify-all` — Run lint, type check, tests, then launch all reviewers
+- `/full-audit` — Run every audit and review agent in a single pass
 - `/audit-spec` — Validate implementation against a spec/PRD
 - `/audit-wiring` — Find dead or unwired features
 - `/audit-security` — Run a security audit
@@ -22,5 +29,9 @@ Show the developer what workflows are available.
 - `/generate-uat` — Generate UAT scenarios and checklists
 - `/optimize-claude-md` — Slim down an oversized CLAUDE.md
 
+### Session
+- `/save-session` — Save current work context for later resumption
+- `/resume-session` — Load a saved session and continue where you left off
+
 ## Quick Start
 Run `/status` to see where things stand, then `/next` to pick up work.

package/templates/claude-code/hooks/polyglot.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash .claude/hooks/guard-protected-files.sh"
+            "command": "node .claude/hooks/guard-protected-files.mjs"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash .claude/hooks/autofix-polyglot.sh"
+            "command": "node .claude/hooks/autofix-polyglot.mjs"
           }
         ]
       }

package/templates/claude-code/hooks/python.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash .claude/hooks/guard-protected-files.sh"
+            "command": "node .claude/hooks/guard-protected-files.mjs"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash .claude/hooks/autofix-python.sh"
+            "command": "node .claude/hooks/autofix-python.mjs"
           }
         ]
       }

package/templates/claude-code/hooks/scripts/autofix-polyglot.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Auto-fix lint issues on saved TypeScript or Python files (polyglot)
+
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const filePath = data?.tool_input?.file_path || '';
+
+    if (!filePath || filePath.includes('..')) {
+      process.exit(0);
+    }
+
+    // Ensure path stays within the working directory
+    const resolved = resolve(filePath);
+    const cwd = resolve('.');
+    if (!resolved.startsWith(cwd)) {
+      process.exit(0);
+    }
+
+    if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
+      try {
+        execFileSync('npx', ['eslint', '--fix', filePath], { stdio: 'pipe', cwd: 'frontend' });
+      } catch {
+        // eslint may exit non-zero for unfixable issues — that's okay
+      }
+    } else if (filePath.endsWith('.py')) {
+      try {
+        execFileSync('ruff', ['check', '--fix', filePath], { stdio: 'pipe', cwd: 'backend' });
+      } catch {
+        // ruff may exit non-zero for unfixable issues — that's okay
+      }
+    }
+
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+});

package/templates/claude-code/hooks/scripts/autofix-python.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Auto-fix lint issues on saved Python files
+
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const filePath = data?.tool_input?.file_path || '';
+
+    if (!filePath || filePath.includes('..')) {
+      process.exit(0);
+    }
+
+    // Ensure path stays within the working directory
+    const resolved = resolve(filePath);
+    const cwd = resolve('.');
+    if (!resolved.startsWith(cwd)) {
+      process.exit(0);
+    }
+
+    if (filePath.endsWith('.py')) {
+      try {
+        execFileSync('ruff', ['check', '--fix', filePath], { stdio: 'pipe', cwd: 'backend' });
+      } catch {
+        // ruff may exit non-zero for unfixable issues — that's okay
+      }
+    }
+
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+});

package/templates/claude-code/hooks/scripts/autofix-typescript.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Auto-fix lint issues on saved TypeScript files
+
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const filePath = data?.tool_input?.file_path || '';
+
+    if (!filePath || filePath.includes('..')) {
+      process.exit(0);
+    }
+
+    // Ensure path stays within the working directory
+    const resolved = resolve(filePath);
+    const cwd = resolve('.');
+    if (!resolved.startsWith(cwd)) {
+      process.exit(0);
+    }
+
+    if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
+      try {
+        execFileSync('npx', ['eslint', '--fix', filePath], { stdio: 'pipe' });
+      } catch {
+        // eslint may exit non-zero for unfixable issues — that's okay
+      }
+    }
+
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+});

package/templates/claude-code/hooks/scripts/guard-protected-files.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// Block modifications to .env files and migration files
+// Exit 0 = allow, Exit 2 = block
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const filePath = data?.tool_input?.file_path || '';
+
+    if (!filePath) {
+      process.exit(0);
+    }
+
+    // Block .env files
+    const basename = filePath.split('/').pop().split('\\').pop();
+    if (basename === '.env' || basename.startsWith('.env.')) {
+      process.stderr.write('BLOCKED: Do not modify .env files directly\n');
+      process.exit(2);
+    }
+
+    // Block migration files
+    if (filePath.includes('prisma/migrations/') || filePath.includes('alembic/versions/')) {
+      process.stderr.write('BLOCKED: Do not modify migration files directly\n');
+      process.exit(2);
+    }
+
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+});

package/templates/claude-code/hooks/typescript.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash .claude/hooks/guard-protected-files.sh"
+            "command": "node .claude/hooks/guard-protected-files.mjs"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash .claude/hooks/autofix-typescript.sh"
+            "command": "node .claude/hooks/autofix-typescript.mjs"
           }
         ]
       }

package/templates/claude-code/skills/ai-prompts/SKILL.md

@@ -33,6 +33,7 @@ description: AI/LLM integration patterns and best practices
 ## Security
 - Never include user secrets in prompts
 - Sanitize user input before including in prompts
+- Protect against prompt injection attacks (delimiter tokens, input validation, output filtering)
 - Validate and sanitize AI output before using
 - Don't trust AI output for security decisions
 

package/templates/claude-code/skills/fastapi/SKILL.md

@@ -29,7 +29,7 @@ description: FastAPI + SQLAlchemy 2.0 + Pydantic v2 patterns
 - Raise `AppError` subclasses, never `HTTPException` with raw strings
 - Global exception handler catches unhandled errors
 - Never expose stack traces or internal details to clients
-- Use structured error format: `{ error: { code, message } }`
+- Use structured error format: `{ "error": { "code": "ERR_CODE", "message": "Error description" } }`
 
 ## Testing
 - Use `httpx.AsyncClient` with `ASGITransport` for async tests

package/templates/claude-code/skills/git-workflow/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: git-workflow
+description: Git branching, commits, PR workflow, and conflict resolution patterns
+---
+
+## Branching Strategy
+
+- `main` — production-ready code, never commit directly
+- `feat/<name>` — new features, branch from main
+- `fix/<name>` — bug fixes, branch from main
+- `chore/<name>` — maintenance, config changes, dependency updates
+
+Always create a feature branch before starting work:
+```bash
+git checkout -b feat/my-feature main
+```
+
+## Commit Conventions
+
+Use conventional commit messages:
+
+| Prefix | When |
+|--------|------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `docs:` | Documentation only |
+| `test:` | Adding or updating tests |
+| `refactor:` | Code change that neither fixes nor adds |
+| `chore:` | Build process, deps, config |
+
+Rules:
+- Keep subject under 72 characters
+- Use imperative mood ("add feature" not "added feature")
+- Body explains WHY, not WHAT (the diff shows what)
+- Reference issue numbers: `fix: handle null user (#123)`
+
+## Pull Request Workflow
+
+1. Push feature branch: `git push -u origin feat/my-feature`
+2. Create PR with clear title and description
+3. PR description should include: what changed, why, how to test
+4. Request review, address feedback
+5. Squash merge to main (keeps history clean)
+6. Delete the feature branch after merge
+
+## Conflict Resolution
+
+When conflicts occur:
+1. `git fetch origin main`
+2. `git rebase origin/main` (preferred over merge)
+3. Resolve conflicts file by file
+4. `git add <resolved-files>`
+5. `git rebase --continue`
+6. Run tests after resolving: ensure nothing broke
+
+If rebase gets messy: `git rebase --abort` and start over.
+
+## Common Mistakes
+
+- Never force-push to `main`
+- Never commit `.env` files, credentials, or large binaries
+- Never rebase commits that have been pushed and shared
+- Never merge main into feature branches (rebase instead)
+- Always pull before pushing: `git pull --rebase` (pulls current branch's upstream)

package/templates/claude-code/skills/playwright/SKILL.md

@@ -25,8 +25,8 @@ description: Playwright E2E testing patterns and best practices
 
 ## Common Patterns
 - Navigation: `await page.goto('/')` then assert page loaded
-- Form filling: `await page.fill('[name=email]', 'test@example.com')`
-- Clicking: `await page.click('button[type=submit]')` or `getByRole`
+- Form filling: `await page.getByLabel('Email').fill('test@example.com')`
+- Clicking: `await page.getByRole('button', { name: 'Submit' }).click()`
 - Waiting: prefer auto-waiting over explicit waits
 - Network: `page.waitForResponse()` for API-dependent tests
 - Authentication: use `storageState` for persistent auth across tests