@juancr11/sibu 0.3.0 → 0.4.0

package/bin/shared/catalog.js

@@ -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 when a feature has UI changes, use `ux-expert`; downstream technical design, Scrum planning, implementation planning, and implementation must treat mockups in `docs/features/<feature-slug>/ux.md` 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.0",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "templateVersion": "46",
+  "templateVersion": "47",
   "templates": {
     "AGENTS.md": {
       "version": "20",
@@ -54,10 +54,10 @@
       ]
     },
     "skills/technical-design-writer/SKILL.md": {
-      "version": "8",
+      "version": "9",
       "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."
+        "Requires UI-related technical designs to read ux.md and treat UX mockups as binding implementation goals instead of redesign targets."
       ]
     },
     "skills/typescript/SKILL.md": {
@@ -103,28 +103,24 @@
       ]
     },
     "skills/scrum-master-planner/SKILL.md": {
-      "version": "2",
+      "version": "3",
       "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."
+        "Requires UI-related Scrum planning to read ux.md and preserve binding mockups in Epics and User Stories."
       ]
     },
     "skills/ai-implementation-planner/SKILL.md": {
-      "version": "4",
+      "version": "5",
       "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."
+        "Requires UI-related implementation plans to read ux.md and turn binding mockups into implementation steps without redesigning them."
       ]
     },
     "skills/ai-implementation-plan-executor/SKILL.md": {
-      "version": "5",
+      "version": "6",
       "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."
+        "Requires UI-related implementation execution to read ux.md and implement binding mockups without redesigning them."
       ]
     },
     "skills/ai-prompt-engineer-master/SKILL.md": {
@@ -133,6 +129,13 @@
       "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."
       ]
+    },
+    "skills/ux-expert/SKILL.md": {
+      "version": "1",
+      "description": "Selectable UX expert skill for UI-changing features, responsive design, flows, states, accessibility, and binding mockups.",
+      "changes": [
+        "Adds an optional UX expert skill for UI-changing features, including implementation-ready UX guidance and binding mockups."
+      ]
     }
   }
 }

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

@@ -33,10 +33,15 @@ 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.
 
+If the story, current 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 changing code, read and apply the implementation skills required by the plan and repository routing:
 
 - always read and apply `clean-code`

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

@@ -30,10 +30,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`

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.

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

@@ -15,9 +15,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 +26,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
 

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

@@ -0,0 +1,93 @@
+---
+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 explicitly revised.
+
+If a materially affected state/breakpoint lacks a mockup, UX work is incomplete.
+
+## 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 as separate UX problems. Choose different layouts/components across breakpoints when that improves 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 and unambiguous: layout regions, visible content, hierarchy/emphasis, key controls, major state differences, and breakpoint changes. Use annotated text/box wireframes when enough. Show decisions that 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.