@juancr11/sibu 0.5.3 → 0.7.0

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

@@ -1,13 +1,49 @@
 ---
 name: ai-implementation-plan-executor
-description: Execute an existing ai-implementation-planner story implementation plan one ordered step at a time. Use when asked to implement, execute, continue, or work through a story implementation plan under docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl_plan/.
+description: Execute an existing ai-implementation-planner story implementation plan from start to finish, then request story-level review before marking steps approved and committing.
 ---
 
 # AI Implementation Plan Executor
 
 ## Purpose
 
-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.
+Execute one existing story implementation plan completely, one ordered step file at a time, with a single human review gate after the full story plan has been implemented. This skill owns execution from an existing `.impl_plan/` folder; it does not change story scope or skip the final story approval gate.
+
+## Pipeline Contract
+
+### What this skill needs
+
+- Exactly one User Story file or one story-local `.impl_plan/` folder to start.
+- 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, any step, or feature has UI impact.
+- Relevant repo files, validation output, and implementation skills needed for the story plan.
+
+### What this skill writes
+
+- Code, docs, tests, or other repo changes required by all unapproved implementation steps in the story plan.
+- Step approval metadata in every completed step file only after explicit story-level user approval.
+- One focused commit for the approved story implementation.
+- When continuing an Epic and the next story has no plan, story-local implementation step files created by applying `ai-implementation-planner`.
+
+### When this skill stops
+
+- The user does not provide or clearly identify exactly one User Story file or `.impl_plan/` folder.
+- The starting 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, any step, or feature has UI impact and `ux.md` is missing; direct the user to `ux-expert`.
+- Validation fails and the fix is ambiguous, risky, or would exceed the approved plan.
+- A step conflicts with the story, Epic, feature brief, technical design, UX spec, or approved Deep Module boundaries.
+- A newly planned next story is ready for plan review and approval before execution.
+
+### What this skill must not do
+
+- Do not create product visions, Deep Module Maps, feature briefs, technical designs, UX specs, Epics, or User Stories.
+- Do not modify prior-stage artifacts except for approval metadata in implementation step files.
+- Do not reread `docs/deep-module-map.md` by default; trust `technical_design.md` for Deep Module implementation boundaries.
+- Do not mark any step approved before explicit story-level user approval.
+- Do not commit story implementation changes before explicit story-level user approval.
+- Do not continue past a newly created implementation plan for the next story until the user approves that plan.
 
 ## Required source context
 
@@ -31,11 +67,13 @@ docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl
 docs/features/<feature-slug>/epics/<epic-slug>/epic_brief.md
 docs/features/<feature-slug>/feature_brief.md
 docs/features/<feature-slug>/technical_design.md
-docs/features/<feature-slug>/ux.md  # when the story, step, or feature has UI impact
+docs/features/<feature-slug>/ux.md  # when the story, any step, 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 story, implementation plan, feature brief, or technical design includes Deep Module guidance, treat it as part of the execution contract. Deep Modules answer “where does this implementation work belong?” Approved modules define where implementation 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.
@@ -47,13 +85,13 @@ Before the first implementation step that changes code, read and apply the imple
 - read and apply language skills when relevant, such as `typescript`
 - read and apply framework skills when relevant, such as `react` or `nextjs`
 
-Inspect existing code, tests, scripts, and docs only as needed for the current step.
+Inspect existing code, tests, scripts, and docs only as needed for the story plan and current step.
 
 ## Context reuse rule
 
 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.
 
-After each approved step, do not reread unchanged broad context before continuing. For the next step, inspect only:
+After each completed 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
@@ -64,7 +102,7 @@ Reread broad source context only when scope changes, validation fails in a way t
 
 ## Hard start rule
 
-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:
+If the initial User Story has no matching `.impl_plan/`, or the initial `.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.
@@ -78,11 +116,11 @@ If required source context is missing:
 3. Ask the user to create or restore the missing artifact first.
 4. Do not invent implementation scope from partial context.
 
-## Step execution model
+## Story execution model
 
-Work on exactly one step at a time.
+Work through the full story plan in filename order, one step at a time, without asking for review or approval between steps.
 
-When a valid implementation plan exists, begin implementing the first unapproved step immediately. Do not ask for pre-implementation confirmation before changing code for that step. This is an explicit exception to repository-level instructions that normally require confirmation before code changes: selecting this executor skill and providing a valid plan is the user's confirmation to implement the current step.
+When a valid implementation plan exists, begin implementing the first unapproved step immediately. Do not ask for pre-implementation confirmation before changing code. This is an explicit exception to repository-level instructions that normally require confirmation before code changes: selecting this executor skill and providing a valid plan is the user's confirmation to implement the full story plan.
 
 A step file is considered approved only when it contains this section:
 
@@ -95,21 +133,22 @@ A step file is considered approved only when it contains this section:
 When starting or resuming a plan:
 
 1. Read all step files in filename order.
-2. Identify the first step file that is not approved.
-3. Implement only that step immediately, without asking for confirmation first.
-4. Run the validation named in that step when practical.
-5. Report what changed, validation results, and any risks.
-6. Stop and wait for explicit user confirmation before moving to the next step.
+2. Identify all step files that are not approved.
+3. Implement the unapproved steps in order, exactly one step at a time.
+4. Run the validation named in each step when practical before moving to the next step.
+5. If a step is validation-only and produces no code changes, record the validation result in the story execution summary and continue.
+6. Stop only for ambiguity, missing required files, conflicting scope, failed validation that cannot be safely fixed within the plan, or material risk.
+7. After the final unapproved step is implemented, report what changed, validation results, and any risks, then wait for explicit story-level approval.
 
-Do not begin the next step in the same response unless the user has already explicitly approved the current step in this turn.
+Do not mark steps approved, commit changes, or move to the next story until the user explicitly approves the completed story implementation.
 
-## User review gate
+## Story review gate
 
-After implementing a step, say that the step is ready for review and that you are waiting for confirmation before continuing.
+After implementing all unapproved steps for a story, say that the full story implementation is ready for review and that you are waiting for story-level approval before marking all completed steps approved, committing, and continuing the Epic.
 
-If the user asks questions or requests changes, stay on the same step until those changes are complete.
+If the user asks questions or requests changes, keep working within the same story until those changes are complete. If requested changes exceed the approved story plan, stop and ask whether the plan should be revised.
 
-When the user explicitly approves the current step, update that step file by adding or updating:
+When the user explicitly approves the completed story, update every step file completed in this story by adding or updating:
 
 ```md
 ## Review status
@@ -119,60 +158,63 @@ When the user explicitly approves the current step, update that step file by add
 - Approved at: <ISO-8601 timestamp>
 ```
 
-Before writing the approval marker, identify the current Git user with `git config user.name`; if it is unavailable, use `git config user.email`. Use that value for `Approved by`.
-
-After writing the approval marker, commit only the changes produced by the approved step before continuing. The commit must include the step file approval marker and files intentionally changed while implementing that step. It must not include unrelated local edits, pre-existing worktree changes, or changes from other steps. Use the files tracked during step execution and a focused `git status --short` check to stage the correct paths. Do not run broad `git diff` investigations or other "what changed?" archaeology unless it is required to avoid committing unrelated changes and the user has approved that extra inspection.
-
-Use a Conventional Commits 1.0.0 message that describes the completed step. If the commit fails, stop and report the failure instead of continuing.
+Before writing approval markers, identify the current Git user with `git config user.name`; if it is unavailable, use `git config user.email`. Use that value for `Approved by`.
 
-Then continue with the next unapproved step immediately, without asking for another pre-implementation confirmation, only after the approval marker is written and the approved step changes are committed.
+After writing approval markers, commit only the changes produced by the approved story before continuing. The commit must include all step file approval markers and files intentionally changed while implementing the story. It must not include unrelated local edits or pre-existing worktree changes. Use the files tracked during story execution and a focused `git status --short` check to stage the correct paths. Do not run broad `git diff` investigations or other "what changed?" archaeology unless it is required to avoid committing unrelated changes and the user has approved that extra inspection.
 
-If the user asks to continue without clearly approving the current step, ask for explicit approval before marking it approved, committing, or moving on.
+Use a Conventional Commits 1.0.0 message that describes the completed story. If the commit fails, stop and report the failure instead of continuing.
 
 ## Epic continuation check
 
-When all step files in the current story implementation plan are approved and committed:
+After the approved story implementation is committed:
 
 1. Inspect the current Epic's `stories/` folder in filename order.
 2. Identify whether there is a next User Story after the completed story.
-3. If a next User Story exists and its `.impl_plan/` folder exists with ordered step files, ask the user whether they want to implement that next story.
-4. If a next User Story exists but its `.impl_plan/` folder is missing or empty, ask the user whether they want to plan that next story with `ai-implementation-planner`.
-5. If there is no next User Story in the Epic, tell the user the Epic appears ready.
+3. If there is no next User Story in the Epic, tell the user the Epic appears ready and stop.
+4. If a next User Story exists and its `.impl_plan/` folder exists with ordered step files, immediately begin implementing that next story plan using this same story execution model.
+5. If a next User Story exists but its `.impl_plan/` folder is missing or empty, immediately create the implementation plan for that story by applying `ai-implementation-planner`, then stop and ask the user to review and approve the new plan before executing it.
 
-Do not automatically start planning or implementing the next story. This check is a handoff prompt after the current story is complete, not permission to continue without the user's explicit direction.
+This continuation behavior is an explicit exception to the normal hard-start rule only after a story has been approved and committed. It lets the executor keep an Epic moving while still preserving the required review gate before executing a newly created plan.
 
 ## Implementation rules
 
 Do:
 
 - preserve the source story scope and acceptance criteria
-- follow the current step file exactly unless it conflicts with source context
-- keep changes focused on the current step's `## Scope` and `## Files`
+- preserve approved Deep Module boundaries when present
+- follow each step file exactly unless it conflicts with source context
+- keep each step focused on its `## Scope` and `## Files`
+- complete all unapproved steps in order before requesting story review
+- keep work inside the contexts named by the approved steps 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
+- run focused validation for each step when possible
+- stop and ask if a step is ambiguous, missing required files, or conflicts with the technical design
+- stop and ask before moving work into an unrelated Deep Module unless the approved step or technical design explicitly justifies it
 
 Do not:
 
-- create a missing plan from scratch
-- 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
+- create a missing initial plan from scratch
+- mark any step approved before the user explicitly approves the completed story
+- commit story implementation changes before story approval
+- add product scope absent from the story, Epic, feature brief, technical design, or step files
+- silently move work into unrelated or unapproved Deep Modules
 - continue past a failed validation without reporting it and asking how to proceed
-- leave approved step changes uncommitted before moving to the next step
+- leave approved story changes uncommitted before moving to the next story
+- execute a newly created next-story plan before the user approves that plan
 
-## Final response behavior after each step
+## Final response behavior
 
-After implementing one step, briefly report:
+After implementing all unapproved steps in one story, briefly report:
 
-- that the step finished
-- if the step was validation-only and produced no code changes, say that it was just a validation step and all validations passed
-- current step file path
-- the next step file path, or that no next step remains
-- that you are waiting for user approval before marking the step approved, committing it, and continuing to the next step
+- that the story implementation finished and is ready for review
+- the story file path and implementation plan folder
+- the steps completed
+- validations run and their results
+- notable risks or follow-up questions, if any
+- that you are waiting for story approval before marking all completed steps approved, committing, and continuing the Epic
 
-After approving and committing the final step in a story implementation plan, also briefly report the Epic continuation check result:
+After approving and committing a story implementation, briefly report the commit and the Epic continuation result:
 
-- next story ready to implement
-- next story needs an implementation plan
-- or Epic appears ready
+- next story is being implemented immediately because it already has a plan
+- next story was planned and is waiting for plan review and approval
+- or the Epic appears ready

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

@@ -1,13 +1,44 @@
 ---
 name: ai-implementation-planner
-description: Turn one approved User Story Markdown file into LLM-sized implementation step files. Use when asked to create an implementation plan, coding checklist, step-by-step execution plan, or baby-step plan for completing a specific User Story from docs/features/<feature-slug>/epics/<epic-slug>/stories/.
+description: Turn one approved User Story Markdown file into LLM-sized implementation step files, then request plan review before execution. Use when asked to create an implementation plan, coding checklist, step-by-step execution plan, or baby-step plan for completing a specific User Story from docs/features/<feature-slug>/epics/<epic-slug>/stories/.
 ---
 
 # AI Implementation Planner
 
 ## Purpose
 
-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.
+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. After writing the plan, it asks for plan review and approval before any executor begins 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.
+- A newly created implementation plan is ready for user review and approval before execution.
+
+### What this skill must not do
+
+- Do not create or update product visions, Deep Module Maps, feature briefs, technical designs, UX specs, Epics, User Stories, 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 infer implementation scope from an Epic brief, feature brief, or technical design without exactly one User Story.
+- Do not execute the plan after creating it, even when invoked as the next-story planning handoff from `ai-implementation-plan-executor`.
 
 ## Required input
 
@@ -33,6 +64,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 Deep Module guidance, treat it as required planning context. Deep Modules answer “where does this implementation work belong?” Implementation steps must preserve approved module 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 +134,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 Deep Modules unless cross-module work is explicit in the source artifacts
+- call out cross-module ownership and coordination in the relevant step files
 
 Do not:
 
@@ -110,6 +145,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 Deep Modules; add a stop-and-ask condition instead
 
 ## Workflow
 
@@ -129,11 +165,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 Deep Module ownership when present.
 
 From the technical design, identify:
 
 - intended implementation approach
+- Deep Module boundaries, ownership, and any explicit cross-module work
 - affected commands, modules, files, adapters, docs, or tests
 - known risks or unresolved decisions
 - expected validation commands or checks
@@ -184,6 +221,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 Deep Module boundaries in `Scope`; call out cross-module work explicitly when required
 - include validation commands in `Done when` when known
 - ensure the full set of step files covers every acceptance criterion
 
@@ -200,15 +238,21 @@ 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 Deep Module boundaries and stop before unrelated module movement
 - architecture and code-quality steps align with the relevant skills
 
-## Final response behavior
+### 6. Request plan review
 
-After writing the files, final-answer with only:
+After writing and quality-checking the implementation step files, stop and ask the user to review and approve the plan before execution. Do not start implementation in the same turn.
+
+When this skill is invoked as the next-story planning handoff from `ai-implementation-plan-executor`, the same gate applies: create the plan, summarize it, and wait for explicit approval before the executor starts changing code for that story.
+
+The final planning response must briefly include:
 
-- the implementation plan folder path
-- the step file paths created
 - the source User Story path
-- any risks or stop conditions captured in the step files
+- the implementation plan folder path
+- the ordered step files created
+- any assumptions, risks, or validation commands worth reviewing
+- that execution should wait until the user approves the plan
 
 Do not paste step-file bodies, excerpts, outlines, task text, done conditions, or section summaries. Only include generated step files when the user explicitly asks for inline review in the current request.

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

@@ -10,6 +10,18 @@ Use this skill to design and implement software features as independent, end-to-
 
 ---
 
+## Deep Module Compatibility
+
+Deep Modules answer “where does this implementation work belong?” Command Pattern guidance answers “how is that work structured as command-oriented vertical slices inside the selected module?”
+
+When `docs/deep-module-map.md`, a feature brief, or a technical design names Deep Modules, place each vertical slice inside the relevant Deep Module. The feature-local Command, Handler, Port, Adapter, and Result guidance still applies inside that module boundary.
+
+Do not invent new Deep Modules during design or implementation. If work does not fit the approved modules, stop and route the decision back to the `deep-module-map-writer` workflow.
+
+Do not treat shallow technical buckets such as `utils`, `api`, `db`, or `services` as Deep Modules. A Deep Module should expose a small, stable interface while hiding meaningful implementation complexity; product alignment can help explain why work changes together, but product category alone does not make a module deep.
+
+---
+
 ## 1. The Component Contract
 Every feature is defined by four distinct roles. This separation ensures that the "Core" logic remains pure and testable.
 
@@ -27,20 +39,30 @@ Organize by Capability (what the system does) rather than Technical Layer (what
 
 ```text
 /src
-  ├── /entrypoints          # Driving Adapters (The "Edges")
-  │    └── /cli             # Parses flags/args -> creates Command -> calls Handler
-  ├── /features             # THE HEXAGON (Domain & Application Logic)
-  │    └── /feature-name    # e.g., "archive-project"
-  │         ├── command     # The Input DTO
-  │         ├── handler     # The Orchestration logic
-  │         ├── ports       # Interfaces required by the handler
-  │         └── result      # The Output DTO/Contract
-  ├── /shared               # Universal logic only
-  │    ├── /domain          # Global Entities (e.g., "User", "Project")
-  │    └── /errors          # Global error definitions
-  └── /infrastructure       # Driven Adapters (Implementation Details)
-       ├── /persistence     # DB implementations of feature Ports
-       └── /clients         # External API implementations of feature Ports
+  ├── /entrypoints                  # Driving Adapters (The "Edges")
+  │    └── /cli                     # Parses flags/args -> creates Command -> calls Handler
+  ├── /modules                      # Deep Modules from docs/deep-module-map.md
+  │    └── /module-slug             # e.g., "workflow-adoption"
+  │         └── /feature-slice      # e.g., "archive-project"
+  │              ├── command        # The Input DTO
+  │              ├── handler        # The Orchestration logic
+  │              ├── ports          # Interfaces required by the handler
+  │              └── result         # The Output DTO/Contract
+  ├── /shared                       # Universal logic only
+  │    ├── /domain                  # Global Entities (e.g., "User", "Project")
+  │    └── /errors                  # Global error definitions
+  └── /infrastructure               # Driven Adapters (Implementation Details)
+       ├── /persistence             # DB implementations of feature Ports
+       └── /clients                 # External API implementations of feature Ports
+```
+
+Default slice paths:
+
+```text
+/src/modules/<module-slug>/<feature-slice>/command
+/src/modules/<module-slug>/<feature-slice>/handler
+/src/modules/<module-slug>/<feature-slice>/ports
+/src/modules/<module-slug>/<feature-slice>/result
 ```
 
 ---
@@ -48,7 +70,7 @@ Organize by Capability (what the system does) rather than Technical Layer (what
 ## 3. Operational Rules for Implementation
 
 ### Rule 1: Feature Isolation
-A feature folder must never import from another feature folder. If two features need the same logic, that logic must be promoted to the /shared directory.
+A feature-slice folder must never import from another feature-slice folder. If two slices need the same logic, that logic must be promoted to the owning Deep Module or to /shared when it is truly universal.
 
 ### Rule 2: Dependency Inversion
 The Handler must never instantiate a database, a file system, or a network client. It must receive its dependencies (via Ports) through its constructor or initialization.
@@ -73,5 +95,5 @@ Entrypoints (CLI/API) are responsible for Syntactic Validation (is the input the
 ## 5. Constraint Checklist for Agent Reviews
 - [ ] Zero Leakage: Does the Handler contain CLI-specific code (like fmt.Printf or flags)?
 - [ ] Interface-Driven: Does the Handler depend on a concrete Database class or an Interface (Port)?
-- [ ] Folder Integrity: Does the feature folder contain the Command, Handler, and Ports?
+- [ ] Folder Integrity: Does the Deep Module feature-slice folder contain the Command, Handler, and Ports?
 - [ ] Dependency Direction: Does the infrastructure layer depend on the feature ports, and not the other way around?

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

@@ -27,6 +27,18 @@ This skill is backend-focused. It does not cover frontend component architecture
 
 If a simpler structure preserves clear boundaries, prefer the simpler structure.
 
+## Deep Module compatibility
+
+Deep Modules answer “where does this implementation work belong?” DDD + Hexagonal answers “how is that module structured internally?”
+
+When `docs/deep-module-map.md`, a feature brief, or a technical design names Deep Modules, treat each selected Deep Module as the default top-level implementation boundary before choosing domain/application/infra placement. Prefer placing domain concepts, use cases, ports, and adapters under the selected module's ownership. If work crosses modules, name the owning module for each part and keep dependencies explicit.
+
+A Deep Module may contain `domain`, `application`, and `infra`/adapter concerns, but it is not automatically a DDD Bounded Context, service, package, database boundary, or team boundary. Projects that already use DDD Bounded Contexts may align a Bounded Context one-to-one with a Deep Module when that preserves the model and language.
+
+Do not invent new Deep Modules during design or implementation. If work does not fit the approved modules, stop and route the decision back to the `deep-module-map-writer` workflow.
+
+Do not treat shallow technical buckets such as `utils`, `api`, `db`, or `services` as Deep Modules. A Deep Module should expose a small, stable interface while hiding meaningful implementation complexity; product alignment can help explain why work changes together, but product category alone does not make a module deep.
+
 ## The layers
 
 ### Domain
@@ -120,10 +132,13 @@ Do not create an entity or value object when:
 
 Use this default mapping when the project does not already have a clearer convention:
 
-- `<feature-or-domain>/domain/**` → domain concepts and rules
-- `<feature-or-domain>/application/**` → use cases and application orchestration
-- `<feature-or-domain>/infra/**` → technical implementations and external integrations
-- entrypoints such as routes, jobs, or handlers → thin driving adapters that call application behavior
+```text
+/src/modules/<module-slug>/domain/**       # Domain concepts and rules
+/src/modules/<module-slug>/application/**  # Use cases and application orchestration
+/src/modules/<module-slug>/infra/**        # Technical implementations and external integrations
+```
+
+Entrypoints such as routes, jobs, or handlers should remain thin driving adapters that call application behavior inside the selected Deep Module.
 
 ## Ports and adapters