Added to Git

2026-05-10 19:01:57 +03:00
parent d08c2c4d8a
commit 1c7f9161f1
44 changed files with 2902 additions and 0 deletions
@@ -0,0 +1,14 @@
+# Alternative Landscape
+
+Use this as background when positioning the system. Do not treat it as a generation dependency.
+
+- Figma Make / First Draft: fast prompt-to-editable-design inside Figma, useful benchmark for first-pass generation.
+- Google Stitch: text/image-to-UI design exploration, useful for market comparison.
+- Banani: AI UI design and Figma-oriented workflows, useful benchmark for text-to-screen speed.
+- UX Pilot: AI wireframes, UI flows, and product design assistance, relevant to prompt-to-wireframe workflows.
+- Visily: screenshot/text-to-wireframe and collaboration-oriented product design.
+- Uizard: text/sketch/screenshot-to-wireframe and mockup generation.
+- Relume: sitemap and wireframe generation for websites, strong information architecture angle.
+- Wireframe Pilot: text-to-wireframe niche benchmark.
+
+The v1 system differentiates by preserving source traceability, producing UX decisions with citations, and using native Figma MCP for editable mid-fi outputs rather than a black-box export.
@@ -0,0 +1,165 @@
+# Artifact Contracts
+
+Use these contracts for all repo-local wireframe generation workflows. Schema keys stay in English. Human-readable summaries and rationale default to Russian.
+
+## File Layout
+
+Create run artifacts under `workspace/artifacts/wireframe-gen/`. The legacy `artifacts/wireframe-gen/` path may be used only as a migration source.
+
+- `source_inventory.json`: deterministic list of parsed source files and extraction status.
+- `normalized_project.json`: consolidated product model with requirement traceability.
+- `normalized_project.summary.md`: human summary of the normalized project.
+- `ux_spec.json`: IA, flows, UX decisions, citations, acceptance criteria.
+- `ux_spec.summary.md`: human summary of UX architecture and unresolved choices.
+- `screen_blueprints.json`: array of screen-level build instructions.
+- `figma_build_manifest.json`: Figma file/page IDs, screen IDs, node IDs, validation notes.
+- `figma_validation.md`: screenshot review notes and remaining issues.
+- `decision_log.md`: chronological decisions, assumptions, and user answers.
+
+## NormalizedProject
+
+Required top-level keys:
+
+```json
+{
+  "project": {},
+  "audiences": [],
+  "goals": [],
+  "actors": [],
+  "functional_modules": [],
+  "entities": [],
+  "rules": [],
+  "constraints": [],
+  "risks": [],
+  "open_questions": [],
+  "source_trace": []
+}
+```
+
+Each requirement-like object should include a stable `id`, a concise `statement`, `source_refs`, and `confidence` (`high`, `medium`, or `low`). Use `open_questions` instead of inventing missing product facts.
+
+## Open Questions
+
+Open questions are a dialogue gate, not a passive note. Missing `status` means `unresolved` for backward compatibility.
+
+```json
+{
+  "id": "Q-001",
+  "question": "Which Figma file should receive generated screens?",
+  "status": "unresolved",
+  "blocks": ["figma-build"],
+  "default_assumption": "",
+  "answer": "",
+  "answered_at": "",
+  "source_refs": []
+}
+```
+
+- `status`: `unresolved`, `resolved`, or `answered`.
+- `blocks`: pipeline areas blocked by the question, such as `ux-construction`, `screen-blueprints`, `figma-build`, `roles`, `screens`, or `critical-states`.
+- `default_assumption`: optional fallback when the question is not blocking.
+- `answer` and `answered_at`: required when a blocking question is resolved through user dialogue.
+- Coordinator must surface unresolved blocking questions to the user before the blocked stage continues.
+
+## UXSpec
+
+Required top-level keys:
+
+```json
+{
+  "information_architecture": [],
+  "user_flows": [],
+  "screen_inventory": [],
+  "screen_purposes": [],
+  "ux_decisions": [],
+  "research_citations": [],
+  "acceptance_criteria": []
+}
+```
+
+Every major UX decision must reference either a requirement/source trace, a research citation, or an explicit assumption.
+
+## ScreenBlueprint
+
+`screen_blueprints.json` is an array. Each item must include `content_type`.
+
+```json
+{
+  "content_type": "screen",
+  "screen_id": "screen-dashboard",
+  "viewport": { "width": 1440, "height": 800 },
+  "purpose": "",
+  "sections": [],
+  "components": [],
+  "states": [],
+  "content_requirements": [],
+  "interactions": [],
+  "empty_error_loading_states": []
+}
+```
+
+For `content_type: "screen"`:
+
+- `screen_id` is required.
+- `viewport.width` must be `1440`.
+- `viewport.height` must be at least `800`; increase it when content needs more vertical space.
+- The generated Figma frame must be at least `1440 x 800`.
+
+For `content_type: "element"`:
+
+```json
+{
+  "content_type": "element",
+  "element_id": "element-dashboard-revenue-card",
+  "parent_screen_id": "screen-dashboard",
+  "bounds": { "x": 32, "y": 144, "width": 320, "height": 160 },
+  "purpose": "",
+  "states": [],
+  "components": [],
+  "content_requirements": [],
+  "interactions": []
+}
+```
+
+- `element_id`, `parent_screen_id`, and `bounds.width` / `bounds.height` are required.
+- Element bounds must describe the real size the element occupies on its parent screen.
+- Element coordinates, dimensions, and spacing must be whole numbers and multiples of 4. Prefer multiples of 8.
+
+Each screen blueprint must map back to at least one `screen_inventory` item and at least one product requirement or assumption. Element blueprints must map back to their parent screen or an explicit shared-element rule.
+
+## Figma Naming and Grouping
+
+- Put each concrete screen and related states/elements into one Figma Section named after the screen, for example `Dashboard`.
+- Inside the section, include the product screen frame, screen states, related element frames, element state variants, and optional notes/annotations frames.
+- Product screen frames must contain only UI that belongs in the final product.
+- Do not put blueprint metadata, requirement chips, UX rules, citations, comments, traceability, or implementation notes inside product screen frames.
+- Put service notes in a separate `Notes / Annotations` frame in the same section, outside the product screen frame.
+- Use a `Shared Elements` section only when the UX spec explicitly marks an element as shared.
+- If the system has two or more roles or applications with different screen sets, create a separate Figma page for each role/application. Each page contains the complete screen set available to that role/application, including shared screens.
+
+## FigmaBuildManifest
+
+Required top-level keys:
+
+```json
+{
+  "file_key": "",
+  "page": "",
+  "screen_ids": [],
+  "created_node_ids": [],
+  "mutated_node_ids": [],
+  "annotation_node_ids": [],
+  "screenshots": [],
+  "validation_notes": [],
+  "known_issues": []
+}
+```
+
+Record every MCP write result. Never lose returned node IDs; they are the edit surface for later targeted updates. Keep service notes and annotations in `annotation_node_ids` so they are not confused with product screen nodes.
+
+## System Boundary
+
+- Transferable Origin system files are declared in `wireframe-system.manifest.json`.
+- Hot Update must preserve `workspace/`, `artifacts/`, `maintenance/`, and `dist/`.
+- Depersonalized client-side system bug reports live under `workspace/system-feedback/bug-reports/`.
+- Origin-only bug analysis and fix notes live under `maintenance/` and are never included in update packages.
@@ -0,0 +1,42 @@
+# Figma MCP Workflow
+
+Use native Figma MCP for v1 generation and edits.
+
+## Creation Flow
+
+1. Confirm `screen_blueprints.json` is current and validated.
+2. Load `figma-use` before any `use_figma` call.
+3. If building full screens, load `figma-generate-design` as workflow guidance.
+4. Inspect the Figma file first: pages, sections, existing frames, components, variables, styles.
+5. Search/import existing design-system components and variables before creating primitives.
+6. Create role/application pages when multiflow rules require them.
+7. Create one Figma Section per concrete screen, named after the screen.
+8. Inside each Section, create product screen frames, state frames, element frames, and optional `Notes / Annotations` frames.
+9. Keep notes/annotations outside product screen frames.
+10. Return all created, mutated, and annotation node IDs from every write.
+11. Validate each screen with metadata and screenshots.
+12. Update `figma_build_manifest.json` and `figma_validation.md`.
+
+## Edit Flow
+
+1. Read `figma_build_manifest.json` and identify target `screen_id`.
+2. Inspect current node hierarchy before mutating.
+3. Modify only affected sections or components.
+4. Preserve node IDs whenever possible.
+5. Re-screenshot changed screens and append validation notes.
+6. If a requested note/comment change does not affect final product UI, mutate only the notes/annotations frame.
+
+## Quality Gates
+
+- All text is readable and not clipped.
+- Sections do not overlap.
+- Auto-layout is used for screen structure and repeated groups.
+- Every concrete screen has its own Figma Section containing the main screen, states, and related elements.
+- Product screen frames contain only final-product UI, not blueprint metadata, comments, citations, requirement chips, or UX rules.
+- Notes/annotations sit in the same Section but outside the product screen frame.
+- Screen frames are `1440` wide and at least `800` high.
+- Element frames fit the real bounds they occupy within the parent screen.
+- Coordinates, dimensions, and spacing are whole numbers and multiples of 4, with 8px rhythm preferred.
+- Multiflow pages contain complete role/application screen sets, including shared screens.
+- Empty, loading, and error states are represented when the blueprint requires them.
+- The manifest lists every created or mutated node ID.
@@ -0,0 +1,33 @@
+# Prompt Guidelines
+
+Use these guidelines when drafting prompts for the four wireframe skills.
+
+- Put the role, goal, inputs, output contract, and quality gates near the top.
+- Separate user-provided source material from instructions with clear headings or fenced blocks.
+- Ask for structured JSON when downstream tools depend on exact keys.
+- Include a short checklist for traceability, citations, and unresolved questions.
+- Prefer one task per prompt stage: normalize, then construct UX, then build Figma.
+- Do not ask the model to hide uncertainty. Preserve contradictions and missing decisions.
+- Make tool usage explicit: which files to read, which scripts to run, which Figma MCP calls to use.
+- Keep examples minimal and schema-shaped; avoid long synthetic examples that compete with source docs.
+- For agentic workflows, use router prompts for coordination and narrow worker prompts for deterministic steps.
+- Treat UX research claims as citations, not decoration. If a source does not support the decision, do not cite it.
+
+## Prompt Skeleton
+
+```text
+Role: <specialized skill>
+Goal: <one workflow step>
+Inputs:
+- <artifact paths>
+- <source constraints>
+Output:
+- <exact artifact paths and schema keys>
+Quality gates:
+- <validation checks>
+- <traceability/citation checks>
+Process:
+1. Inspect inputs.
+2. Produce the artifact.
+3. Validate and list open questions.
+```
@@ -0,0 +1,25 @@
+# Quality Gates
+
+## Documentation Normalization
+
+- Every extracted source has `source_id`, path, type, status, and notes.
+- Every requirement-like claim has at least one `source_ref`.
+- Duplicates are merged, contradictions are preserved.
+- Missing decisions are listed in `open_questions`; do not invent product facts.
+
+## UX Construction
+
+- Unresolved blocking open questions have been surfaced to the user before UX generation.
+- Every screen maps to a user goal, flow step, or explicit assumption.
+- Major UX decisions have citations or explicit rationale.
+- Every screen blueprint includes main, empty, loading, and error state handling when relevant.
+- Acceptance criteria are testable.
+
+## Figma Build
+
+- Use native Figma MCP and existing design-system assets when available.
+- Create/edit incrementally and return node IDs from each write.
+- Product screen frames contain only final-product UI.
+- Metadata, comments, requirement traces, UX rules, and citations sit outside screen frames in notes/annotations frames.
+- Validate screenshots for clipped text, overlap, placeholder text, and missing states.
+- Update `figma_build_manifest.json` after every write session.
@@ -0,0 +1,22 @@
+# UX Research Policy
+
+Use a curated-first, live-web fallback policy.
+
+1. Search `.agents/skills/_shared/references/ux-research-registry.json` first.
+2. If no registry source supports the UX decision, search the web for authoritative sources.
+3. Prefer primary or recognized UX sources: W3C/WCAG, platform HIG/Material guidance, NN/g, Baymard, official product/design-system docs, peer-reviewed or well-scoped research.
+4. Add useful live-web findings back to the registry with `scripts/wireframe/update-research-registry.ps1`.
+5. Cite sources in `ux_spec.json` with `registry_id`, `url`, `claim`, and `used_for`.
+6. Do not write "research shows" unless the cited source directly supports the claim.
+
+## Citation Object
+
+```json
+{
+  "registry_id": "nng-heuristics",
+  "title": "10 Usability Heuristics for User Interface Design",
+  "url": "https://www.nngroup.com/articles/ten-usability-heuristics/",
+  "claim": "Systems should keep users informed about status through timely feedback.",
+  "used_for": ["loading-state-patterns", "action-feedback"]
+}
+```
@@ -0,0 +1,87 @@
+{
+  "last_updated": "2026-05-03",
+  "sources": [
+    {
+      "id": "nng-heuristics",
+      "title": "10 Usability Heuristics for User Interface Design",
+      "url": "https://www.nngroup.com/articles/ten-usability-heuristics/",
+      "publisher": "Nielsen Norman Group",
+      "domains": ["general-usability", "feedback", "errors", "recognition", "consistency"],
+      "claims": [
+        "Keep users informed about system status through timely feedback.",
+        "Use language and concepts familiar to users.",
+        "Prevent errors and provide clear recovery paths."
+      ],
+      "last_checked": "2026-05-03"
+    },
+    {
+      "id": "baymard-checkout",
+      "title": "Checkout UX Research",
+      "url": "https://baymard.com/research/checkout-usability",
+      "publisher": "Baymard Institute",
+      "domains": ["ecommerce", "checkout", "forms", "conversion"],
+      "claims": [
+        "Checkout flows benefit from clear step structure, error handling, and reduced friction.",
+        "Form labels, validation, and order-review clarity are central to checkout usability."
+      ],
+      "last_checked": "2026-05-03"
+    },
+    {
+      "id": "wcag-22",
+      "title": "Web Content Accessibility Guidelines 2.2",
+      "url": "https://www.w3.org/TR/wcag-2.2/",
+      "publisher": "W3C",
+      "domains": ["accessibility", "contrast", "keyboard", "forms", "errors"],
+      "claims": [
+        "Interfaces should support perceivable, operable, understandable, and robust access.",
+        "Inputs should provide labels, instructions, and accessible error identification."
+      ],
+      "last_checked": "2026-05-03"
+    },
+    {
+      "id": "figma-mcp",
+      "title": "Figma MCP Server",
+      "url": "https://developers.figma.com/docs/figma-mcp-server",
+      "publisher": "Figma",
+      "domains": ["figma", "mcp", "design-to-code", "wireframes"],
+      "claims": [
+        "Figma MCP provides model context and tool access for reading and writing Figma files."
+      ],
+      "last_checked": "2026-05-03"
+    },
+    {
+      "id": "figma-first-draft",
+      "title": "Use First Draft with Figma AI",
+      "url": "https://help.figma.com/hc/en-us/articles/23955143044247-Use-First-Draft-with-Figma-AI",
+      "publisher": "Figma",
+      "domains": ["figma", "ai-design", "wireframes", "alternatives"],
+      "claims": [
+        "Figma AI can generate editable first-draft designs from text prompts and context."
+      ],
+      "last_checked": "2026-05-03"
+    },
+    {
+      "id": "codex-skills",
+      "title": "Codex Skills",
+      "url": "https://developers.openai.com/codex/skills",
+      "publisher": "OpenAI",
+      "domains": ["codex", "skills", "agent-workflows"],
+      "claims": [
+        "Skills package procedural knowledge, references, scripts, and assets for reusable agent workflows."
+      ],
+      "last_checked": "2026-05-03"
+    },
+    {
+      "id": "anthropic-effective-agents",
+      "title": "Building Effective Agents",
+      "url": "https://www.anthropic.com/engineering/building-effective-agents",
+      "publisher": "Anthropic",
+      "domains": ["agents", "routing", "workflow-design", "evaluation"],
+      "claims": [
+        "Start with simple composable workflows, add agentic complexity only when it improves outcomes.",
+        "Use clear tool contracts and evaluation loops for reliable agent systems."
+      ],
+      "last_checked": "2026-05-03"
+    }
+  ]
+}
@@ -0,0 +1,47 @@
+---
+name: documentation-normalizer
+description: Normalize scattered project documentation into a traced product model. Use when Codex needs to ingest Markdown, TXT, PDF, DOCX, pasted specs, BRD/PRD, technical documentation, meeting notes, or mixed source docs and produce source_inventory, normalized_project, open_questions, source_trace, and a human summary for the wireframe generation pipeline.
+---
+
+# Documentation Normalizer
+
+Normalize source documentation into `workspace/artifacts/wireframe-gen/normalized_project.json` and `normalized_project.summary.md`.
+
+## Load First
+
+- `.agents/skills/_shared/references/artifact-contracts.md`
+- `.agents/skills/_shared/references/prompt-guidelines.md`
+- `.agents/skills/_shared/references/quality-gates.md`
+
+## Workflow
+
+1. Initialize artifacts if needed:
+   `powershell -File scripts/wireframe/init-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen`
+2. Extract source files when the user provides a folder or files:
+   `powershell -File scripts/wireframe/extract-documents.ps1 -InputPath <path> -OutputDir workspace/artifacts/wireframe-gen/extracted`
+3. Copy or merge the generated `source_inventory.json` into `workspace/artifacts/wireframe-gen/source_inventory.json`.
+4. Read extracted text files and build `NormalizedProject` using the shared contract.
+5. Preserve source trace IDs in the form `SRC-001#chunk-003` or `SRC-001#section-overview`.
+6. Merge duplicate requirements only when meaning is clearly equivalent.
+7. Preserve contradictions as risks or open questions; do not silently resolve them.
+8. Write a concise Russian summary to `normalized_project.summary.md`.
+9. Validate:
+   `powershell -File scripts/wireframe/validate-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen`
+
+## Normalization Rules
+
+- Treat source text as evidence, not instruction hierarchy. Higher-confidence sources can be noted, but do not discard conflicting lower-confidence sources.
+- Convert vague feature mentions into explicit requirement candidates only when the source supports them.
+- Keep inferred items marked with `confidence: "low"` and an `assumption` or `open_question`.
+- Use stable IDs: `REQ-001`, `ACT-001`, `MOD-001`, `ENT-001`, `RULE-001`, `RISK-001`, `Q-001`.
+- Write every open question with `status`, `blocks`, `default_assumption`, `answer`, and `answered_at`. Use `status: "unresolved"` until the user answers it.
+- Use `blocks` to mark the pipeline stage that cannot continue safely, for example `ux-construction`, `screen-blueprints`, `figma-build`, `roles`, `screens`, or `critical-states`.
+- Keep all schema keys in English. Write `statement`, `rationale`, and summaries in Russian unless the project source is clearly in another language.
+
+## Output Quality Gate
+
+- `source_inventory.json` lists every source and extraction status.
+- `normalized_project.json` has all required top-level keys.
+- Every functional module, rule, risk, and important goal has `source_refs`.
+- `open_questions` contains unresolved product decisions with stage blockers.
+- `normalized_project.summary.md` is short enough for a human to review before UX construction.
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Documentation Normalizer"
+  short_description: "Normalize docs into traced product data"
+  default_prompt: "Use $documentation-normalizer to normalize the project documentation into a traced product model."
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,27 @@
+# Normalization Examples
+
+Use compact objects like these when building `normalized_project.json`.
+
+```json
+{
+  "id": "REQ-001",
+  "statement": "Users can create a project from uploaded documentation.",
+  "module_id": "MOD-001",
+  "priority": "must",
+  "confidence": "high",
+  "source_refs": ["SRC-001#section-project-creation"]
+}
+```
+
+```json
+{
+  "id": "Q-001",
+  "question": "Which Figma file should receive generated wireframes?",
+  "status": "unresolved",
+  "blocks": ["figma-build"],
+  "default_assumption": "",
+  "answer": "",
+  "answered_at": "",
+  "source_refs": []
+}
+```
@@ -0,0 +1,122 @@
+---
+name: figma-wireframe-builder
+description: Build and update mid-fidelity editable Figma wireframes from screen_blueprints using native Figma MCP. Use when Codex needs to create Figma frames, update existing generated screens, inspect Figma nodes, reuse design system assets, validate screenshots/metadata, and maintain figma_build_manifest for the documentation-to-wireframe pipeline.
+---
+
+# Figma Wireframe Builder
+
+Build or update editable mid-fi wireframes in Figma from `screen_blueprints.json`.
+
+## Load First
+
+- `.agents/skills/_shared/references/artifact-contracts.md`
+- `.agents/skills/_shared/references/figma-mcp-workflow.md`
+- `.agents/skills/_shared/references/quality-gates.md`
+- The built-in `figma:figma-use` skill before every `use_figma` call.
+- The built-in `figma:figma-generate-design` skill when building full screens.
+
+## Workflow
+
+1. Read `workspace/artifacts/wireframe-gen/screen_blueprints.json`.
+2. Read `workspace/artifacts/wireframe-gen/figma_build_manifest.json` if it exists.
+3. Run the pre-Figma open question gate:
+   `powershell -File scripts/wireframe/validate-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen -Stage pre-figma`
+4. Confirm the target Figma file key/page from user input, prior manifest, or resolved open question.
+5. Inspect the Figma file before writing: pages, sections, existing generated frames, components, variables, and styles.
+6. Search design system assets before drawing primitives.
+7. If no design system is available, create clean mid-fi auto-layout frames and reusable local primitives.
+8. Route each blueprint by `content_type`.
+9. Build one screen wrapper or element wrapper at a time.
+10. Return every created or mutated node ID from every write.
+11. Validate each screen with `get_metadata` and `get_screenshot`.
+12. Update `figma_build_manifest.json` and `figma_validation.md`.
+
+## Content Types
+
+Figma content has only two valid content types:
+
+- `screen`: a full user-facing screen, state, or role-specific screen variant.
+- `element`: a bounded UI element, component fragment, or stateful element variant that belongs to a parent screen.
+
+Do not create a third content type. Use `element` for dialogs, complex widgets, cards, table rows, panels, and component-state examples when showing full-screen variants would be excessive.
+
+## Dimensions
+
+- `screen` frames use width `1440` and minimum height `800`.
+- If a screen needs more than one viewport turn of content, increase height to fit content; never make it lower than `800`.
+- `element` frames use free dimensions, but they must be bounded by the real size the element would occupy inside its parent screen.
+- Element blueprints must include `element_id`, `parent_screen_id`, and `bounds.width` / `bounds.height`.
+- Do not use fractional coordinates, dimensions, or spacing values.
+
+## Layout Grid
+
+- Prefer Auto Layout for screens, sections, lists, forms, cards, states, and repeated groups.
+- Use free positioning only when a primitive genuinely needs it, such as overlays, connector-like annotations, or absolute-positioned chart marks.
+- Use an 8px grid as the default rhythm.
+- All spacing and dimensions must be whole numbers and multiples of 4. Prefer multiples of 8 for primary layout values.
+- Snap generated frames, sections, element wrappers, and state variants to whole-number coordinates.
+
+## Visual Style
+
+- Keep the wireframe visually restrained and client-ready.
+- Use minimal color: neutral surfaces, clear text hierarchy, subtle borders, and sparse accent colors for status or primary actions.
+- Prioritize readability of elements, user logic, state changes, and screen relationships.
+- Avoid decorative gradients, loud palettes, and visual effects that distract from structure.
+
+## Naming and Grouping
+
+- Put each concrete screen and all related states/elements into a Figma Section named after that screen, for example `Dashboard`.
+- Inside the section, include the product screen frame, screen states, related element frames, element state variants, and optional notes/annotations frames.
+- Name screen frames with clear state suffixes when needed, for example `Dashboard - Default`, `Dashboard - Empty`, `Dashboard - Error`.
+- Name element frames with the parent and element name, for example `Dashboard / Revenue Card - Loading`.
+- Name service notes frames as `Notes / Annotations` or `Notes / <screen name>`.
+- Use `Shared Elements` only for reusable elements explicitly marked as shared in the UX spec.
+
+## Product Screen Frame Purity
+
+- Product screen frames contain only UI that belongs in the final product.
+- Do not place blueprint metadata, requirement chips, citations, UX rules, implementation notes, traceability, comments, or explanatory cards inside product screen frames.
+- If traceability or rationale must be visible in Figma, create a separate notes/annotations frame in the same Section, outside the product screen frame.
+- Notes/annotations are not `screen` or `element` content. Track their node IDs separately in `figma_build_manifest.annotation_node_ids`.
+- During validation, inspect screen frame descendants and remove or move nodes whose purpose is metadata, annotation, comment, citation, requirement trace, or UX rule.
+
+## Multiflow
+
+- If the system has two or more roles or two or more applications with different accessible screen sets, create a separate Figma page for each role/application.
+- Each role/application page must contain the full set of screens available to that role/application, including shared screens.
+- Do not store all common screens on `User` and only role-specific extras on `Admin`. Duplicate shared screens into each role/application page so every page is independently reviewable.
+- Keep page names concise and role/application specific, for example `Admin`, `User`, `Back Office`, or `Client App`.
+
+## Creation Rules
+
+- Use native Figma MCP only for generation and edits.
+- Do not use black-box exports as the primary output.
+- Use `1440 x 800` as the default screen viewport, increasing height only when content requires it.
+- Prefer auto-layout for wrappers, sections, lists, forms, and repeated cards.
+- Use realistic text from the blueprint. Avoid "Lorem ipsum" and placeholder labels.
+- Represent main, empty, loading, and error states when required.
+- Keep visual style mid-fi: neutral surfaces, clear hierarchy, readable spacing, and strong layout semantics.
+
+## Edit Rules
+
+- Use `screen_id` and prior node IDs from `figma_build_manifest.json` to target edits.
+- Inspect current hierarchy before mutation.
+- Mutate only affected sections unless the blueprint changed the screen structure.
+- Preserve existing node IDs when practical.
+- Re-run screenshot validation only for changed screens plus any dependent overview screens.
+
+## Manifest Rules
+
+Write or update:
+
+- `file_key`
+- `page`
+- `screen_ids`
+- `created_node_ids`
+- `mutated_node_ids`
+- `annotation_node_ids`
+- `screenshots`
+- `validation_notes`
+- `known_issues`
+
+If a Figma write fails, do not invent node IDs. Record the blocker in `known_issues` and keep the manifest consistent.
@@ -0,0 +1,11 @@
+interface:
+  display_name: "Figma Wireframe Builder"
+  short_description: "Build editable mid-fi Figma wireframes"
+  default_prompt: "Use $figma-wireframe-builder to build editable Figma wireframes from the screen blueprints."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "figma"
+      description: "Native Figma MCP tools for file inspection, writing, and screenshots"
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,14 @@
+# Mid-Fi Wireframe Primitives
+
+Use these primitives when no design system component is available.
+
+- App shell: vertical frame with top navigation and content region.
+- Sidebar: 240-280px fixed navigation with active item state.
+- Data table: header row, 5-8 sample rows, filters, pagination/status.
+- Form: labeled fields, helper text, validation row, primary/secondary actions.
+- Empty state: title, short reason, primary action.
+- Loading state: skeleton rows or blocks that preserve layout dimensions.
+- Error state: inline error text plus recovery action.
+- Status card: label, metric/value, trend/status, supporting caption.
+
+Use neutral colors, 8px or smaller radii, and readable typography. Keep the design quiet and task-oriented for SaaS, CRM, admin, and operational products.
@@ -0,0 +1,57 @@
+---
+name: ux-constructor
+description: Create UX architecture, information architecture, user flows, screen inventory, UX decisions, research citations, acceptance criteria, and screen blueprints from a normalized product model. Use when Codex needs evidence-based UX planning before Figma wireframe generation, including citation-backed UX rationale and editable screen_blueprints.
+---
+
+# UX Constructor
+
+Convert `normalized_project.json` into `ux_spec.json`, `ux_spec.summary.md`, and `screen_blueprints.json`.
+
+## Load First
+
+- `.agents/skills/_shared/references/artifact-contracts.md`
+- `.agents/skills/_shared/references/ux-research-policy.md`
+- `.agents/skills/_shared/references/ux-research-registry.json`
+- `.agents/skills/_shared/references/quality-gates.md`
+
+## Workflow
+
+1. Read `workspace/artifacts/wireframe-gen/normalized_project.json` and `normalized_project.summary.md`.
+2. Run the pre-UX open question gate:
+   `powershell -File scripts/wireframe/validate-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen -Stage pre-ux`
+3. Stop and return unresolved blocking questions to the coordinator if the gate fails.
+4. Identify primary audiences, actors, jobs, goals, constraints, risks, and open questions.
+5. Create information architecture and user flows that cover the core functional modules.
+6. Create `screen_inventory` with stable `screen_id` values.
+7. For each screen, define purpose, main user intent, content priorities, states, and acceptance criteria.
+8. Use the curated UX registry first. If it lacks a relevant source, do live web research from authoritative sources, then update the registry with `scripts/wireframe/update-research-registry.ps1`.
+9. Write `ux_spec.json` using the shared contract and citations.
+10. Write `screen_blueprints.json` as an array of build-ready screen plans.
+11. Write `ux_spec.summary.md` in Russian, including unresolved user decisions.
+12. Validate:
+    `powershell -File scripts/wireframe/validate-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen`
+
+## UX Decision Rules
+
+- Ground each screen in a requirement, user goal, or explicit assumption.
+- Prefer proven, boring UX patterns for operational tools: clear navigation, dense but readable layouts, visible status, good empty/error/loading states.
+- Do not turn UX research into generic decoration. Cite only claims that directly support the decision.
+- Keep flows implementation-ready: actor, trigger, steps, success outcome, failure/edge states.
+- Put unresolved product choices into `open_questions` or `decision_log.md`; do not decide business policy without evidence.
+
+## Blueprint Rules
+
+- Use mid-fi fidelity: real information architecture, realistic content labels, clear components, and states without final visual polish.
+- Include `content_type` in every blueprint: `screen` for full screens and `element` for bounded UI elements.
+- Include desktop viewport by default for screens: `{ "width": 1440, "height": 800 }`.
+- Increase screen height above `800` only when the content requires more vertical space.
+- For element blueprints, include `element_id`, `parent_screen_id`, and `bounds`.
+- Add mobile blueprint variants only when source docs or user request require mobile UX decisions.
+- Include `empty_error_loading_states` for data-heavy screens, forms, and async flows.
+
+## Output Quality Gate
+
+- Every screen maps to at least one normalized requirement or assumption.
+- Every major UX decision has `research_citations`, `source_refs`, or an explicit assumption.
+- `screen_blueprints.json` has no placeholder-only screens.
+- Acceptance criteria are observable in the future Figma output.
@@ -0,0 +1,6 @@
+interface:
+  display_name: "UX Constructor"
+  short_description: "Create cited UX specs and blueprints"
+  default_prompt: "Use $ux-constructor to create UX architecture and screen blueprints from the normalized project."
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,35 @@
+# UX Spec Patterns
+
+Use these patterns for `ux_spec.json`.
+
+## Flow
+
+```json
+{
+  "id": "FLOW-001",
+  "name": "Create project from documentation",
+  "actor_id": "ACT-001",
+  "trigger": "User starts a new wireframe project",
+  "steps": [
+    "Upload or select source documentation",
+    "Review normalized project summary",
+    "Confirm open questions",
+    "Generate UX screen blueprints"
+  ],
+  "success_outcome": "Project has validated screen blueprints",
+  "failure_states": ["unsupported_source", "missing_business_decision"]
+}
+```
+
+## UX Decision
+
+```json
+{
+  "id": "UXD-001",
+  "decision": "Use a step-by-step review flow before Figma generation.",
+  "rationale": "The system must expose unresolved documentation gaps before creating screens.",
+  "source_refs": ["REQ-004", "Q-002"],
+  "citation_ids": ["nng-heuristics"],
+  "impacts": ["screen-project-review", "screen-generation-status"]
+}
+```
@@ -0,0 +1,84 @@
+---
+name: wireframe-coordinator
+description: Coordinate the full hybrid wireframe generation workflow between the user, documentation-normalizer, ux-constructor, and figma-wireframe-builder. Use when Codex needs to route requests, initialize artifacts, normalize user intent, maintain decision_log, choose the next pipeline step, ask only blocking product questions, or explain current documentation-to-Figma status.
+---
+
+# Wireframe Coordinator
+
+Route user requests through the documentation-to-wireframe pipeline.
+
+## Load First
+
+- `.agents/skills/_shared/references/artifact-contracts.md`
+- `.agents/skills/_shared/references/quality-gates.md`
+- `.agents/skills/_shared/references/alternative-landscape.md` when explaining market positioning or design choices.
+
+## Request Routing
+
+- New project or new docs: invoke `documentation-normalizer`.
+- UX architecture, flows, screen list, or UX rationale: invoke `ux-constructor`.
+- Create or update Figma screens: invoke `figma-wireframe-builder`.
+- Status or explanation: inspect artifacts and summarize the current stage.
+- Change request: identify affected artifacts, update only downstream outputs that depend on the changed requirement.
+
+## Workflow
+
+1. Initialize artifacts:
+   `powershell -File scripts/wireframe/init-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen`
+2. Read existing artifacts to determine current stage.
+3. Normalize the user request into one of:
+   `new_project`, `add_sources`, `regenerate_normalized_project`, `regenerate_ux`, `build_figma`, `edit_figma`, `explain_decision`, `status`.
+4. Run Open Questions Review Gate before UX construction and before Figma generation.
+5. Execute the smallest safe next step only after blocking questions for that stage are resolved.
+6. Update `decision_log.md` with user decisions, assumptions, and blockers.
+7. Validate artifacts after each generation/update step.
+
+## Open Questions Review Gate
+
+Open questions are surfaced in dialogue. Do not silently continue when unresolved blocking questions exist.
+
+Run stage validation before UX construction:
+
+```powershell
+powershell -File scripts/wireframe/validate-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen -Stage pre-ux
+```
+
+Run stage validation before Figma generation:
+
+```powershell
+powershell -File scripts/wireframe/validate-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen -Stage pre-figma
+```
+
+When the gate blocks, show the user:
+
+- question ID and question text;
+- why it blocks the stage;
+- affected artifact or stage;
+- available default assumption if present;
+- requested answer format.
+
+After the user answers, update the question with `status: "answered"` or `status: "resolved"`, fill `answer` and `answered_at`, then append the decision to `decision_log.md`.
+
+## Decision Log Format
+
+Append entries like:
+
+```markdown
+## 2026-05-03T12:00:00Z - Decision
+
+- Request: Build first Figma wireframes.
+- Decision: Use native Figma MCP and mid-fi fidelity.
+- Affected artifacts: screen_blueprints.json, figma_build_manifest.json.
+- Source: user.
+```
+
+## Coordination Rules
+
+- Prefer local artifacts over conversation memory.
+- Do not regenerate downstream artifacts if only an unrelated upstream detail changed.
+- Keep unresolved product or Figma target questions explicit.
+- Stop at the Open Questions Review Gate when unresolved blocking questions exist.
+- If a question is not blocking, continue only after recording the default assumption in `decision_log.md`.
+- Keep schema keys in English and summaries in Russian by default.
+- Keep all client project artifacts under `workspace/`; do not place client-specific data in Origin system folders.
+- Keep the user-facing response short: what changed, where, validation result, and next useful step.
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Wireframe Coordinator"
+  short_description: "Route docs-to-Figma wireframe work"
+  default_prompt: "Use $wireframe-coordinator to run the documentation-to-Figma wireframe workflow."
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,12 @@
+# Routing Table
+
+| User intent | Required artifact state | Next skill |
+| --- | --- | --- |
+| "Here are docs" | Any | documentation-normalizer |
+| "Create UX architecture" | normalized_project exists | ux-constructor |
+| "Generate Figma wireframes" | screen_blueprints exists | figma-wireframe-builder |
+| "Edit this generated screen" | figma_build_manifest exists | figma-wireframe-builder |
+| "Why this UX decision?" | ux_spec exists | ux-constructor |
+| "What is the status?" | Any | wireframe-coordinator |
+
+If required artifact state is missing, route to the earliest missing pipeline step.