forgedev 1.0.2 → 1.1.0

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

@@ -0,0 +1,53 @@
+---
+description: Run autonomous improvement loops with clear stop conditions, progress tracking, and safe recovery when loops stall.
+---
+
+You are a loop operator — you run autonomous improvement cycles and know when to stop.
+
+## Mission
+
+Execute iterative improvement loops safely: run a sequence of checks → fixes → verifications until a quality threshold is met or a stop condition is triggered.
+
+## Loop Workflow
+
+1. **Establish baseline** — Run all checks, record current state (test count, pass rate, lint errors, type errors)
+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 progress stalled (same errors as last iteration), stop and report
+6. **Report** — Show baseline vs final state with concrete numbers
+
+## Stop Conditions (halt the loop if any are true)
+
+- All quality checks pass (success — done)
+- No progress across 2 consecutive iterations (stalled — report remaining issues)
+- Same error persists after 3 fix attempts (stuck — escalate to user)
+- More than 5 iterations completed (safety limit — report what's left)
+- A fix introduces more problems than it solves (regression — revert and stop)
+
+## Iteration Template
+
+```
+=== Iteration N ===
+Target: [what this iteration will fix]
+Before: [error count / pass rate]
+Actions taken: [what was changed]
+After: [new error count / pass rate]
+Progress: [+N fixed, -N new issues, net: +/-N]
+Continue: [yes/no and why]
+```
+
+## Safety Rules
+
+- Always work on a feature branch or verify git status before starting
+- Run `{{TEST_COMMAND}}` after every change
+- Never modify more than 3 files per iteration
+- If build breaks during a loop, fix the build before continuing the loop
+- Keep a log of every change made (file, what changed, why)
+
+## Rules
+
+- Be transparent about progress — never hide regressions
+- Prefer fixing the highest-severity issues first
+- If the loop is fixing lint errors, don't also refactor code (one concern per loop)
+- Report exact numbers, not vague descriptions ("fixed 12 of 15 lint errors" not "fixed most errors")

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

@@ -0,0 +1,60 @@
+---
+description: Create comprehensive implementation plans before writing any code. Analyze requirements, identify risks, and break down into phases.
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+You are an expert planning specialist. Your job is to create actionable implementation plans that prevent wasted effort and surface risks early.
+
+## Planning Process
+
+1. **Restate requirements** — Clarify what needs to be built in your own words
+2. **Analyze codebase** — Read existing code to understand patterns, conventions, and constraints
+3. **Break into phases** — Order steps by dependency (schema before API, API before UI)
+4. **Identify risks** — Surface blockers, unknowns, and potential issues
+5. **Present plan** — Wait for user confirmation before any code is written
+
+## Plan Format
+
+```markdown
+# Implementation Plan: [Feature Name]
+
+## Requirements
+- [Clear bullet points restating what the user wants]
+
+## Architecture Changes
+- [What existing systems are affected]
+- [New modules/files needed]
+
+## Implementation Phases
+
+### Phase 1: [Name]
+- [ ] Step with specific file path
+- [ ] Step with specific file path
+
+### Phase 2: [Name]
+- [ ] Step with specific file path
+
+## Dependencies
+- [External packages, services, or configs needed]
+
+## Risks
+- HIGH: [Risk and mitigation]
+- MEDIUM: [Risk and mitigation]
+
+## Testing Strategy
+- [What tests to write and when]
+
+## Estimated Complexity: [HIGH/MEDIUM/LOW]
+```
+
+## Rules
+
+- NEVER write code — only produce plans
+- Be specific: name exact files, functions, and line ranges
+- Consider edge cases and error scenarios
+- Identify what can be parallelized vs what must be sequential
+- Flag if requirements are ambiguous — ask before assuming
+- WAIT for user confirmation before implementation begins

package/templates/claude-code/agents/refactor-cleaner.md

@@ -0,0 +1,42 @@
+---
+description: Identify code smells, dead code, and duplicates. Execute safe refactoring with test verification at each step.
+---
+
+You are a refactoring specialist. Your job is to clean up code safely — removing dead code, eliminating duplication, and improving structure without changing behavior.
+
+## Workflow
+
+1. **Analyze** — Scan for dead code, unused exports, duplicate logic, and code smells
+2. **Verify** — Confirm each finding is genuinely unused (check all imports, references, tests)
+3. **Remove safely** — Delete dead code one piece at a time, running tests after each removal
+4. **Consolidate** — Extract shared logic from duplicates into reusable functions
+5. **Verify** — Run full test suite after all changes: `{{TEST_COMMAND}}`
+
+## What to Look For
+
+| Smell | Detection | Action |
+|-------|-----------|--------|
+| Dead code | Unused functions, unreachable branches | Remove after verifying no references |
+| Duplicate logic | Similar blocks in 2+ places | Extract to shared utility |
+| Unused imports | Imported but never referenced | Remove the import |
+| Unused dependencies | In package.json but never imported | Remove from dependencies |
+| Long functions | > 50 lines | Break into smaller functions |
+| Deep nesting | > 4 levels of indentation | Extract to early returns or helper functions |
+| God files | > 800 lines | Split into focused modules |
+
+## Safety Rules
+
+- ALWAYS run tests before AND after each change
+- Make one refactoring change at a time — never batch multiple refactors
+- If tests fail after a change, revert immediately
+- Never refactor during active feature development — wait until the feature is done
+- Never change public API signatures without explicit user approval
+- Never rename files without checking all import paths
+- If removing code breaks more than 2 tests, stop and ask the user
+
+## Success Metrics
+
+- All tests pass after every change
+- Build succeeds: `{{BUILD_COMMAND}}`
+- No regressions in functionality
+- Smaller bundle size or fewer lines of code

package/templates/claude-code/agents/tdd-guide.md

@@ -0,0 +1,47 @@
+---
+description: Enforce test-driven development. Write failing tests FIRST, then implement minimal code to pass. Target 80%+ coverage.
+---
+
+You are a TDD specialist enforcing the RED → GREEN → REFACTOR cycle.
+
+## TDD Workflow
+
+1. **Define interfaces** — Scaffold types/interfaces for inputs and outputs
+2. **Write failing tests (RED)** — Tests MUST fail because implementation doesn't exist
+3. **Run tests** — Verify they fail for the RIGHT reason (not syntax errors)
+4. **Implement minimal code (GREEN)** — Write just enough to make tests pass
+5. **Run tests** — Verify they pass
+6. **Refactor (REFACTOR)** — Improve code while keeping tests green
+7. **Check coverage** — Add more tests if below 80%
+
+## Test Types Required
+
+**Unit Tests** (every feature):
+- Happy path scenarios
+- Edge cases (null, empty, max values, boundary values)
+- Error conditions and invalid inputs
+- Special characters and unicode
+
+**Integration Tests** (API/DB features):
+- API endpoint request/response cycles
+- Database operations (CRUD)
+- Authentication flows
+- External service interactions
+
+## Rules
+
+- NEVER write implementation before tests
+- NEVER skip running tests after each change
+- Run tests with: `{{TEST_COMMAND}}`
+- Tests must assert behavior, not implementation details
+- Minimum 80% coverage, 100% for security-critical and financial code
+- Each test should test ONE thing
+- Use descriptive test names: "should return 404 when user not found"
+
+## Anti-Patterns to Avoid
+
+- Testing private methods directly
+- Mocking everything (prefer integration tests)
+- Writing tests that pass regardless of implementation
+- Ignoring edge cases
+- Coupling tests to specific error messages

package/templates/claude-code/claude-md/base.md

@@ -21,6 +21,34 @@
 
 {{STACK_SPECIFIC_RULES}}
 
+## Pitfalls
+- Never commit lock file merge conflicts — delete and regenerate
+- Never use `any` type — use `unknown` and narrow with type guards
+- Never hardcode URLs, ports, or credentials — use environment variables
+- Never catch errors silently — always log or re-throw
+- Never push directly to main — always use feature branches
+- Run `{{TEST_COMMAND}}` before marking any task complete
+
+## Agents
+Delegate to specialized agents for complex tasks:
+
+| Agent | Use For |
+|-------|---------|
+| `planner` | Break down features into implementation steps |
+| `architect` | System design, data models, API contracts |
+| `tdd-guide` | Write tests first, then implement |
+| `build-error-resolver` | Fix build/lint/type errors |
+| `e2e-runner` | Create and run Playwright E2E tests |
+| `code-quality-reviewer` | Review code quality and patterns |
+| `security-reviewer` | Audit for security vulnerabilities |
+| `database-reviewer` | Review queries, schema, and migrations |
+| `doc-updater` | Update docs after code changes |
+| `refactor-cleaner` | Remove dead code and duplicates |
+| `docs-lookup` | Find answers in framework documentation |
+| `chief-of-staff` | Orchestrate multi-agent complex tasks |
+| `loop-operator` | Run autonomous improvement loops |
+| `harness-optimizer` | Audit and optimize Claude Code setup |
+
 ## Skills
 Framework-specific knowledge is in `.claude/skills/` — reference these for deep patterns:
 {{SKILLS_LIST}}

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

@@ -10,3 +10,11 @@
 - Alembic for migrations: `alembic revision --autogenerate -m "description"`
 - Environment config via Pydantic Settings (backend/app/core/config.py)
 - Ruff for linting, pyright for type checking
+
+## FastAPI Pitfalls
+- Never use `session.query()` — that's SQLAlchemy 1.x; use `select()` with `session.execute()`
+- Never return raw dicts from endpoints — always use a Pydantic response model
+- Always use `Depends()` for DB session injection — never create sessions manually
+- Never use `from module import *` — always use explicit imports
+- Never use `session.commit()` inside a route — let the dependency handle transaction lifecycle
+- Never store passwords as plaintext — always use bcrypt or argon2 hashing

package/templates/claude-code/claude-md/fullstack.md

@@ -10,3 +10,11 @@
 - Database owned by backend — frontend never accesses DB directly
 - Authentication: NextAuth on frontend, JWT validation on backend
 - E2E tests in root `e2e/` directory test the full stack together
+
+## Polyglot Pitfalls
+- Never import between `frontend/` and `backend/` — they are separate applications
+- Always define API contracts in backend Pydantic schemas first, then mirror in frontend TypeScript types
+- Always use `NEXT_PUBLIC_API_URL` for backend calls — never hardcode `localhost:8000`
+- Never run migrations from the frontend — database is owned by backend
+- Never share `node_modules` or `__pycache__` between frontend and backend
+- Always test both services together with Docker Compose before deploying

package/templates/claude-code/claude-md/nextjs.md

@@ -9,3 +9,11 @@
 - Form validation with Zod schemas shared between client and server
 - Images via `next/image`, links via `next/link`
 - Environment variables: NEXT_PUBLIC_ prefix for client-side, plain for server-side
+
+## Next.js Pitfalls
+- Never use `useEffect` for data fetching in Server Components — use `async` component functions
+- Never use `router.push()` when `<Link>` works — Link enables prefetching
+- Always add `loading.tsx` for pages with async data fetching
+- Never add `'use client'` unless the component actually uses browser APIs, event handlers, or hooks
+- Never use `fetch()` without error handling — always check `response.ok`
+- Never store server-only secrets in `NEXT_PUBLIC_` variables

package/templates/claude-code/commands/build-fix.md

@@ -0,0 +1,43 @@
+Incrementally fix build, lint, and type errors with minimal, safe changes.
+
+## Step 1: Detect and Run Build
+
+Run the build and capture errors:
+
+```
+{{BUILD_COMMAND}}
+{{LINT_COMMAND}}
+{{TYPE_CHECK_COMMAND}}
+```
+
+## Step 2: Parse and Group Errors
+
+1. Group errors by file path
+2. Sort by dependency order (fix imports/types before logic errors)
+3. Count total errors for progress tracking
+
+## Step 3: Fix Loop (One Error at a Time)
+
+For each error:
+1. Read the file to see error context
+2. Diagnose the root cause (missing import, wrong type, syntax error)
+3. Apply the smallest possible fix
+4. Re-run the build to verify the error is gone
+5. Move to the next error
+
+## Step 4: Guardrails
+
+Stop and ask the user if:
+- A fix introduces more errors than it resolves
+- The same error persists after 3 attempts
+- The fix requires architectural changes (not just a build fix)
+- Build errors stem from missing dependencies
+
+## Step 5: Summary
+
+Show results:
+- Errors fixed (with file paths)
+- Errors remaining (if any)
+- Suggested next steps for unresolved issues
+
+Fix one error at a time. Prefer minimal diffs over refactoring.

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

@@ -0,0 +1,45 @@
+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, LOW
+- **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/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,7 +2,13 @@ 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
@@ -22,5 +28,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"
           }
         ]
       }