@juancr11/sibu 0.3.0 → 0.4.1

package/bin/shared/catalog.js

@@ -103,7 +103,7 @@ export const SELECTABLE_FRAMEWORK_SKILLS = [
         id: 'react',
         name: 'React',
         description: 'Install guidance for React components, props, state ownership, and component boundaries',
-        routingInstruction: 'For tasks that create or change React components, component responsibility, props, state ownership, or presentational vs data-owning boundaries, use `react`.',
+        routingInstruction: 'For React component changes involving responsibility, props, state ownership, or presentational/data-owning boundaries, use `react`.',
         templateRelativePath: 'skills/react/SKILL.md',
         targetRelativePathsByAgent: {
             codex: '.agents/skills/react/SKILL.md',
@@ -116,7 +116,7 @@ export const SELECTABLE_FRAMEWORK_SKILLS = [
         id: 'nextjs',
         name: 'Next.js',
         description: 'Install guidance for Next.js App Router and framework-specific files',
-        routingInstruction: 'For tasks that change Next.js App Router or framework-specific files, including `src/app/**`, pages, layouts, route handlers, loading/error/not-found files, metadata, or Server/Client Component boundaries, use `nextjs`.',
+        routingInstruction: 'For Next.js App Router or framework-specific changes—`src/app/**`, pages, layouts, route handlers, loading/error/not-found files, metadata, or Server/Client boundaries—use `nextjs`.',
         templateRelativePath: 'skills/nextjs/SKILL.md',
         targetRelativePathsByAgent: {
             codex: '.agents/skills/nextjs/SKILL.md',
@@ -131,7 +131,7 @@ export const SELECTABLE_ARCHITECTURE_SKILLS = [
         id: 'ddd-hexagonal',
         name: 'DDD + Hexagonal Architecture',
         description: 'Install back-end architecture guidance for DDD, ports/adapters, and inward dependencies',
-        routingInstruction: 'For any back-end work, use `ddd-hexagonal`. This includes new features, refactors, bug fixes, persistence, external integrations, application/service boundaries, domain modeling, and architectural tradeoffs.',
+        routingInstruction: 'For backend features, refactors, bug fixes, persistence, external integrations, application/service boundaries, domain modeling, or architectural tradeoffs, use `ddd-hexagonal`.',
         templateRelativePath: 'skills/architecture/ddd-hexagonal/SKILL.md',
         targetRelativePathsByAgent: {
             codex: '.agents/skills/ddd-hexagonal/SKILL.md',
@@ -159,7 +159,7 @@ export const SELECTABLE_WORKFLOW_SKILLS = [
         id: 'ai-prompt-engineer-master',
         name: 'AI Prompt Engineer Master',
         description: 'Install guidance for creating, rewriting, optimizing, compressing, and evaluating AI prompts',
-        routingInstruction: 'For requests to create, rewrite, optimize, compress, evaluate, or systematize prompts for AI models, agents, tools, coding assistants, product workflows, or reusable prompt templates, use `ai-prompt-engineer-master`.',
+        routingInstruction: 'For prompt creation, rewriting, optimization, compression, evaluation, or reusable templates for AI models, agents, tools, coding assistants, or product workflows, use `ai-prompt-engineer-master`.',
         templateRelativePath: 'skills/ai-prompt-engineer-master/SKILL.md',
         targetRelativePathsByAgent: {
             codex: '.agents/skills/ai-prompt-engineer-master/SKILL.md',
@@ -168,6 +168,19 @@ export const SELECTABLE_WORKFLOW_SKILLS = [
             windsurf: '.agents/skills/ai-prompt-engineer-master/SKILL.md',
         },
     },
+    {
+        id: 'ux-expert',
+        name: 'UX Expert',
+        description: 'Install senior UX/UI guidance for UI-changing features, responsive layouts, flows, states, accessibility, and binding mockups',
+        routingInstruction: 'For UX/UI design after product definition for UI-changing features, use `ux-expert`; downstream design, planning, and implementation must treat `docs/features/<feature-slug>/ux.md` mockups as binding UI goals, not redesign targets.',
+        templateRelativePath: 'skills/ux-expert/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/ux-expert/SKILL.md',
+            gemini: '.agents/skills/ux-expert/SKILL.md',
+            claude: '.agents/skills/ux-expert/SKILL.md',
+            windsurf: '.agents/skills/ux-expert/SKILL.md',
+        },
+    },
 ];
 export const SUPPORTED_AGENTS = [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",

package/templates/AGENTS.md

@@ -49,13 +49,9 @@ At the start of each session in this repository, run `sibu doctor` once before m
 
 After `sibu doctor` finishes, guide the user based on the outcome:
 
-- If the workflow is healthy, mention that the Sibu check passed and proceed with the requested work.
-- If `.sibu/state.json` is missing because the project has not been initialized, tell the user to run `sibu init` once before continuing.
-- If managed workflow files are missing, unrecorded, modified, or generated from older templates, tell the user to run `sibu sync` to review and repair them.
-- If `sibu doctor` cannot run because Sibu is unavailable, tell the user how to install or run Sibu for this project before relying on template status.
+- Healthy workflow: mention that the Sibu check passed and proceed.
+- Missing `.sibu/state.json`: tell the user to run `sibu init` once before continuing.
+- Missing, unrecorded, modified, or older managed files: tell the user to run `sibu sync` to review and repair them.
+- Sibu unavailable: tell the user how to install or run Sibu before relying on template status.
 
 Sibu records managed workflow file metadata in `.sibu/state.json`, including template versions, file hashes, selected agent support, and whether files are `managed`, `customized`, or `unmanaged`.
-
-If `.sibu/state.json` is missing because Sibu has not been adopted in the project, ask the user to run `sibu init` once.
-If workflow files may be missing, modified, unrecorded, or drifted from the recorded Sibu state, ask the user to run `sibu doctor` first.
-If `sibu doctor` reports missing managed files, unrecorded expected files, local edits, or older templates, ask the user to run `sibu sync`.

package/templates/manifest.json

@@ -1,12 +1,11 @@
 {
-  "templateVersion": "46",
+  "templateVersion": "49",
   "templates": {
     "AGENTS.md": {
-      "version": "20",
+      "version": "21",
       "description": "Project-level agent instructions and Sibu maintenance guidance.",
       "changes": [
-        "Routes User Story implementation requests to the AI implementation plan executor, even when the story plan may still be missing.",
-        "Clarifies that the executor should direct users to the AI implementation planner when a User Story has no implementation plan."
+        "Tightens Sibu maintenance outcome guidance while preserving startup health checks, safety, confirmation, routing, and workflow repair instructions."
       ]
     },
     ".codex/config.toml": {
@@ -39,25 +38,24 @@
       ]
     },
     "skills/product-vision-writer/SKILL.md": {
-      "version": "3",
+      "version": "4",
       "description": "Mandatory product vision writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Changes product vision discovery to ask one question at a time so users can shape the vision through a focused interview instead of answering a large batch up front."
+        "Compresses discovery and drafting guidance while preserving one-question-at-a-time discovery, output location, incomplete-input handling, and product-vision quality expectations."
       ]
     },
     "skills/feature-brief-writer/SKILL.md": {
-      "version": "2",
+      "version": "3",
       "description": "Mandatory feature brief writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Clarifies that agents must not draft feature briefs from vague feature requests and should ask one focused discovery question at a time until the feature intent is clear.",
-        "Adds minimum context guidance so feature briefs are written only after the feature intent, target user or scenario, desired outcome, and rough MVP boundary are clear."
+        "Compresses feature-brief guidance while preserving product-vision grounding, vague-request stop behavior, minimum context requirements, and feature brief output location."
       ]
     },
     "skills/technical-design-writer/SKILL.md": {
-      "version": "8",
+      "version": "10",
       "description": "Mandatory technical design writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Updates the technical design examples to refer to the Sibu command names instead of the old Echo branding."
+        "Compresses technical-design wording while preserving required grounding, UX binding, delegation boundaries, output location, and smallest-useful-design guidance."
       ]
     },
     "skills/typescript/SKILL.md": {
@@ -103,35 +101,38 @@
       ]
     },
     "skills/scrum-master-planner/SKILL.md": {
-      "version": "2",
+      "version": "4",
       "description": "Mandatory Scrum planner skill for creating pragmatic Epics and User Stories from approved feature and technical design docs.",
       "changes": [
-        "Moves Scrum User Stories into an Epic-local stories/ folder.",
-        "Adds two-digit execution-order filename prefixes for User Stories, with shared numbers indicating parallelizable work."
+        "Compresses Scrum planning guidance while preserving required inputs, pragmatic story splitting, output paths, sequencing rules, and UX mockup binding."
       ]
     },
     "skills/ai-implementation-planner/SKILL.md": {
-      "version": "4",
+      "version": "6",
       "description": "Mandatory AI implementation planner skill for turning one approved User Story into small, story-local implementation step files.",
       "changes": [
-        "Changes AI implementation planner step files to use lowercase .md extensions.",
-        "Updates the step-file format to use Markdown headings for Step, Goal, Scope, Files, and Done when sections."
+        "Compresses implementation-planning guidance while preserving exact story input requirements, source context, output path conventions, step-file format, and plan-quality checks."
       ]
     },
     "skills/ai-implementation-plan-executor/SKILL.md": {
-      "version": "5",
+      "version": "8",
       "description": "Mandatory AI implementation plan executor skill for implementing existing story implementation plans one reviewed step at a time.",
       "changes": [
-        "Clarifies that missing story implementation plans must be created with the AI implementation planner before execution.",
-        "Allows agents to begin the first unapproved implementation step immediately when a valid plan exists, while preserving review approval between steps.",
-        "Clarifies that after user approval, agents should mark the step approved, commit it, and continue to the next step without another pre-implementation confirmation."
+        "Adds context reuse guidance so story implementation plans load broad context once, then continue step-by-step using cached context unless scope, validation, or file changes require rereading."
       ]
     },
     "skills/ai-prompt-engineer-master/SKILL.md": {
-      "version": "1",
+      "version": "2",
       "description": "Selectable AI prompt engineering skill for prompt creation, optimization, compression, and evaluation.",
       "changes": [
-        "Adds an optional AI prompt engineering skill for projects that create, improve, evaluate, or maintain reusable prompts for AI models, agents, tools, and coding assistants."
+        "Compresses the prompt quality checklist while preserving quality-first token discipline, missing-context behavior, output pattern, and prompt verification guidance."
+      ]
+    },
+    "skills/ux-expert/SKILL.md": {
+      "version": "2",
+      "description": "Selectable UX expert skill for UI-changing features, responsive design, flows, states, accessibility, and binding mockups.",
+      "changes": [
+        "Compresses UX guidance while preserving product grounding, no-code boundary, phone-first design, output location, concrete mockup requirements, and binding downstream mockup authority."
       ]
     }
   }

package/templates/skills/ai-implementation-plan-executor/SKILL.md

@@ -7,9 +7,7 @@ description: Execute an existing ai-implementation-planner story implementation
 
 ## Purpose
 
-Execute one existing story implementation plan, one ordered step file at a time, with human review between steps.
-
-This skill owns implementation execution from an existing `.impl_plan/` folder. It does not create implementation plans, change story scope, or skip user review gates.
+Execute one existing story implementation plan, one ordered step file at a time, with human review between steps. This skill owns execution from an existing `.impl_plan/` folder; it does not create plans, change story scope, or skip review gates.
 
 ## Required source context
 
@@ -25,7 +23,7 @@ or:
 docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl_plan/
 ```
 
-Before implementing any step, read:
+Before starting a story implementation plan, read once:
 
 ```txt
 docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.md
@@ -33,11 +31,16 @@ docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl
 docs/features/<feature-slug>/epics/<epic-slug>/epic_brief.md
 docs/features/<feature-slug>/feature_brief.md
 docs/features/<feature-slug>/technical_design.md
+docs/features/<feature-slug>/ux.md  # when the story, step, or feature has UI impact
 ```
 
 Also read `docs/product-vision.md` when product fit, target user, scope boundaries, or success signals are ambiguous.
 
-Before changing code, read and apply the implementation skills required by the plan and repository routing:
+If the story, any step, or feature has UI impact and `docs/features/<feature-slug>/ux.md` is missing, stop and ask the user to create the UX spec with `ux-expert` before implementation.
+
+When `ux.md` includes mockups, treat them as binding UI goals. Implementation must preserve the mockup structure, hierarchy, visible content, dominant interactions, major visual emphasis, and breakpoint-specific layout. Do not redesign the UI during execution; implement the approved UX and stop if technical constraints require a UX revision.
+
+Before the first implementation step that changes code, read and apply the implementation skills required by the plan and repository routing:
 
 - always read and apply `clean-code`
 - read and apply architecture skills when relevant, such as `command-pattern` or `ddd-hexagonal`
@@ -46,20 +49,26 @@ Before changing code, read and apply the implementation skills required by the p
 
 Inspect existing code, tests, scripts, and docs only as needed for the current step.
 
-## Hard start rule
+## Context reuse rule
 
-If the user provides a User Story file and the matching `.impl_plan/` folder does not exist, is empty, or has no ordered `.md` step files:
+At the start of a story implementation plan, read all required source context, relevant implementation skills, and all ordered step files once. Build a concise execution context summary and rely on it for the rest of the story.
 
-1. Stop.
-2. Tell the user the implementation plan is missing.
-3. Instruct the user to use `templates/skills/ai-implementation-planner/SKILL.md` to create the implementation plan first.
-4. Do not infer steps from the story or technical design.
+After each approved step, do not reread unchanged broad context before continuing. For the next step, inspect only:
+
+- the next step file if it was not already read
+- files changed by previous steps when needed
+- validation output
+- current `git status` and relevant diffs
+
+Reread broad source context only when scope changes, validation fails in a way that requires it, required context was missing, relevant source files changed outside the plan, or the user asks to reconsider direction.
+
+## Hard start rule
 
-If the user provides an `.impl_plan/` folder and it does not exist, is empty, or has no ordered `.md` step files:
+If the provided User Story has no matching `.impl_plan/`, or the provided `.impl_plan/` folder is missing, empty, or has no ordered `.md` step files:
 
 1. Stop.
 2. Tell the user the implementation plan is missing or invalid.
-3. Instruct the user to use `templates/skills/ai-implementation-planner/SKILL.md` to create or repair the implementation plan first.
+3. Instruct the user to use `templates/skills/ai-implementation-planner/SKILL.md` to create or repair it first.
 4. Do not infer steps from the story or technical design.
 
 If required source context is missing:

package/templates/skills/ai-implementation-planner/SKILL.md

@@ -7,9 +7,7 @@ description: Turn one approved User Story Markdown file into LLM-sized implement
 
 ## Purpose
 
-Turn one approved User Story into a set of concrete Markdown step files an AI coding agent can execute to complete the story safely and completely.
-
-This skill owns implementation planning for one story at a time. It does not own product scope, technical design decisions, Scrum planning, or code implementation.
+Turn one approved User Story into concrete Markdown step files an AI coding agent can execute safely and completely. This skill owns implementation planning for one story at a time, not product scope, technical design decisions, Scrum planning, or code implementation.
 
 ## Required input
 
@@ -30,10 +28,15 @@ docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.md
 docs/features/<feature-slug>/epics/<epic-slug>/epic_brief.md
 docs/features/<feature-slug>/feature_brief.md
 docs/features/<feature-slug>/technical_design.md
+docs/features/<feature-slug>/ux.md  # when the story or feature has UI impact
 ```
 
 Also read `docs/product-vision.md` when product fit, target user, scope boundaries, or success signals are ambiguous.
 
+If the story or feature has UI impact and `docs/features/<feature-slug>/ux.md` is missing, stop and ask the user to create the UX spec with `ux-expert` before implementation planning.
+
+When `ux.md` includes mockups, treat them as binding UI goals. Implementation steps must preserve the mockup structure, hierarchy, visible content, dominant interactions, major visual emphasis, and breakpoint-specific layout. Do not redesign the UI in the implementation plan; plan code steps that implement the approved UX and stop if technical constraints require a UX revision.
+
 Before writing the step files, read and apply the required planning skills as source context:
 
 - always read and apply `clean-code`
@@ -88,9 +91,7 @@ File naming rules:
 
 ## Planning rules
 
-Create pragmatic implementation step files, not a second technical design.
-
-Each step file must be a concrete implementation step, not a discovery, scope-confirmation, or generic review step. The skill performs source reading and targeted inspection before writing the step files; each step tells the AI what to change, where to change it, how to implement it at a high level, and how to know that step is done.
+Create pragmatic implementation step files, not a second technical design. Each step must be concrete—not discovery, scope confirmation, or generic review—and tell the AI what to change, where, at what high level, and how to know it is done.
 
 Do:
 
@@ -139,7 +140,7 @@ From the technical design, identify:
 
 ### 3. Inspect the repository narrowly
 
-Inspect only the files and commands needed to make the checklist actionable. Useful targets include:
+Inspect only files and commands needed to make the checklist actionable, such as:
 
 - existing feature folders or handlers related to the story
 - entrypoints or command wiring mentioned by the technical design

package/templates/skills/ai-prompt-engineer-master/SKILL.md

@@ -48,16 +48,7 @@ Do not trade quality away for fewer tokens. First define the quality bar, then f
 
 ## Prompt quality checklist
 
-A strong prompt usually has:
-
-- **Role or perspective** only when it changes behavior.
-- **Task** stated as a concrete outcome.
-- **Context** limited to information the model needs.
-- **Constraints** that prevent real failures.
-- **Output format** specific enough for the consumer.
-- **Missing-context behavior** so the model does not invent facts.
-- **Tone/style** only when user-facing quality depends on it.
-- **Validation criteria** for important workflows.
+A strong prompt usually has: role only when useful, a concrete task, necessary context, failure-preventing constraints, sufficient output format, missing-context behavior, user-facing tone only when needed, and validation criteria for important workflows.
 
 ## Token discipline rules
 

package/templates/skills/feature-brief-writer/SKILL.md

@@ -7,9 +7,7 @@ description: Use this skill to define business-level feature briefs that stay lo
 
 ## Purpose
 
-Create concise feature briefs that explain what a feature is, why it matters, who it serves, and how it follows the product vision required by this skill.
-
-Every feature shaped with this skill must stay loyal to `docs/product-vision.md`: it should support the product's purpose, fit its intended audience, respect its boundaries, and move in the same direction as its success signals.
+Create concise feature briefs that explain what a feature is, why it matters, who it serves, and how it follows `docs/product-vision.md`: purpose, audience, boundaries, and success signals.
 
 This skill owns the product/business shape of a feature. It does not own UI interaction design, technical architecture, implementation plans, data models, APIs, or task breakdowns.
 
@@ -92,9 +90,7 @@ Do not ask the user to answer a large questionnaire all at once. Keep the interv
 
 ### 3. Gather the minimum required feature context
 
-Ask only for missing information that materially affects the brief. Prefer the fewest questions needed to produce a useful document, but ask as many one-at-a-time questions as needed when the feature is underdefined.
-
-Clarify:
+Ask only for missing information that materially affects the brief. Use as few questions as possible, one at a time when underdefined. Clarify:
 
 - what feature or capability the user wants
 - what the user means by broad labels such as MVP, onboarding, sync, analytics, or automation
@@ -106,7 +102,7 @@ Clarify:
 - what should stay out of scope
 - known constraints, risks, or open decisions
 
-Only move to drafting once the feature intent, target user or scenario, desired outcome, and rough MVP boundary are clear enough to avoid inventing the product direction.
+Draft only once feature intent, target user/scenario, desired outcome, and rough MVP boundary are clear enough to avoid invention.
 
 ### 4. Write a business-level brief
 

package/templates/skills/product-vision-writer/SKILL.md

@@ -15,13 +15,7 @@ Default output path: `docs/product-vision.md`.
 
 ### 1. Start with discovery, not drafting
 
-Ask focused questions before writing the document unless the user has already provided enough source material.
-
-Ask one question at a time. Wait for the user's answer before asking the next discovery question.
-
-Prefer the fewest questions that can produce a useful document. Ask follow-ups only when an answer materially changes the document or when a critical input is missing.
-
-Cover these areas over the course of the interview:
+Ask focused questions before writing unless the user already provided enough source material. Ask one question at a time and use the fewest questions that can produce a useful document. Cover these areas over the interview:
 
 - **Product essence:** What is the product? What should it help people do, feel, or become?
 - **Current context:** Is this a new concept, an active project, or an existing product?
@@ -52,9 +46,7 @@ If the user's answers conflict, resolve the conflict explicitly in the draft by
 
 ### 3. Draft the product vision document
 
-Write in Markdown. Use clear headings, short paragraphs, and bullets where they improve readability.
-
-Recommended structure:
+Write in Markdown with clear headings, short paragraphs, and useful bullets. Recommended structure:
 
 ```markdown
 # <Product Name> Product Vision
@@ -107,11 +99,7 @@ Use the user's own language when it is vivid or revealing. Improve clarity witho
 
 ### 5. Handle incomplete inputs
 
-If the user has only a rough idea, produce a sharper first-pass vision with clearly stated assumptions.
-
-If the user has an existing product, make the document reflect what the product is today and what it must protect or change.
-
-If there is not enough context to write responsibly, ask the smallest possible follow-up question set instead of inventing details.
+For rough ideas, produce a sharper first-pass vision with clear assumptions. For existing products, reflect what the product is today and what it must protect or change. If context is still insufficient, ask the smallest useful follow-up instead of inventing details.
 
 ### 6. Save the document
 

package/templates/skills/scrum-master-planner/SKILL.md

@@ -18,10 +18,15 @@ Before planning, read:
 ```txt
 docs/features/<feature-slug>/feature_brief.md
 docs/features/<feature-slug>/technical_design.md
+docs/features/<feature-slug>/ux.md  # when the feature has UI impact
 ```
 
 Also read `docs/product-vision.md` when it exists and the planning decision depends on product fit, scope boundaries, user value, or success signals.
 
+If the feature has UI impact and `docs/features/<feature-slug>/ux.md` is missing, stop and ask the user to create the UX spec with `ux-expert` before Scrum planning.
+
+When `ux.md` includes mockups, treat them as binding UI goals. Epics and Stories must preserve the mockup structure, hierarchy, visible content, dominant interactions, major visual emphasis, and breakpoint-specific layout. Do not redesign the UI in Scrum planning; create delivery slices that implement the approved UX.
+
 ## Hard start rule
 
 Do not create Epics or User Stories if either the feature brief or technical design is missing.
@@ -59,11 +64,7 @@ Rules:
 
 ## Planning rule
 
-Create the smallest useful planning structure.
-
-If one Epic with one User Story fully captures the work, create one Epic and one User Story. Add more Epics or User Stories only when there are meaningfully distinct outcomes, delivery slices, risks, dependencies, validation paths, or contributor ownership boundaries.
-
-Avoid Agile theater. Do not create multiple Epics or Stories just because Scrum artifacts usually appear in groups.
+Create the smallest useful planning structure. Use one Epic and one User Story when that fully captures the work. Add more only for distinct outcomes, delivery slices, risks, dependencies, validation paths, or contributor ownership boundaries. Avoid Agile theater.
 
 ## Workflow
 
@@ -134,7 +135,7 @@ Adapt headings only when it improves clarity. Keep the Epic brief short.
 
 Within each Epic, decide the order of execution before writing User Story files. Use the lowest practical sequence number for the first story that should be implemented, then increment only when later stories depend on earlier work. If two or more stories can be developed at the same time, give them the same order number.
 
-Each User Story should be independently understandable and should represent a reviewable slice of work.
+Each User Story should be independently understandable and reviewable.
 
 Use this structure:
 

package/templates/skills/technical-design-writer/SKILL.md

@@ -5,9 +5,7 @@ description: Use this skill to turn an approved feature brief into a concise, im
 
 # technical-design-writer
 
-Write the smallest useful technical design doc for an approved feature.
-
-The doc should help a human say, “cool, I understand the implementation direction,” and help a later coding agent say, “nice, I know what to do next.” Avoid filler, generic engineering advice, and restating other skills.
+Write the smallest useful technical design doc for an approved feature: enough for a human to understand the implementation direction and a later coding agent to know what to do next. Avoid filler, generic engineering advice, and restating other skills.
 
 ## Grounding
 
@@ -15,9 +13,10 @@ Before writing, read:
 
 1. `docs/product-vision.md`
 2. the feature brief
-3. `clean-code`
-4. any selected architecture, language, or framework skills that apply
-5. relevant existing repo files and flows
+3. `docs/features/<feature-slug>/ux.md` when the feature has UI impact
+4. `clean-code`
+5. any selected architecture, language, or framework skills that apply
+6. relevant existing repo files and flows
 
 Apply those inputs. Do not summarize them back into the technical design unless a specific implication changes the implementation.
 
@@ -25,7 +24,11 @@ Apply those inputs. Do not summarize them back into the technical design unless
 
 Require a Markdown feature brief. If the user only has a vague idea, route to `feature-brief-writer` first.
 
-If the feature has UI impact, use an existing UX artifact when available. If missing, note the UI uncertainty briefly instead of inventing UX.
+If the feature has UI impact, require `docs/features/<feature-slug>/ux.md`. If it is missing, stop and ask the user to create the UX spec with `ux-expert` first.
+
+## UX binding rule
+
+For UI-related features, `ux.md` is source context, not inspiration. If `ux.md` includes mockups, treat those mockups as binding UI goals for structure, hierarchy, visible content, dominant interactions, major visual emphasis, and breakpoint-specific layout. Do not redesign the mockups in the technical design. Translate them into implementation direction and call out only technical feasibility issues, missing states, or conflicts that require UX revision.
 
 ## Design stance
 
@@ -78,7 +81,7 @@ Use the same kebab-case feature slug as the feature brief.
 
 ## Output format
 
-Use this structure as a starting point, not a contract. Delete sections that do not add value.
+Use this structure as a starting point. Delete sections that do not add value.
 
 ```md
 # Technical Design: <Feature Name>

package/templates/skills/ux-expert/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ux-expert
+description: Use this skill for UX/UI design after product definition when a feature has UI changes. Requires an approved Markdown product artifact (feature brief) that defines goals, scope, and acceptance criteria; if none exists, route to feature-brief-writer (and product-vision-writer if missing). Use for senior UX/UI direction, phone-first responsive design, breakpoint-specific layouts/components, user flows, information architecture, wireframes, concrete mockups, interaction states, accessibility, visual direction, creative UI concepts, and implementation-ready UI guidance.
+---
+
+# ux-expert
+
+Act as a senior UX/UI designer. Turn an approved product artifact into usable, expressive, phone-first, implementation-ready UI direction. Do not include code, file paths, architecture, or framework-specific guidance.
+
+## Required grounding
+
+Read `docs/product-vision.md` and apply only relevant implications: target user, principles, voice, boundaries, trust expectations, success signal. Do not restate the full vision.
+
+Require a product artifact such as `docs/features/<feature-slug>/feature_brief.md` that defines goal, scope, and acceptance criteria. If the user has only an idea, route to `feature-brief-writer` first. If the artifact says there is no UI impact, say so and do not invent UI work.
+
+## Mockup authority rule
+
+For UI-changing features, the UX artifact must include concrete mockups for affected screens, states, and breakpoints. Mockups are the source of truth for structure, hierarchy, visible content, dominant interactions, and major visual emphasis; downstream technical design, stories, implementation plans, and implementation must follow them unless this UX spec is revised. UX work is incomplete if a materially affected state/breakpoint lacks a mockup.
+
+## Confirmation behavior
+
+Creating/updating the Markdown UX artifact is not a code change. Write it without pre-change confirmation when the target is clear and requested. Ask only when context is missing, the target is ambiguous, overwrite/destruction is possible, or code changes are required.
+
+## UX principles
+
+Design for user experience first, component reuse second. Prefer clear task completion, strong hierarchy, obvious affordances/feedback/recovery, progressive disclosure, accessibility, resilient states, and distinctive but shippable UI. Avoid generic SaaS/page-builder layouts, decorative clarity loss, desktop-first thinking, product scope changes, and technical architecture decisions.
+
+## Phone-first responsive rule
+
+Design phone first, then re-evaluate tablet and desktop separately. Choose different layouts/components across breakpoints when they improve hierarchy, interaction, density, touch/pointer behavior, or content priority. Share components only when they remain the best experience.
+
+## Workflow
+
+1. Read product vision and feature brief.
+2. Identify affected UI surfaces and whether UI work is valid.
+3. Design phone-first flow, information architecture, and layout.
+4. Re-evaluate tablet and desktop independently.
+5. Define interaction states, failure/recovery behavior, accessibility requirements, and creative direction.
+6. Create concrete mockups for primary screens, affected breakpoints, and critical states.
+7. Write implementation-ready UX guidance only: flows, hierarchy, states, accessibility, visual direction.
+
+## Output location
+
+Write to `docs/features/<feature-slug>/ux.md` using the feature artifact slug. Keep same-feature artifacts together; do not write UX specs in product, technical design, story, or implementation-plan files.
+
+## Mockup requirements
+
+Mockups may be low fidelity but must be concrete: layout regions, visible content, hierarchy/emphasis, key controls, major state differences, and breakpoint changes. Use annotated text/box wireframes when enough. Show decisions downstream implementation must not improvise.
+
+## Output format
+
+Use only helpful sections from this shape:
+
+```md
+# UX Spec: <Feature Name>
+
+## Input Product Artifact
+## Product Vision Implications
+## UX Intent
+## Affected Surfaces
+## Phone-First User Flow
+## Information Architecture
+## Phone Layout
+## Tablet Layout
+## Desktop Layout
+## Binding Mockups
+### Phone
+```text
+<Annotated phone mockup>
+```
+
+### Tablet
+```text
+<Annotated tablet mockup>
+```
+
+### Desktop
+```text
+<Annotated desktop mockup>
+```
+## Breakpoint-Specific Component Strategy
+## Interaction States
+## Accessibility Requirements
+## Visual Direction
+## Creative Opportunities
+## Implementation Notes
+## UI Authority Rule
+## Open UX Questions
+```
+
+The Binding Mockups section is authoritative for downstream work unless this UX spec is revised.