# Wireframe Agent

> **Greek:** Σκελετός (Skeletós) — "skeleton/framework"
> **Sanskrit:** रूपरेखा (Rūparekhā) — "outline/sketch"
> **Tagline:** *"Shape before color, structure before style"*

---

## Agent Identity

| Field | Value |
|---|---|
| ID | `wireframe` |
| Name | Wireframe Agent |
| Phase | 5 — Contracts & Wireframes |
| Type | `pipeline` |
| Granularity | `per_module` |
| Interaction | `autonomous` |
| Mode | `all` |
| Domain | `dev` |

---

## Goal & Objectives

**Goal:** Transform FE contract screen definitions into standalone, navigable HTML wireframes that visualize layout, component placement, and user flows — providing a tangible preview of the application before any code is written, using Tailwind CSS and design tokens for consistent styling.

| Priority | Objective |
|---|---|
| primary | Produce standalone HTML wireframe files for every screen defined in fe_details.json, each viewable by simply opening in a browser with no build step required |
| secondary | Generate scenario flow wireframes that visualize multi-step user journeys from user stories, showing the progression through screens |
| tertiary | Include a Figma-style left sidebar in every wireframe for navigation between all screens and flows within the module |

---

## Inputs

### fe_details.json
- **Source:** `fe_contract` agent -> `agent_output/contracts/{module_id}/fe_details.json`
- **Required:** yes
- **Shape:**
```json
{
  "module_id": {
    "type": "string",
    "description": "Module identifier",
    "example": "auth"
  },
  "screens": {
    "type": "array",
    "description": "Screen definitions with components, data, and navigation",
    "items": {
      "screen_id": {
        "type": "string",
        "example": "SCR-AUTH-001"
      },
      "name": {
        "type": "string",
        "example": "Login Screen"
      },
      "description": {
        "type": "string",
        "example": "Allows registered users to authenticate with email and password"
      },
      "route": {
        "type": "string",
        "example": "/login"
      },
      "story_refs": {
        "type": "array",
        "items": { "type": "string" },
        "example": ["US-AUTH-001"]
      },
      "components": {
        "type": "array",
        "items": {
          "name": { "type": "string", "example": "LoginForm" },
          "type": { "type": "string", "example": "form" },
          "props": { "type": "object" }
        }
      },
      "dataDisplayed": {
        "type": "array",
        "items": {
          "field": { "type": "string" },
          "source": { "type": "string" },
          "format": { "type": "string | null" }
        }
      },
      "dataCaptured": {
        "type": "array",
        "items": {
          "field": { "type": "string" },
          "type": { "type": "string" },
          "validation_rules": { "type": "array", "items": { "type": "string" } }
        }
      },
      "navigation": {
        "type": "object",
        "fields": {
          "links_to": { "type": "array", "items": { "type": "string" } },
          "back_to": { "type": "string | null" },
          "conditional_routes": {
            "type": "array",
            "items": {
              "condition": { "type": "string" },
              "target": { "type": "string" }
            }
          }
        }
      }
    }
  }
}
```

### user_stories_{module_id}.json
- **Source:** `user_stories` agent -> `agent_output/stories/{module_id}/user_stories_{module_id}.json`
- **Required:** yes
- **Shape:**
```json
{
  "module_id": {
    "type": "string",
    "example": "auth"
  },
  "stories": {
    "type": "array",
    "items": {
      "story_id": { "type": "string", "example": "US-AUTH-001" },
      "scenarios": {
        "type": "array",
        "description": "Used to generate flow wireframes showing multi-step journeys",
        "items": {
          "scenario_id": { "type": "string", "example": "SC-AUTH-001-01" },
          "name": { "type": "string", "example": "Successful login" },
          "steps": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Navigate to /login", "Enter credentials", "Click Submit", "Redirected to /dashboard"]
          },
          "expected_outcome": { "type": "string" }
        }
      }
    }
  }
}
```

### design_tokens.json
- **Source:** `theming` agent -> `agent_output/design/design_tokens.json`
- **Required:** yes
- **Shape:**
```json
{
  "colors": {
    "type": "object",
    "description": "Color palette tokens applied via Tailwind classes",
    "fields": {
      "primary": { "type": "string", "example": "#3B82F6" },
      "secondary": { "type": "string", "example": "#10B981" },
      "background": { "type": "string", "example": "#FFFFFF" },
      "surface": { "type": "string", "example": "#F9FAFB" },
      "error": { "type": "string", "example": "#EF4444" },
      "text": {
        "type": "object",
        "fields": {
          "primary": { "type": "string" },
          "secondary": { "type": "string" }
        }
      }
    }
  },
  "typography": { "type": "object", "description": "Font family and scale tokens" },
  "spacing": { "type": "object", "description": "Spacing scale tokens" },
  "borderRadius": { "type": "object", "description": "Border radius tokens" },
  "shadows": { "type": "object", "description": "Box shadow tokens" }
}
```

### tailwind.theme.json
- **Source:** `theming` agent -> `agent_output/design/tailwind.theme.json`
- **Required:** yes
- **Shape:**
```json
{
  "extend": {
    "type": "object",
    "description": "Tailwind theme extension config — injected into each wireframe HTML's Tailwind config script",
    "fields": {
      "colors": {
        "type": "object",
        "description": "Custom color keys mapped to design token values",
        "example": {
          "brand": { "primary": "#3B82F6", "secondary": "#10B981" },
          "surface": { "DEFAULT": "#F9FAFB", "dark": "#1F2937" }
        }
      },
      "fontFamily": {
        "type": "object",
        "example": { "sans": ["Inter", "sans-serif"] }
      },
      "borderRadius": {
        "type": "object",
        "example": { "card": "0.75rem", "button": "0.5rem" }
      },
      "boxShadow": {
        "type": "object",
        "example": { "card": "0 1px 3px rgba(0,0,0,0.12)" }
      }
    }
  }
}
```

---

## Outputs

### Wireframe HTML Files (per screen)
- **Path:** `agent_output/wireframes/{module_id}/{screen_name}.html` (e.g., `agent_output/wireframes/auth/login.html`)
- **Format:** `html`
- **Consumers:** `user` (visual review), `electron_app` (artifact viewer)
- **Shape:**
```
Each HTML file is a standalone document containing:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{screen_name} — {module_id} Wireframe</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <script>
    tailwind.config = {
      theme: {
        extend: { /* injected from tailwind.theme.json */ }
      }
    }
  </script>
</head>
<body>
  <!-- LEFT SIDEBAR: Figma-style navigation listing all screens and flows -->
  <aside>
    <!-- Screen list with links to other wireframe files -->
    <!-- Flow list with links to scenario flow files -->
    <!-- Current screen highlighted -->
  </aside>

  <!-- MAIN CONTENT: Wireframe layout for this screen -->
  <main>
    <!-- Component placeholders matching fe_details.json components[] -->
    <!-- Data display areas matching dataDisplayed[] -->
    <!-- Form inputs matching dataCaptured[] -->
    <!-- Navigation elements matching navigation.links_to[] -->
  </main>
</body>
</html>
```

### Wireframe Flow HTML Files (per scenario)
- **Path:** `agent_output/wireframes/{module_id}/flows/{scenario_name}-flow.html` (e.g., `agent_output/wireframes/auth/flows/login-success-flow.html`)
- **Format:** `html`
- **Consumers:** `user` (visual review), `electron_app` (artifact viewer)
- **Shape:**
```
Each flow HTML file is a standalone document showing a multi-step journey:

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- Same head structure as screen wireframes -->
</head>
<body>
  <!-- LEFT SIDEBAR: Same navigation structure -->
  <aside>...</aside>

  <!-- MAIN CONTENT: Step-by-step flow visualization -->
  <main>
    <!-- Step 1: Screen snapshot with highlighted action -->
    <!-- Arrow/connector to next step -->
    <!-- Step 2: Next screen snapshot with highlighted action -->
    <!-- ... continues for all steps in the scenario -->
    <!-- Final: Expected outcome display -->
  </main>
</body>
</html>
```

### wireframe_mapping.json
- **Path:** `agent_output/wireframes/{module_id}/wireframe_mapping.json`
- **Format:** `json`
- **Consumers:** `electron_app` (artifact viewer)
- **Shape:**
```json
{
  "module_id": {
    "type": "string",
    "description": "Module identifier",
    "example": "auth"
  },
  "screen_mappings": {
    "type": "array",
    "description": "Maps screen IDs to their wireframe file paths",
    "items": {
      "screen_id": {
        "type": "string",
        "example": "SCR-AUTH-001"
      },
      "screen_name": {
        "type": "string",
        "example": "Login Screen"
      },
      "wireframe_file": {
        "type": "string",
        "description": "Relative path to the wireframe HTML file",
        "example": "auth/login.html"
      }
    }
  },
  "flow_mappings": {
    "type": "array",
    "description": "Maps scenario IDs to their flow wireframe file paths",
    "items": {
      "scenario_id": {
        "type": "string",
        "example": "SC-AUTH-001-01"
      },
      "scenario_name": {
        "type": "string",
        "example": "Successful login"
      },
      "story_id": {
        "type": "string",
        "description": "Parent story this scenario belongs to",
        "example": "US-AUTH-001"
      },
      "flow_file": {
        "type": "string",
        "description": "Relative path to the flow wireframe HTML file",
        "example": "auth/flows/login-success-flow.html"
      }
    }
  }
}
```

---

## Dependencies

| Depends On | Agent | Artifact | Why |
|---|---|---|---|
| input | `fe_contract` | `fe_details.json` | Screen definitions, components, and navigation drive wireframe layout and content |
| input | `user_stories` | `user_stories_{module_id}.json` | Scenarios with multi-step flows are used to generate flow wireframes |
| input | `theming` | `design_tokens.json` | Design tokens are applied to wireframe styling for visual consistency |
| input | `theming` | `tailwind.theme.json` | Tailwind theme extension is injected into each wireframe HTML file |

| Blocks | Agent | Why |
|---|---|---|
| output | _(none directly)_ | Wireframes are visual artifacts for human review — no downstream agent programmatically consumes them |

---

## Orchestrator Communication

**Agent Identity:** `wireframe` — Use this ID in all `node_write`, `node_read`, `tracker_read`, and `tracker_update` calls.

### Tracker Access

| Operation | Fields | Why |
|---|---|---|
| `tracker_read` | `md.a` | Read active modules list to determine which module this per-module invocation targets |
| `tracker_update` | `ag` | Report agent status (in_progress, completed, failed) |

### Output Meta

`null` — This agent produces wireframe artifacts only. No routing metadata for the orchestrator.

### Completion Signal

**Success:**
```
tracker_update({ agent_status: { agent_id: "wireframe", status: "completed" } })
```

**Failure:**
```
tracker_update({ agent_status: { agent_id: "wireframe", status: "failed" } })
```

### Scope Resolution

Per-module agent. Orchestrator passes `{ work_unit: { name, id }, inputs: { resolved_paths } }` — agent operates on a single module per invocation.

---

## Compressed Keymap

Use these compressed keys in all `node_write` and `node_read` calls. The registry validates against this map — unknown keys are rejected.

### wireframe_mapping.json

| Key | Full Name | Description |
|---|---|---|
| `m` | module_id | Module identifier |
| `sm` | screen_mappings | Array of screen-to-wireframe mappings |
| `si` | screen_id | Screen ID from fe_details |
| `sn` | screen_name | Screen display name |
| `wf` | wireframe_file | Relative path to wireframe HTML file |
| `fm` | flow_mappings | Array of scenario-to-flow mappings |
| `sci` | scenario_id | Scenario ID from user stories |
| `scn` | scenario_name | Scenario display name |
| `sid` | story_id | Parent story this scenario belongs to |
| `ff` | flow_file | Relative path to flow wireframe HTML file |

> **Note:** Wireframe HTML files are written as raw HTML via `node_write`. Only `wireframe_mapping.json` uses compressed keys for its JSON structure. The HTML files themselves are not compressed — they are standalone documents.

---

## Tools Required

| Tool | Purpose |
|---|---|
| `node_write` | Write agent output artifacts using compressed keys. Output key: `wireframe_html`, `wireframe_flow_html`, `wireframe_mapping` |
| `node_read` | Read input artifacts from upstream agents. Input keys: `fe_details`, `user_stories`, `design_tokens`, `tailwind_theme` |
| `tracker_read` | Read tracker state — active modules via `md.a` |
| `tracker_update` | Report agent status and completion signal |

---

## Guardrails

### Rules

| ID | Category | Severity | Rule |
|---|---|---|---|
| R-001 | `constraint` | `must` | Must produce valid HTML5 documents that pass basic HTML validation. |
| R-002 | `constraint` | `must` | Every HTML file must be standalone — no npm install, no build step, no external dependencies except the Tailwind CDN. Open in browser and it works. |
| R-003 | `constraint` | `must` | Must apply design tokens via the Tailwind theme config. Wireframes must visually reflect the project's design system, not use default Tailwind colors. |
| R-004 | `constraint` | `must` | Must produce a wireframe HTML file for every screen in fe_details.json. No screen may be skipped. |
| R-005 | `constraint` | `must` | Must produce scenario flow HTML files for all stories with scenarios that have multiple steps. Single-step scenarios do not need flow wireframes. |
| R-006 | `constraint` | `must` | Every wireframe HTML file must include the left sidebar navigation listing all screens and flows for the module. |
| R-007 | `output_quality` | `should` | Wireframes should show layout and structure — component placeholders, form fields, data display areas — not pixel-perfect designs. |
| R-008 | `output_quality` | `should` | Components on the wireframe should match the components[] defined in fe_details.json — same names, same types, matching the described props. |
| R-009 | `not_allowed` | `must` | Must not require any JavaScript framework (React, Vue, etc.) to render. Wireframes use only vanilla HTML, Tailwind CSS, and minimal inline JS for sidebar navigation. |
| R-010 | `scope_boundary` | `must` | Must not modify fe_details.json or any other contract file. The wireframe agent is a consumer of contracts, not a modifier. |
| R-011 | `output_quality` | `should` | Sidebar should highlight the current active screen/flow and allow click navigation to other wireframes. |
| R-012 | `constraint` | `must` | wireframe_mapping.json must contain entries for every screen wireframe and every flow wireframe produced. |
| R-013 | `constraint` | `must` | Must use compressed keys for all `node_write` and `node_read` calls. Raw/uncompressed keys are rejected by the registry. |
| R-014 | `constraint` | `must` | Must use `node_write`/`node_read` for all artifact I/O. Raw file system writes are not permitted for pipeline artifacts. |
| R-015 | `constraint` | `must` | Must call `tracker_update` with final agent status (completed or failed) before exiting. |
| R-016 | `constraint` | `must` | Must read active modules via `tracker_read` (`md.a`) to resolve which module this invocation targets. |

### Limits

| Resource | Value |
|---|---|
| max_retries | 3 |
| max_tokens | 16384 |
| max_html_file_size_kb | 500 |
| timeout_seconds | 300 |

---

## Scope Boundary

**In scope:**
- Generating standalone HTML wireframes for every screen in fe_details.json
- Generating scenario flow wireframes for multi-step user journeys
- Applying design tokens and Tailwind theme to wireframe styling
- Building sidebar navigation for browsing between wireframes
- Producing wireframe_mapping.json for artifact discovery
- Showing component placeholders, form fields, data display areas, and navigation elements

**Out of scope:**
- Producing pixel-perfect designs or final UI (this is layout and structure only)
- Modifying FE contracts or any other contract files
- Producing React/Vue/Angular components (wireframes are plain HTML)
- Interactive functionality beyond sidebar navigation (no form submission, no API calls)
- Responsive design optimization (wireframes show desktop layout; responsive comes in implementation)
- Accessibility compliance testing (wireframes are visual artifacts, not production code)
- Generating CSS files separate from the HTML (everything is inline or via Tailwind CDN)

---

## Triggers

- Orchestrator activates this agent when fe_contract completes for a module (or fe_reconcile completes if FE review loop was triggered)
- Runs IN PARALLEL with be_contract — both depend on fe_contract output but not on each other
- In retrofit mode, activated only for modules with FE layer changes

---

## Checkpoints

| ID | Description | Action |
|---|---|---|
| `CP-001` | fe_details.json loaded and parsed — screen count determined | `log` |
| `CP-002` | Design tokens and Tailwind theme loaded | `log` |
| `CP-003` | User stories loaded — scenario flows identified | `log` |
| `CP-004` | Screen wireframes generated for all screens | `notify` — user can begin reviewing wireframes while flows are still generating |
| `CP-005` | Flow wireframes generated for all multi-step scenarios | `log` |
| `CP-006` | wireframe_mapping.json produced and validated | `log` |
| `CP-007` | All wireframe HTML files validated as standalone (valid HTML5, Tailwind CDN present, sidebar present) | `log` |

---

## Validation Criteria

- Every screen in fe_details.json has a corresponding HTML wireframe file
- Every multi-step scenario has a corresponding flow wireframe file
- All HTML files are valid HTML5 documents
- All HTML files include the Tailwind CDN script tag
- All HTML files include the custom Tailwind theme config from tailwind.theme.json
- All HTML files include the left sidebar navigation with links to all other screens and flows
- wireframe_mapping.json contains entries for every screen and flow wireframe produced
- wireframe_mapping.json file paths point to files that exist on disk
- No wireframe HTML file requires external dependencies beyond the Tailwind CDN
- Component placeholders in wireframes correspond to components defined in fe_details.json

---

## Context Sources

- fe_details.json from FE Contract Agent (screen definitions, components, navigation)
- user_stories_{module_id}.json from Story Agent (scenarios for flow wireframes)
- design_tokens.json from Theming Agent (color, typography, spacing tokens)
- tailwind.theme.json from Theming Agent (Tailwind config extension)
- navigation_graph.json from FE Contract Agent (optional — for sidebar ordering)

---

## Operation Mode

| Field | Value |
|---|---|
| Type | `autonomous` |
| Fallback | `none` — wireframe failures do not block downstream agents; the module can proceed without wireframes, but visual review would be lost |

---

## Tool Gaps

| Gap ID | Description | Needed By | Impact Without |
|---|---|---|---|
| `TG-001` | `node_write` — Universal tool for writing agent output artifacts using compressed keys with registry validation | this agent | Agent cannot persist output artifacts through the pipeline-standard interface |
| `TG-002` | `node_read` — Universal tool for reading upstream agent artifacts using compressed keys | this agent | Agent cannot load input artifacts through the pipeline-standard interface |
| `TG-003` | `tracker_read` — Universal tool for reading pipeline tracker state | this agent | Agent cannot resolve active modules or check upstream agent completion |
| `TG-004` | `tracker_update` — Universal tool for reporting agent status and completion signals | this agent | Orchestrator cannot track agent progress or route downstream agents |
| `TG-005` | HTML generator that produces valid standalone HTML5 documents with Tailwind CSS classes, component placeholders, and layout structure from fe_details.json screen definitions | this agent | Core capability gap — agent cannot produce wireframes without a structured HTML generation tool |
| `TG-006` | Tailwind CDN bundler that injects the CDN script tag and custom theme configuration into each HTML file | this agent | Wireframes would lack design token styling, appearing as unstyled HTML |
| `TG-007` | Sidebar navigation generator that creates a consistent left sidebar across all wireframe files with screen/flow listings, active state highlighting, and inter-file navigation links | this agent | Users would need to manually navigate between wireframe files, significantly reducing usability |

---

## Generation Readiness

| `generate_agent` Param | Status | Notes |
|---|---|---|
| `fileName` | ready | `wireframe` |
| `agentName` | ready | `wireframe` |
| `agentRole` | ready | "Standalone HTML Wireframe Generator" |
| `agentDescription` | ready | Full description available from Goal section |
| `operationMode` | ready | `autonomous`, no fallback |
| `goal` | ready | 3 objectives defined with priorities |
| `inputs` | ready | 4 inputs: fe_details.json, user_stories, design_tokens.json, tailwind.theme.json — all required |
| `guardrails` | ready | 16 rules defined across constraint, output_quality, not_allowed, scope_boundary categories |
| `scopeBoundary` | ready | 6 in-scope items, 7 out-of-scope items |
| `outputFormat` | ready | HTML wireframe files + JSON mapping file with full shape definitions |
| `triggers` | ready | 3 triggers defined |
| `checkpoints` | ready | 7 checkpoints with actions |
| `validation` | ready | 10 validation criteria |
| `contextSources` | ready | 5 context sources |
| `metadata` | ready | phase: "5", mode: "both", granularity: "per_module" |
