@jamie-tam/forge 6.0.0

package/skills/build-tdd/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: build-tdd
+description: "Use when writing production code (post-harden, Phase 6) and the user asks to add a feature, fix a bug, or add tests for new behavior. Drives strict RED-GREEN-REFACTOR with integration coverage at module boundaries. Triggers on phrases like 'add test for', 'TDD this', 'write a failing test', 'implement <feature>'. Skip during prototype phases (Phase 4 iterate-prototype) where mock-heavy tests under-catch wiring bugs."
+---
+
+# Test-Driven Development (TDD)
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+**Announce at start:** "I'm using the build-tdd skill to implement this with strict TDD."
+
+## When to Use
+
+This skill is the Phase 6 (production-build) discipline. Phase 4 (prototype) is exempt — that work runs through `build-prototype` / `iterate-prototype` with manual click-through verification instead.
+
+**Within Phase 6:** New features, bug fixes, behavior changes.
+
+**Refactoring:** Always — but if existing tests already cover the code being refactored (passing coverage), use them as the safety net directly. Write characterization tests only for untested code paths. The Iron Law still applies to any *new behavior*. For pure refactoring (no behavior change), existing passing tests serve as the failing-test equivalent — if they break, the refactoring changed behavior.
+
+**Exceptions (ask your human partner):** Throwaway prototypes, generated code, configuration files.
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over. Do not keep it as "reference." Do not "adapt" it while writing tests.
+
+## The Cycle
+
+| Step | What | Mandatory verification |
+|---|---|---|
+| **RED** | Write one minimal failing test for the next behavior | Run the test — confirm it fails because the feature is missing (not syntax/import errors) |
+| **GREEN** | Write the simplest code that passes | Run the test — confirm new test passes AND existing tests still pass |
+| **REFACTOR** | Clean up after green; remove duplication, improve names | Keep tests green; do not add behavior |
+
+The detailed methodology — examples per step, common rationalizations, red flags, when-stuck guidance — is canonical in `agents/builder.md`. **When this skill runs inline, Read `agents/builder.md` before starting and follow its protocol exactly.** When this skill dispatches the **builder** subagent, the agent loads that methodology automatically.
+
+## Wiring Coverage
+
+After GREEN, if the slice crosses a module boundary defined in architecture artifacts, write one contract or integration test that exercises the real wiring (no mocks at the boundary). If you can't, that's a wiring-test debt; record in `support-gotcha`.
+
+Module boundaries from `harden`'s slice graph commonly include: CLI entry points, filesystem reads/writes, child-process invocations, manifest I/O, external service calls. Unit-level tests with mocks at these seams are necessary but not sufficient — the load-bearing question is whether the real components compose correctly. If every boundary in the slice has at least one no-mock test somewhere in the suite, the slice is wired; if any boundary is mock-only across the whole suite, file a `support-gotcha` entry naming the boundary and the missing test so the next pass can close it.
+
+## Execution Mode
+
+This skill dispatches the **builder** subagent or executes inline, based on persisted manifest state.
+
+Read `execution.mode` from `.forge/work/{type}/{name}/manifest.yaml` (set by `plan-task-decompose` during execution handoff):
+
+| Manifest state | Mode |
+|---|---|
+| `execution.mode: subagent` | Dispatch **builder** subagent with the task + architecture artifacts inline in prompt |
+| `execution.mode: inline` | Execute RED-GREEN-REFACTOR directly in current session — Read `agents/builder.md` first |
+| No manifest or no field | Inline (default) |
+
+When dispatching **builder**, pass the task and required artifacts ONLY. Do NOT include TDD methodology in the prompt; builder owns that methodology inline.
+
+Do not ask the user. The decision was persisted at task decompose handoff.
+
+## Architecture Constraints
+
+When architecture artifacts exist (from `plan-architecture` or `harden`), use them to set unit-test expectations for shapes, constraints, and error behavior. Treat those contracts as the source of truth for assertions at the unit boundary. Integration tests at boundaries identified by `harden`'s slice graph are required per the Wiring Coverage subsection above — they are not optional even when the task description omits them.
+
+## Codex Integration
+
+**Mode:** Delegate | **Protocol:** `protocols/codex.md`
+
+**When:** Before the task execution loop begins. User explicitly requests: "Use Codex as builder for this feature."
+
+**All-or-nothing:** If the user chooses Codex as builder, ALL tasks in the feature use Codex. No per-task or per-phase mixing. To switch back to Claude mid-feature, the user says "switch to Claude builder" — completed Codex tasks are kept, remaining tasks proceed with Claude.
+
+**Context to pass:**
+- Path to the specific task description from `tasks.md`
+- Path to `architecture/` directory (all artifacts)
+- Path to `codebase-analysis.md` (if existing project)
+- Path to `agents/builder.md` — Codex reads and follows the TDD methodology
+
+**Prompt focus:** "Implement the following task using strict TDD methodology as defined in agents/builder.md. Architecture artifacts are at [paths]. Write the failing test first, verify it fails, then implement minimally to pass."
+
+**Quality gate:** Every Codex-built task goes through:
+1. Tests pass (test runner from project profile)
+2. Coverage meets threshold (80%+, 100% for critical paths)
+3. `quality-code-review` by Claude (cross-review — Claude reviews Codex's work)

package/skills/build-wireframe/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: build-wireframe
+description: "Use when the user wants to build a wireframe, annotated mockup, click-through prototype demo, presales walkthrough, or any HTML artifact with callout/leader lines pointing into a UI design — even if they don't say 'wireframe'. Also use when extending an existing wireframe HTML (new screens, callouts, demo flows). Triggers on 'wireframe', 'annotated mockup', 'click-through', 'callouts', 'legend lines', 'leader lines', 'tabs to switch screens/states', 'presales artifact'. This skill encodes hard-won fixes (label clipping, sticky-tabbar overlap, demo state races) so don't re-derive from scratch."
+---
+
+# Build wireframe
+
+You are building a **single self-contained HTML file** that renders multiple annotated wireframe states accessible via tab navigation, plus optionally interactive click-through demos. Every wireframe state has callouts ("legend lines") in the side gutters explaining its key components.
+
+This artifact format is for **concept verification, annotated walkthroughs, and prototype design discussions** — visual fidelity, no real backend, no real interactivity beyond the click-through demos. The deliverable opens directly in any modern browser; no build step.
+
+## When to load each reference
+
+The full rule set and the iteration history are in references — load on demand:
+
+- **`references/legend-lines.md`** — the 7 visual rules for callouts, with the "why" behind each. Read this when adding callouts to a new state or when a leader is rendering wrong.
+- **`references/demo-walkthroughs.md`** — the per-step callouts pattern with `dynamicCallouts` state and cleanup-on-unmount. Read this when building or modifying a click-through demo.
+- **`references/gotchas.md`** — the iteration history. Read this when something doesn't render right despite following the rules — often it's a known race or layout trap.
+
+The baseline template at **`assets/baseline-template.html`** is your starting point. It contains all the boilerplate (React + Tailwind + Babel CDN, primitives, StateShell, Tabs, Callouts, App with hash routing, one example state). **Always start from this template** — don't write the boilerplate from scratch.
+
+## Architecture in one breath
+
+```
+single index.html
+├── React + Tailwind + Babel + Lucide via CDN (no build step)
+├── Inter font from Google Fonts
+├── Stage = 1920×1080 16:9 div, scaled to fit viewport via transform: scale()
+├── 320px symmetric gutters (where callout labels live)
+├── Tab strip at the top (NOT sticky — it would cover top callouts)
+├── State components, each rendered inside StateShell
+├── Each state has its own _CALLOUTS array (id + side + anchor + label)
+├── Callouts overlay reads view.callouts (or App.dynamicCallouts for demo views)
+└── Hash routing (#s1, #demo-inbound, etc.) so views are linkable
+```
+
+## Three view types
+
+| Type | Has callouts? | Has internal state? | Example |
+|---|---|---|---|
+| **Static state** | Yes — array on `view.callouts` | No | Home screen, Live ops dashboard |
+| **Interactive demo** | Yes — per-step array via `dynamicCallouts` | Yes — `useState` for current step | Inbound walkthrough |
+| **Flow diagram** | No — the layout itself is the explanation | No | Agent flow, Supervisor flow |
+
+## The 7 visual rules for callouts
+
+These rules are non-negotiable. Read `references/legend-lines.md` for examples and the math behind each one.
+
+1. **Anchor on the section's edge facing its label.** Right-side label → dot on the element's right edge. Left-side label → left edge. Don't put the dot in the centre or the far edge.
+2. **Leader is mostly a single straight run.** One horizontal or vertical segment from anchor to label. No diagonals through the wireframe.
+3. **Bend only in the gutter, never over UI.** When the label sits at a different y from the anchor, the leader bends 16px inside the gutter — not over the wireframe stage.
+4. **Comprehensive over minimal.** Aim for 5–8 callouts per main-shell state, covering each chrome column AND each section of the main-content area. Drop a callout only if the leader genuinely cannot avoid crossing other UI.
+5. **Collision-avoidance push direction is fixed.** Top/bottom labels push right (later labels move x+). Left/right labels push down (later labels move y+).
+6. **Overlay states annotate the overlay, not the underlying shell.** Modal / sheet / banner states draw callouts targeting overlay anchors. The dimmed shell underneath is context, not content.
+7. **Closest path wins — for both `side` and `anchor`.** Pick the side whose gutter is NEAREST the anchor element. Then anchor on the element's edge facing that gutter. A banner at the top of the wireframe gets `side: "top"`, NEVER `"bottom"`. A toast in the top-right corner gets `side: "top"` (or `"right"`). For row-spanning components (a row of cards, a footer strip, a multi-column row), the dot lands on the outer ROW's edge — humans read that as "this row of components", not "this single column".
+
+## Stage geometry (memorize these numbers)
+
+| Knob | Value | Why |
+|---|---|---|
+| Stage design size | 1920 × 1080 | 16:9, kiosk-shaped, wide enough for 3-column shells |
+| Outer max-width | 2400px | Lets stage hit 1:1 on wide monitors |
+| Stage maxWidth | 1920px | Caps scale at 1.0 |
+| Gutter | 320 px each side | Label width 230 + offset 60 + slack 30 |
+| Top/bottom callout offset | 60 px | Breathing room above/below stage |
+| Tab-bar clearance | mt-32 (128 px) | Top callouts must clear tab bar — see gotchas |
+| Label width | 230 px | Fits ~2 lines of body copy |
+| Label height (estimated) | ~32 px | Two-line labels grow upward from `bottom: …` |
+
+Don't change these without good reason. The numbers are interlocked: `gutter ≥ label_width + offset` is a hard constraint, and the tab-bar clearance is what separates "labels are visible" from "labels are clipped above viewport".
+
+## Workflow
+
+### Adding a static state
+
+1. Build the state component as a JSX function returning `<StateShell>...</StateShell>`. Reuse `Topbar`, `Sidebar`, `LeftCaseList`, `RightRail` shared components where they apply.
+2. For each element you want to annotate, give it `id="a-something"` (descriptive prefix, kebab-case). For elements that should be highlighted with a 0-size dot, use a `<span id="a-..." className="absolute ..." data-callout-anchor="" />` inside the parent. The span's position determines where the dot lands.
+3. Define `<NewState>_CALLOUTS = [{id, side, anchor, label}, ...]` next to the state. Apply rules 1–7. Aim for 5–8 entries on a main-shell state.
+4. Register in `VIEWS`: `"key": {label: "User-facing tab label", group: "agent" | "sup" | "demo", render: NewState, callouts: NewState_CALLOUTS}`.
+5. Add the key to the right group's tab list.
+6. **Verify in the browser.** Use Playwright (or any browser) to measure: no clipping (label fits in viewport), no overlap with the tab bar, leader lines hit visible elements. See `references/gotchas.md` for the exact measurement queries.
+
+### Adding an interactive demo
+
+Read `references/demo-walkthroughs.md` first. Key pattern: the demo holds a `step` state, defines a `D{N}_STEP_CALLOUTS` array indexed by step, pushes the active step's slice via `useEffect` keyed on `[step, setCallouts]` with a **cleanup that nulls** `setCallouts(null)` on unmount. The cleanup is critical — without it you get stale callouts on tab switches.
+
+### Fixing wrong callout placement
+
+Symptom → first thing to check:
+- **Label clipped at viewport edge** → gutter too narrow OR the outer container has `overflow: hidden` clipping the label box. Bump gutter to ≥ label_width + offset + 30.
+- **Top label hidden behind tab bar** → tab bar is `sticky` (don't do that) OR top padding above stage is < tab_bar_height + ~50. Add `mt-32` to the stage wrapper.
+- **Leader cuts across UI** → wrong `side` (you picked the far gutter) or wrong `anchor` (dot landed inside the element instead of on its edge). Apply rule 7.
+- **Dot at zero-length leader** (label flush against wireframe edge) → element is at the wireframe edge AND `anchor` is on the same edge. Flip `anchor` to the opposite edge so the leader has visible travel, OR move the anchor to the outer row wrapper.
+- **Leader points at the wrong row** when a section spans multiple columns → anchor span is inside ONE cell instead of the outer row. Add `relative` to the outer row wrapper and host the span there.
+
+## When NOT to add a callout
+
+- Pure flow views (the layout itself is the explanation).
+- A second callout pointing at the same `id` as another callout in the same view (one is enough — duplicate IDs produce two leaders into the same dot).
+- An element whose function is obvious from its on-screen label (a search box that says "Search…" doesn't need annotation).
+
+## Output format
+
+The deliverable is `index.html` in a directory you can recommend (e.g. `pocs/wireframe/index.html`). Open with `open index.html` or via a local HTTP server (`npx http-server -p 8767 -c-1`) — http-server is required if your demo or asset paths use `file://`-incompatible features.
+
+Always alongside the HTML: write a short `README.md` that lists the views, hash routes, and which deck slides / spec docs each view derives from. This is the index a future contributor reads first.
+
+## When the user says "iterate" or shows a screenshot of broken callouts
+
+Don't redesign. The 7 rules + the gotchas catalog cover ~95% of issues. Read `references/gotchas.md`, identify the failure mode, apply the fix. If the user is on the first iteration of a new project, start from `assets/baseline-template.html` — copy it to their target path and extend.