@jamie-tam/forge 6.0.0

package/references/common/agent-coordination.md

@@ -0,0 +1,65 @@
+# Agent Coordination
+
+Quality principles for dispatching and managing subagents.
+
+## Agent Roles
+
+| Role | Agents | Output type | Review needed? |
+|------|--------|-------------|---------------|
+| **Builder** | builder | Production code + tests via TDD | Yes — quality-code-review after each task |
+| **Producer** | architect, doc-writer | Artifacts that downstream work depends on | Yes — errors cascade |
+| **Reviewer** | critic, code-reviewer, craft-reviewer, security-reviewer, spec-reviewer | Assessments and verdicts | No — output IS the review |
+| **Executor** | e2e-runner | Objective results (pass/fail) | No |
+| **Investigator** | tracer | Hypotheses and analysis | No — feeds back to main agent |
+| **Recall** | gotcha-hunter | Diff-relevant entries from the gotcha catalogs | No — output is a citation list, not a judgment |
+
+## Pre-Dispatch Requirements
+
+- API contracts defined before dispatching parallel builders or producers
+- Provide task objective, scope, and success criteria in the prompt
+- Builder agents need architecture artifacts inline in the prompt (`.forge/` is not in version control — worktree checkouts won't have them)
+- Define clear expected outputs to verify delivery
+
+## Communication
+
+- Main agent bridges ALL inter-agent communication — subagents never talk directly
+- If a subagent discovers a dependency on another's work, STOP and ask the main agent
+
+## Review Gates
+
+Producer output is reviewed in two stages — first `spec-reviewer` for compliance against the source artifact (requirements / architecture / design), then the `quality-code-review` chain (safety → craft → reachability → gotcha-hunter) for code quality. The `critic` agent reviews planning artifacts before they are presented to the user.
+
+## Model Routing
+
+| Complexity | Model | Examples |
+|-----------|-------|---------|
+| Simple | Haiku | Formatting, simple refactors |
+| Standard | Sonnet | Implementation, tests, code review, docs |
+| Complex | Opus | Architecture, multi-perspective critique, cross-system design |
+
+## Worktree Isolation
+
+`isolation: "worktree"` is a **safety mechanism** preventing file interference, not a speed mechanism. Agents MUST commit changes; merge via `git merge --no-ff`, never `cp`. See `build-pr-workflow` for the full protocol.
+
+## Coupling Rules
+
+- If two tasks share a DB table, API endpoint, state, or modify the same file — serialize them
+- Independent modules (separate APIs, separate UI components) can run in parallel
+- When in doubt, serialize — correctness over speed
+- **File-overlap = serialize.** If two tasks in the same phase create or modify the same file, they MUST be in different phases. This is validated during task decomposition. A merge conflict at build time means decomposition failed — resolve the conflict, then re-serialize remaining related tasks in the current and future phases.
+
+## Agent Self-Containment
+
+Agents carry their own execution methodology inline in their definition. They do not load skills via frontmatter (`skills:` field).
+
+- Skills are for human or inline sessions — they define process and can dispatch agents
+- Agents are execution units — they receive task scope + artifacts and follow their built-in protocol
+- Dispatch prompts pass task + artifacts only, not methodology (the agent already has it)
+
+This prevents circular loading (skill dispatches agent, agent loads skill that dispatches agent) and keeps each agent's context focused on the task.
+
+## Failure Handling
+
+- If a subagent fails, diagnose before retrying
+- Review partial results before discarding
+- Report failures to the user with context

package/references/common/coding-standards.md

@@ -0,0 +1,54 @@
+# Coding Standards
+
+Universal code quality principles. Language-specific rules extend these.
+
+## Immutability
+
+- Prefer creating new objects over mutating existing ones
+- Use `const` by default; `let` only when mutation is required
+- Avoid side effects in functions where possible
+
+## Function Size and Complexity
+
+- Functions: 50 lines max (excluding docstring/comments)
+- Max nesting depth: 4 levels (use early returns to flatten)
+- Single responsibility: one function does one thing
+- If a function needs a comment explaining what it does, it needs a better name
+
+## File Size
+
+- Typical: 200-400 lines
+- Maximum: 800 lines
+- If a file exceeds 800 lines, split by responsibility
+
+## Organization
+
+- Organize by feature/domain, not by file type
+- Good: `features/payments/controller.ts`, `features/payments/service.ts`
+- Bad: `controllers/paymentController.ts`, `services/paymentService.ts`
+- Co-locate tests with implementation (`foo.ts` + `foo.test.ts`)
+
+## No Hardcoded Values
+
+- Magic numbers and strings go into named constants
+- Configuration values come from config files or environment variables
+- URLs, ports, timeouts, limits — all configurable
+
+## Error Handling
+
+- Handle errors at system boundaries (API calls, file I/O, DB queries)
+- Use typed errors or error codes, not generic catch-all
+- Never swallow errors silently
+- Log errors with context (what was attempted, what failed, relevant IDs)
+
+## Input Validation
+
+- Validate all external input at system boundaries
+- Parse, don't validate: transform untyped input into typed structures
+- Fail fast with clear error messages
+
+## DRY Without Over-Abstraction
+
+- Three similar lines are better than one premature abstraction
+- Extract when you see the pattern three times (Rule of Three)
+- Abstractions should simplify, not just reduce line count

package/references/common/feature-tracking.md

@@ -0,0 +1,21 @@
+# Work Tracking
+
+Every command creates a work manifest that tracks phases, gates, and artifacts. State lives at `.forge/work/{type}/{name}/manifest.yaml`. Each skill reads it to find the work directory, writes to record artifacts and gates passed.
+
+Full manifest schema: canonical templates live in `.claude/templates/manifests/`. Commands reference these templates — do not duplicate manifest schemas elsewhere.
+
+- `feature.yaml` — template for `/feature`
+- `greenfield.yaml` — template for `/greenfield`
+- `bugfix.yaml` — template for `/bugfix`
+- `refactor.yaml` — template for `/refactor`
+- `hotfix.yaml` — template for `/hotfix` (compressed phases; follow-up tracked via successor_path)
+
+## Rules
+
+- One manifest per work item — never share manifests across work items
+- Manifests may be committed to version control for traceability (team preference)
+- Never manually edit a manifest unless debugging the workflow
+- Every command (including `/bugfix` and `/hotfix`) creates a manifest — work state is uniform across types
+- Phases with `status: not-applicable` are skipped during resume and gate checking (e.g., `design-system` for backend-only features)
+- Terminal states (`completed`, `escalated`) must not be resumed — hooks and commands filter them out
+- Work identifier is `{type}/{name}` — names may collide across types (e.g., `feature/add-auth` and `bugfix/add-auth` can coexist)

package/references/common/io-protocol.md

@@ -0,0 +1,36 @@
+# I/O Protocol
+
+Skills that materially participate in artifact handoff declare an I/O contract. This enables dependency checking and workflow automation without forcing pure methodology skills to duplicate orchestration metadata.
+
+## Contract Format
+
+When a skill needs an I/O contract, use this section format:
+
+```yaml
+io_contract:
+  requires:           # Input artifacts that must exist before invocation
+    - artifact: "requirements.md"
+      path: "{work-dir}/requirements.md"
+  produces:           # Output artifacts created by this skill
+    - artifact: "architecture/api-contract.md"
+      path: "{work-dir}/architecture/api-contract.md"
+  feeds_into:         # Downstream skills that consume this skill's output
+    - task-decompose
+  updates_manifest:   # Which manifest fields this skill writes
+    - artifacts.architecture
+```
+
+`{work-dir}` resolves to `.forge/work/{type}/{name}/`.
+
+## Pre-Invocation Check
+
+Before invoking any skill with an I/O contract:
+1. Verify each required artifact exists at the expected path
+2. If missing: invoke the producing skill first, or ask the user
+
+## Post-Completion Check
+
+After a skill with an I/O contract completes:
+1. Verify all `produces` artifacts were created
+2. Verify manifest was updated
+3. If missing: report the gap — do not silently proceed

package/references/common/phases.md

@@ -0,0 +1,57 @@
+# Phase Vocabulary
+
+The canonical phase numbering and names for forge's prototype-driven SDLC. Skills, agents, and command files reference this when stating phase context. Other files must NOT invent their own numbering.
+
+## The seven phases
+
+| # | Canonical name | Primary skill | Primary agent | What happens |
+|---|---|---|---|---|
+| 1 | **Concept** | `concept-slides` | `concept-designer` | Low-fidelity slide deck capturing the product idea — hook, sub-concepts, sketch fidelity, user journey, deferrals |
+| 2 | **Wireframe** | `build-wireframe` | `wireframer` | Single-HTML annotated wireframe with click-through demo and callouts; static, no real backend |
+| 3 | **Prototype** | `build-prototype` | `prototype-builder` | Working interactive build with mocked data — fast iteration, manual verification, no test rigor |
+| 4 | **Iterate** | `iterate-prototype` | `prototype-reviewer` | Tighten interactions, fix gotchas, capture conventions as side effects of doing the work |
+| 5 | **Codify** | `harden` | `prototype-codifier` | Transcribe locked prototype into architecture pages, ADRs, slice graph — the bridge to production-build |
+| 6 | **Production-build** | `build-tdd` | `builder` | Real code with full TDD discipline, production standards, gates, and reviews |
+| 7 | **Deliver** | `deliver-deploy` / `deliver-db-migration` / `deliver-onboarding` | (skills only; no dedicated agent) | Ship to production: migrations, deploy, onboarding docs |
+
+## Softening rule
+
+Phases are **defaults, not requirements**. The work-item manifest at `.forge/work/{type}/{name}/manifest.yaml` tracks the plan under `phase_plan.{phase}` (v6) with values like `active`, `active-light`, `skipped`, `complete-inline` — skips, reduced-rigor runs, and retroactive entries are all legitimate. See `templates/manifests/v6/SCHEMA.md` §3 for the full vocabulary. Examples:
+
+- A 30-line bugfix may skip concept + wireframe + prototype entirely and start at codify
+- A library extraction may skip prototype + iterate (no UI surface to verify against)
+- A spike may stop at prototype and never codify
+
+Commands (`/feature`, `/bugfix`, `/greenfield`, `/refactor`) ask the AI to propose phase skips at preflight; the user confirms. Forcing all seven on every work item is wrong shape with current model capability.
+
+## Phase-conditional rules
+
+The following rules apply from Phase 5 (codify) onward, per their own phase headers:
+
+- `rules/common/testing.md` — TDD becomes mandatory
+- `references/common/quality-gates.md` — full gate set (the rule-tier stub at `rules/common/quality-gates.md` fans out to this reference)
+- `rules/common/git-workflow.md` — conventional commits + branch hygiene
+
+Phases 1–4 operate under the safety-floor rules only (`rules/common/security.md`, `guardrails.md`, `verification.md`, `skill-selection.md`).
+
+## How to reference this in agent/skill files
+
+When a file needs to state its phase context, use the canonical name and number together on first mention:
+
+> "Dispatched at Phase 5 (codify) lock."
+> "This skill runs in Phase 6 (production-build), after harden has produced the architecture and slice graph."
+
+Do NOT:
+- Use a different number for the same phase across files
+- Use only the number ("Phase 5") without the canonical name on first mention
+- Coin new phase names ("hardening phase", "the codification step") — use `codify` everywhere
+- Refer to a non-existent phase ("Phase 4 lock" when you mean Phase 3 prototype lock or Phase 4 iterate lock)
+
+## Skill-name vs phase-name mismatches (intentional)
+
+Two skills carry names that don't match their phase name:
+
+| Phase | Phase name | Skill name | Why mismatch is OK |
+|---|---|---|---|
+| 5 | codify | `harden` | "Harden" describes what the work feels like (production-grade hardening of prototype decisions); "codify" describes what the output is (codified plans). Both names persist; use phase name when stating context, skill name when invoking. |
+| 7 | deliver | `deliver-*` (multiple) | The phase has several skills, not one; "deliver" is the phase, each skill is one delivery surface. |

package/references/common/quality-gates.md

@@ -0,0 +1,130 @@
+# Quality Gates
+
+Phase transition criteria. Every gate must pass before proceeding.
+
+> **v6 status — read this first.** The canonical gate list for v6 lives in
+> `hooks/config/gate-requirements.json` (machine-readable; consumed by
+> `gate-enforcer.sh`). The v6 prototype-driven pipeline collapses the v5
+> "brainstorm / architecture / task-decompose" trio into Phase 5 `codify`
+> (the `harden` skill); their checklists below remain accurate for **v5
+> fallback** workflows (`/refactor` keeps the brainstorm + task-decompose
+> shape) and for any v4/v5 manifests still in flight. New `/feature` and
+> `/greenfield` runs will not surface `brainstorm-approved.md` or
+> `architecture-approved.md` — those v5 artifacts have v6 equivalents
+> under `aiwiki/decisions/` and `aiwiki/architecture/`.
+
+## Gate Definitions (v5 — fallback)
+
+### requirements -> brainstorm
+- [ ] Every requirement has acceptance criteria
+- [ ] Every requirement has a priority (must/should/could/won't)
+- [ ] No implementation details in requirements
+- [ ] User has reviewed and approved requirements
+
+### brainstorm -> architecture
+- [ ] User explicitly approved the chosen approach
+- [ ] Rejected alternatives documented with rationale
+- [ ] Approach is documented in brainstorm-approved.md
+
+### architecture -> task-decompose
+- [ ] API contracts fully defined (endpoints, request/response shapes, error codes)
+- [ ] DB schema complete (tables, columns, indexes, constraints)
+- [ ] System diagram created (ASCII format)
+- [ ] ZERO TBDs remaining in architecture documents
+- [ ] Architectural decisions recorded in decision log
+
+### task-decompose -> tdd
+- [ ] Every task has: description, affected files, inputs, expected outputs
+- [ ] Task dependencies identified (which block which)
+- [ ] Parallel vs. sequential tasks marked
+- [ ] Tasks reviewed by spec-reviewer
+
+### tdd -> code-review
+- [ ] All unit tests pass
+- [ ] No skipped tests
+- [ ] Coverage meets project threshold (80%+ default)
+- [ ] Implementation matches API contracts from architecture
+
+### code-review -> test-execution
+- [ ] All critical review items resolved
+- [ ] All important review items resolved or documented as accepted risk
+- [ ] Security audit passed (required when changes touch auth, payments, encryption, PII, user-input handling that introduces injection/XSS surfaces, or external service integrations — see `quality-security-audit`)
+
+### test-execution -> deploy
+- [ ] Every test plan item has a pass/fail result
+- [ ] Zero test failures
+- [ ] Coverage report generated and meets threshold
+- [ ] Traceability: every requirement maps to a passing test
+
+## Refactor Gates
+
+Refactoring uses a compressed gate set — no requirements or architecture phases.
+
+### discover -> brainstorm
+- [ ] Codebase analysis complete and approved by user
+- [ ] Refactoring scope, rationale, and constraints documented
+
+### brainstorm -> task-decompose
+- [ ] User approved refactoring approach
+- [ ] Rejected alternatives documented
+
+### task-decompose -> tdd
+- [ ] Tasks reviewed and approved by user
+- [ ] Dependencies and parallel/sequential execution marked
+- [ ] Coverage baseline recorded
+
+### tdd -> test-execution
+- [ ] All phases complete, per-task code reviews passed
+- [ ] All tests pass on merged result
+- [ ] Coverage equals or exceeds baseline
+- [ ] Any test breakage during refactoring was reverted — not fixed by adjusting the test to match new behavior
+
+### test-execution -> assessment
+- [ ] All tests pass
+- [ ] Coverage equals or exceeds baseline from Step 0
+
+### assessment (Refactoring Assessment) -> deliver
+- [ ] Before/after summary produced (quantitative + qualitative)
+- [ ] User has reviewed the assessment
+- [ ] Assessment feeds into PR description
+
+## Bugfix Gates
+
+Bugfix uses a minimal gate set — root cause identification is the critical gate.
+
+### debug -> build
+- [ ] Root cause confirmed with evidence trail
+- [ ] Debugging summary produced (root cause, evidence, hypotheses tested)
+- [ ] User reviewed root cause analysis
+
+### build -> code-review
+- [ ] Regression test written and passes
+- [ ] All existing tests still pass
+- [ ] Fix is minimal — no unrelated changes
+
+### code-review -> deliver
+- [ ] All critical and important review items resolved
+
+## Hotfix Gate Exemptions
+
+The `/hotfix` command uses a compressed gate set for emergency fixes. These exemptions are intentional, not bugs:
+
+| Standard Gate | Hotfix Equivalent | Deferred To |
+|---|---|---|
+| requirements -> brainstorm | Skipped | Follow-up ticket |
+| brainstorm -> architecture | Skipped | Follow-up ticket |
+| architecture -> task-decompose | Skipped | Follow-up ticket |
+| tdd -> test-execution | Existing tests + smoke tests + regression test (not full test plan) | Follow-up ticket |
+| test-execution -> code-review | Critical pass only (not full two-pass) | Follow-up ticket |
+| code-review -> deploy | Direct after critical pass | Follow-up ticket |
+
+Every hotfix MUST create a follow-up ticket that completes the skipped gates. A hotfix without follow-up is incomplete.
+
+## Gate Outcomes
+
+| Result | Action |
+|--------|--------|
+| **Pass** | Proceed to next phase |
+| **Warn** | Proceed with documented concerns in manifest |
+| **Fail** | STOP. Report what is missing. Return to previous phase. |
+| **Blocked** | Cannot fully verify — proceed to PR with INCOMPLETE flag visible in PR description and test results. Cannot deploy to production without resolution. |

package/references/common/skill-authoring.md

@@ -0,0 +1,154 @@
+# Skill Authoring Guidelines
+
+Principles for creating and modifying skills. Reference this when using the skill-creator or `/evolve`.
+
+## Atomic Single-Responsibility
+
+Each skill does ONE thing. If a skill has two distinct responsibilities, extract one.
+
+**Test:** Can you describe what the skill does in one sentence without "and"? If not, it's compound.
+
+| Atomic | Compound (split it) |
+|--------|-------------------|
+| "Enforce TDD discipline" | "Enforce TDD discipline AND decide execution routing" |
+| "Review code quality" | "Review code quality AND manage PR creation" |
+| "Debug systematically" | "Debug systematically AND fix the bug" |
+
+## Do Not Duplicate Rules
+
+Rules in `rules/common/` are always loaded. Skills should not restate them.
+
+| If this exists in a rule... | The skill should... |
+|---|---|
+| Testing standards (`testing.md`) | Reference, not repeat. Keep only TDD-specific deltas. |
+| Verification protocol (`verification.md`) | Not re-explain "verify before writing code." |
+| Coding standards (`coding-standards.md`) | Not re-explain "minimal code" or "no over-engineering." |
+
+**Why:** Duplication drifts. When the rule is updated, the skill copy becomes stale and may contradict it.
+
+## Target Size
+
+| Size | Assessment |
+|------|-----------|
+| < 100 lines | Likely too thin — missing process constraints |
+| 100-250 lines | Ideal for most skills |
+| 250-400 lines | Acceptable for complex skills (architecture, task decompose) |
+| > 400 lines | Review for bloat — likely duplicates rules or has compound responsibility |
+
+## Avoid Internal Repetition
+
+State each rule once. Do not restate it in:
+- The overview AND the process AND the checklist AND the red flags AND the examples AND the final rule
+
+Choose the highest-signal location. One clear statement beats six diluted ones.
+
+## Separate Methodology from Orchestration
+
+Skills define HOW to do something (methodology). Orchestration decisions (which agent to dispatch, how to read manifest state, whether to fork or inline) should be minimal — a short section at most, not a parallel responsibility.
+
+**Methodology:** RED-GREEN-REFACTOR cycle, review criteria, debugging phases.
+
+**Orchestration:** Dispatch builder agent with task + artifacts only, read execution.mode from manifest, merge worktrees. Keep this to a routing table, not a protocol.
+
+## Where Workflow Goes: Command vs Skill (v6 convention)
+
+Forge places multi-phase workflows in **commands**, not skills. This is an intentional divergence from the Anthropic Skills convention (which puts multi-step workflows in skills with auto-load on context match).
+
+**v6 rule:**
+
+| Content type | Goes in |
+|---|---|
+| Phase orchestration across an SDLC pipeline (concept → wireframe → prototype → iterate → codify → production-build → deliver) | Command (`commands/feature.md`, `commands/greenfield.md`, etc.) |
+| Per-phase or per-operation methodology, with its own dispatch logic | Skill (`skills/harden/SKILL.md`, `skills/build-tdd/SKILL.md`, etc.) |
+| Specialized role definitions invoked with their own context window | Agent (`agents/*.md`) |
+| Ad-hoc / one-shot / mid-task corrections | Command (Claude Code's native pattern — `/btw`, `/simplify`, etc.) |
+| Auto-load on user intent description ("add a logger here") | Rule + state-aware routing (`rules/common/skill-selection.md`) |
+
+**When tempted to put a multi-step workflow in a skill:** ask whether it needs human-, script-, or CI-readable graph state. If yes (gate-enforcer reads the manifest, telemetry tracks invocations), keep it in a command. If no (pure prose orchestration; no external readers), a skill works.
+
+**Why this matters at authoring time:** an inadvertently-skill-shaped workflow with multi-phase orchestration creates a parallel state model alongside commands+manifests. Two sources of truth for "what phase are we in" is the failure mode to avoid.
+
+**v7 plan:** Revisit. Anthropic's hybrid pattern (`/feature` command becomes a thin invocation of `feature-workflow` skill) is the long-term direction. Until then, treat the command/skill boundary as documented above. See `AGENTS.md` "Architectural Layers" section.
+
+## Agent/Skill Boundary
+
+Agents and skills are different layers:
+- Skills are for human or inline sessions. They can decide when to dispatch an agent.
+- Agents do not load skills via frontmatter. The agent definition must contain its own execution methodology inline.
+- Dispatch prompts should pass task scope and required artifacts only, not a copy of the parent skill text.
+
+## Agent Dispatch Ownership
+
+Skills that dispatch agents should:
+- Name the agent and the condition for dispatch
+- Keep the dispatch handoff to task scope plus required artifacts
+- Not duplicate the agent's own protocol (the agent definition handles that)
+- Use a guard only when the skill itself should be skipped in a given context; do not rely on skill-preloading recursion guards
+
+## I/O Contract
+
+Use an I/O Contract when the skill's artifact handoffs, downstream consumers, or manifest updates need to be explicit in the workflow graph. Pure methodology skills can omit the table when it only duplicates surrounding orchestration.
+
+| Field | Required | Purpose |
+|---|---|---|
+| Requires | Usually | What artifacts must exist before this skill runs |
+| Produces | Usually | What artifacts this skill creates |
+| Feeds into | Usually | Which skills consume this skill's output |
+| Updates manifest | If applicable | Which manifest fields change |
+| Dispatches | If applicable | Which agents this skill dispatches |
+
+## Description Authoring
+
+The `description` field in frontmatter drives Claude Code's auto-triggering — it decides whether to load the full SKILL.md. Get this right.
+
+**Format:** Single "Use when..." sentence. No "and" joining two responsibilities. Command-agnostic — never reference `/feature`, `/hotfix`, or other command names.
+
+**Target:** 15-25 words, under 250 characters. Front-load keywords — truncated text still aids discovery.
+
+**What belongs here:** When to use it (triggering conditions) and what it does (one capability).
+
+**What belongs in the body:** Detailed triggering scenarios, skip conditions, command-specific scoping, and methodology. Use a `## When to Use` section in the SKILL.md body for this (see `support-skill-validator` for an example).
+
+**Why this split:** Claude Code uses semantic matching on descriptions to decide relevance. Long descriptions dilute signal — the matcher weighs every word. Detailed skip/scope logic is needed by the agent *after* the skill is loaded, not before.
+
+| Good | Bad (don't do this) |
+|------|---------------------|
+| `"Use when encountering any bug, test failure, or unexpected behavior — enforces systematic root cause investigation."` | `"TRIGGER when: any bug, test failure, error; user says 'it's broken', 'not working'. Enforces root cause investigation, fact-checking, and the 3-fix threshold. SKIP for: cosmetic tweaks, /hotfix emergency path."` |
+| `"Use when code has been written — orchestrates the review chain (safety → craft → reachability → gotcha-hunter → Codex adversarial) with risk-based escalation."` | `"Use after build-tdd completes, per-task during /feature build phase, or as final review before PR. Multi-pass chain. Scope varies: critical-pass only for /hotfix, per-task + final for /feature and /refactor."` |
+
+**Standalone vs chained skills:** Most skills are invoked by commands in sequence. Their descriptions must signal *which step they are*, not *what the user's goal is* — otherwise broad intent ("I want to build X") triggers multiple skills simultaneously instead of routing to a command.
+
+| Skill type | Description pattern | Example |
+|---|---|---|
+| **Standalone** (user may invoke directly) | "Use when {triggering condition}" | `"Use when encountering any bug, test failure, or unexpected behavior..."` |
+| **Chained** (always inside a command sequence) | "Use {phase signal} to {specific step}" | `"Use during the build phase to write or change production code..."` |
+
+Phase signals that prevent false triggers on broad intent: "Use after architecture is approved...", "Use as the first planning step...", "Use during the build phase...", "Use when an approach has been approved...". These imply a prior step completed, so they won't fire on "I want to build a task manager."
+
+**Cross-harness reference:**
+
+| Harness | Pattern | Lesson for forge |
+|---------|---------|-----------------|
+| SuperPowers (obra) | `"Use when..."` + symptoms, ~200 chars | Concrete triggers, no workflow details — forge's primary lineage |
+| Claude Code official | `"Use when..."` + keywords, ~250 chars | Semantic matching; front-load keywords, third person |
+| Everything Claude Code (AffaanMustafa) | Brief frontmatter + `## When to Activate` in body | Split concerns — forge adopts this with `## When to Use` |
+| gStack (garrytan) | 200-300 word descriptions with voice aliases | Over-specified; command-coupled; descriptions became stale — the anti-pattern |
+
+## Checklist for New Skills
+
+- [ ] One sentence description — "Use when..." format, no "and", under 250 chars, command-agnostic
+- [ ] No content duplicated from `rules/common/`
+- [ ] Under 400 lines
+- [ ] Each rule stated once, in one location
+- [ ] Orchestration is a short section, not a parallel responsibility
+- [ ] Agent dispatch passes task scope + artifacts only; agent owns its methodology inline
+- [ ] Add an I/O Contract only when it materially clarifies artifact handoffs or manifest updates
+- [ ] Run `/validate` after adding
+
+## Checklist for Modifying Skills
+
+- [ ] Cross-check with rules — did the rule already cover what you're adding?
+- [ ] Check line count before and after — did it grow significantly?
+- [ ] Review for internal repetition — did you add a point already made elsewhere in the file?
+- [ ] If adding agent dispatch — is the handoff limited to task scope + artifacts, with methodology kept in the agent?
+- [ ] Run `/validate` after modifying

package/references/common/skill-compliance.md

@@ -0,0 +1,30 @@
+# Skill Compliance
+
+Skills contain critical process constraints. Skipping them produces work that looks complete but misses quality gates.
+
+## REQUIRED SUB-SKILL Means Invoke the Skill Tool
+
+When a command says "REQUIRED SUB-SKILL: Use **X**", you MUST invoke the skill via the Skill tool. Do not substitute your own judgment for the skill's process.
+
+**Red flags that indicate you are about to skip a skill:**
+- "This is straightforward enough without the skill"
+- "I already know how to do this"
+- "The skill would just slow me down"
+- "I'll follow the spirit of the skill without loading it"
+
+If you catch yourself thinking any of these, STOP and load the skill. The skill exists because the process has constraints you will miss without it.
+
+## Dispatch the Agent Means Use the Agent Tool
+
+When a skill says "Dispatch the **X** subagent", you MUST call the Agent tool. Do not perform the review yourself — the subagent exists to provide independent evaluation.
+
+## Gate Verification
+
+Before marking any manifest gate as `gate-passed: true`:
+
+1. Confirm the required skill was invoked via the Skill tool in this session
+2. Confirm all agents specified by the skill were dispatched via the Agent tool
+3. Confirm the skill's `produces` artifacts exist at the expected paths
+4. If any are missing, go back and complete the requirement
+
+A gate-enforcer hook verifies skill and agent invocations against telemetry. If you attempt to pass a gate without the required invocations, the edit will be blocked.

package/references/python/standards.md

@@ -0,0 +1,44 @@
+# Python Standards
+
+Extends common coding standards with Python-specific rules.
+
+## Type Hints
+
+- Type hints on all function signatures (PEP 484), return types always specified
+- `from __future__ import annotations` for modern syntax
+- `TypeAlias` for complex definitions, `TypeVar` or PEP 695 for generics
+
+## Data Structures
+
+- `dataclasses` (prefer `frozen=True`) for simple data containers
+- Pydantic `BaseModel` for validated data (API boundaries, config, external input)
+- Named tuples or dataclasses over plain tuples/dicts
+
+## Environment and Dependencies
+
+- Virtual environments mandatory (`venv`, `poetry`, or `uv`)
+- Pin all versions in lock files; `pyproject.toml` as single config source
+- Separate dev from production dependencies
+
+## Formatting and Linting
+
+- **Ruff** for linting and formatting (line length: 88)
+- Import sorting: stdlib → third-party → local
+
+## File System and I/O
+
+- `pathlib.Path` over `os.path`
+- Context managers for all resource management
+- `async`/`await` for I/O-bound operations
+- Never bare `open()` without `with`
+
+## Documentation
+
+- Google style docstrings (Args / Returns / Raises) on all public functions, classes, modules
+
+## Error Handling
+
+- Custom exception classes for domain errors
+- Never bare `except:` — always specify the type
+- `raise ... from e` to preserve chains
+- Return typed results over raising for expected cases

package/references/react/standards.md

@@ -0,0 +1,61 @@
+# React Standards
+
+Extends `references/common/coding-standards.md` with React-specific conventions. Loaded at codify/harden phase — not active during prototype iteration.
+
+## Imports
+
+- Named imports only: `import { useState } from 'react'` — never `import React from 'react'`
+- Group: react → third-party → local components → local utils → types
+- Absolute imports via path aliases (`@/components/Button`) over deep relative paths
+
+## Minimize useEffect
+
+Most effects are unnecessary. See [React docs: You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect).
+
+| You want to... | Use this instead |
+|---|---|
+| Derive/transform data from props/state | Compute during render (`useMemo` or variable) |
+| Respond to a user event | Event handler (`onClick`, `onSubmit`) |
+| Fetch data | React Query / SWR / loader |
+| Reset state when props change | `key` prop (remount) |
+
+**When useEffect IS appropriate:** synchronizing with external systems (WebSocket, DOM APIs, third-party widgets), subscriptions, non-React integrations.
+
+**Rules when you must use it:** always specify deps array, one effect per concern, always clean up, never set derivable state, avoid effect chains.
+
+## Component Patterns
+
+- Functional components only — no class components
+- Composition over inheritance
+- Custom hooks (`use*`) for shared stateful logic
+- Single responsibility — split at 200 lines
+- Props interface for every component
+
+## State Management
+
+- Local state first (`useState`) → lift up only when siblings share → context for low-frequency global (theme, auth) → external store for complex state
+- Avoid prop drilling > 2 levels — use composition or context
+- Derive, don't sync — if B computes from A, compute it. Don't useEffect to sync.
+
+## Performance
+
+- `useMemo` for expensive computations, `useCallback` for callbacks to memoized children (only when needed)
+- `React.memo` for components that render often with same props — profile first
+- `React.lazy()` + `Suspense` for routes and heavy components
+- Avoid anonymous objects/arrays in JSX props — extract to stable references
+
+## Event Handling
+
+- Handle events in event handlers, not effects
+- Use `useActionState` or form actions (React 19+) for form submissions
+
+## Data Fetching
+
+- Use React Query, SWR, or framework loaders — never `useEffect` + `fetch` + `useState` in new code
+
+## Testing
+
+- Test behavior (what the user sees), not implementation (hook internals, state)
+- React Testing Library — query by role, label, text; not className or testId
+- "One behavior per test" = one user intent: a full form flow (fill → submit → verify) is ONE test
+- Prefer `msw` for network mocks; render real child components