forge-orkes 0.1.0

package/template/.claude/skills/planning/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: planning
+description: "Use when you need to break work into executable tasks with verification gates. Trigger after researching, when you have enough context to plan but haven't started building. This skill enforces constitutional gates, structures requirements, decomposes tasks, and sets up goal-backward verification."
+---
+
+# Planning
+
+Turn research and requirements into executable, verifiable plans.
+
+## Step 1: Resolution Gate
+
+Read `.forge/context.md`. Check the **Needs Resolution** section.
+
+If any unresolved items exist (unchecked `- [ ]` items under "Needs Resolution"):
+
+**Pause and triage with the user.** This is a quick conversation, not a planning phase. Present all unresolved items and ask the user to make a call on each one.
+
+Present each item clearly:
+*"Before we plan, there are {N} items that need your input: [list items]. For each one, should we lock it as a decision, defer it, treat it as a bug to fix, or drop it?"*
+
+**For each unresolved item, the user picks one:**
+- **→ Lock it**: The answer is clear. Record in Locked Decisions section.
+- **→ Defer it**: Not now. Move to Deferred Ideas with revisit date.
+- **→ Fix it**: This is a gap/bug. Add as a requirement (FR-xxx) in `.forge/requirements.yml` — it flows into the plan being created.
+- **→ Drop it**: No longer relevant. Note in Amendment Log.
+
+Check off each resolved item `- [x]` and move it to the appropriate section.
+
+**This should take 2-5 minutes, not a whole planning cycle.** The goal is to get quick human decisions so planning can proceed with accurate information.
+
+Also scan the **Carried Forward** section — items here that affect the current phase should be triaged the same way.
+
+## Step 2: Constitutional Gate Check
+
+Read `.forge/constitution.md`. For each article relevant to this phase:
+- Check the gate checkboxes
+- If any gate fails → **STOP.** Resolve before planning.
+- If an article needs amendment → flag for user decision (discuss phase)
+
+Document gate results in the plan frontmatter.
+
+## Step 3: Lock User Decisions
+
+If not already done, create `.forge/context.md` from template:
+
+1. Ask user about key decisions (framework choices, constraints, preferences)
+2. Record as **Locked Decisions** — these are contracts
+3. Record **Deferred Ideas** — explicitly out of scope
+4. Record **Discretion Areas** — agent picks best approach
+
+**Critical:** Do this BEFORE creating plans. Plans must reference context.md.
+
+## Step 4: Structure Requirements
+
+If `.forge/requirements.yml` doesn't exist, create from template:
+
+1. Extract functional requirements from user description + research
+2. Assign IDs: FR-001, FR-002, etc.
+3. Write acceptance criteria in Given/When/Then format
+4. Mark uncertain items: `[NEEDS CLARIFICATION]`
+5. Separate P1 (must-have) from P2 (should-have) and P3 (nice-to-have)
+6. List deferred items explicitly (DEF-001, etc.)
+
+**Planning blocks until all P1 `[NEEDS CLARIFICATION]` items are resolved.**
+
+## Step 5: Create Roadmap
+
+If `.forge/roadmap.yml` doesn't exist (Full tier only):
+
+1. Group requirements by natural delivery boundaries
+2. Identify dependencies between groups
+3. Create phases (coherent, verifiable capabilities)
+4. Assign requirements to phases (every FR → exactly one phase, no orphans)
+5. Analyze waves (independent phases = Wave 1, dependencies = Wave 2+)
+
+## Step 6: Decompose into Tasks
+
+For each phase (or the single feature in Standard tier):
+
+1. Copy `.forge/templates/plan.md` → `.forge/phases/{N}-{name}/plan-{NN}.md`
+2. Fill in frontmatter (phase, plan number, wave, dependencies)
+3. Create goal-backward must_haves:
+   - **Truths:** Observable from user perspective when done (3-7)
+   - **Artifacts:** Files that must exist and be substantive, not stubs
+   - **Key Links:** Critical connections between artifacts
+4. Decompose into XML tasks (2-3 per plan, 15-60 min each):
+
+```xml
+<task type="auto">
+  <name>Action-oriented name</name>
+  <files>Exact paths created/modified</files>
+  <action>What to build, how, what to avoid (with WHY)</action>
+  <verify>Command or check to prove completion</verify>
+  <done>Measurable acceptance criteria</done>
+</task>
+```
+
+### Task Sizing
+- Under 15 min → too small, combine with adjacent task
+- 15-60 min → right size
+- Over 60 min → too large, split into separate plan
+
+### Task Types
+- `auto` — Fully autonomous (90% of tasks)
+- `checkpoint:human-verify` — Pause for visual/functional check
+- `checkpoint:decision` — Pause for user choice between options
+- `checkpoint:human-action` — Pause for truly manual action (email verification, 2FA)
+
+### Vertical Slices (Preferred)
+```
+Plan 01: User feature (model + API + UI)   → Wave 1
+Plan 02: Product feature (model + API + UI) → Wave 1
+```
+Independent plans run in parallel.
+
+### Avoid Horizontal Layers
+```
+Plan 01: All models    → Wave 1
+Plan 02: All APIs      → Wave 2 (depends on 01)
+Plan 03: All UI        → Wave 3 (depends on 02)
+```
+Forces sequential execution. Only use when architecturally necessary.
+
+## Step 7: Test Spec Generation (Optional)
+
+**When to use:** Invoke this step when the work involves testable contracts — APIs with defined endpoints, libraries with public interfaces, data transformations with known inputs/outputs, or services with observable behavior. Skip for UI-heavy work where the existing must_haves approach is sufficient.
+
+**The user can also explicitly request this:** *"Generate test specs for this plan."*
+
+### Detect Testable Contracts
+
+Scan the tasks from Step 6. A task is a testable contract candidate if it involves:
+- **API endpoints** — defined request/response shapes, status codes, error cases
+- **Library/module interfaces** — public functions with typed inputs and expected outputs
+- **Data transformations** — parsers, formatters, validators, converters with known input→output mappings
+- **Service integrations** — external API calls with expected payloads and error handling
+- **Business logic** — calculations, rules engines, state machines with deterministic behavior
+
+If no testable contracts are found, skip to Step 8.
+
+### Generate Test Specifications
+
+For each testable contract, create a test spec file alongside the plan:
+
+**Location:** `.forge/phases/{N}-{name}/specs/`
+
+**Format:** Language-appropriate test files (e.g., `.test.ts`, `_test.go`, `test_*.py`) that:
+
+1. **Import the module that will exist** (the path from the task's `<files>` field)
+2. **Describe expected behavior** derived from requirements, NOT from implementation:
+   - Happy path cases from acceptance criteria
+   - Edge cases from requirements (empty input, max limits, invalid data)
+   - Error cases from the `<done>` criteria
+3. **Assert outcomes, not internals** — test what the function returns or what side effects occur, not how it's implemented
+4. **Mark as pending/skipped** — tests should be valid syntax but marked to skip (e.g., `it.skip()`, `@pytest.mark.skip`, `t.Skip()`) so they don't break CI before implementation
+
+```typescript
+// Example: .forge/phases/1-auth/specs/login-endpoint.test.ts
+describe('POST /api/auth/login', () => {
+  it.skip('returns 200 with valid token for correct credentials', () => {
+    // From FR-001: "User can log in with email and password"
+  });
+
+  it.skip('returns 401 for invalid password', () => {
+    // From FR-001 acceptance: "Invalid credentials show error"
+  });
+
+  it.skip('returns 422 for missing email field', () => {
+    // Edge case: required field validation
+  });
+
+  it.skip('rate-limits after 5 failed attempts', () => {
+    // From NFR-002: "Brute force protection"
+  });
+});
+```
+
+### Update Plan Tasks
+
+For tasks with generated test specs, update the task XML to reference the spec:
+
+```xml
+<task type="tdd">
+  <name>Implement login endpoint</name>
+  <files>src/api/auth/login.ts</files>
+  <spec>.forge/phases/1-auth/specs/login-endpoint.test.ts</spec>
+  <action>Make all tests in the spec file pass. Remove skip markers as you implement.</action>
+  <verify>All spec tests pass: npm test -- login-endpoint</verify>
+  <done>All skip markers removed, all tests green</done>
+</task>
+```
+
+Note: The task type changes to `tdd` when a spec exists. The executor's TDD flow (RED → GREEN → REFACTOR) kicks in automatically.
+
+### What NOT to Spec
+
+- UI component rendering (use must_haves truths instead)
+- Visual layout and styling (use human verification)
+- Integration flows spanning many components (use key_links verification)
+- Anything where the interface isn't defined yet (spec after architecting, not before)
+
+## Step 8: Verify Plans (Plan Checker)
+
+Before passing to executor, verify across 8 dimensions:
+
+1. **Requirement Coverage** — Every phase requirement has task(s)
+2. **Task Completeness** — All tasks have files + action + verify + done
+3. **Dependency Correctness** — Valid DAG, no circular deps
+4. **Key Links Planned** — Artifacts will be wired together (not orphaned)
+5. **Scope Sanity** — 2-3 tasks per plan, targeting ~50% context
+6. **Verification Derivation** — must_haves trace to phase goal
+7. **Context Compliance** — Plans honor locked decisions, exclude deferred ideas
+8. **Spec Validity** (when Step 7 was used) — Test specs are valid syntax, reference correct paths, derive from requirements not assumptions
+
+If issues found → fix and re-verify. Max 3 revision cycles.
+
+## Step 9: Present to User
+
+Show the user:
+1. Requirements summary (P1/P2/P3 counts, clarifications needed)
+2. Phase/plan structure with wave analysis
+3. Estimated effort per phase
+4. Ask: "Does this plan match your expectations? Any changes?"
+
+Planning is complete when user approves.

package/template/.claude/skills/quick-tasking/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: quick-tasking
+description: "Use for small, scoped changes: typo fixes, config updates, minor bug fixes, dependency bumps, documentation tweaks. Trigger when the change is under 50 lines, touches 1-2 files, and requires no architectural decisions. This is the Quick tier — skip planning ceremony, just do it right."
+---
+
+# Quick-Tasking
+
+Small change? Skip the ceremony. Do it right, do it fast.
+
+## Qualifies as Quick
+
+- Single file change, under 50 lines
+- Typo, grammar, or formatting fix
+- Config or environment variable update
+- Dependency version bump
+- Simple bug fix with obvious root cause
+- Documentation update
+- CSS/style tweak within design system
+- Adding a missing import or export
+
+## Does NOT Qualify as Quick
+
+Upgrade to Standard tier if any of these are true:
+- Change touches 3+ files
+- Requires new component, function, or module
+- Involves logic changes affecting multiple features
+- Needs a new dependency
+- Requires architectural decision
+- Estimated at more than 30 minutes
+- You're unsure about the right approach
+
+## Quick Workflow
+
+### 1. Identify
+What exactly needs to change? Be specific: which file, which line, what's wrong.
+
+### 2. Validate Scope
+Confirm it's truly quick:
+- [ ] Under 50 lines of changes
+- [ ] 1-2 files maximum
+- [ ] No architectural decisions needed
+- [ ] Root cause is obvious (or bug fix is straightforward)
+
+If any check fails → escalate to Standard tier.
+
+### 3. Execute
+Make the change. Follow existing patterns in the codebase.
+
+### 4. Test
+- Run relevant tests: `npm test -- --filter={related}`
+- If no tests exist for this area, at minimum verify it compiles/builds
+- For UI changes, visually confirm the fix
+
+### 5. Commit
+Atomic commit with proper format:
+```
+{type}({scope}): {description}
+```
+Examples:
+- `fix(docs): correct typo in API reference`
+- `chore(deps): bump react to 19.1.0`
+- `fix(ui): align header padding with design system`
+
+### 6. Done
+No verification ceremony needed. Move on.
+
+## Scope Creep Detection
+
+While executing a quick task, if you discover:
+- The fix is bigger than expected → **STOP**. Escalate to Standard.
+- Related issues that should also be fixed → **LOG** to `.forge/deferred-issues.md`. Don't fix now.
+- An architectural question → **STOP**. Escalate to Standard with a note about what triggered it.
+
+Quick-tasking is about discipline: do the small thing, only the small thing, and move on.

package/template/.claude/skills/refactoring/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: refactoring
+description: "Review code built during a milestone for refactoring opportunities. Runs after auditing passes. Produces a structured backlog of improvements the user can work through via quick-tasking. Soft gate — review items, add to backlog, complete milestone."
+---
+
+# Refactoring: Post-Milestone Code Review for Improvement Opportunities
+
+You review the code built during a milestone and catalog opportunities for improvement. This is not about correctness (that's `verifying`) or health (that's `auditing`) — it's about identifying code that works but could be cleaner, simpler, or more consistent.
+
+## When to Trigger
+
+- **Automatically** after `auditing` completes (all three paths: HEALTHY, NEEDS ATTENTION after fix, ACCEPTABLE WITH CAVEATS after accept)
+- **On-demand** at any time via user request
+
+## Step 1: Read Context
+
+```
+Read: .forge/project.yml → tech stack, conventions
+Read: .forge/state/milestone-{id}.yml → milestone ID, name, phases completed
+Read: .forge/audits/milestone-{id}-health-report.md → health findings (avoid overlap)
+Read: .forge/refactor-backlog.yml → existing backlog items (if any)
+Read: .forge/constitution.md → active architectural gates (if exists)
+```
+
+Determine the milestone's starting point for the git diff:
+- Check git log for the commit tagged or noted as the milestone start
+- If unavailable, use the first commit after the previous milestone's completion date
+- Fallback: ask the user for the starting commit or branch
+
+## Step 2: Scan Milestone Code
+
+Spawn a fresh agent with isolated context. Pass it:
+- The explicit list of files changed during the milestone (from `git diff --name-only {start}..HEAD`)
+- The tech stack from `project.yml`
+- The health report findings (so it doesn't duplicate auditing's work)
+- The constitution (so it respects intentional decisions)
+
+**The agent scans for 6 categories:**
+
+| # | Category | What to Look For |
+|---|----------|-----------------|
+| 1 | **Duplication** | Similar logic in 2+ places that could be extracted into a shared function, hook, or utility |
+| 2 | **Complexity hotspots** | Functions >50 lines, nesting >3 levels deep, high cyclomatic complexity, overly long files |
+| 3 | **Naming & clarity** | Unclear variable/function names, misleading abstractions, functions that do more than their name suggests |
+| 4 | **Pattern inconsistency** | Same thing done differently across the milestone's files (e.g., error handling, data fetching, state management) |
+| 5 | **Dead code** | Unused functions, unreachable branches, commented-out code left behind, unused imports |
+| 6 | **Abstraction issues** | Over-engineered helpers used once, repeated inline code that warrants extraction, premature or missing abstractions |
+
+**Agent behavior rules:**
+- Read every file in the diff. No sampling.
+- Every finding must reference a specific file and line range.
+- Understand context — don't flag intentional patterns documented in the constitution.
+- Don't duplicate findings already in the health report from auditing.
+- Estimate effort for each item: `quick` (< 30 min, under 50 lines) or `standard` (needs planning).
+- Suggest a concrete approach for each finding, not just "refactor this."
+- Prefer fewer high-quality findings over many low-signal ones.
+
+**Output format** (return to orchestrator):
+
+```yaml
+findings:
+  - category: duplication
+    file: "src/api/users.ts"
+    lines: "42-67"
+    description: "Duplicate validation logic — same email check in createUser and updateUser"
+    effort: quick
+    suggested_approach: "Extract shared validateEmail() helper to src/utils/validation.ts"
+  - category: complexity
+    file: "src/components/Dashboard.tsx"
+    lines: "120-245"
+    description: "Dashboard render function is 125 lines with 4 levels of nesting"
+    effort: standard
+    suggested_approach: "Extract stat cards, chart section, and filter bar into subcomponents"
+```
+
+## Step 3: Present Findings to User
+
+Group findings by category. Show each with:
+- File and line range
+- What the issue is
+- Estimated effort
+- Suggested approach
+
+Present top findings (max 10 initially). If there are more, mention the count.
+
+*"I found {N} refactoring opportunities in the code built during this milestone:"*
+
+Then for each category with findings:
+
+*"**Duplication** ({N} items):*
+*1. `src/api/users.ts:42-67` — Duplicate email validation in createUser and updateUser. Quick fix: extract shared helper. [Accept / Dismiss]*
+*2. ...*"
+
+## Step 4: User Triage
+
+The user can respond with:
+- **Accept** (individual item) → add to backlog
+- **Dismiss** (individual item) → skip, not a real issue or intentional
+- **Accept all** → bulk add all remaining items to backlog
+- **Dismiss all** → skip everything, no backlog items added
+
+For dismissed items, optionally ask for a brief reason (helps calibrate future scans).
+
+## Step 5: Write Backlog
+
+Read existing `.forge/refactor-backlog.yml` (if any). Determine the next item ID by incrementing from the highest existing ID.
+
+Append accepted items to `.forge/refactor-backlog.yml`:
+
+```yaml
+items:
+  - id: R001
+    milestone: 1
+    category: duplication
+    file: "src/api/users.ts"
+    lines: "42-67"
+    description: "Duplicate validation logic — same email check in createUser and updateUser"
+    effort: quick
+    suggested_approach: "Extract shared validateEmail() helper"
+    status: pending
+    added: "2026-03-18"
+    completed: null
+```
+
+If the file doesn't exist yet, create it from the template at `.forge/templates/refactor-backlog.yml`.
+
+Present summary:
+*"Added {N} items to the refactor backlog. {M} dismissed. You can work these anytime — pending items with `effort: quick` will show up as available Quick tasks when you start a session."*
+
+## Step 6: Route
+
+Update `.forge/state/milestone-{id}.yml`:
+- Set `current.status` to `complete`
+
+Update `.forge/state/index.yml`:
+- Set milestone status to `complete`
+- Update `last_updated` timestamp
+
+Present to user:
+*"Milestone [{name}] is complete. {N} refactoring items are in the backlog for whenever you want to tackle them."*
+
+If Beads is installed, run `bd complete` to update the dependency graph.
+
+## Gate Type: Soft Gate
+
+This is a soft gate — it presents opportunities but never blocks milestone completion. Rationale:
+- Refactoring is improvement, not correctness. The code already works (verified) and is healthy (audited).
+- Users should review opportunities but aren't forced to act on them immediately.
+- Backlog items persist across sessions and can be worked whenever it makes sense.
+- Some items may become irrelevant as the codebase evolves — that's fine.
+
+## Backlog Lifecycle
+
+Backlog items follow this lifecycle:
+
+```
+pending → in_progress → done
+pending → dismissed (during triage or later review)
+```
+
+Items with `effort: quick` can be picked up directly via `quick-tasking`.
+Items with `effort: standard` should go through the Standard tier flow.
+
+When working a backlog item:
+1. `forge` surfaces it as an available task
+2. User selects it
+3. Route to `quick-tasking` or Standard tier based on effort
+4. On completion, update the item's `status` to `done` and set `completed` date

package/template/.claude/skills/researching/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: researching
+description: "Use when you need to investigate before building: understand the codebase, evaluate technologies, clarify requirements, or assess feasibility. Trigger before any Standard or Full tier planning. Also trigger when joining an existing project or when blocked on 'how should this work?'"
+---
+
+# Researching
+
+Gather context before planning. Bad research → bad plans → wasted time.
+
+## Research Types
+
+### 1. Codebase Research
+**When:** Joining existing project, planning changes to existing code, brownfield work.
+
+Steps:
+1. Map directory structure (`ls`, `find`, `tree`)
+2. Identify key files: entry points, config, routes, models, components
+3. Read conventions: naming, imports, error handling, testing patterns
+4. Identify tech stack: framework, libraries, versions
+5. Find existing patterns similar to planned work (reuse, don't reinvent)
+6. Document concerns: tech debt, fragile areas, missing tests
+
+Output: Research summary with file paths, patterns found, reuse opportunities.
+
+### 2. Requirements Research
+**When:** Requirements are vague, conflicting, or incomplete.
+
+Steps:
+1. Read all available requirements/specs/user stories
+2. Identify gaps — what's not specified?
+3. Mark uncertainties with `[NEEDS CLARIFICATION]`
+4. Draft acceptance criteria (Given/When/Then)
+5. Present clarification questions to user
+
+Output: Structured requirements draft with uncertainty markers.
+
+### 3. Technology Research
+**When:** Evaluating libraries, frameworks, APIs, or integration approaches.
+
+Steps:
+1. Check MCP servers first (structured data beats web scraping)
+2. Read official documentation (not blog posts)
+3. Check version compatibility with existing stack
+4. Look for known issues, migration guides, breaking changes
+5. Find working code examples from official sources
+
+Output: Technology assessment with recommendation and confidence level.
+
+### 4. Feasibility Research
+**When:** Unsure if approach will work, need to spike a risky idea.
+
+Steps:
+1. Identify the riskiest assumption
+2. Build minimal proof-of-concept (< 30 minutes)
+3. Test the critical path only
+4. Document: works / doesn't work / works with caveats
+
+Output: Feasibility verdict with evidence.
+
+## Tool Priority
+
+Use tools in this order (highest confidence first):
+
+1. **Codebase itself** — Read actual code. Highest confidence.
+2. **MCP servers** — Structured data from Notion, GitHub, Linear, etc.
+3. **Official docs** — Framework/library documentation via WebFetch.
+4. **Web search** — Community solutions, Stack Overflow, blog posts.
+5. **Training data** — Use as hypothesis only. Verify before trusting.
+
+## Confidence Levels
+
+Tag every finding:
+
+| Level | Meaning | Source Required |
+|-------|---------|----------------|
+| **HIGH** | Verified in codebase or official docs | Direct observation or official source |
+| **MEDIUM** | Found in multiple sources, not directly verified | 2+ independent sources agree |
+| **LOW** | Single source or inferred from patterns | Flag for verification |
+
+## Parallel Research
+
+When investigating independent topics, research them simultaneously:
+- Spawn separate research agents for each topic
+- Each agent gets a focused scope
+- Collect and synthesize results
+
+Do NOT research sequentially when topics are independent.
+
+## Output Template
+
+```markdown
+# Research: [Topic]
+
+## Summary
+[2-3 sentence executive summary of findings]
+
+## Key Findings
+1. [Finding] — Confidence: HIGH/MEDIUM/LOW — Source: [source]
+2. [Finding] — Confidence: HIGH/MEDIUM/LOW — Source: [source]
+
+## Recommendations
+- [Recommended approach with rationale]
+
+## Uncertainties
+- [NEEDS CLARIFICATION]: [What we don't know and why it matters]
+
+## Sources
+- [Source 1]: [URL or file path]
+- [Source 2]: [URL or file path]
+```
+
+## Size Gate
+
+Research output should be under 500 lines. If larger, split into focused documents:
+- `research-codebase.md` for codebase findings
+- `research-tech.md` for technology evaluation
+- `research-requirements.md` for requirements analysis

package/template/.claude/skills/securing/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: securing
+description: "Use when building features that touch authentication, user data, external APIs, or secrets. Trigger before shipping anything that handles sensitive data, manages sessions, calls third-party services, or processes user input. Also use for periodic security reviews of existing code."
+---
+
+# Securing
+
+Security is a requirement, not a feature. Review before shipping.
+
+## When This Skill Triggers
+
+Ask these 4 questions. If YES to any, run this skill:
+
+1. Does this feature touch **authentication or authorization**?
+2. Does it **store or transmit user data**?
+3. Does it **call external APIs** or accept webhooks?
+4. Does it **handle secrets, keys, or tokens**?
+
+## Security Checklist
+
+### Authentication & Authorization
+- [ ] Passwords hashed with bcrypt/scrypt/argon2 (never MD5/SHA)
+- [ ] Sessions/tokens expire (configurable, reasonable default)
+- [ ] Token refresh mechanism exists
+- [ ] Authorization checked server-side before every data access
+- [ ] Failed login attempts rate-limited
+- [ ] Password reset flow doesn't reveal account existence
+
+### Input Validation & Injection
+- [ ] All user input validated server-side (not just client-side)
+- [ ] SQL queries use parameterized statements (never string concatenation)
+- [ ] HTML output escaped to prevent XSS
+- [ ] File uploads validated: type, size, content (not just extension)
+- [ ] URL parameters sanitized before use
+- [ ] JSON parsing has size limits
+
+### Secrets Management
+- [ ] Secrets stored in environment variables, never in code
+- [ ] `.env` file in `.gitignore`
+- [ ] No secrets in logs, error messages, or stack traces
+- [ ] API keys scoped to minimum required permissions
+- [ ] Secrets rotated periodically (documented rotation process)
+
+### Data Protection
+- [ ] Sensitive data encrypted at rest (if stored)
+- [ ] HTTPS enforced for all data in transit
+- [ ] PII not logged (names, emails, addresses, IPs)
+- [ ] Data retention policy defined (how long, when deleted)
+- [ ] CORS configured to allow only known origins
+
+### Dependencies
+- [ ] `npm audit` (or equivalent) passes or vulnerabilities documented
+- [ ] No known vulnerable versions of critical dependencies
+- [ ] Lock file committed (package-lock.json, yarn.lock)
+- [ ] Dependencies from trusted registries only
+
+### Error Handling
+- [ ] Error messages don't leak internal details (stack traces, DB schema, file paths)
+- [ ] Unhandled exceptions caught and logged (not displayed to user)
+- [ ] Rate limiting on all public endpoints
+- [ ] Graceful degradation when external services fail
+
+## Output
+
+Create `security-review.md`:
+
+```markdown
+# Security Review: [Feature Name]
+
+Date: [YYYY-MM-DD]
+Reviewer: Claude (Forge security skill)
+
+## Scope
+[What was reviewed: files, endpoints, data flows]
+
+## Findings
+
+### Critical (Must fix before shipping)
+- [Finding with file path and line reference]
+
+### Warning (Should fix soon)
+- [Finding with file path and line reference]
+
+### Info (Improvement opportunity)
+- [Finding with file path and line reference]
+
+## Checklist Results
+[Copy checklist with pass/fail marks]
+
+## Recommendations
+[Prioritized list of actions]
+```
+
+## Common Patterns to Flag
+
+| Pattern | Risk | Fix |
+|---------|------|-----|
+| `eval()` or `new Function()` | Code injection | Remove; use safe alternatives |
+| `dangerouslySetInnerHTML` | XSS | Sanitize with DOMPurify first |
+| `SELECT * FROM users WHERE id = '${id}'` | SQL injection | Use parameterized queries |
+| `console.log(user)` with PII | Data leak | Log user.id only |
+| Hardcoded `Bearer sk-...` | Secret leak | Move to env var |
+| `cors({ origin: '*' })` | CORS bypass | Whitelist specific origins |
+| Missing `httpOnly` on auth cookie | Cookie theft | Add `httpOnly: true, secure: true` |