@juancr11/sibu 0.5.3 → 0.7.0

package/templates/skills/deep-module-map-writer/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: deep-module-map-writer
+description: Create or update docs/deep-module-map.md as a map of deep, complexity-hiding implementation modules before feature brief work.
+---
+
+# Deep Module Map Writer
+
+## Purpose
+
+Create or update `docs/deep-module-map.md`, a technical design map of deep implementation modules that downstream technical designs, feature briefs, and implementation plans use to decide where code work belongs.
+
+A Deep Module is primarily a technical design concept from software architecture: a module with a small, simple interface and a larger, more complex implementation hidden behind it. In this artifact, Deep Modules may align with product responsibilities, but their depth comes from technical abstraction and complexity hiding, not from being a product category, command, folder, service, or team boundary.
+
+This skill owns the Deep Module Map only. It does not own feature briefs, technical designs, user stories, implementation plans, production code, or the internal architecture used inside each module.
+
+## Pipeline Contract
+
+### What this skill needs
+
+- `docs/product-vision.md`.
+- Existing `docs/deep-module-map.md` when revising the map.
+- Enough user interview context to identify candidate technical modules, the simple interface each module should expose to the rest of the app, the complexity each module should hide, boundaries, scenarios, relationships, and cross-module rules.
+
+### What this skill writes
+
+- `docs/deep-module-map.md`.
+
+### When this skill stops
+
+- `docs/product-vision.md` is missing; tell the user to create it first with `product-vision-writer`.
+- The request belongs to another pipeline stage, such as feature brief, technical design, UX design, Scrum planning, implementation planning, or implementation execution.
+- User answers are still too vague to defend module depth, interfaces, hidden complexity, or boundaries; ask one focused question instead of drafting.
+
+### What this skill must not do
+
+- Do not create feature briefs, technical designs, UX specs, Epics, User Stories, implementation plans, or production code.
+- Do not choose a specific internal architecture, service split, database model, framework, or team ownership structure.
+- Do not ask for or require a final confirmation summary before writing once enough Deep Module Map information is available.
+- Do not invent Deep Modules without grounding them in the product vision, current system behavior, and user interview.
+- Do not treat a command, screen, helper, folder, data object, or technical layer as a Deep Module merely because it exists.
+
+## What a Deep Module is
+
+A Deep Module is a module whose interface is much simpler than its implementation.
+
+Use this mental model:
+
+```txt
+Deep Module = small/simple interface + substantial hidden implementation complexity
+Shallow Module = interface nearly as complex as the implementation it hides
+```
+
+A module can be a function, class, package, subsystem, CLI workflow, or top-level code area. Size alone does not make a module deep. A large module can be shallow if callers must understand many details to use it, and a small module can be deep if it creates useful semantic distance between caller intent and implementation details.
+
+For this map, identify deep modules that are useful as durable technical implementation boundaries. Product responsibilities can help discover them, but the module is only valid if it hides meaningful technical complexity behind a simpler interface. A good entry should answer:
+
+```txt
+What simple capability should the rest of the app be able to rely on, and what messy details should be hidden behind that capability?
+```
+
+A Deep Module is not automatically:
+
+- a one-off feature
+- a screen
+- a command
+- a workflow step
+- a generic technical bucket such as `utils`, `api`, `db`, `shared`, or `services`
+- a technical layer
+- a required DDD Bounded Context
+- a required service, package, database, or team boundary
+
+Good Deep Modules:
+
+- expose a small, stable interface to callers or neighboring modules
+- hide complex decisions, orchestration, data handling, validation, or edge cases
+- reduce how much other code must know
+- have clear semantic distance between the module name/interface and the internal work it performs
+- are stable enough to absorb related changes over time
+- are broad enough to own meaningful behavior and narrow enough that boundaries are defensible
+
+Use these tests:
+
+- If callers can say what they want without knowing how it is done, the module may be deep.
+- If the module hides several details that would otherwise leak into many callers, it may be deep.
+- If using the module requires understanding almost the same steps as implementing it, it is probably shallow.
+- If it only renames one obvious operation, it is probably shallow unless the name adds important semantic meaning for callers.
+- If it describes one command, page, database object, helper folder, or implementation mechanism, it is probably too small or too technical for this map.
+- If it only says "user control," "quality," "security," or another value that applies everywhere, it is probably a cross-module rule instead of a module.
+- If two candidates cannot explain what interface and hidden complexity they own differently, merge or rename them.
+- If future feature work would routinely ask "does this code belong here or there?", keep clarifying the boundary.
+
+## Required source of truth
+
+Before doing any Deep Module Map work, read:
+
+```txt
+docs/product-vision.md
+```
+
+Use the product vision as the source of truth for purpose, audience, positioning, principles, boundaries, trust expectations, and success signals.
+
+## Hard start rule
+
+Do not create or update a Deep Module Map if `docs/product-vision.md` is missing.
+
+If the product vision is missing:
+
+1. Stop.
+2. Tell the user that a Deep Module Map requires `docs/product-vision.md`.
+3. Instruct the user to create the product vision first with `product-vision-writer`.
+4. Do not draft, infer, or save a module map until the product vision exists.
+
+## Output location
+
+Write the map to:
+
+```txt
+docs/deep-module-map.md
+```
+
+This file is user-owned product and implementation-boundary content created or updated by this skill. It is not a Sibu-managed workflow template.
+
+## Interview posture
+
+Be deliberately interrogative before writing.
+
+- Ask one focused question at a time.
+- Ask as many one-at-a-time questions as needed to understand the app well enough to defend the map.
+- Do not rush to draft after a single answer unless the answer already makes interfaces, hidden complexity, boundaries, scenarios, and relationships clear.
+- Treat "enough context" as: candidate modules, suggested slugs, simple external interfaces, hidden implementation complexity, responsibilities, exclusions, scenarios, relationships, and cross-module rules are clear enough to defend.
+- Do not ask the user to name the Deep Modules up front. Most users do not know what the modules should be yet.
+- Extract modules by asking about caller intent, complexity that should be hidden, product jobs, decisions, promises, lifecycle moments, confusing boundaries, and where code should stay coherent over time.
+- Teach briefly as needed. If the user seems unsure, explain that a Deep Module hides a lot of implementation behind a simple interface, then ask the next question.
+- Do not create modules from vague labels without confirming what interface they expose and what complexity they hide.
+- If the conversation stalls, propose one concise assumption for the next unresolved point and ask the user to confirm or correct it.
+
+## Interview method
+
+Derive candidate modules from answers. Do not make the user design the map from scratch.
+
+Prefer questions like:
+
+- "What should the rest of the app be able to ask this area to do in one simple phrase?"
+- "What messy details should callers not need to know?"
+- "If this were a good abstraction, what would its small public interface look like conceptually?"
+- "What steps, checks, edge cases, or policies would be hidden behind that interface?"
+- "Where are callers currently forced to know too much?"
+- "What behavior changes for the same product reason and should stay together?"
+- "What decisions should this module own, and which decisions should it not own?"
+- "Where do you expect future implementation work to create boundary confusion?"
+- "Is this a deep module, or is it just a command/helper/folder that exposes nearly as much complexity as it hides?"
+- "If this behavior changed, what other modules would need to know?"
+- "What module slug would be clear in code without forcing a specific architecture?"
+
+Avoid questions like:
+
+- "What bounded contexts should we use?"
+- "What services should exist?"
+- "What database boundaries should exist?"
+- "What layers should this module have?"
+- "What framework structure do you want?"
+
+When a user gives a feature, command, screen, template, or technical mechanism, translate it into the possible deep abstraction it suggests and ask the user to confirm or correct the interface and hidden complexity.
+
+Example:
+
+```txt
+User: "sibu doctor checks for drift."
+Assistant: "That sounds like it may belong to a workflow health module. Its simple interface could be 'check workflow health,' while it hides state loading, manifest comparison, file hashing, missing-file detection, and update advice. Is that the right abstraction, or does it leak too much into sync/adoption?"
+```
+
+Ask enough follow-up to fill these fields for each module:
+
+- Module name
+- Suggested module slug
+- Simple interface / outside promise
+- Hidden complexity
+- Owns
+- Does not own
+- Key scenarios
+- Related modules
+- Boundary notes
+
+Also identify cross-module rules, especially values and policies that apply everywhere, such as user ownership, safety, transparency, local customization, quality, validation, and read-only vs mutating behavior.
+
+## Deep Module principles
+
+Deep Modules should be:
+
+- complexity-hiding abstractions with simple external interfaces
+- deep enough that callers do not need to understand internal orchestration, edge cases, or policies
+- technical design boundaries first, with product alignment used only where it helps explain why code changes together
+- durable enough to absorb related technical and product changes over time
+- named in language useful across technical design, implementation planning, feature briefs, and code organization
+- flexible internally so different projects can use layered, DDD, Hexagonal, command-oriented, MVC, functional, or other architectures inside them
+
+Avoid shallow modules based on one feature, screen, command, workflow step, database table, generic helper folder, technical layer, or thin wrapper around an obvious operation.
+
+## Workflow
+
+1. Read `docs/product-vision.md`.
+2. Read existing `docs/deep-module-map.md` if it exists.
+3. Ask one focused question at a time until the module direction is clear.
+4. Keep asking focused follow-up questions until the simple interface and hidden complexity of each candidate module are defensible.
+5. Write or update `docs/deep-module-map.md` once enough context is available.
+
+## Recommended map structure
+
+```md
+# Deep Module Map
+
+## Purpose
+<How this map guides technical design, feature briefs, and implementation boundaries.>
+
+## Modules
+
+### <Module Name>
+- Suggested module slug:
+- Simple interface / outside promise:
+- Hidden complexity:
+- Owns:
+- Does not own:
+- Key scenarios:
+- Related modules:
+- Boundary notes:
+
+## Cross-Module Rules
+- <Rules for work that spans modules or needs a new module.>
+```
+
+Adapt the structure when useful, but keep the map concise and module-focused. Do not omit the simple interface/outside promise or hidden complexity fields unless the user explicitly asks for another format.
+
+## Final response behavior
+
+After writing the file, final-answer with only the path created or updated:
+
+```txt
+docs/deep-module-map.md
+```
+
+Do not paste the map body, excerpt, outline, or section summaries unless the user explicitly asks for inline review in the current request.

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

@@ -11,21 +11,52 @@ Create concise feature briefs that explain what a feature is, why it matters, wh
 
 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.
 
+## Pipeline Contract
+
+### What this skill needs
+
+- `docs/product-vision.md`.
+- `docs/deep-module-map.md`.
+- Enough user-provided feature intent to define the feature problem, target user/scenario, business goal, MVP boundary, out-of-scope boundary, success signals, constraints, and Deep Module fit.
+
+### What this skill writes
+
+- `docs/features/<feature-slug>/feature_brief.md`.
+- The containing `docs/features/<feature-slug>/` directory when needed.
+
+### When this skill stops
+
+- `docs/product-vision.md` is missing; tell the user to create it first with `product-vision-writer`.
+- `docs/deep-module-map.md` is missing; tell the user to create it first with `deep-module-map-writer`.
+- The feature appears to require a new or changed Deep Module; direct the user back to `deep-module-map-writer`.
+- The request belongs to another pipeline stage, such as technical design, UX design, Scrum planning, implementation planning, or implementation execution.
+- Current-stage feature intent is unclear; ask one focused question at a time until enough information is available.
+
+### What this skill must not do
+
+- Do not create or update Deep Module Maps, technical designs, UX specs, Epics, User Stories, implementation plans, or production code.
+- Do not invent Deep Modules or use modules that are absent from `docs/deep-module-map.md`.
+- Do not require a final confirmation summary before writing once enough feature brief context is available.
+- Do not duplicate or rewrite the product vision; apply only the relevant implications to the feature.
+
 ## Required source of truth
 
 Before doing any feature-brief work, read:
 
 ```txt
 docs/product-vision.md
+docs/deep-module-map.md
 ```
 
 Use the product vision as the source of truth for the product's purpose, audience, positioning, principles, voice, boundaries, trust expectations, and success signals.
 
+Use the Deep Module Map as the source of truth for where feature work belongs. Deep Modules answer “where does this work belong?” Do not invent Deep Modules in a feature brief.
+
 Do not duplicate or rewrite the product vision inside the feature brief. Apply it to the specific feature being defined.
 
 ## Hard start rule
 
-Do not start a feature brief if `docs/product-vision.md` is missing.
+Do not start a feature brief if `docs/product-vision.md` or `docs/deep-module-map.md` is missing.
 
 If the product vision is missing:
 
@@ -34,6 +65,13 @@ If the product vision is missing:
 3. Instruct the user to create the product vision first with the `product-vision-writer` skill.
 4. Do not draft, infer, or save a feature brief until the product vision exists.
 
+If the Deep Module Map is missing:
+
+1. Stop.
+2. Tell the user that a feature brief requires `docs/deep-module-map.md`.
+3. Instruct the user to create the map first with the `deep-module-map-writer` skill.
+4. Do not draft, infer, or save a feature brief until the map exists.
+
 ## Use this skill for
 
 - defining a new feature at the business/product level
@@ -56,9 +94,21 @@ Use a short kebab-case feature slug that matches the feature name. Keep all arti
 
 Do not write the brief to technical design, UX, user story, implementation plan, or backlog files unless the user explicitly asks for a separate artifact after the feature brief exists.
 
+## Interview posture
+
+Be deliberately interrogative before drafting. The feature brief should reflect the user's intent, not the assistant's assumptions.
+
+- Ask one focused question at a time.
+- Keep asking until you have complete practical understanding and explicit user alignment.
+- Prefer follow-up questions over filling gaps with plausible invention.
+- Treat "100% understanding" as: feature intent, target user, scenario, user problem, business goal, MVP boundary, out-of-scope boundary, success signals, and known constraints are all clear enough to defend in the brief.
+- Treat "enough context" as: feature intent, target user/scenario, desired outcome, MVP boundary, out-of-scope boundary, success signals, constraints, and Deep Module fit are clear enough to defend in the brief.
+- If the user gives a partial answer, acknowledge the useful part and ask the next most important unresolved question.
+- Do not ask a large questionnaire all at once.
+
 ## Workflow
 
-### 1. Read the product vision
+### 1. Read the product vision and Deep Module Map
 
 Read `docs/product-vision.md` first and identify:
 
@@ -72,25 +122,40 @@ Read `docs/product-vision.md` first and identify:
 
 Use these as constraints for the feature brief.
 
-### 2. Clarify vague feature intent before drafting
+Then read `docs/deep-module-map.md` and identify which existing Deep Modules may own the requested feature. A feature brief must name one or more existing Deep Modules.
 
-Do not draft a feature brief from a vague request.
+If no existing Deep Module fits:
+
+1. Stop before drafting.
+2. Tell the user the feature appears to require a Deep Module Map update.
+3. Provide this suggested prompt, adapted to the user's feature:
+
+```txt
+Use deep-module-map-writer to update docs/deep-module-map.md for this feature: <feature summary>. Decide whether it belongs in an existing Deep Module or requires a new/changed module, then update the map only after confirming the responsibility boundary with me.
+```
+
+4. Do not draft, infer, or save a feature brief until the map is updated.
+
+### 2. Clarify feature intent before drafting
+
+Do not draft a feature brief from a vague or merely plausible request.
 
 A request is too vague when the user gives only a broad area, product milestone, theme, or label such as "define the MVP," "write the onboarding feature," "make a sync feature," or "I want analytics" without enough detail to know what the user actually means.
 
-When feature intent is vague:
+When feature intent is vague or incomplete:
 
 1. Stop before drafting.
 2. Explain briefly that the feature direction needs clarification before a responsible brief can be written.
 3. Ask one focused discovery question.
 4. Wait for the user's answer.
 5. Continue asking one question at a time until there is enough context to write a useful, product-vision-aligned brief.
+6. Draft once the missing information is clear enough to produce the feature brief.
 
 Do not ask the user to answer a large questionnaire all at once. Keep the interview conversational and focused.
 
 ### 3. Gather the minimum required feature context
 
-Ask only for missing information that materially affects the brief. Use as few questions as possible, one at a time when underdefined. Clarify:
+Ask every question needed to remove material ambiguity, but only one at a time. Clarify:
 
 - what feature or capability the user wants
 - what the user means by broad labels such as MVP, onboarding, sync, analytics, or automation
@@ -102,7 +167,9 @@ Ask only for missing information that materially affects the brief. Use as few q
 - what should stay out of scope
 - known constraints, risks, or open decisions
 
-Draft only once feature intent, target user/scenario, desired outcome, and rough MVP boundary are clear enough to avoid invention.
+Draft only once feature intent, target user/scenario, desired outcome, MVP boundary, out-of-scope boundary, success signals, constraints, and Deep Module fit are clear enough to avoid invention.
+
+If the conversation stalls, offer a concise default assumption for the next unresolved point and ask the user to confirm or correct it before proceeding.
 
 ### 4. Write a business-level brief
 
@@ -119,6 +186,9 @@ Recommended structure:
 ## Product Vision Fit
 <How this feature supports the product vision, principles, audience, or positioning.>
 
+## Deep Module
+<One or more existing Deep Modules from docs/deep-module-map.md that own this feature, with a brief fit rationale.>
+
 ## User / Customer Problem
 <The user need, pain, desire, or opportunity this feature addresses.>
 
@@ -181,6 +251,7 @@ If the file already exists, read it first. Treat the request as a revision when
 Aim for writing that is:
 
 - loyal to the required product vision
+- explicit about which existing Deep Modules own the feature
 - specific to the user's feature
 - grounded in the product vision
 - concise
@@ -194,6 +265,7 @@ Avoid:
 - vague benefits without user or business grounding
 - feature lists without rationale
 - drafting from vague feature labels without discovery
+- inventing new Deep Modules instead of stopping for a map update
 - inventing certainty where the product vision or user input is unresolved
 
 ## Decision rule
@@ -201,12 +273,13 @@ Avoid:
 When shaping a feature brief, prefer:
 
 1. alignment with `docs/product-vision.md`
-2. clear user value
-3. clear business or product outcome
-4. simple MVP scope
-5. honest boundaries and tradeoffs
-6. measurable success signals
-7. non-technical acceptance criteria
+2. fit with existing Deep Modules from `docs/deep-module-map.md`
+3. clear user value
+4. clear business or product outcome
+5. simple MVP scope
+6. honest boundaries and tradeoffs
+7. measurable success signals
+8. non-technical acceptance criteria
 
 ## Final response behavior
 

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

@@ -11,6 +11,31 @@ Help write product vision documents that make a product feel clear, intentional,
 
 Default output path: `docs/product-vision.md`.
 
+## Pipeline Contract
+
+### What this skill needs
+
+- Enough user-provided product discovery to define or revise a product vision.
+- No upstream pipeline artifact is required.
+- If an existing `docs/product-vision.md` is being revised, read it first.
+
+### What this skill writes
+
+- `docs/product-vision.md` by default.
+- A different path only when the user explicitly requests one.
+
+### When this skill stops
+
+- The user's intent is too unclear to ask a useful discovery question.
+- Writing would overwrite an existing vision when the user appears to want a separate new vision.
+- The request is for a downstream artifact such as a Deep Module Map, feature brief, technical design, UX spec, stories, implementation plan, or implementation work.
+
+### What this skill must not do
+
+- Do not create Deep Module Maps, feature briefs, technical designs, UX specs, Epics, User Stories, implementation plans, or production code.
+- Do not require a final confirmation summary before writing once enough product vision context is available.
+- Do not pretend unresolved strategy questions are settled; ask a focused question or document a clear assumption.
+
 ## Workflow
 
 ### 1. Start with discovery, not drafting

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

@@ -11,6 +11,35 @@ Turn an approved feature brief and technical design into the smallest useful Scr
 
 This skill owns delivery planning artifacts. It does not own product vision, feature definition, technical design, code implementation, or project-management tool automation.
 
+## Pipeline Contract
+
+### What this skill needs
+
+- `docs/features/<feature-slug>/feature_brief.md`.
+- `docs/features/<feature-slug>/technical_design.md`.
+- `docs/features/<feature-slug>/ux.md` only when the feature has UI impact.
+- Enough source-artifact detail to create delivery slices without inventing product scope or implementation boundaries.
+
+### What this skill writes
+
+- `docs/features/<feature-slug>/epics/<epic-slug>/epic_brief.md`.
+- `docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<user-story-slug>.md`.
+- Supporting Epic and Story directories under the same feature tree when needed.
+
+### When this skill stops
+
+- The feature brief or technical design is missing; direct the user to the owning prior stage.
+- The feature has UI impact and `ux.md` is missing; direct the user to `ux-expert`.
+- A prior artifact is obviously incomplete or invalid in a way its owning stage should repair.
+- The request belongs to another pipeline stage, such as product definition, technical design, UX design, implementation planning, or implementation execution.
+
+### What this skill must not do
+
+- Do not create or update product visions, Deep Module Maps, feature briefs, technical designs, UX specs, implementation plans, or production code.
+- Do not modify prior-stage artifacts.
+- Do not reread `docs/deep-module-map.md` by default; trust `technical_design.md` for Deep Module implementation boundaries.
+- Do not add product scope or architecture decisions absent from the feature brief and technical design.
+
 ## Required inputs
 
 Before planning, read:

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

@@ -7,16 +7,48 @@ description: Use this skill to turn an approved feature brief into a concise, im
 
 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.
 
+## Pipeline Contract
+
+### What this skill needs
+
+- A Markdown feature brief at `docs/features/<feature-slug>/feature_brief.md`.
+- `docs/deep-module-map.md`.
+- The feature brief's `## Deep Module` section naming one or more existing Deep Modules.
+- Relevant existing repo files and flows needed to make implementation direction concrete.
+- `docs/features/<feature-slug>/ux.md` only when the feature has UI impact.
+- Relevant implementation guidance skills such as `clean-code`, selected architecture skills, language skills, or framework skills.
+
+### What this skill writes
+
+- `docs/features/<feature-slug>/technical_design.md`.
+
+### When this skill stops
+
+- The feature brief is missing or the user only has a vague feature idea; direct the user to `feature-brief-writer`.
+- `docs/deep-module-map.md` is missing; direct the user to `deep-module-map-writer`.
+- The feature brief does not name existing Deep Modules, or the selected modules are missing, ambiguous, or inconsistent with the map.
+- The feature has UI impact and `docs/features/<feature-slug>/ux.md` is missing; direct the user to `ux-expert`.
+- The request belongs to another pipeline stage, such as feature definition, UX design, Scrum planning, implementation planning, or implementation execution.
+
+### What this skill must not do
+
+- Do not create or update product visions, Deep Module Maps, feature briefs, UX specs, Epics, User Stories, implementation plans, or production code.
+- Do not invent new Deep Modules or move work into unselected modules.
+- Do not redesign binding UX mockups.
+- Do not duplicate architecture, language, framework, or clean-code skill guidance.
+- Do not require a final confirmation summary before writing once enough technical design context is available.
+
 ## Grounding
 
 Before writing, read:
 
 1. `docs/product-vision.md`
-2. the feature brief
-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
+2. `docs/deep-module-map.md`
+3. the feature brief, including its `## Deep Module` section
+4. `docs/features/<feature-slug>/ux.md` when the feature has UI impact
+5. `clean-code`
+6. any selected architecture, language, or framework skills that apply
+7. 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.
 
@@ -24,6 +56,10 @@ 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.
 
+Require `docs/deep-module-map.md`. If it is missing, stop and ask the user to create it with `deep-module-map-writer` first. Do not infer or invent Deep Modules.
+
+Require the feature brief to name one or more existing Deep Modules. Preserve those selected modules in the technical design; if they appear missing, ambiguous, or inconsistent with the map, stop and ask the user to update the feature brief or Deep Module Map first.
+
 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
@@ -34,6 +70,8 @@ For UI-related features, `ux.md` is source context, not inspiration. If `ux.md`
 
 Translate product intent into implementation direction.
 
+Deep Modules answer “where does this implementation work belong?” Architecture guidance answers “how is that module structured internally?” Translate the feature brief's selected Deep Modules into implementation boundaries appropriate for the selected architecture. Capture those boundaries in the technical design so downstream Scrum planning, implementation planning, and execution can trust the technical design instead of rereading the Deep Module Map by default.
+
 Prefer:
 
 - concise decisions over long explanation
@@ -41,6 +79,7 @@ Prefer:
 - current codebase patterns over speculative redesigns
 - explicit open questions over risky assumptions
 - delegation to the right skills instead of duplicating their guidance
+- preserving the feature brief's selected Deep Modules
 
 Avoid:
 
@@ -48,6 +87,7 @@ Avoid:
 - product scope expansion
 - user stories, tickets, or delivery plans
 - invented CLI/database/API concepts that the feature brief did not ask for
+- inventing new Deep Modules or moving work into unselected modules
 - large template sections that say “none” without adding value
 
 ## Delegation rule
@@ -88,6 +128,7 @@ Use this structure as a starting point. Delete sections that do not add value.
 
 ## Inputs
 - Product vision: <path>
+- Deep Module Map: <path>
 - Feature brief: <path>
 - Delegated skills: <skills later implementation should apply>
 
@@ -100,6 +141,8 @@ Use this structure as a starting point. Delete sections that do not add value.
 ## Proposed Design
 <Concrete implementation decisions. Include command flows, file/module impact, state changes, and integration boundaries when relevant.>
 
+<Explain how the selected Deep Modules translate into architecture, module, command, file, or implementation boundaries when that affects downstream work.>
+
 ## Validation
 <Focused test/build/manual checks.>
 

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

@@ -7,6 +7,34 @@ description: Use this skill for UX/UI design after product definition when a fea
 
 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.
 
+## Pipeline Contract
+
+### What this skill needs
+
+- `docs/product-vision.md`.
+- A product artifact such as `docs/features/<feature-slug>/feature_brief.md` that defines goals, scope, and acceptance criteria.
+- Confirmation from the request or source artifact that the feature has UI impact.
+- Enough user or product context to design affected surfaces, flows, responsive layouts, states, accessibility requirements, and binding mockups.
+
+### What this skill writes
+
+- `docs/features/<feature-slug>/ux.md`.
+
+### When this skill stops
+
+- The user only has a product idea; direct the user to `feature-brief-writer` first.
+- `docs/product-vision.md` is missing; direct the user to `product-vision-writer` first.
+- The product artifact is missing, unclear, or lacks goals, scope, and acceptance criteria.
+- The feature or request has no UI impact; say so and do not invent UI work.
+- The request belongs to another pipeline stage, such as product definition, technical design, Scrum planning, implementation planning, or implementation execution.
+
+### What this skill must not do
+
+- Do not create or update product visions, Deep Module Maps, feature briefs, technical designs, Epics, User Stories, implementation plans, or production code.
+- Do not make architecture, framework, API, data model, or file-path decisions.
+- Do not treat UX work as optional for UI-changing features; concrete mockups are required.
+- Do not require a final confirmation summary before writing once enough UX context is available.
+
 ## 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.

package/bin/features/sync-project/preview.js

@@ -1 +0,0 @@
-export { getSyncPreviews, isActionableSyncPreview, shouldAskForSyncAction } from '../../shared/sync-preview.js';