@juancr11/sibu 0.5.3 → 0.6.0

package/bin/features/doctor-project/handler.js

@@ -77,7 +77,7 @@ function logSyncNextStep() {
         log.info(line);
     }
 }
-function diagnoseState({ rootPath, state }) {
+export function diagnoseState({ rootPath, state }) {
     const issues = [];
     const manifest = readTemplateManifest();
     if (state.templateVersion !== manifest.templateVersion) {

package/bin/shared/catalog.js

@@ -27,6 +27,15 @@ export const MANDATORY_SKILLS = [
             windsurf: '.agents/skills/product-vision-writer/SKILL.md',
         },
     },
+    {
+        templateRelativePath: 'skills/product-context-map-writer/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/product-context-map-writer/SKILL.md',
+            gemini: '.agents/skills/product-context-map-writer/SKILL.md',
+            claude: '.agents/skills/product-context-map-writer/SKILL.md',
+            windsurf: '.agents/skills/product-context-map-writer/SKILL.md',
+        },
+    },
     {
         templateRelativePath: 'skills/feature-brief-writer/SKILL.md',
         targetRelativePathsByAgent: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
     "dev:unlink": "pnpm unlink --global sibu",
     "prepack": "pnpm run build",
     "smoke:init": "node ./bin/sibu.js init",
-    "test": "pnpm build && node --test bin/shared/catalog.test.js bin/shared/npm-version.test.js bin/shared/prompts.test.js bin/shared/workflow-targets.test.js bin/shared/workflow-mutation-readiness.test.js bin/admin/generate-changelog/handler.test.js bin/admin/release.test.js bin/admin/release-workflow/handler.test.js bin/admin/release-workflow/package-json.test.js bin/features/doctor-project/handler.test.js bin/features/use-skill/handler.test.js bin/features/stop-managing-file/handler.test.js",
+    "test": "pnpm build && node ./scripts/run-tests.mjs",
     "validate:packed-runtime": "node ./scripts/validate-packed-cli-runtime.mjs",
     "validate:doctor-version-advisory": "pnpm build && node ./scripts/validate-doctor-version-advisory.mjs",
     "validate:post-update-doctor-drift": "pnpm build && node ./scripts/validate-post-update-doctor-drift.mjs",

package/templates/AGENTS.md

@@ -36,9 +36,12 @@ Keep responses concise by default, but spend the context needed for correctness,
 
 ## Skill routing
 
+For planned product/feature work, use this pipeline: product vision -> product context map -> feature brief -> technical design -> optional UX -> epics/stories -> AI implementation plan -> AI executor. Narrow code fixes and small local changes do not require the full pipeline unless product scope, context ownership, or architecture direction is unclear.
+
 - For any code-writing task, use `clean-code`.
 - For requests to create, revise, or clarify a product vision, product strategy narrative, product north star, positioning, product principles, product voice, target user definition, product boundaries, or success signals, use `product-vision-writer`.
-- For requests to create, revise, or clarify a business-level feature brief, feature definition, feature scope, MVP feature boundaries, business acceptance criteria, or product-level feature rationale, use `feature-brief-writer`.
+- For requests to create, revise, or clarify a Product Context Map, product responsibility boundaries, context ownership, or `docs/product-context-map.md`, use `product-context-map-writer`.
+- For requests to create, revise, or clarify a business-level feature brief after Product Context Map work, feature definition, feature scope, MVP feature boundaries, business acceptance criteria, or product-level feature rationale, use `feature-brief-writer`.
 - For requests to create, revise, or clarify a technical design, implementation-oriented design doc, architecture approach, technical tradeoffs, technical risks, or implementation plan for an approved feature, use `technical-design-writer`.
 - For requests to create Epics, User Stories, Scrum planning artifacts, backlog slices, or delivery plans from an approved feature brief and technical design, use `scrum-master-planner`.
 - For requests to turn a specific User Story into an implementation checklist, coding plan, step-by-step execution plan, or baby-step plan, use `ai-implementation-planner`.

package/templates/manifest.json

@@ -1,11 +1,11 @@
 {
-  "templateVersion": "55",
+  "templateVersion": "63",
   "templates": {
     "AGENTS.md": {
-      "version": "22",
+      "version": "23",
       "description": "Project-level agent instructions and Sibu maintenance guidance.",
       "changes": [
-        "Adds concise context-budget discipline so agents prefer narrow reads, summarize large outputs, and preserve quality over token savings."
+        "Adds Product Context Map routing and clarifies the planned feature-work pipeline without requiring it for narrow code fixes."
       ]
     },
     ".codex/config.toml": {
@@ -38,24 +38,31 @@
       ]
     },
     "skills/product-vision-writer/SKILL.md": {
-      "version": "5",
+      "version": "6",
       "description": "Mandatory product vision writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Strengthens final response rules so saved product visions report only the path unless inline review is explicitly requested."
+        "Adds a pipeline contract that clarifies required inputs, owned output, stop conditions, and stage boundaries for product vision work."
+      ]
+    },
+    "skills/product-context-map-writer/SKILL.md": {
+      "version": "3",
+      "description": "Mandatory Product Context Map writer skill installed once at the shared .agents/skills workspace path.",
+      "changes": [
+        "Adds a pipeline contract that clarifies required inputs, owned output, stop conditions, and stage boundaries for Product Context Map work."
       ]
     },
     "skills/feature-brief-writer/SKILL.md": {
-      "version": "4",
+      "version": "7",
       "description": "Mandatory feature brief writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Strengthens final response rules so saved feature briefs report only the path unless inline review is explicitly requested."
+        "Adds a pipeline contract that clarifies required inputs, owned output, stop conditions, and stage boundaries for feature brief work."
       ]
     },
     "skills/technical-design-writer/SKILL.md": {
-      "version": "12",
+      "version": "14",
       "description": "Mandatory technical design writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Strengthens final response rules so saved technical designs report only the path and never include excerpts unless inline review is explicitly requested."
+        "Adds a pipeline contract that clarifies required inputs, owned output, stop conditions, and Product Context boundary translation for technical design work."
       ]
     },
     "skills/typescript/SKILL.md": {
@@ -69,21 +76,21 @@
       "version": "1",
       "description": "Selectable Go skill installed when Go language support is selected.",
       "changes": [
-        "Adds an optional Go skill with concise, Effective Go\u2013style guidance for .go files, package APIs, interfaces, errors, receivers, concurrency, and tests."
+        "Adds an optional Go skill with concise, Effective Go–style guidance for .go files, package APIs, interfaces, errors, receivers, concurrency, and tests."
       ]
     },
     "skills/architecture/ddd-hexagonal/SKILL.md": {
-      "version": "1",
+      "version": "2",
       "description": "Selectable back-end architecture skill for DDD and Hexagonal Architecture.",
       "changes": [
-        "Adds an optional DDD + Hexagonal Architecture skill for projects that want opinionated back-end architecture guidance."
+        "Adds Product Context compatibility so DDD + Hexagonal guidance preserves approved context ownership while structuring domain, application, and infrastructure concerns."
       ]
     },
     "skills/architecture/command-pattern/SKILL.md": {
-      "version": "2",
+      "version": "3",
       "description": "Selectable architecture skill for command-oriented vertical slices using Command Pattern, Hexagonal Architecture, and DDD principles.",
       "changes": [
-        "Reframes Command Pattern guidance around command-oriented vertical slices, feature-local ports, thin entrypoints, and infrastructure adapters."
+        "Adds Product Context compatibility so command-oriented vertical slices stay within or clearly under approved context ownership."
       ]
     },
     "skills/nextjs/SKILL.md": {
@@ -101,24 +108,24 @@
       ]
     },
     "skills/scrum-master-planner/SKILL.md": {
-      "version": "5",
+      "version": "6",
       "description": "Mandatory Scrum planner skill for creating pragmatic Epics and User Stories from approved feature and technical design docs.",
       "changes": [
-        "Strengthens final response rules so generated Epics and Stories are summarized by paths and counts, not pasted inline unless explicitly requested."
+        "Adds a pipeline contract that clarifies required inputs, owned Epic and Story outputs, stop conditions, and stage boundaries for Scrum planning."
       ]
     },
     "skills/ai-implementation-planner/SKILL.md": {
-      "version": "7",
+      "version": "9",
       "description": "Mandatory AI implementation planner skill for turning one approved User Story into small, story-local implementation step files.",
       "changes": [
-        "Strengthens final response rules so generated implementation step files are listed by path, not pasted inline unless explicitly requested."
+        "Adds a pipeline contract that clarifies required inputs, owned implementation plan outputs, stop conditions, and stage boundaries for implementation planning."
       ]
     },
     "skills/ai-implementation-plan-executor/SKILL.md": {
-      "version": "12",
+      "version": "14",
       "description": "Mandatory AI implementation plan executor skill for implementing existing story implementation plans one reviewed step at a time.",
       "changes": [
-        "Clarifies focused approved-step commits and validation-only step reporting."
+        "Adds a pipeline contract that clarifies required inputs, current-step outputs, stop conditions, and review-gated execution boundaries."
       ]
     },
     "skills/ai-prompt-engineer-master/SKILL.md": {
@@ -129,10 +136,10 @@
       ]
     },
     "skills/ux-expert/SKILL.md": {
-      "version": "4",
+      "version": "5",
       "description": "Selectable UX expert skill for UI-changing features, responsive design, flows, states, accessibility, and binding mockups.",
       "changes": [
-        "Strengthens final response rules so saved UX specs report only the path and never include mockups or excerpts unless inline review is explicitly requested."
+        "Adds a pipeline contract that clarifies required inputs, owned output, stop conditions, and UI-impact boundaries for UX design work."
       ]
     }
   }

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

@@ -9,6 +9,38 @@ description: Execute an existing ai-implementation-planner story implementation
 
 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.
 
+## Pipeline Contract
+
+### What this skill needs
+
+- Exactly one User Story file or one story-local `.impl_plan/` folder.
+- Ordered implementation step files in that `.impl_plan/` folder.
+- The story, Epic brief, feature brief, and technical design for the selected plan.
+- `docs/features/<feature-slug>/ux.md` only when the story, step, or feature has UI impact.
+- Relevant repo files, validation output, and implementation skills needed for the current step.
+
+### What this skill writes
+
+- Code, docs, tests, or other repo changes required by the current implementation step only.
+- Step approval metadata in the current step file only after explicit user approval.
+- A focused commit for each approved step.
+
+### When this skill stops
+
+- The user does not provide or clearly identify exactly one User Story file or `.impl_plan/` folder.
+- The implementation plan is missing, empty, invalid, or has no ordered step files; direct the user to `ai-implementation-planner`.
+- Any required source artifact is missing, incomplete, or invalid in a way its owning stage should repair.
+- The story, step, or feature has UI impact and `ux.md` is missing; direct the user to `ux-expert`.
+- The request is to create an implementation plan, change story scope, skip review gates, or perform another pipeline stage.
+
+### What this skill must not do
+
+- Do not create product visions, Product Context Maps, feature briefs, technical designs, UX specs, Epics, User Stories, or implementation plans.
+- Do not modify prior-stage artifacts except for approval metadata in the current step file.
+- Do not reread `docs/product-context-map.md` by default; trust `technical_design.md` for implementation boundaries.
+- Do not implement multiple unapproved steps in one pass or mark a step approved before explicit user approval.
+- Do not weaken the one-step-at-a-time execution model, user review gate, or approved-step commit behavior.
+
 ## Required source context
 
 The user must provide or clearly identify exactly one User Story or implementation plan folder:
@@ -36,6 +68,8 @@ 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.
 
+When the story, implementation plan, feature brief, or technical design includes Product Context guidance, treat it as part of the execution contract. Product Contexts answer “where does this work belong?” Approved contexts define where code work should stay.
+
 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.
@@ -146,11 +180,14 @@ Do not automatically start planning or implementing the next story. This check i
 Do:
 
 - preserve the source story scope and acceptance criteria
+- preserve approved Product Context boundaries when present
 - follow the current step file exactly unless it conflicts with source context
 - keep changes focused on the current step's `## Scope` and `## Files`
+- keep work inside the contexts named by the approved step and technical design
 - use existing project patterns and the relevant skills
 - run focused validation for the current step when possible
 - stop and ask if the step is ambiguous, missing required files, or conflicts with the technical design
+- stop and ask before moving work into an unrelated Product Context unless the approved step or technical design explicitly justifies it
 
 Do not:
 
@@ -158,6 +195,7 @@ Do not:
 - implement multiple unapproved steps in one pass
 - mark a step approved before the user explicitly approves it
 - add product scope absent from the story, Epic, feature brief, technical design, or step file
+- silently move work into unrelated or unapproved Product Contexts
 - continue past a failed validation without reporting it and asking how to proceed
 - leave approved step changes uncommitted before moving to the next step
 

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

@@ -9,6 +9,35 @@ description: Turn one approved User Story Markdown file into LLM-sized implement
 
 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.
 
+## Pipeline Contract
+
+### What this skill needs
+
+- Exactly one User Story file at `docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.md`.
+- The story's `epic_brief.md`.
+- The feature's `feature_brief.md`.
+- The feature's `technical_design.md`.
+- `docs/features/<feature-slug>/ux.md` only when the story or feature has UI impact.
+- Relevant repo files, tests, scripts, and implementation skills needed to make concrete step files.
+
+### What this skill writes
+
+- Story-local implementation step files under `docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl_plan/*.md`.
+
+### When this skill stops
+
+- The user does not provide or clearly identify exactly one User Story file.
+- Any required source artifact is missing, incomplete, or invalid in a way its owning stage should repair.
+- The story or feature has UI impact and `ux.md` is missing; direct the user to `ux-expert`.
+- The request is to write production code, execute an implementation plan, create stories, or perform another pipeline stage.
+
+### What this skill must not do
+
+- Do not create or update product visions, Product Context Maps, feature briefs, technical designs, UX specs, Epics, User Stories, or production code.
+- Do not modify prior-stage artifacts.
+- Do not reread `docs/product-context-map.md` by default; trust `technical_design.md` for implementation boundaries.
+- Do not infer implementation scope from an Epic brief, feature brief, or technical design without exactly one User Story.
+
 ## Required input
 
 The user must provide or clearly identify exactly one User Story file:
@@ -33,6 +62,8 @@ 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.
 
+When the feature brief or technical design includes Product Context guidance, treat it as required planning context. Product Contexts answer “where does this work belong?” Implementation steps must preserve approved context boundaries.
+
 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.
@@ -101,6 +132,8 @@ Do:
 - call out dependencies, sequencing constraints, and risk checkpoints
 - include test, build, lint, or manual validation commands when known
 - include a stop-and-ask condition when the implementation would exceed the technical design
+- keep work inside the approved Product Contexts unless cross-context work is explicit in the source artifacts
+- call out cross-context ownership and coordination in the relevant step files
 
 Do not:
 
@@ -110,6 +143,7 @@ Do not:
 - include prerequisite reading, scope confirmation, or repository inspection as step files
 - create task noise such as “review the code” without a specific implementation or validation purpose
 - prescribe architecture that conflicts with the selected architecture skill or technical design
+- move work into unrelated or unapproved Product Contexts; add a stop-and-ask condition instead
 
 ## Workflow
 
@@ -129,11 +163,12 @@ If the story lacks testable acceptance criteria, stop and ask for the User Story
 
 ### 2. Read feature and technical context
 
-From the Epic and feature brief, identify delivery boundaries and user value.
+From the Epic and feature brief, identify delivery boundaries, user value, and approved Product Context ownership when present.
 
 From the technical design, identify:
 
 - intended implementation approach
+- Product Context boundaries, ownership, and any explicit cross-context work
 - affected commands, modules, files, adapters, docs, or tests
 - known risks or unresolved decisions
 - expected validation commands or checks
@@ -184,6 +219,7 @@ Step-file requirements:
 - keep each step small enough for one AI coding pass
 - name every known file, module, command, or artifact to change or validate
 - include explicit out-of-scope boundaries in `Scope` when they prevent scope creep
+- preserve Product Context boundaries in `Scope`; call out cross-context work explicitly when required
 - include validation commands in `Done when` when known
 - ensure the full set of step files covers every acceptance criterion
 
@@ -200,6 +236,7 @@ Before finishing, verify:
 - every step file has clear done conditions
 - validation is explicit enough to prove the story is complete
 - the step files do not add scope beyond the source artifacts
+- the step files preserve approved Product Context boundaries and stop before unrelated context movement
 - architecture and code-quality steps align with the relevant skills
 
 ## Final response behavior

package/templates/skills/architecture/command-pattern/SKILL.md

@@ -10,6 +10,16 @@ Use this skill to design and implement software features as independent, end-to-
 
 ---
 
+## Product Context Compatibility
+
+Product Contexts answer “where does this work belong?” Command Pattern guidance answers “how is that work structured as command-oriented vertical slices?”
+
+When `docs/product-context-map.md`, a feature brief, or a technical design names Product Contexts, place each vertical slice within or clearly under the relevant Product Context's ownership. The feature-local Command, Handler, Port, Adapter, and Result guidance still applies inside that context boundary.
+
+Do not invent new Product Contexts during design or implementation. If work does not fit the approved contexts, stop and route the decision back to the `product-context-map-writer` workflow.
+
+---
+
 ## 1. The Component Contract
 Every feature is defined by four distinct roles. This separation ensures that the "Core" logic remains pure and testable.
 

package/templates/skills/architecture/ddd-hexagonal/SKILL.md

@@ -27,6 +27,16 @@ This skill is backend-focused. It does not cover frontend component architecture
 
 If a simpler structure preserves clear boundaries, prefer the simpler structure.
 
+## Product Context compatibility
+
+Product Contexts answer “where does this work belong?” DDD + Hexagonal answers “how is that context structured internally?”
+
+When `docs/product-context-map.md`, a feature brief, or a technical design names Product Contexts, treat them as the first ownership boundary to preserve before choosing domain/application/infra placement. Prefer placing domain concepts, use cases, ports, and adapters under the selected context's ownership. If work crosses contexts, name the owning context for each part and keep dependencies explicit.
+
+A Product Context may contain `domain`, `application`, and `infra`/adapter concerns, but the map remains architecture-agnostic: it is not a required DDD Bounded Context, folder structure, service boundary, or layer model.
+
+Do not invent new Product Contexts during design or implementation. If work does not fit the approved contexts, stop and route the decision back to the `product-context-map-writer` workflow.
+
 ## The layers
 
 ### Domain

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/product-context-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 Product Context 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/product-context-map.md` is missing; tell the user to create it first with `product-context-map-writer`.
+- The feature appears to require a new or changed Product Context; direct the user back to `product-context-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 Product Context Maps, technical designs, UX specs, Epics, User Stories, implementation plans, or production code.
+- Do not invent Product Contexts or use contexts that are absent from `docs/product-context-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/product-context-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 Product Context Map as the source of truth for where feature work belongs. Product Contexts answer “where does this work belong?” Do not invent Product Contexts 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/product-context-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 Product Context Map is missing:
+
+1. Stop.
+2. Tell the user that a feature brief requires `docs/product-context-map.md`.
+3. Instruct the user to create the map first with the `product-context-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 Product Context 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 Product Context 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/product-context-map.md` and identify which existing Product Contexts may own the requested feature. A feature brief must name one or more existing Product Contexts.
 
-Do not draft a feature brief from a vague request.
+If no existing Product Context fits:
+
+1. Stop before drafting.
+2. Tell the user the feature appears to require a Product Context Map update.
+3. Provide this suggested prompt, adapted to the user's feature:
+
+```txt
+Use product-context-map-writer to update docs/product-context-map.md for this feature: <feature summary>. Decide whether it belongs in an existing Product Context or requires a new/changed context, 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 Product Context 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.>
 
+## Product Context
+<One or more existing Product Contexts from docs/product-context-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 Product Contexts 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 Product Contexts 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 Product Contexts from `docs/product-context-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-context-map-writer/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: product-context-map-writer
+description: Create or update docs/product-context-map.md as an architecture-agnostic map of durable product responsibility boundaries before feature brief work.
+---
+
+# Product Context Map Writer
+
+## Purpose
+
+Create or update `docs/product-context-map.md`, the product-level map of responsibility areas that downstream feature briefs, technical designs, and implementation plans use to decide where work belongs.
+
+A Product Context is DDD-inspired but architecture-agnostic. It is not a folder structure, service boundary, layer, package, or requirement to use Domain-Driven Design.
+
+This skill owns the Product Context Map only. It does not own feature briefs, technical designs, user stories, implementation plans, code structure, or architecture selection.
+
+## Pipeline Contract
+
+### What this skill needs
+
+- `docs/product-vision.md`.
+- Existing `docs/product-context-map.md` when revising the map.
+- Enough user interview context to identify durable product responsibility boundaries, exclusions, scenarios, relationships, and cross-context rules.
+
+### What this skill writes
+
+- `docs/product-context-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 Product Context 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 application architecture, folders, services, packages, database tables, or team ownership.
+- Do not ask for or require a final confirmation summary before writing once enough context map information is available.
+- Do not invent Product Contexts without grounding them in the product vision and user interview.
+
+## What a Product Context is
+
+A Product Context is a durable area of product responsibility: a named part of the product that owns specific user-facing behaviors, rules, decisions, promises, and language.
+
+Use Product Contexts to answer:
+
+```txt
+When future work changes behavior, which part of the product is responsible for deciding how that behavior should work?
+```
+
+A Product Context is not:
+
+- a feature
+- a screen
+- a command
+- a workflow step
+- a code folder
+- a package, service, or database table
+- a technical layer
+- an org chart or team boundary
+
+Good Product Contexts are stable product jobs that will absorb multiple features over time. They should be broad enough to own meaningful behavior and narrow enough that ownership is defensible.
+
+Use these tests:
+
+- If it describes a stable product job or promise, it may be a context.
+- If it describes one command, page, database object, or implementation mechanism, it is probably too small or too technical.
+- If it only says "user control," "quality," "security," or another value that applies everywhere, it is probably a cross-context rule instead of a context.
+- If two candidates cannot explain what decisions they own differently, merge or rename them.
+- If future feature work would routinely ask "does this belong here or there?", keep clarifying the boundary.
+
+## Required source of truth
+
+Before doing any Product Context 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 Product Context Map if `docs/product-vision.md` is missing.
+
+If the product vision is missing:
+
+1. Stop.
+2. Tell the user that a Product Context 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 context map until the product vision exists.
+
+## Output location
+
+Write the map to:
+
+```txt
+docs/product-context-map.md
+```
+
+This file is user-owned product 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.
+- Keep asking until you understand the product's major responsibility areas, boundaries, key scenarios, relationships, and naming.
+- Treat "100% understanding" as: contexts, responsibilities, exclusions, scenarios, relationships, and deep-module boundaries are clear enough to defend.
+- Treat "enough context" as: contexts, responsibilities, exclusions, scenarios, relationships, and deep-module boundaries are clear enough to defend in the map.
+- Do not ask the user to name the Product Contexts up front. Most users do not know what the contexts should be yet.
+- Extract contexts by asking about product jobs, decisions, promises, lifecycle moments, and confusing boundaries.
+- Teach briefly as needed. If the user seems unsure, explain Product Contexts in plain language before asking the next question.
+- Do not create contexts from vague labels without confirming what they own and do not own.
+- 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 contexts from answers. Do not make the user design the map from scratch.
+
+Prefer questions like:
+
+- "What is the existing product/repo state before the product starts helping?"
+- "What durable job is the product doing for the user at this moment?"
+- "What decisions should this area own, and which decisions should it not own?"
+- "What should never be silently changed or overwritten?"
+- "After the first setup, what ongoing responsibilities does the product have?"
+- "What user scenarios would feel like the same responsibility area over time?"
+- "Where do you expect future features to create boundary confusion?"
+- "Is this a separate responsibility area, or a rule that applies across all areas?"
+- "If this behavior changed, what other parts of the product would need to know?"
+- "What language would a product manager, designer, engineer, and agent all understand?"
+
+Avoid questions like:
+
+- "What contexts do you want?"
+- "What bounded contexts should we use?"
+- "What services/packages/modules should exist?"
+- "What are your DDD boundaries?"
+
+When a user gives a feature, command, screen, template, or technical mechanism, translate it into the product responsibility it represents and ask the user to confirm or correct that responsibility.
+
+Example:
+
+```txt
+User: "sibu init scaffolds the AI files."
+Assistant: "That sounds like an AI workflow adoption/scaffolding responsibility, not general project onboarding. It owns how an existing repo adopts Sibu-managed AI workflow files. Is that right?"
+```
+
+Ask enough follow-up to fill these fields for each context:
+
+- Purpose
+- Owns
+- Does not own
+- Key scenarios
+- Related contexts
+- Boundary notes
+
+Also identify cross-context rules, especially product values that apply everywhere, such as user ownership, safety, transparency, local customization, or quality.
+
+## Context principles
+
+Product Contexts should be:
+
+- product responsibility boundaries, not implementation details
+- deep modules: simple from the outside, rich enough inside to own meaningful behavior
+- durable enough to guide multiple features over time
+- named in language useful across product planning, technical design, implementation planning, and code organization
+
+Avoid shallow contexts based on one feature, screen, command, workflow step, database table, folder, or technical layer.
+
+## Workflow
+
+1. Read `docs/product-vision.md`.
+2. Read existing `docs/product-context-map.md` if it exists.
+3. Ask one focused question at a time until the context direction is clear.
+4. Write or update `docs/product-context-map.md` once enough context is available.
+
+## Recommended map structure
+
+```md
+# Product Context Map
+
+## Purpose
+<How this map guides feature briefs, technical design, and implementation.>
+
+## Contexts
+
+### <Context Name>
+- Purpose:
+- Owns:
+- Does not own:
+- Key scenarios:
+- Related contexts:
+- Boundary notes:
+
+## Cross-Context Rules
+- <Rules for when work spans contexts or needs a new context.>
+```
+
+Adapt the structure when useful, but keep the map concise and product-level.
+
+## Final response behavior
+
+After writing the file, final-answer with only the path created or updated:
+
+```txt
+docs/product-context-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/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 Product Context Map, feature brief, technical design, UX spec, stories, implementation plan, or implementation work.
+
+### What this skill must not do
+
+- Do not create Product Context 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, Product Context Maps, feature briefs, technical designs, UX specs, implementation plans, or production code.
+- Do not modify prior-stage artifacts.
+- Do not reread `docs/product-context-map.md` by default; trust `technical_design.md` for 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/product-context-map.md`.
+- The feature brief's `## Product Context` section naming one or more existing Product Contexts.
+- 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/product-context-map.md` is missing; direct the user to `product-context-map-writer`.
+- The feature brief does not name existing Product Contexts, or the selected contexts 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, Product Context Maps, feature briefs, UX specs, Epics, User Stories, implementation plans, or production code.
+- Do not invent new Product Contexts or move work into unselected contexts.
+- 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/product-context-map.md`
+3. the feature brief, including its `## Product Context` 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/product-context-map.md`. If it is missing, stop and ask the user to create it with `product-context-map-writer` first. Do not infer or invent Product Contexts.
+
+Require the feature brief to name one or more existing Product Contexts. Preserve those selected contexts 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 Product Context 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.
 
+Product Contexts answer “where does this work belong?” Architecture guidance answers “how is that context structured internally?” Translate the feature brief's selected Product Contexts 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 Product Context 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 Product Contexts
 
 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 Product Contexts or moving work into unselected contexts
 - 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>
+- Product Context 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 Product Contexts 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, Product Context 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.