haiku-method 2.2.0

package/studios/software/stages/design/discovery/DESIGN-SYSTEM-ANCHOR.md

@@ -0,0 +1,84 @@
+---
+name: design-system-anchor
+location: .haiku/intents/{intent-slug}/knowledge/DESIGN-SYSTEM-ANCHOR.md
+scope: intent
+format: text
+required: true
+purpose: Concrete design-system specs extracted from real source — button heights, radii, color tokens, spacing scale — cited to file:line.
+---
+
+# Design System Anchor
+
+Concrete design-system specs extracted from the project's source code. Every value is cited to its source file and line number. Downstream hats (designer, design-reviewer) must use these values — not guesses.
+
+## Content Guide
+
+### 1. Atoms
+
+For each reusable atomic component found in source (e.g. Button, Surface, Card, Input, Badge):
+
+- **Component name** and its source file path
+- **Dimensions** — height, min-height, min-width, padding (cited to file:line)
+- **Border radius** (cited to file:line)
+- **States** — list any conditional styles for the canonical 8-state set: `default, hover, focus, active, disabled, error, loading, empty` (cited to file:line). Match `DESIGN-BRIEF.md`'s state vocabulary so downstream consistency review can compare like-for-like.
+- **Variants** — any size/color/shape variants the component declares (cited to file:line)
+
+Example entry:
+```
+### Button
+Source: atorasu/atoms/Button.tsx
+
+- height: 44px             # Button.tsx:23
+- border-radius: 8px        # Button.tsx:31
+- padding-h: 16px           # Button.tsx:28
+- default: solid bg, brand-primary text  # Button.tsx:18
+- disabled-opacity: 0.4     # Button.tsx:47
+- empty: ghost variant w/ placeholder copy  # Button.tsx:55
+```
+
+### 2. Tokens
+
+Color, spacing, typography, and radius scales pulled from the project's tokens module (e.g. `atorasu/style/theme/colors.ts`, `style/spacing.ts`):
+
+Every recorded color value MUST carry both its raw source value AND its named-token alias as defined in `knowledge/DESIGN-TOKENS.md`. The designer hat is forbidden from using raw hex; if a color exists in source but has no named alias yet, route the gap to `## Open Questions` rather than emitting a raw hex into the anchor — never let unaliased values flow into the design context.
+
+- **Color tokens** — name (token alias), raw value, source citation (file:line)
+- **Spacing scale** — each step's named alias and step value (cited to file:line)
+- **Typography scale** — font family, sizes, weights, line heights (cited to file:line)
+- **Radius scale** — each named radius alias and value (cited to file:line)
+- **Shadow/elevation** — any named shadow tokens (cited to file:line)
+
+Example entry:
+```
+### Color Tokens
+Source: atorasu/style/theme/colors.ts → mapped to knowledge/DESIGN-TOKENS.md
+
+- color.brand.primary    = #1A73E8    # colors.ts:12 → DESIGN-TOKENS.md:8
+- color.surface.bg       = #FFFFFF    # colors.ts:18 → DESIGN-TOKENS.md:14
+- color.text.primary     = #212121    # colors.ts:24 → DESIGN-TOKENS.md:20
+- (gap) #F5A623 used in Button.tsx:62 has no named alias → see Open Questions
+```
+
+### 3. Active vs Dormant Patterns
+
+Cross-reference era/status tags from the inception stage's `DISCOVERY.md` `## Existing Code Structure` section. For each prior-art file listed there:
+
+- **Active** — pattern is used in the current codebase, values are current
+- **Dormant** — era-tagged as legacy (e.g. Stripe-era, Branch-era) — flag these explicitly so the designer avoids them
+
+### 4. Open Questions
+
+Anything ambiguous from source that requires designer judgment before proceeding:
+
+- Token values that appear overridden in multiple places (list each location and value)
+- Components with undocumented variants
+- Source files listed in DISCOVERY.md that could not be located
+- Any token that has no source citation (must not be used until resolved)
+
+## Quality Signals
+
+- Every atom spec entry cites source file and line number
+- Every token entry cites source file and line number
+- No invented or approximated values — open questions section covers gaps
+- Active vs dormant flags are present for all prior-art files with era tags
+- The designer hat can read this document and produce mockups without touching source files

package/studios/software/stages/design/discovery/DESIGN-TOKENS.md

@@ -0,0 +1,31 @@
+---
+name: design-tokens
+location: .haiku/intents/{intent-slug}/knowledge/DESIGN-TOKENS.md
+scope: intent
+format: text
+required: true
+---
+
+# Design Tokens
+
+Named design values that downstream stages must use instead of raw values. All colors, spacing, typography, and other visual properties should be referenced by token name throughout the project.
+
+## Content Guide
+
+Define tokens for:
+
+- **Color tokens** — primary, secondary, surface, error, warning, success, and semantic aliases
+- **Spacing scale** — consistent spacing values (e.g., 4px, 8px, 12px, 16px, 24px, 32px, 48px)
+- **Typography scale** — font families, sizes, weights, line heights for each usage context (heading, body, caption, etc.)
+- **Border radii** — small, medium, large, pill, circle
+- **Shadow definitions** — elevation levels with shadow values
+- **Animation/transition values** — duration and easing for standard transitions
+
+If the project has an existing design system, tokens should reference or extend it. If no design system exists, this document establishes one.
+
+## Quality Signals
+
+- All downstream stages use token names, never raw values
+- Token names are semantic (e.g., `color-error` not `color-red-500`)
+- The scale is consistent and complete — no gaps that force raw values
+- Tokens are documented with their intended usage context

package/studios/software/stages/design/hats/design-reviewer.md

@@ -0,0 +1,11 @@
+---
+interpretation: lens
+---
+**Focus:** The agent **MUST** check consistency with the design system, verify all interaction states are covered, confirm responsive behavior at all breakpoints, and validate accessibility requirements.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** approve designs without checking state coverage
+- The agent **MUST NOT** ignore accessibility requirements
+- The agent **MUST** verify responsive behavior at all breakpoints
+- The agent **MUST NOT** accept raw hex values — named tokens are **REQUIRED**
+- The agent **MUST** cross-reference component usage against the existing design system

package/studios/software/stages/design/hats/designer-prep.md

@@ -0,0 +1,21 @@
+**Focus:** Ground the design stage in real source. Read the project's design system — atoms, quarks, and token files (e.g. `atorasu/style/theme/colors.ts`, `atorasu/atoms/Button.tsx`, `atorasu/atoms/Surface.tsx`, `atorasu/quarks/Spacer.tsx`) — and produce a `DESIGN-SYSTEM-ANCHOR.md` discovery artifact with concrete specs: real button heights, real radii, real spacing scale, real color tokens. Every value must be cited to its source file and line number. The baton to the designer hat is a fully-populated anchor document, not a summary.
+
+**During elaborate (pre-execution reading):**
+- Read inception's `DISCOVERY.md` at `knowledge/DISCOVERY.md` (intent-root relative — this is the canonical `scope: intent` location set by the inception discovery template) and read its `## Existing Code Structure` section — this lists the prior-art files the inception agent enumerated, including any era/status tags
+- Edge case: if `knowledge/DISCOVERY.md` does not exist, OR exists but has no `## Existing Code Structure` section, record an open question naming the missing input and proceed using only files the user explicitly references — do not invent prior-art paths
+- Read each source file listed there that relates to the design system (tokens, atoms, quarks, surfaces, spacing utilities)
+- If `DESIGN-SYSTEM-ANCHOR.md` is already present from the elaborate-phase discovery fan-out (at `knowledge/DESIGN-SYSTEM-ANCHOR.md`), read it as a starting scaffold — you will fill in or correct any placeholder values before writing the final artifact
+
+**During execute (your phase):**
+- For each atom/quark/token file identified in elaborate: open the file, read it, extract exact values — do not paraphrase or approximate
+- Produce the anchor artifact at `knowledge/DESIGN-SYSTEM-ANCHOR.md` following the schema declared by the elaborate-phase fan-out (the `DESIGN-SYSTEM-ANCHOR.md` discovery scaffold delivered into the intent's knowledge dir)
+- Every spec entry MUST cite source `file:line` — e.g. `height: 44px  # atorasu/atoms/Button.tsx:23`
+- Flag any era-tagged patterns from DISCOVERY.md's prior-art section as dormant vs. active
+- Record open questions where source is ambiguous or a value appears overridden in multiple places
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** produce mockups or wireframes — that is the designer hat's job
+- The agent **MUST NOT** summarize or approximate token values — record the concrete value from source
+- The agent **MUST** cite the source file and line number for every token and spec recorded
+- The agent **MUST NOT** invent values when source files are absent — record as an open question instead
+- The agent **MUST NOT** skip the DISCOVERY.md prior-art section — it is the enumeration of files to read

package/studios/software/stages/design/hats/designer.md

@@ -0,0 +1,32 @@
+**Focus:** Produce high-fidelity design artifacts from approved wireframes. The elaboration phase already created wireframes and got user alignment — your job is to turn those into production-ready mockups.
+
+**During execute (your phase):**
+- **Read `knowledge/DESIGN-SYSTEM-ANCHOR.md` first** — the designer-prep hat extracted real specs from source. Use those values, not guesses.
+- Read design tokens from `knowledge/DESIGN-TOKENS.md` — use ONLY named tokens for colors, spacing, typography
+- Read the design brief from `stages/design/DESIGN-BRIEF.md` for screen specs and interaction patterns
+- Take the approved wireframes from `stages/design/artifacts/` and produce high-fidelity mockups
+- Apply real design tokens from the tokens document — no raw hex values, no magic numbers
+- Specify all interactive states: default, hover, focus, active, disabled, error, loading, empty
+- Define responsive behavior at each breakpoint (mobile 375px, tablet 768px, desktop 1280px)
+- Check for existing design system: look for Storybook MCP (`mcp__storybook__*` tools) and reference existing components before creating new ones
+- Use design provider MCP if available (Pencil/OpenPencil, Figma) for rich .pen/.fig files
+- Otherwise generate detailed HTML mockups with inline CSS that look like the real product
+- Save final artifacts to `stages/design/artifacts/`
+
+Record all produced wireframes and design artifacts in the unit's `outputs:` frontmatter field as paths relative to the intent directory.
+
+**Design provider workflow:**
+- If Pencil MCP is available (`mcp__pencil__*` tools): create designs in .pen format, then call `mcp__pencil__export_nodes` to export PNG/SVG previews to `stages/design/artifacts/`
+- If OpenPencil MCP is available (`mcp__openpencil__*` tools): same pattern
+- If no design MCP: generate detailed HTML mockups with inline CSS
+- ALWAYS export reviewable previews (PNG/SVG) — the review UI cannot render .pen/.fig files directly
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** aSCII art or text-only descriptions — ALWAYS produce visual artifacts
+- The agent **MUST NOT** low-fidelity wireframes — that was elaboration's job, you produce the real thing
+- The agent **MUST NOT** design without referencing the approved wireframes
+- The agent **MUST NOT** use raw hex colors instead of named tokens
+- The agent **MUST NOT** skip state coverage
+- The agent **MUST NOT** ignore responsive behavior
+- The agent **MUST NOT** touch targets smaller than 44px
+- The agent **MUST** specify accessibility requirements

package/studios/software/stages/design/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you are a verifier, not a fixer
+- The agent **MUST NOT** close a finding that isn't actually resolved — that is how drift hides
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
+- The agent **MUST NOT** expand the scope beyond the one feedback item you were dispatched against

package/studios/software/stages/design/outputs/DESIGN-ARTIFACTS.md

@@ -0,0 +1,28 @@
+---
+name: design-artifacts
+location: .haiku/intents/{intent-slug}/stages/design/artifacts/
+scope: intent
+format: design
+required: true
+---
+
+# Design Artifacts
+
+High-fidelity design deliverables for the intent's user-facing surfaces. These are the actual visual designs — mockups, wireframes, component specs — stored inside the intent as part of its specification.
+
+Design artifacts live in the intent's stage directory because they ARE the spec. Downstream stages (product, development) reference them as inputs to understand what gets built.
+
+## Content Guide
+
+- Screen mockups at all specified breakpoints (e.g., login-screen-desktop.png, login-screen-mobile.png)
+- Component library additions or modifications
+- Icon/asset exports needed for development
+- Interactive prototypes or flow diagrams
+- Design tool source files (.pen, .fig, .sketch) when applicable
+
+## Quality Signals
+
+- Every screen specified in the design brief has a corresponding mockup
+- Mockups match the design tokens (colors, spacing, typography)
+- Interactive states are visually represented, not just documented
+- Assets are in formats usable by development (PNG, SVG, or design tool native)

package/studios/software/stages/design/package.json

@@ -0,0 +1,3 @@
+{
+	"private": true
+}

package/studios/software/stages/design/phases/ELABORATION.md

@@ -0,0 +1,53 @@
+---
+skip: []
+add: []
+wireframe_fidelity: high
+criteria_focus: design
+---
+
+# Design Stage — Elaboration
+
+## Phase Instructions (RFC 2119)
+
+The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "REQUIRED" in this section are to be interpreted as described in RFC 2119.
+
+During elaboration, the agent **MUST** create **multiple low-fidelity wireframe variants** and present them for the user to choose a direction:
+
+1. The agent **MUST** generate 2-3 distinct design approaches as HTML wireframe snippets (different layouts, interaction patterns, or visual hierarchies)
+2. The agent **MUST** call `pick_design_direction` with the variants as `archetypes` — each with a `name`, `description`, and `preview_html` (the rendered wireframe).
+3. The user either picks one as the final direction (optionally annotating it via the pencil tool — strokes are screen-captured and returned to the agent as image content blocks) **or** asks the agent to regenerate variants — keeping a subset of the current archetypes and steering the next batch via comments. On a regenerate response, the agent **MUST** produce replacements for the unkept slots and call `pick_design_direction` again with the merged set.
+4. The agent **MUST** use the final selected direction to create the wireframes saved to `stages/design/artifacts/`
+5. The agent **MUST NOT** produce ASCII art wireframes — all wireframes **MUST** be HTML or design provider files
+6. If a design provider MCP is available (Pencil, OpenPencil, Figma), the agent **SHOULD** use it instead of raw HTML
+
+## Criteria Guidance
+
+Design criteria are verified by **visual approval** — a reviewer inspects the deliverable against the criterion, not by command-exit-code. The condition can be a structural check (counting screen variants, asserting tokens-only colors via grep) or a reviewer-applied condition stated precisely enough that two reviewers would reach the same verdict.
+
+### Good criteria — concrete and verifiable
+
+When generating criteria for this stage, focus on verifiable design deliverables:
+
+- Screen layouts defined for all breakpoints (mobile 375px / tablet 768px / desktop 1280px)
+- All interactive states specified (default, hover, focus, active, disabled, error)
+- Color usage references only design system tokens — no raw hex values (verifiable by grep for `#[0-9a-fA-F]{3,6}` outside token files)
+- Touch targets meet 44px minimum on mobile breakpoints
+- Empty states, loading states, and error states designed
+- Contrast ratios meet WCAG AA (4.5:1 body text, 3:1 large text) — verifiable by automated contrast checker
+- Focus order documented for keyboard navigation
+- Component hierarchy documented (which design system components to use/extend)
+- Interaction specs complete for all user actions (tap, swipe, scroll, transition)
+
+### Bad criteria — vague (no clear condition)
+
+- "Design looks good" — what does good mean?
+- "It's responsive" — at which breakpoints? With what behavior?
+- "Accessible" — to which standard? WCAG A, AA, AAA?
+
+### Bad criteria — design-specific unverifiable
+
+(In addition to the universal unverifiable shapes called out in the workflow engine contracts.)
+
+- "Design is intuitive" — needs a usability test pass against a stated success-rate threshold
+- "Visual hierarchy is clear" — needs a structural rule (e.g. heading scale, contrast progression) the reviewer can apply consistently
+- "Brand feels right" — needs a brand-guideline document to compare against, not a subjective vibe check

package/studios/software/stages/design/phases/EXECUTION.md

@@ -0,0 +1,22 @@
+# Design Stage — Execution
+
+## Phase Instructions (RFC 2119)
+
+The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "REQUIRED" in this section are to be interpreted as described in RFC 2119.
+
+During execute, the designer hat **MUST** produce **high-fidelity mockups** from the approved wireframes. The agent **MUST** apply real design tokens, specify all interactive states, and define responsive behavior at each breakpoint. The output **MUST** be production-ready design — polished, not sketched.
+
+## Builder Focus
+
+- Explore wireframes, mockups, or prototypes to clarify the visual and interaction direction
+- Define or extend design tokens (colors, spacing, typography, elevation) as shared vocabulary
+- Specify component structure, states, and interaction behavior
+- Document responsive breakpoints and adaptive layout rules
+- Capture micro-interactions and transition specifications
+
+## Reviewer Focus
+
+- Verify design thinking addresses every acceptance criterion in the unit
+- Check consistency with existing design system tokens and patterns
+- Confirm interaction flows cover error states, empty states, and loading states
+- Ensure accessibility considerations are documented (contrast, focus order, ARIA semantics)

package/studios/software/stages/design/review-agents/accessibility.md

@@ -0,0 +1,27 @@
+---
+applies_to:
+  - "*.html"
+  - "*.htm"
+  - "*.tsx"
+  - "*.jsx"
+  - "*.vue"
+  - "*.svelte"
+interpretation: lens
+---
+<!--
+  `applies_to:` gates this review agent by output kind. The web a11y checks
+  below (contrast, touch targets, focus indicators, SR flow) presume DOM /
+  HTML artifacts. On a stage whose artifacts are all backend specs, CLI
+  docs, or non-UI markdown, this agent skips itself rather than raising
+  not-applicable findings. Absence of `applies_to:` means "always runs"
+  (backward-compatible default).
+-->
+
+**Mandate:** The agent **MUST** verify the design meets accessibility requirements and does not exclude users.
+
+**Check:**
+- The agent **MUST** verify that color contrast ratios meet WCAG AA minimum (4.5:1 for text, 3:1 for large text and UI components)
+- The agent **MUST** verify that touch targets are at least 44px on mobile
+- The agent **MUST** verify that all interactive elements are reachable via keyboard and have visible focus indicators
+- The agent **MUST** verify that information is not conveyed by color alone
+- The agent **MUST** verify that screen reader flow is logical and all images/icons have appropriate labels

package/studios/software/stages/design/review-agents/consistency.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the design is internally consistent and aligns with the project's existing design system.
+
+**Check:**
+- The agent **MUST** verify that all spacing, typography, and color values reference named tokens — no raw hex, px, or magic numbers
+- The agent **MUST** verify that interactive elements have consistent state coverage (default, hover, focus, active, disabled, error)
+- The agent **MUST** verify that component naming follows the existing pattern language
+- The agent **MUST** verify that layout grid and breakpoint behavior is consistent across all screens

package/studios/software/stages/design/review-agents/inception-coverage.md

@@ -0,0 +1,95 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** audit design-stage artifacts against inception artifacts to ensure decisions are honored, UI surfaces are covered, and resolved questions are not re-opened.
+
+## Step 1 — Discover inception artifacts
+
+The agent **MUST** dynamically enumerate inception artifacts — do **NOT** hardcode file paths. Perform the following enumeration at the start of every run:
+
+1. Collect all files under `.haiku/intents/{slug}/knowledge/` (recursively).
+2. Collect all files under `.haiku/intents/{slug}/stages/inception/` (recursively), if the directory exists.
+
+**Short-circuit on missing inception:** If neither location yields any files, emit a single info-severity note:
+
+> "Inception not run for this intent — coverage audit skipped."
+
+Then return cleanly with **no blocking findings**. This makes the agent safe to use in single-stage / quick-mode intents where inception was not run.
+
+## Step 2 — Classify inception artifacts by content
+
+Read each file in full. **MUST NOT** infer content from filenames — classify by heading scan and section text:
+
+- **Decisions** — any heading or section text containing `decision`, `decided`, `resolved`, or `## Decisions`.
+- **Open questions** — any heading or section text containing `open question`, `unresolved question`, or `## Open Questions`.
+- **UI surfaces** — any heading or section text containing `ui surface`, `affected surface`, `ui impact`, or `## UI Impact`.
+- **Constraints / risks** — any explicit constraint or risk statement.
+
+When `DISCOVERY.md` is the only inception artifact, all four roles will be subsections within it. Extract each role by section — do **NOT** treat the whole file as a single block.
+
+**Short-circuit on unclassifiable inception:** If inception files exist but Step 2's heading scan finds zero hits across all four roles (decisions, open questions, UI surfaces, constraints/risks), emit a single warning-severity note:
+
+> "Inception artifacts present but use non-standard headings — coverage audit cannot classify content. Reviewer recommends running classification heuristics by hand or aligning inception to the canonical DISCOVERY.md template."
+
+Then return cleanly with **no blocker findings** (the warning above is the sole emission). This prevents a flood of false-positive scope-creep findings on intents whose inception used custom heading vocabulary.
+
+## Step 3 — Read design-stage outputs
+
+The agent **MUST** dynamically enumerate the following design output locations and read each that exists:
+
+- Every file under `.haiku/intents/{slug}/stages/design/artifacts/`
+- `.haiku/intents/{slug}/stages/design/DESIGN-BRIEF.md`
+- `.haiku/intents/{slug}/knowledge/DESIGN-TOKENS.md`
+- `.haiku/intents/{slug}/knowledge/DESIGN-SYSTEM-ANCHOR.md`
+
+**Short-circuit on no design output:** If none of the above paths exist, emit a single info-severity note:
+
+> "Design stage has produced no readable artifacts yet — coverage audit skipped."
+
+Then return cleanly with no blocker findings. This is the safe state for an intent that has not yet executed the design stage.
+
+**MUST NOT** summarize inception artifacts — read them in full on each audit pass.
+
+## Step 4 — Emit findings
+
+When inception artifacts ARE present, emit a `haiku_feedback` finding for each of the following failure modes:
+
+### Decision violation — severity: **blocker**
+The design contradicts a decision extracted from inception.
+
+Every finding body **MUST** include:
+- Inception artifact path + line range (or `(decision: <text>)` for inline-extracted decisions)
+- Design artifact path + line range (or screen ID) where the violation occurs
+- One-line recommendation: revisit inception decision, revise design, or escalate to human review
+
+### Surface gap — severity: **blocker**
+A UI surface listed in inception is not represented in the design artifacts.
+
+Every finding body **MUST** include:
+- Inception artifact path + the passage that names the surface
+- What design artifacts were checked and which surface is absent
+- One-line recommendation: add the missing surface or confirm it is intentionally deferred
+
+### Resolved-question regression — severity: **blocker**
+The design re-introduces a question that was already settled in inception.
+
+Every finding body **MUST** include:
+- Inception artifact path + the passage where the question was resolved
+- Design artifact path + the passage that re-opens it
+- One-line recommendation: align design with the settled answer or escalate for explicit re-decision
+
+### Scope creep — severity: **warning**
+The design covers a surface or feature that inception did NOT list. May be legitimate but requires human triage.
+
+Every finding body **MUST** include:
+- The specific inception artifact passage that omits the surface (do **NOT** flag scope creep without naming this passage)
+- Design artifact path + the passage that introduces the unlisted surface
+- One-line recommendation: confirm alignment with inception scope or create a follow-on intent
+
+## Anti-patterns (RFC 2119)
+
+- `MUST NOT` hardcode **inception** artifact filenames — Step 1 discovers them dynamically because inception's filenames are agent-authored and vary per intent. (Design-side artifact paths in Step 3 are stable by contract — those listed paths are the canonical locations declared by their discovery templates and may be referenced directly.)
+- `MUST NOT` summarize inception artifacts — read them in full per audit pass
+- `MUST NOT` infer coverage from titles or filenames — diff actual content
+- `MUST NOT` flag scope-creep without naming the specific inception artifact passage that omits the surface
+- `MUST` short-circuit cleanly when inception is absent

package/studios/software/stages/development/STAGE.md

@@ -0,0 +1,32 @@
+---
+name: development
+description: Implement the specification through code
+hats: [planner, builder, reviewer]
+fix_hats: [builder, feedback-assessor]
+review: [external, ask]
+elaboration: collaborative
+inputs:
+  - stage: inception
+    discovery: discovery
+  - stage: design
+    discovery: design-brief
+  - stage: design
+    discovery: design-tokens
+  - stage: design
+    output: design-artifacts
+  - stage: product
+    discovery: acceptance-criteria
+  - stage: product
+    discovery: behavioral-spec
+  - stage: product
+    discovery: data-contracts
+review-agents-include:
+  - stage: design
+    agents: [consistency, accessibility]
+  - stage: product
+    agents: [completeness]
+---
+
+# Development
+
+Implement the specification through code.

package/studios/software/stages/development/discovery/ARCHITECTURE.md

@@ -0,0 +1,35 @@
+---
+name: architecture
+location: .haiku/knowledge/ARCHITECTURE.md
+scope: project
+format: text
+required: false
+---
+
+# Architecture
+
+Living document recording significant architectural decisions made during development. This persists across intents — write for future readers who need to understand why the system is shaped the way it is.
+
+## Content Guide
+
+Update this document when development introduces new patterns or changes existing ones:
+
+- **Module map** — what each module/package does, its boundaries, and what it depends on
+- **Data flow** — how data moves through the system (text diagrams are fine)
+- **Key abstractions** — the core interfaces, types, and patterns that shape the codebase
+- **Dependency graph** — external dependencies and why they were chosen
+- **Architectural decisions** — non-obvious choices with rationale (why X over Y)
+
+## When to Update
+
+- New module or package boundary introduced
+- Data flow pattern changed
+- New external dependency added
+- Significant refactor that changes system structure
+
+## Quality Signals
+
+- A new developer can understand the system's shape from this document
+- Rationale explains "why" not just "what"
+- Diagrams use text format (mermaid, ASCII) so they live in version control
+- Outdated sections are updated or removed, not left to accumulate

package/studios/software/stages/development/hats/builder.md

@@ -0,0 +1,21 @@
+---
+run_quality_gates: true
+---
+**Focus:** Implement code to satisfy completion criteria using **test-driven development** in small verifiable increments. Each acceptance criterion follows RED → GREEN → REFACTOR: write the failing test that encodes the criterion, watch it fail for the *right* reason (assertion failure, not setup error), write the minimum code to make it pass, then refactor while keeping tests green. Quality gates (tests, lint, typecheck) provide continuous feedback — treat failures as guidance, not obstacles.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** build without reading the completion criteria first
+- The agent **MUST NOT** write implementation before its failing test exists — tests-first answers "what should this do?"; tests-after only answers "what does this do?" and inherits the implementation's blind spots
+- The agent **MUST NOT** delete or weaken a test that catches a real bug — fix the production code, do not skip the test
+- The agent **MUST NOT** disable lint, type checks, or test suites to make code pass
+- The agent **MUST NOT** continue past 3 failed attempts without documenting a blocker
+- The agent **MUST** commit working increments — large uncommitted changes get lost on context reset
+- The agent **MUST NOT** attempt to remove or weaken quality gates
+
+**TDD red flags (STOP if you catch yourself thinking):**
+- "I'll write the test after, it's the same thing" — tests-after inherits the implementation's biases and misses edge cases the test would have surfaced
+- "This test passed on the first run" — the test is wrong; it's testing existing behavior, not new behavior. Rewrite to fail first.
+- "I'll adjust the test to match the code" — inverts the discipline. The criterion defines correct; the test enforces the criterion; the code makes the test pass.
+- "TDD is overkill for this small change" — small slips are exactly what TDD catches. Bypassing it for "small" changes is how regressions ship.
+
+When stuck, the agent **MUST** apply the node repair operator in order: retry (transient failure, max 2 attempts) then decompose (break into smaller subtasks) then prune (try alternative approach) then escalate (document blocker for human intervention). The agent **MUST NOT** skip levels.

package/studios/software/stages/development/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you are a verifier, not a fixer
+- The agent **MUST NOT** close a finding that isn't actually resolved — that is how drift hides
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
+- The agent **MUST NOT** expand the scope beyond the one feedback item you were dispatched against

package/studios/software/stages/development/hats/planner.md

@@ -0,0 +1,10 @@
+**Focus:** Read the unit spec and prior stage outputs, plan the implementation approach, identify files to modify, assess risks, and search for relevant learnings. The plan is a tactical document — specific enough for the builder to execute without guessing.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** plan without reading the completion criteria
+- The agent **MUST NOT** copy a previous failed plan without changes
+- The agent **MUST** identify risks or potential blockers up front
+- The agent **MUST NOT** skip verification steps in the plan
+- The agent **MUST NOT** plan more work than can be completed in one bolt
+
+Informed by git history analysis — high-churn files need extra care, stable files need communication, recent refactors indicate directional intent. Use relevance-ranked learning search to find applicable patterns from past work. Apply rule-based decision filtering to evaluate candidate approaches against project constraints.

package/studios/software/stages/development/hats/reviewer.md

@@ -0,0 +1,15 @@
+---
+interpretation: lens
+---
+**Focus:** Verify implementation satisfies completion criteria through multi-stage review. Stage 1: spec compliance (does it do what the criteria say?). Stage 2: code quality (is it well-written?). Stage 3: operational readiness (conditional — only when deployment/monitoring/operations blocks are present).
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** approve without running verification commands
+- The agent **MUST NOT** trust claims ("I tested it") over evidence (actual test output)
+- The agent **MUST NOT** block on low-confidence style issues
+- The agent **MUST** check all three artifact levels: existence, substance, and wiring
+- The agent **MUST NOT** approve code that lacks tests for new functionality
+- The agent **MUST** flag obvious TDD violations — implementation commits with no preceding failing-test commit in the unit's history, or tests that pass on first run with no RED-state evidence — even when overall quality looks acceptable
+- The agent **MUST** verify that every scenario in the product stage's `.feature` files has corresponding test coverage that passes — either as Cucumber step definitions or equivalent tests in the project's test framework
+
+The agent **MUST** apply chain-of-verification (CoVe) for each criterion: form initial judgment, generate verification questions, answer with evidence, revise if needed. For non-trivial units, the agent **MUST** delegate to specialized review agents (correctness, security, performance, etc.) and consolidate findings.

package/studios/software/stages/development/outputs/CODE.md

@@ -0,0 +1,29 @@
+---
+name: code
+location: (project source tree)
+scope: repo
+format: code
+required: true
+---
+
+# Code
+
+Implementation output — code written directly to the project source tree. This is not a document to be authored; it is the working software that satisfies the unit's completion criteria.
+
+## Content Guide
+
+- **Follow existing project patterns** for file organization, naming conventions, and module boundaries
+- **Include appropriate tests** alongside implementation — unit tests for business logic, integration tests for API boundaries
+- **Commit working increments** with clear messages describing what changed and why
+- **Match the behavioral spec** — the code should implement what the spec describes, not a reinterpretation
+
+## Completion
+
+This output is "complete" when all unit completion criteria pass verification and the reviewer approves. There is no separate document to produce — the code in the repository is the output.
+
+## Quality Signals
+
+- Tests pass and cover the new functionality
+- Lint and typecheck pass without suppressions
+- Code follows existing project conventions
+- Commits are incremental and well-described

package/studios/software/stages/development/phases/ELABORATION.md

@@ -0,0 +1,28 @@
+# Development Stage — Elaboration
+
+## Criteria Guidance
+
+The verify-command examples below illustrate the **pattern**. Map them to the project's actual stack — read `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` during elaboration to know which test runner, coverage tool, and linter the project uses, then write the gate against that.
+
+### Good — criterion paired with verifying command
+
+- "All API endpoints return correct status codes for success (200/201), validation errors (400), auth failures (401/403), and not-found (404)"
+  - JS/TS: `pnpm test --run api/contracts.test.ts` exits 0
+  - Python: `pytest tests/api/test_contracts.py` exits 0
+  - Go: `go test ./api/contracts_test.go` exits 0
+
+- "Test coverage is at least 80% for new code"
+  - JS/TS: `pnpm coverage --check 80` exits 0
+  - Python: `pytest --cov --cov-fail-under=80` exits 0
+  - Rust: `cargo tarpaulin --fail-under 80` exits 0
+
+- "No type-evasion in new code (typed-language equivalents of unsafe escape hatches)"
+  - TS: `! grep -rnE ': any\b' --include='*.ts' src/ | grep -v '// eslint-disable.*no-explicit-any'`
+  - Go: `! grep -rnE 'interface\{\s*\}' --include='*.go' .`
+  - Python: `mypy --strict src/` exits 0
+
+### Bad — vague (no clear check)
+
+- "API works correctly" — what does correctly mean?
+- "Tests are written" — how many? Which scenarios? What coverage?
+- "Types are correct" — passes the type-checker? No escape hatches? No casts?