@juancr11/sibu 0.6.0 → 0.8.0

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

@@ -10,13 +10,15 @@ Use this skill to design and implement software features as independent, end-to-
 
 ---
 
-## Product Context Compatibility
+## Deep Module Compatibility
 
-Product Contexts answer “where does this work belong?” Command Pattern guidance answers “how is that work structured as command-oriented vertical slices?”
+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/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.
+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 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.
+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.
 
 ---
 
@@ -37,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
 ```
 
 ---
@@ -58,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.
@@ -83,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,15 +27,17 @@ 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
+## Deep Module compatibility
 
-Product Contexts answer “where does this work belong?” DDD + Hexagonal answers “how is that context structured internally?”
+Deep Modules answer “where does this implementation work belong?” DDD + Hexagonal answers “how is that module 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.
+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 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.
+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 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.
+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
 
@@ -130,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
 

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

@@ -16,8 +16,8 @@ This skill owns the product/business shape of a feature. It does not own UI inte
 ### 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.
+- `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
 
@@ -27,15 +27,15 @@ This skill owns the product/business shape of a feature. It does not own UI inte
 ### 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`.
+- `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 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 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.
 
@@ -45,18 +45,18 @@ Before doing any feature-brief work, read:
 
 ```txt
 docs/product-vision.md
-docs/product-context-map.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 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.
+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` or `docs/product-context-map.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:
 
@@ -65,11 +65,11 @@ 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:
+If the Deep Module 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.
+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
@@ -102,13 +102,13 @@ Be deliberately interrogative before drafting. The feature brief should reflect
 - 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.
+- 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 and Product Context Map
+### 1. Read the product vision and Deep Module Map
 
 Read `docs/product-vision.md` first and identify:
 
@@ -122,16 +122,16 @@ Read `docs/product-vision.md` first and identify:
 
 Use these as constraints for the feature brief.
 
-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.
+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.
 
-If no existing Product Context fits:
+If no existing Deep Module fits:
 
 1. Stop before drafting.
-2. Tell the user the feature appears to require a Product Context Map update.
+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 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.
+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.
@@ -167,7 +167,7 @@ Ask every question needed to remove material ambiguity, but only one at a time.
 - what should stay out of scope
 - known constraints, risks, or open decisions
 
-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.
+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.
 
@@ -186,8 +186,8 @@ 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.>
+## 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.>
@@ -251,7 +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
+- explicit about which existing Deep Modules own the feature
 - specific to the user's feature
 - grounded in the product vision
 - concise
@@ -265,7 +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 new Deep Modules instead of stopping for a map update
 - inventing certainty where the product vision or user input is unresolved
 
 ## Decision rule
@@ -273,7 +273,7 @@ Avoid:
 When shaping a feature brief, prefer:
 
 1. alignment with `docs/product-vision.md`
-2. fit with existing Product Contexts from `docs/product-context-map.md`
+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

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

@@ -0,0 +1,72 @@
+---
+name: postgresql-expert
+description: Use this skill for PostgreSQL schema design, migrations, constraints, queries, indexing, and database tradeoffs when practical database judgment is needed.
+---
+
+# PostgreSQL Expert
+
+Use this skill when working with PostgreSQL database design or database-facing application changes.
+
+Apply this skill together with `clean-code`. Keep the guidance practical: prefer the simplest database design that protects data integrity and supports the application's real access patterns.
+
+## Use this skill for
+
+- designing or reviewing PostgreSQL schemas
+- planning migrations and safe schema evolution
+- choosing keys, constraints, relationships, and transactions
+- reasoning about queries, access patterns, and indexes
+- deciding whether PostgreSQL-specific features are worth using
+- reviewing database-related tradeoffs in application code
+
+## Core principles
+
+### 1. Start with the product model
+- Model the real domain concepts, not speculative future reporting or scaling needs.
+- Prefer clear table and column names that match product language.
+- Keep schemas boring until the product needs something more specialized.
+- Do not add tables, abstractions, or generic metadata columns just in case.
+
+### 2. Protect data integrity in the database
+- Use primary keys, foreign keys, `NOT NULL`, `UNIQUE`, and `CHECK` constraints when they express real invariants.
+- Prefer database-enforced integrity over relying only on application checks for durable rules.
+- Make deletion behavior explicit with appropriate foreign-key actions.
+- Use transactions when a change must succeed or fail as one unit.
+
+### 3. Evolve schemas safely
+- Treat migrations as production changes that need clear rollback or recovery thinking.
+- Prefer small, reversible migration steps for risky changes.
+- Avoid destructive changes until data has been backfilled, verified, and callers have moved over.
+- Consider lock behavior and table size before changing large production tables.
+
+### 4. Design from access patterns, not guesses
+- Understand the queries the application actually needs before optimizing.
+- Keep common reads and writes straightforward before introducing denormalization.
+- Use normalization for clarity and integrity; denormalize only for a measured or well-understood reason.
+- Explain tradeoffs when choosing between simpler schema shape and query convenience.
+
+### 5. Add indexes only when justified
+- Do not add indexes just because a column is used, foreign-keyed, or might be queried someday.
+- Add an index when there is a clear query, filtering, joining, sorting, uniqueness, or constraint need.
+- Remember that indexes speed some reads but add write cost, storage cost, and maintenance overhead.
+- Prefer a small number of purposeful indexes over broad defensive indexing.
+
+### 6. Use PostgreSQL features with restraint
+- Consider PostgreSQL capabilities such as JSONB, arrays, partial indexes, generated columns, enums, extensions, and full-text search when they simplify a real requirement.
+- Do not use PostgreSQL-specific features to appear sophisticated when standard relational modeling is clearer.
+- Be explicit about portability tradeoffs when choosing PostgreSQL-specific behavior.
+- Prefer built-in PostgreSQL capabilities before adding extra infrastructure.
+
+### 7. Keep database advice actionable
+- Tie recommendations to the schema, query, migration, or invariant at hand.
+- Say what evidence would change the recommendation, such as query plans, row counts, write volume, or latency targets.
+- When context is missing, ask for the relevant schema, migration, query, or access pattern instead of guessing.
+- Avoid broad DBA checklists unless the task is explicitly about operations or performance investigation.
+
+## Decision rule
+
+When unsure, prefer:
+1. simple schema design that matches current product needs
+2. explicit database constraints for real invariants
+3. safe, incremental migrations
+4. query-aware design over speculative optimization
+5. purposeful indexes over blanket indexing

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

@@ -28,11 +28,11 @@ Default output path: `docs/product-vision.md`.
 
 - 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.
+- 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 Product Context Maps, feature briefs, technical designs, UX specs, Epics, User Stories, implementation plans, or production code.
+- 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.
 

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

@@ -35,9 +35,9 @@ This skill owns delivery planning artifacts. It does not own product vision, fea
 
 ### 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 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/product-context-map.md` by default; trust `technical_design.md` for implementation boundaries.
+- 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