@juancr11/sibu 0.4.0 → 0.4.2

package/bin/shared/catalog.js

@@ -1,5 +1,8 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 export const SIBU_PACKAGE_NAME = '@juancr11/sibu';
-export const SIBU_VERSION = '0.1.0';
+export const SIBU_VERSION = readPackageVersion();
 export const STATE_RELATIVE_PATH = '.sibu/state.json';
 export const NPM_VERSION_LOOKUP_MODE_ENV = 'SIBU_NPM_LOOKUP_MODE';
 export const NPM_VERSION_OVERRIDE_ENV = 'SIBU_NPM_LATEST_VERSION';
@@ -103,7 +106,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 +119,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 +134,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 +162,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',
@@ -172,7 +175,7 @@ export const SELECTABLE_WORKFLOW_SKILLS = [
         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.',
+        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',
@@ -229,3 +232,14 @@ export function resolveSelectableSkillById(skillId) {
     }
     return { ok: false, message: `Unknown skill \`${skillId}\`. Run \`sibu skills list\` to see available skills.` };
 }
+function readPackageVersion() {
+    const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    if (!isPackageJsonWithVersion(packageJson)) {
+        throw new Error(`Could not read Sibu version from ${packageJsonPath}.`);
+    }
+    return packageJson.version;
+}
+function isPackageJsonWithVersion(value) {
+    return Boolean(value && typeof value === 'object' && typeof value.version === 'string');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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": "47",
+  "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": "9",
+      "version": "10",
       "description": "Mandatory technical design writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Requires UI-related technical designs to read ux.md and treat UX mockups as binding implementation goals instead of redesign targets."
+        "Compresses technical-design wording while preserving required grounding, UX binding, delegation boundaries, output location, and smallest-useful-design guidance."
       ]
     },
     "skills/typescript/SKILL.md": {
@@ -103,38 +101,38 @@
       ]
     },
     "skills/scrum-master-planner/SKILL.md": {
-      "version": "3",
+      "version": "4",
       "description": "Mandatory Scrum planner skill for creating pragmatic Epics and User Stories from approved feature and technical design docs.",
       "changes": [
-        "Requires UI-related Scrum planning to read ux.md and preserve binding mockups in Epics and User Stories."
+        "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": "5",
+      "version": "6",
       "description": "Mandatory AI implementation planner skill for turning one approved User Story into small, story-local implementation step files.",
       "changes": [
-        "Requires UI-related implementation plans to read ux.md and turn binding mockups into implementation steps without redesigning them."
+        "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": "6",
+      "version": "8",
       "description": "Mandatory AI implementation plan executor skill for implementing existing story implementation plans one reviewed step at a time.",
       "changes": [
-        "Requires UI-related implementation execution to read ux.md and implement binding mockups without redesigning them."
+        "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": "1",
+      "version": "2",
       "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."
+        "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
@@ -38,11 +36,11 @@ docs/features/<feature-slug>/ux.md  # when the story, step, or feature has UI im
 
 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.
+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 changing code, read and apply the implementation skills required by the plan and repository routing:
+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`
@@ -51,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
 
@@ -93,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:
 
@@ -144,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

@@ -64,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
 
@@ -139,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
 
@@ -83,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

@@ -15,9 +15,7 @@ Require a product artifact such as `docs/features/<feature-slug>/feature_brief.m
 
 ## 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.
+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
 
@@ -29,7 +27,7 @@ Design for user experience first, component reuse second. Prefer clear task comp
 
 ## 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.
+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
 
@@ -47,7 +45,7 @@ Write to `docs/features/<feature-slug>/ux.md` using the feature artifact slug. K
 
 ## 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.
+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