@jamie-tam/forge 6.0.0

package/references/typescript/standards.md

@@ -0,0 +1,42 @@
+# TypeScript Standards
+
+Extends common coding standards with TypeScript-specific rules.
+
+## Compiler Configuration
+
+- `strict: true` always — no exceptions
+- `noUncheckedIndexedAccess: true`, `exactOptionalProperties: true`
+
+## Type Safety
+
+- No `any` — use `unknown` and narrow
+- `interface` for object shapes, `type` for unions/intersections/computed
+- Discriminated unions over type guards: `{ ok: true; data: T } | { ok: false; error: E }`
+
+## Runtime Validation
+
+- Zod (or similar) at system boundaries: API bodies, env vars, config
+- Parse external data into typed structures — never trust raw input
+
+## Module Organization
+
+- Barrel exports (`index.ts`) for public APIs; internals not exported
+- One responsibility per file, co-locate tests
+
+## Modern TypeScript
+
+- `as const` for literal types, `satisfies` for type-safe inference
+- Template literal types for string patterns
+- `Map`/`Set` over plain objects for dynamic keys
+
+## Error Handling
+
+- Typed Result types over try/catch where possible
+- Catch at boundaries, not every function
+- Never catch and ignore — handle, transform, or re-throw
+
+## Naming
+
+- Interfaces/Types: PascalCase (no `I` prefix)
+- Enums: PascalCase members
+- Constants: UPPER_SNAKE_CASE for true constants

package/rules/common/forge-system.md

@@ -0,0 +1,59 @@
+---
+description: Forge system structure — skills (prefix-grouped), commands (orchestrate skills), .forge/ directory layout, context recovery. Auto-loaded every session so agents know the system they're operating in.
+---
+
+# Forge System
+
+This project uses **forge** as its development workflow. Every session should follow it.
+
+## Skills (prefix-grouped)
+
+| Prefix | Purpose | Examples |
+|--------|---------|---------|
+| `discover-` | Understand inputs and codebase | requirements, codebase-analysis |
+| `plan-` | Design before building | brainstorm, architecture, task-decompose, design-system |
+| `build-` | Write code and manage git | scaffold, tdd, pr-workflow, wireframe, prototype |
+| `quality-` | Review, test, audit | code-review, test-plan, test-execution, security-audit, uiux |
+| `deliver-` | Ship and migrate | deploy, db-migration, onboarding |
+| `support-` | Maintain and learn | system-guide, debug, gotcha, skill-validator |
+
+v6 also adds phase skills: concept-slides, build-wireframe, build-prototype, iterate-prototype, harden.
+
+## Commands (orchestrate skills)
+
+| Command | When to use |
+|---------|------------|
+| `/forge` | One-screen discovery — installed capabilities, active work, suggested next |
+| `/setup` | Detect stack, install matching language rules, and fill the project profile |
+| `/feature` | Full feature development |
+| `/greenfield` | New project from zero |
+| `/bugfix` | Fix a bug |
+| `/refactor` | Improve existing code |
+| `/hotfix` | Emergency production fix |
+| `/evolve` | Improve the forge system itself |
+| `/validate` | Check skill consistency |
+
+## .forge/ Directory
+
+```
+.forge/
+  work/                        # Per-work-item artifacts, one subdir per type
+    feature/{name}/            # manifest, requirements, architecture, tasks, test plan/results
+    bugfix/{name}/             # manifest, debug notes, regression tests
+    refactor/{name}/           # manifest, codebase analysis, tasks, test results
+    hotfix/{name}/             # manifest, minimal debug, smoke tests
+    greenfield/{name}/         # manifest + full project scaffold artifacts
+  state/                       # Runtime state (notepad.md, telemetry, dream history)
+```
+
+Project knowledge (ADRs, gotchas) lives under `aiwiki/` — see `aiwiki/decisions/` and `aiwiki/gotchas/`. The `.forge/` directory retains operational state only (manifests, telemetry, dream history).
+
+Work items are identified by `{type}/{name}` — names may collide across types.
+
+## Context Recovery
+
+If `.forge/state/notepad.md` exists, read it FIRST before doing anything else.
+
+## Rules
+
+Rules in `.claude/rules/` are always-on constraints. Common rules apply to all projects. Language-specific rules layer on top.

package/rules/common/git-workflow.md

@@ -0,0 +1,40 @@
+---
+description: Git commit and PR conventions — Conventional Commits format, bisectable commits, branch naming. Auto-loads into every session including forge subagents (builder, prototype-builder) which lack Skill-tool access.
+---
+
+# Git Workflow
+
+## Conventional Commits
+
+Format: `type(scope): description` — lowercase, imperative mood.
+
+| Type | When |
+|------|------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Restructuring (no behavior change) |
+| `test` | Adding or updating tests |
+| `docs` | Documentation only |
+| `chore` | Build, config, tooling |
+
+## Commit Discipline
+
+- One commit per logical change — each must be bisectable
+- Every commit must leave the project in a working state
+- Always create new commits; never amend unless explicitly asked
+- Never commit generated files, build artifacts, or secrets
+
+## Branch Naming
+
+`feat/`, `fix/`, `refactor/`, `hotfix/` + kebab-case description.
+
+## Pull Requests
+
+- One PR per logical function — atomic, independently mergeable
+- PR description references requirements or issue
+- Squash merges for feature branches
+- Every PR must pass CI before merge
+
+## Secrets
+
+See [rules/common/security.md](security.md) for canonical secrets handling.

package/rules/common/guardrails.md

@@ -0,0 +1,37 @@
+---
+description: Safety floor — never run destructive operations (rm -rf, force-push, DROP TABLE, --no-verify) without explicit confirmation. Universal across all phases.
+---
+
+# Guardrails
+
+Safety rules that apply to every action. When in doubt, ask.
+
+## Blocked Operations
+
+Never execute without explicit user confirmation:
+
+- `rm -rf` — Use targeted deletes instead
+- `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`
+- `git push --force` — Suggest `--force-with-lease` and confirm
+- `git reset --hard` — Warn about data loss
+- `--no-verify` on any git command — Hooks exist for a reason
+
+## Require Confirmation Before
+
+- Deleting git branches (local or remote)
+- Modifying CI/CD configuration files
+- Running destructive database migrations
+- Overwriting files outside the current project
+- Any operation described as "irreversible"
+
+## Never Commit Secrets
+
+See [rules/common/security.md](security.md) for canonical secrets handling.
+
+## Deployment
+
+The `deliver-deploy` skill and `/hotfix` command respect all guardrails. Speed does not override the confirmation requirement for irreversible actions.
+
+## When Uncertain
+
+Stop and ask the user. A 30-second question is better than a 30-minute rollback.

package/rules/common/quality-gates.md

@@ -0,0 +1,18 @@
+---
+description: Gate-state names and pass criteria summary — auto-loaded every session for quick recall; references/common/quality-gates.md has the full tables.
+---
+
+# Quality Gates
+
+Gates block phase transitions until criteria are met. See [references/common/quality-gates.md](../../references/common/quality-gates.md) for the full gate-set tables, pass criteria, and fail actions.
+
+Gate names (per `hooks/config/gate-requirements.json`):
+- code-review-final
+- code-review (per-slice)
+- test-plan
+- test-execution
+- uiux-review
+- runtime-reach (per-slice wiring gate)
+- wiki-lint (per-slice)
+
+Security audit is invoked as a skill (`quality-security-audit`) on High/Critical-risk diffs — see `quality-code-review` Risk Classification — rather than a dedicated `phases.*` gate.

package/rules/common/security.md

@@ -0,0 +1,50 @@
+---
+description: Security baseline for all code — no hardcoded secrets, parameterized queries, input validation, secure auth, dependency hygiene. Universal across phases.
+---
+
+# Security Standards
+
+Security is a constraint, not a feature. These rules apply to all code.
+
+## Secrets Management
+
+- ZERO hardcoded secrets: API keys, passwords, tokens, connection strings
+- Use environment variables or a secret manager
+- `.env` files never committed — use `.env.example` with placeholders
+- Rotate any secret that was ever exposed in version control
+
+## Database Security
+
+- Parameterized queries for ALL database access — no string concatenation
+- Use an ORM or query builder that parameterizes by default
+- Principle of least privilege for database users
+
+## Input Validation
+
+- Validate all user-facing input at the boundary
+- Whitelist valid input rather than blacklisting bad input
+- Validate type, length, range, and format
+- Reject unexpected fields — don't silently ignore them
+
+## Web Security
+
+- No `*` CORS in production; CSP, HSTS, X-Content-Type-Options, X-Frame-Options headers required
+- CSRF tokens on all state-changing endpoints; sanitize all HTML output
+
+## Data Protection
+
+- Sensitive data (PII, credentials, tokens) never in logs or error messages
+- Never return sensitive data in API error responses
+- Encrypt sensitive data at rest where applicable
+
+## Dependencies
+
+- Check for known CVEs before adding any new dependency
+- Pin dependency versions — no floating ranges in production
+- Audit periodically (`npm audit`, `pip-audit`)
+
+## Authentication and Authorization
+
+- Use established libraries (don't roll your own auth/crypto)
+- Session tokens: HttpOnly, Secure, SameSite attributes
+- Rate limiting on auth endpoints

package/rules/common/skill-selection.md

@@ -0,0 +1,78 @@
+---
+description: How to route user intent to the right slash command or skill — detect repo mode (prototype vs production) first, then route.
+---
+
+# Skill Selection
+
+When to load a skill — even outside commands. This rule is always active.
+
+## The Rule
+
+**Detect repo state first. Then check intent. Load the matching skill before writing code or responding.**
+
+## Step 1: Detect Repo State
+
+Before routing on user intent, classify the repo. Two primary modes; signals are checked in order.
+
+| Mode | Signals (any of these) | Implications |
+|---|---|---|
+| **Prototype** | Path under `pocs/` or directory name ends in `-prototype`; `package.json` has `"private": true` and no test runner / no CI; `aiwiki/architecture/` is empty or missing; manifest has `phase_plan.prototype: active` and `phase_plan.codify: skipped` | TDD is exempt (per `rules/common/testing.md` phase header). UI work iterates in-place. Gotchas are recorded but production hardening is deferred. |
+| **Production** | `aiwiki/architecture/` has entries (codified); manifest has `phase_plan.codify: active` and `phase_plan.production-build: active`; CI configured + tests pass | Phase-conditional rules (testing, quality-gates, git-workflow) are active. Production code must go through `build-tdd`. |
+
+**Mixed mode** (prototype directory inside a production repo, or vice versa) is rare; treat the work item's local context as authoritative — if you're touching files under `pocs/`, you're in prototype mode for that work.
+
+When the mode is ambiguous, ask the user once. Do not guess.
+
+## Step 2: Priority Rule
+
+When multiple skills match, follow this order:
+
+1. **Diagnose first** — `support-debug` before any fix-skill for bugs
+2. **Route by mode**:
+   - **Prototype mode**: `iterate-prototype` is the default execution skill. No `build-tdd`, no `harden`, no `plan-architecture` unless explicitly invoked.
+   - **Production mode**: `harden` produces architecture/ADRs/slice graph at codify; `build-tdd` implements at production-build.
+3. **Review after build** — `quality-code-review` after production code is written (not for prototype iteration; that uses `prototype-reviewer` via `iterate-prototype`)
+4. **Plan-* skills are non-prototype fallback only** — `plan-brainstorm`, `plan-architecture`, `plan-task-decompose` are for library / internal-tool / refactor work where prototype/wireframe phases don't apply. Not the default for `/feature` or `/greenfield`.
+
+## Step 3: Direct-Request Routing
+
+| User says / situation | Prototype mode loads | Production mode loads | Why |
+|---|---|---|---|
+| Bug, error, unexpected behavior | `iterate-prototype` (capture as feedback item) | `support-debug` → `build-tdd` | Diagnose-then-fix is universal; the fix lives in different skills per mode |
+| "Add X" / "tweak X" / "improve UI" | `iterate-prototype` | `/feature` (full pipeline) or `build-tdd` if mid-flow | Prototype iteration is lightweight; production features need the gated pipeline |
+| "Make this fast" / "refactor this" | `iterate-prototype` (mark as iteration item) | `build-tdd` (refactors need tests proving behavior preserved) | |
+| Before declaring code changes done | `prototype-reviewer` (informal pass) | `quality-code-review` (full multi-stage chain) | Review depth scales with mode |
+| Surprising lesson, workaround, wrong assumption | `support-gotcha` | `support-gotcha` | Mode-independent: writes to `aiwiki/gotchas/` |
+| "How should we approach X?" / design discussion | Existing prototype IS the design exploration — answer inline; no skill | `plan-brainstorm` (non-prototype fallback only) | Prototype-driven flow makes brainstorm redundant |
+| Need API contracts, DB schema, system design | If a prototype exists, use `harden` to codify; otherwise `plan-architecture` (fallback) | `harden` (from prototype) or `plan-architecture` (fallback) | Codify-from-prototype is the default; plan-* is the fallback |
+| New visual direction, design tokens, UI system | `plan-design-system` | `plan-design-system` | Mode-independent design step |
+| Security concerns, pre-deploy audit | Not applicable during prototype phases | `quality-security-audit` | Pre-deploy gate; safety floor rules always active |
+| Database schema changes needed | Not applicable (prototype data is mocked) | `deliver-db-migration` | |
+| Ready to deploy | Not applicable | `deliver-deploy` | |
+| New team member needs onboarding | `deliver-onboarding` (light) | `deliver-onboarding` (full) | Same skill; depth varies by mode |
+
+## Ambiguous Requests
+
+Some requests could mean multiple things. Ask before guessing.
+
+| Request | Could be... | How to decide |
+|---|---|---|
+| "There's no button for X" | Bug (should exist) OR feature (doesn't exist yet) | Ask: "Should this button already exist, or is this a new feature request?" |
+| "X isn't working right" | Bug (broken) OR feature gap (never built) | Check if the code path exists. If yes → diagnose. If no → mode-routed feature work. |
+| "Can we improve X?" | Refactor OR feature enhancement | Ask: "Is this changing behavior or just restructuring?" Then mode-route. |
+| User in production repo says "let me just tweak something" | Production work OR mistaken-for-prototype | Ask: "Is this a one-off ad-hoc change or a tracked feature?" One-off may still need gates if it touches production-built code. |
+
+When genuinely ambiguous, ask — don't guess.
+
+## What This Rule Does NOT Cover
+
+- **Command routing under explicit invocation** — if the user types `/feature`, `/bugfix`, etc., the command's own preflight handles state detection and may redirect (see each command's Step 0). This rule covers routing when the user describes intent without naming a command.
+- **Which skill to invoke inside a command** — commands specify `REQUIRED SUB-SKILL` explicitly
+- **Skill invocation correctness** — see `skill-compliance.md` for that
+
+## The Explicit Rule
+
+- **In production mode**: any production-code change, no matter how small, requires `build-tdd`. "It's just one line" is not an exception. "It's obvious" is not an exception. The skill exists because shortcuts cause regressions.
+- **In prototype mode**: code changes use `iterate-prototype` (or inline editing for trivial cases). TDD is intentionally exempt per `rules/common/testing.md` phase header — the prototype's verification surface is manual click-through, not test coverage.
+
+Mode determines which rule applies. Don't apply production discipline to prototype iteration; don't waive production discipline for "this feels like prototyping" inside a production repo.

package/rules/common/testing.md

@@ -0,0 +1,58 @@
+---
+description: Test-driven development standards for production code — RED-GREEN-REFACTOR, coverage targets, mocking strategy. Loads conditionally via paths on test files and src/ code.
+paths:
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/__tests__/**"
+  - "**/tests/**"
+  - "**/test/**"
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+  - "src/**/*.js"
+  - "src/**/*.jsx"
+  - "src/**/*.py"
+---
+
+# Testing Standards
+
+Test-driven development is mandatory for production code. Code without tests is incomplete. TDD cycle: RED → GREEN → REFACTOR. See `build-tdd` skill for the full process.
+
+## Coverage Requirements
+
+- Minimum: 80% line coverage across the project
+- Critical paths: 100% coverage required (auth, payments, security, data mutations)
+- Coverage is necessary but not sufficient — test quality matters more than numbers
+
+## Test Types Required
+
+| Type | Covers | Required |
+|------|--------|----------|
+| Unit | Individual functions, edge cases | Always |
+| Integration | Component interactions, API contracts | Always |
+| E2E | Full user flows via browser/client | For user-facing features |
+
+## Test Quality
+
+- Every test must fail first (proves it tests something real)
+- One behavior per test — not multiple assertions testing different things
+- Test edge cases: null/undefined, empty collections, boundary values, error paths
+- Use descriptive test names that explain the behavior being verified
+
+## Mocking Strategy
+
+| Test Level | External Services | Internal Dependencies |
+|---|---|---|
+| **Unit** | Mocks OK — isolate the unit | Mocks OK |
+| **Integration** | SHOULD use real if available, mocks require documented justification | Real |
+| **E2E** | MUST use real if confirmed available, BLOCKED if not | Real |
+
+Mock-only suites fail the quality gate. Every external dependency needs at least one integration/E2E test against the real service. E2E tests MUST NOT fall back to fake data on timeout — they FAIL.
+
+**Exemption:** `/hotfix` uses smoke tests + regression test only (not the full test plan). Full test coverage is deferred to the follow-up ticket. See `quality-gates.md` Hotfix Gate Exemptions and `quality-test-execution` Step 2 note.
+
+## Anti-Patterns
+
+- No tests that only verify the mock
+- No skipped tests in CI (fix or delete them)
+- No test code in production builds
+- No flaky tests — fix the root cause or quarantine immediately

package/rules/common/verification.md

@@ -0,0 +1,39 @@
+---
+description: Verify-before-claim discipline — check docs before coding, run tests before claiming done, no "should work" without smoke. Universal anti-hallucination guard.
+---
+
+# Verification
+
+This is a universal rule. It applies to every action.
+
+## Verify Before Using
+
+When uncertain about ANY API, library behavior, function signature, or pattern:
+
+1. Check documentation via context7 MCP or web search BEFORE writing code
+2. Do not assume you know the current API — libraries change between versions
+3. Do not guess parameter names, return types, or default behaviors
+
+## Verify After Implementing
+
+Before claiming any task is complete:
+
+1. Execute the verification command (test suite, build, type check)
+2. Review the output — do not just check the exit code
+3. Confirm the output actually supports the claim of completion
+
+## Red Flags
+
+Stop and verify: "seems fixed", "should work now", "based on my knowledge", claiming completion before running tests.
+
+## No "Should Work"
+
+- If you wrote code, run it
+- If you fixed a bug, reproduce the original failure first, then confirm the fix
+- If you changed a config, validate the config loads correctly
+
+## Library and Framework Rules
+
+- Check the installed version before referencing API docs
+- Use the docs for THAT version, not the latest
+- If a method doesn't exist at runtime, check the version — don't hack around it