forgedev 1.2.0 → 1.3.0

package/templates/claude-code/commands/run-uat.md

@@ -1,13 +1,39 @@
 Read docs/uat/UAT_TEMPLATE.md and execute the UAT verification process.
 
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
+## Phase 1: Automated Verification
+
 For each scenario in the UAT template:
 1. Check if automated tests exist that cover this scenario
 2. If automated: run the test and report PASS/FAIL
 3. If not automated: flag as MANUAL REQUIRED
 4. Update docs/uat/UAT_CHECKLIST.csv with results
 
+## Phase 2: Business Rules Verification
+
+If `docs/uat/BUSINESS_RULES.md` exists (generated by `/generate-uat`):
+1. For each business rule, check if an automated test validates it
+2. If yes: run the test, compare actual output against the documented expected output
+3. If no: flag the rule as UNTESTED and add it to the manual testing queue
+
+## Phase 3: Results Summary
+
 Output:
 - Automated coverage: X/Y scenarios have automated tests
+- Business rule coverage: X/Y rules have automated tests
 - Results: X passed, Y failed, Z need manual testing
 - Blocking issues: list any P0 failures
 
@@ -16,6 +42,37 @@ For P0 failures:
 - Suggest a fix if the failure is obvious
 - Mark as BLOCKED in the checklist
 
+## Phase 4: Manual Testing Bridge
+
 For scenarios needing manual testing:
-- Provide step-by-step instructions for the tester
-- Note any test data or setup required
+1. Group them by page/endpoint
+2. Check if a browser automation tool is available (Claude in Chrome, Playwright MCP)
+3. If available, ask the user: "I found X scenarios that need manual verification. Would you like me to test them live against the running app? (This will run /live-uat on just these scenarios)"
+4. If the user agrees, run `/live-uat` with scope limited to the MANUAL REQUIRED scenarios
+5. If no browser tool available, provide step-by-step manual instructions for each scenario
+
+## Phase 5: Coverage Gap Report
+
+After all phases complete, generate a coverage report:
+
+```
+## UAT Coverage Report
+
+### Automated
+- Scenarios covered: X/Y (Z%)
+- Business rules covered: X/Y (Z%)
+- All P0 scenarios covered: YES/NO
+
+### Manual (tested via /live-uat)
+- Scenarios tested: X
+- Passed: X | Failed: X
+
+### Gaps (no coverage at all)
+- [list scenarios with neither automated nor manual coverage]
+
+### Recommended Actions
+- [write tests for P0 scenarios without automation]
+- [add business rule assertions to existing tests]
+```
+
+Update docs/uat/UAT_CHECKLIST.csv with final results for all scenarios.

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

@@ -2,10 +2,10 @@ 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
+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
 
@@ -23,12 +23,12 @@ Save the current session state so work can be resumed in a future conversation.
 ---
 
 ## What WORKED (with evidence)
-- **[thing]** — confirmed by: [specific evidence like "tests pass", "200 response"]
+- **[thing]** - confirmed by: [specific evidence like "tests pass", "200 response"]
 
 ---
 
 ## What Did NOT Work (and why)
-- **[approach]** — failed because: [exact reason / error message]
+- **[approach]** - failed because: [exact reason / error message]
 
 ---
 
@@ -48,7 +48,7 @@ Save the current session state so work can be resumed in a future conversation.
 ---
 
 ## Decisions Made
-- **[decision]** — reason: [why]
+- **[decision]** - reason: [why]
 
 ---
 
@@ -63,7 +63,7 @@ Save the current session state so work can be resumed in a future conversation.
 
 ## 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
+- Write every section honestly. "Nothing yet" is better than skipping a section
+- The "What Did NOT Work" section is the most critical because it 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/simplify.md

@@ -0,0 +1,36 @@
+Review the current codebase for structural quality and clean it up. This is not about style or formatting — it is about architecture hygiene.
+
+## What to check
+
+1. **Long files** (over 300 lines): Split into smaller, focused modules. Each file should have a single responsibility.
+
+2. **Long functions** (over 50 lines): Extract helper functions. If a function does more than one thing, break it apart.
+
+3. **Duplicate code**: Find code blocks that appear in multiple files. Extract them into a shared utility module that individual files can import. Common patterns to look for:
+   - Repeated validation logic
+   - Identical error handling blocks
+   - Copy-pasted API call patterns
+   - Similar data transformation functions
+
+4. **Directory bloat**: If a directory has more than 20 source files, suggest grouping them into subdirectories by feature or domain.
+
+5. **Stale test files**: Find test files whose corresponding source files have been deleted or renamed. Ask if they should be removed.
+
+6. **Dead exports**: Find exported functions or constants that nothing imports. Ask if they should be removed.
+
+## How to fix
+
+For each issue found:
+- Explain what the problem is and why it matters
+- Show the specific files and line numbers
+- Make the fix (extract utility, split file, delete dead code)
+- Verify imports still work after refactoring
+- Run tests to confirm nothing broke
+
+## Rules
+- Do NOT add new dependencies
+- Do NOT change public APIs or function signatures
+- Do NOT refactor code that is already clean
+- Keep the fixes minimal and focused — one problem at a time
+- When extracting shared utilities, place them in the most logical existing directory (e.g., `src/lib/`, `src/utils/`, `shared/`)
+- Always preserve existing test coverage

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

@@ -6,10 +6,10 @@ Enforce test-driven development: write failing tests FIRST, then implement.
 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
+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
 
@@ -17,40 +17,40 @@ RED → GREEN → REFACTOR → REPEAT
 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
+5. Run `{{TEST_COMMAND}}` to verify tests FAIL for the right reason
 6. Implement minimal code to pass
-7. Run `{{TEST_COMMAND}}` — verify tests PASS
+7. Run `{{TEST_COMMAND}}` to verify tests PASS
 8. Refactor if needed, keeping tests green
-9. Check coverage — target 80%+ minimum
+9. Check coverage. Target 80%+ minimum
 
 ## Example
 
 ```
 User: /tdd I need a function to validate email addresses
 
-Step 1 — SCAFFOLD:
+Step 1 - SCAFFOLD:
   Create types/interfaces for input and output
 
-Step 2 — RED (write failing tests):
+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 3 - Run tests → all FAIL (expected, no implementation yet)
 
-Step 4 — GREEN (implement minimal code):
+Step 4 - GREEN (implement minimal code):
   Write just enough to pass all tests
 
-Step 5 — Run tests → all PASS
+Step 5 - Run tests → all PASS
 
-Step 6 — REFACTOR:
+Step 6 - REFACTOR:
   Extract constants, improve naming, add JSDoc
 
-Step 7 — Run tests → still PASS
+Step 7 - Run tests → still PASS
 
-Step 8 — Check coverage → 100%
+Step 8 - Check coverage → 100%
 ```
 
 ## Rules
@@ -75,6 +75,5 @@ Step 8 — Check coverage → 100%
 
 ## After TDD
 
-- `/build-fix` — if build errors come up
-- `/code-review` — review the implementation
-- `/done` — verify the task is complete
+- `/build-fix` - if build errors come up
+- `/code-review` - review the implementation, then commit

package/templates/claude-code/commands/verify-all.md

@@ -1,5 +1,19 @@
 Run the full verification chain on the current changes.
 
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
 1. Run lint: `{{LINT_COMMAND}}`
 2. Run type check: `{{TYPE_CHECK_COMMAND}}`
 3. Run tests: `{{TEST_COMMAND}}`
@@ -9,3 +23,13 @@ Run the full verification chain on the current changes.
 
 Summarize all findings grouped by severity (critical, high, medium, low).
 If any critical issues found, list them prominently at the top.
+
+## Recommend Next Step
+
+After the summary, always recommend the single best next action based on findings:
+- **CRITICAL findings** → recommend the specific fix
+- **HIGH findings** → recommend addressing before proceeding
+- **No issues** → recommend `/pre-pr`
+- **MEDIUM/LOW only** → recommend committing, note optional improvements
+
+Format: **Next step:** one sentence with the specific command or action to take.

package/templates/claude-code/commands/verify-intent.md

@@ -0,0 +1,55 @@
+Run the Intent Verification Protocol compliance check across all agents and commands.
+
+## Intent Contract
+
+Before invoking any agent, construct this block:
+
+```
+INTENT_CONTRACT:
+  INTENT: "Verify all agents and commands comply with the Intent Verification Protocol"
+  SCOPE: ".claude/agents/, .claude/commands/"
+  SUCCESS_CRITERIA: "Every agent has PROOF_OF_INTENT, every command that invokes agents has Intent Contract, no cross-agent consistency violations"
+  INTENT_HASH: "IVP-COMPLIANCE"
+```
+
+## Step 1: Protocol Compliance Scan
+
+For each file in `.claude/agents/`:
+1. Check for `PROOF_OF_INTENT` block in output section
+2. Check for `NO_CONTRACT_RECEIVED` fallback handling
+3. Record compliance status
+
+For each file in `.claude/commands/` that references an agent:
+1. Check for `INTENT_CONTRACT` section
+2. Check that `INTENT_HASH` is referenced
+3. Record compliance status
+
+## Step 2: Launch prompt-auditor
+
+Run the **prompt-auditor** agent on the full `.claude/` configuration with the Intent Contract above.
+
+## Step 3: Cross-Validation
+
+1. Pick 3 agents at random
+2. For each, evaluate: given a sample intent, would the agent's instructions produce output that includes a valid PROOF_OF_INTENT?
+3. Flag any agent whose instructions are ambiguous enough that the proof section could be skipped
+
+## Step 4: Compliance Report
+
+```
+INTENT VERIFICATION PROTOCOL - COMPLIANCE REPORT
+
+OVERALL: [X/Y agents compliant, A/B commands compliant]
+
+NON-COMPLIANT AGENTS:
+- [agent name]: [what's missing]
+
+NON-COMPLIANT COMMANDS:
+- [command name]: [what's missing]
+
+CONSISTENCY ISSUES:
+- [cross-agent term conflicts, severity definition mismatches]
+
+RECOMMENDATIONS:
+- [prioritized list of fixes]
+```

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

@@ -1,40 +1,52 @@
-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
-- `/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
-
-### Strategy
-- Use `product-strategist` agent — Research competitors, evaluate project maturity, recommend improvements
-
-### 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.
+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
+- `/fix-loop` - Automated fix-review-regression loop until green
+- `/build-ui` - Build frontend UI with AI-powered generation (Google Stitch + UI UX Pro Max)
+- `/code-review` - Review changes for security and quality (required before commit)
+- `/simplify` - Find duplicate code, long files, and extract shared utilities
+
+### Daily
+- `/help` - Not sure what to do? This guides you to the right workflow
+- `/status` - Run all checks and show a project dashboard
+- `/next` - Figure out what to work on next
+
+### 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
+- `/verify-intent` - Verify all agents comply with Intent Verification Protocol
+
+### Strategy
+- Use `product-strategist` agent - Research competitors, evaluate project maturity, recommend improvements
+
+### Release
+- `/pre-pr` - Prepare and create a pull request
+- `/run-uat` - Execute UAT scenarios
+- `/live-uat` - Run live UAT by interacting with the running application
+
+### Generation
+- `/generate-prd` - Generate a PRD from the current codebase
+- `/generate-sdd` - Generate a Software Design Document from the 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
+
+## Quality Gates (automatic)
+
+These run automatically, you don't need to remember them:
+- **On commit**: Pre-commit gate runs lint, tests, secrets check, and requires code review
+- **On stop**: Code hygiene check runs automatically
+
+## Quick Start
+Run `/status` to see where things stand, then `/next` to pick up work.

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

@@ -9,6 +9,15 @@
             "command": "node .claude/hooks/guard-protected-files.mjs"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/pre-commit-gate.mjs"
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -27,7 +36,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd frontend && npx tsc --noEmit 2>&1 && npx eslint . 2>&1 && cd ../backend && ruff check . 2>&1"
+            "command": "node .claude/hooks/code-hygiene.mjs"
           }
         ]
       }

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

@@ -9,6 +9,15 @@
             "command": "node .claude/hooks/guard-protected-files.mjs"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/pre-commit-gate.mjs"
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -27,7 +36,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd backend && ruff check . 2>&1 && pyright 2>&1"
+            "command": "node .claude/hooks/code-hygiene.mjs"
           }
         ]
       }

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

@@ -31,7 +31,7 @@ process.stdin.on('end', () => {
         try {
           execFileSync('npx', ['eslint', '--fix', targetPath], { stdio: 'pipe', cwd: 'frontend' });
         } catch {
-          // eslint may exit non-zero for unfixable issues — that's okay
+          // eslint may exit non-zero for unfixable issues, that's okay
         }
       }
     } else if (filePath.endsWith('.py')) {
@@ -42,7 +42,7 @@ process.stdin.on('end', () => {
         try {
           execFileSync('ruff', ['check', '--fix', targetPath], { stdio: 'pipe', cwd: 'backend' });
         } catch {
-          // ruff may exit non-zero for unfixable issues — that's okay
+          // ruff may exit non-zero for unfixable issues, that's okay
         }
       }
     }

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

@@ -27,7 +27,7 @@ process.stdin.on('end', () => {
       try {
         execFileSync('ruff', ['check', '--fix', resolved], { stdio: 'pipe' });
       } catch {
-        // ruff may exit non-zero for unfixable issues — that's okay
+        // ruff may exit non-zero for unfixable issues, that's okay
       }
     }
     process.exit(0);

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

@@ -27,7 +27,7 @@ process.stdin.on('end', () => {
       try {
         execFileSync('npx', ['eslint', '--fix', resolved], { stdio: 'pipe' });
       } catch {
-        // eslint may exit non-zero for unfixable issues — that's okay
+        // eslint may exit non-zero for unfixable issues, that's okay
       }
     }