forgedev 1.0.1 → 1.1.0

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

@@ -0,0 +1,36 @@
+Show the developer what workflows are available.
+
+## Available Workflows
+
+### 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
+- `/audit-spec` — Validate implementation against a spec/PRD
+- `/audit-wiring` — Find dead or unwired features
+- `/audit-security` — Run a security audit
+
+### Release
+- `/pre-pr` — Run the complete pre-PR checklist
+- `/run-uat` — Execute UAT scenarios
+
+### Generation
+- `/generate-prd` — Generate a PRD from the current codebase
+- `/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,36 @@
+#!/usr/bin/env node
+// Auto-fix lint issues on saved TypeScript or Python files (polyglot)
+
+import { execSync } from 'node:child_process';
+
+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);
+    }
+
+    if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
+      try {
+        execSync(`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 {
+        execSync(`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,30 @@
+#!/usr/bin/env node
+// Auto-fix lint issues on saved Python files
+
+import { execSync } from 'node:child_process';
+
+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);
+    }
+
+    if (filePath.endsWith('.py')) {
+      try {
+        execSync(`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,30 @@
+#!/usr/bin/env node
+// Auto-fix lint issues on saved TypeScript files
+
+import { execSync } from 'node:child_process';
+
+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);
+    }
+
+    if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
+      try {
+        execSync(`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/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 origin main`

package/templates/claude-code/skills/testing-patterns/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: testing-patterns
+description: Universal testing principles — test pyramid, AAA pattern, mocking strategies, and coverage targets
+---
+
+## Test Pyramid
+
+```
+        /  E2E  \        — Few, slow, high confidence
+       / Integration \   — Some, medium speed
+      /    Unit Tests   \— Many, fast, focused
+```
+
+- **Unit tests** (70%): Test individual functions in isolation. Fast, many.
+- **Integration tests** (20%): Test modules working together (API + DB, component + hook).
+- **E2E tests** (10%): Test full user journeys through the real app. Slow, few.
+
+## Arrange-Act-Assert (AAA)
+
+Every test follows this structure:
+
+```
+test('should calculate total with tax', () => {
+  // Arrange — set up test data
+  const items = [{ price: 10 }, { price: 20 }];
+  const taxRate = 0.1;
+
+  // Act — execute the function
+  const total = calculateTotal(items, taxRate);
+
+  // Assert — verify the result
+  expect(total).toBe(33);
+});
+```
+
+## What to Test
+
+**Always test:**
+- Happy path (normal inputs → expected output)
+- Edge cases (empty, null, undefined, zero, max values)
+- Error cases (invalid input, missing data, network failure)
+- Boundary values (off-by-one, exactly at limits)
+- Security-critical paths (auth, permissions, input validation)
+
+**Don't test:**
+- Implementation details (private methods, internal state)
+- Third-party library internals
+- Trivial getters/setters with no logic
+- CSS styling or pixel-perfect layouts
+
+## Mocking Strategy
+
+| What | When to Mock |
+|------|-------------|
+| External APIs | Always — they're slow and unreliable |
+| Database | Integration tests use real DB, unit tests mock |
+| Time/Date | When testing time-dependent logic |
+| File system | When testing file operations |
+| Environment | When testing env-dependent behavior |
+
+Rules:
+- Mock at the boundary, not deep inside
+- Prefer dependency injection over global mocks
+- Reset mocks between tests (`beforeEach` / `afterEach`)
+- Never mock what you're testing
+
+## Test Naming
+
+Use descriptive names that explain the scenario:
+
+```
+// Good
+"should return 404 when user does not exist"
+"should hash password before saving to database"
+"should retry failed request up to 3 times"
+
+// Bad
+"test1"
+"works correctly"
+"handles error"
+```
+
+## Coverage Targets
+
+- **80% minimum** for all code
+- **100% required** for: auth logic, financial calculations, security-critical code
+- Coverage measures lines hit, not correctness — high coverage with weak assertions is useless
+- Focus on meaningful assertions, not just line coverage
+
+## Common Anti-Patterns
+
+- Testing implementation instead of behavior
+- Tests that pass regardless of the implementation
+- Shared mutable state between tests (tests must be independent)
+- Over-mocking (prefer integration tests when possible)
+- Ignoring flaky tests (fix the root cause immediately)
+- Testing only the happy path

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

@@ -1,26 +0,0 @@
-Show the developer what workflows are available.
-
-## Available Workflows
-
-### Daily Development
-- `/project:status` — Run all checks and show a project dashboard
-- `/project:next` — Figure out what to work on next
-- `/project:done` — Verify the current task is complete before moving on
-
-### Verification
-- `/project:verify-all` — Run lint, type check, tests, then launch all reviewers
-- `/project:audit-spec` — Validate implementation against a spec/PRD
-- `/project:audit-wiring` — Find dead or unwired features
-- `/project:audit-security` — Run a security audit
-
-### Release
-- `/project:pre-pr` — Run the complete pre-PR checklist
-- `/project:run-uat` — Execute UAT scenarios
-
-### Generation
-- `/project:generate-prd` — Generate a PRD from the current codebase
-- `/project:generate-uat` — Generate UAT scenarios and checklists
-- `/project:optimize-claude-md` — Slim down an oversized CLAUDE.md
-
-## Quick Start
-Run `/project:status` to see where things stand, then `/project:next` to pick up work.

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

@@ -1,16 +0,0 @@
-#!/usr/bin/env bash
-# Auto-fix lint issues on saved TypeScript or Python files (polyglot)
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")
-
-if [ -z "$FILE_PATH" ]; then
-  exit 0
-fi
-
-if [[ "$FILE_PATH" == *.ts || "$FILE_PATH" == *.tsx ]]; then
-  cd frontend && npx eslint --fix "$FILE_PATH" 2>&1 || true
-elif [[ "$FILE_PATH" == *.py ]]; then
-  cd backend && ruff check --fix "$FILE_PATH" 2>&1 || true
-fi
-
-exit 0

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

@@ -1,14 +0,0 @@
-#!/usr/bin/env bash
-# Auto-fix lint issues on saved Python files
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")
-
-if [ -z "$FILE_PATH" ]; then
-  exit 0
-fi
-
-if [[ "$FILE_PATH" == *.py ]]; then
-  cd backend && ruff check --fix "$FILE_PATH" 2>&1 || true
-fi
-
-exit 0

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

@@ -1,14 +0,0 @@
-#!/usr/bin/env bash
-# Auto-fix lint issues on saved TypeScript files
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")
-
-if [ -z "$FILE_PATH" ]; then
-  exit 0
-fi
-
-if [[ "$FILE_PATH" == *.ts || "$FILE_PATH" == *.tsx ]]; then
-  npx eslint --fix "$FILE_PATH" 2>&1 || true
-fi
-
-exit 0

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

@@ -1,21 +0,0 @@
-#!/usr/bin/env bash
-# Block modifications to .env files and migration files
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")
-
-if [ -z "$FILE_PATH" ]; then
-  exit 0
-fi
-
-case "$FILE_PATH" in
-  *.env|*.env.*)
-    echo "BLOCKED: Do not modify .env files directly" >&2
-    exit 2
-    ;;
-  */prisma/migrations/*|*/alembic/versions/*)
-    echo "BLOCKED: Do not modify migration files directly" >&2
-    exit 2
-    ;;
-esac
-
-exit 0