@juancr11/sibu 0.6.0 → 0.8.0

package/bin/shared/workflow-targets.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { SIBU_VERSION, MANDATORY_SKILLS, SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_SKILLS, SELECTABLE_WORKFLOW_SKILLS, SUPPORTED_AGENTS, } from './catalog.js';
+import { SIBU_VERSION } from './catalog.js';
+import { MANDATORY_SKILLS, SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_SKILLS, SELECTABLE_WORKFLOW_SKILLS, SUPPORTED_AGENTS, } from '../modules/workflow-target-planning/index.js';
 import { sha256 } from './hash.js';
 import { removeUndefinedFields } from './object.js';
 import { readExistingState } from './state.js';
-import { getTemplateVersion, readTemplate, readTemplateManifest, renderSkillRouting } from './templates.js';
+import { getTemplateVersion, readTemplate, readTemplateManifest, renderSkillRouting } from '../modules/template-catalog-rendering/index.js';
 export function getSelectedLanguageSkillsFromState(state) {
     return SELECTABLE_LANGUAGE_SKILLS.filter((skill) => state.selectedLanguageSkills?.includes(skill.id));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",
@@ -16,8 +16,10 @@
   "files": [
     "bin/sibu.js",
     "bin/entrypoints/",
-    "bin/features/",
+    "bin/admin/",
+    "bin/modules/",
     "bin/shared/",
+    "!bin/shared/state.js",
     "!bin/**/*.test.js",
     "!bin/echo.js",
     "templates/",

package/templates/AGENTS.md

@@ -36,12 +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 planned product/feature work, use this pipeline: product vision -> deep module 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, module 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 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 Deep Module Map, deep, complexity-hiding implementation modules, module boundaries, suggested implementation modules, or `docs/deep-module-map.md`, use `deep-module-map-writer`.
+- For requests to create, revise, or clarify a business-level feature brief after Deep Module 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": "63",
+  "templateVersion": "70",
   "templates": {
     "AGENTS.md": {
-      "version": "23",
+      "version": "25",
       "description": "Project-level agent instructions and Sibu maintenance guidance.",
       "changes": [
-        "Adds Product Context Map routing and clarifies the planned feature-work pipeline without requiring it for narrow code fixes."
+        "Clarifies Deep Module routing as complexity-hiding implementation module planning."
       ]
     },
     ".codex/config.toml": {
@@ -38,31 +38,32 @@
       ]
     },
     "skills/product-vision-writer/SKILL.md": {
-      "version": "6",
+      "version": "7",
       "description": "Mandatory product vision 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 vision work."
+        "Updates downstream artifact wording to use Deep Module Map."
       ]
     },
-    "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.",
+    "skills/deep-module-map-writer/SKILL.md": {
+      "version": "2",
+      "description": "Mandatory Deep Module 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."
+        "Clarifies that Deep Modules are primarily technical design boundaries that hide substantial implementation complexity behind simple interfaces.",
+        "Strengthens the interview flow so agents ask focused one-at-a-time questions until module interfaces, hidden complexity, and boundaries are defensible."
       ]
     },
     "skills/feature-brief-writer/SKILL.md": {
-      "version": "7",
+      "version": "8",
       "description": "Mandatory feature brief 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 feature brief work."
+        "Updates feature brief guidance to require Deep Modules from docs/deep-module-map.md."
       ]
     },
     "skills/technical-design-writer/SKILL.md": {
-      "version": "14",
+      "version": "15",
       "description": "Mandatory technical design 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 Product Context boundary translation for technical design work."
+        "Updates technical design guidance to translate selected Deep Modules into implementation boundaries."
       ]
     },
     "skills/typescript/SKILL.md": {
@@ -76,21 +77,28 @@
       "version": "1",
       "description": "Selectable Go skill installed when Go language support is selected.",
       "changes": [
-        "Adds an optional Go skill with concise, Effective Go–style guidance for .go files, package APIs, interfaces, errors, receivers, concurrency, and tests."
+        "Adds an optional Go skill with concise, Effective Go\u2013style guidance for .go files, package APIs, interfaces, errors, receivers, concurrency, and tests."
+      ]
+    },
+    "skills/postgresql-expert/SKILL.md": {
+      "version": "1",
+      "description": "Selectable PostgreSQL Expert skill for practical database schema design and PostgreSQL-specific tradeoff guidance.",
+      "changes": [
+        "Adds an optional PostgreSQL Expert database skill focused on simple schema design, data integrity, migrations, access patterns, and purposeful indexing."
       ]
     },
     "skills/architecture/ddd-hexagonal/SKILL.md": {
-      "version": "2",
+      "version": "4",
       "description": "Selectable back-end architecture skill for DDD and Hexagonal Architecture.",
       "changes": [
-        "Adds Product Context compatibility so DDD + Hexagonal guidance preserves approved context ownership while structuring domain, application, and infrastructure concerns."
+        "Clarifies that Deep Modules hide implementation complexity behind small interfaces and are not product categories by themselves."
       ]
     },
     "skills/architecture/command-pattern/SKILL.md": {
-      "version": "3",
+      "version": "5",
       "description": "Selectable architecture skill for command-oriented vertical slices using Command Pattern, Hexagonal Architecture, and DDD principles.",
       "changes": [
-        "Adds Product Context compatibility so command-oriented vertical slices stay within or clearly under approved context ownership."
+        "Clarifies that Deep Modules hide implementation complexity behind small interfaces and are not product categories by themselves."
       ]
     },
     "skills/nextjs/SKILL.md": {
@@ -108,24 +116,27 @@
       ]
     },
     "skills/scrum-master-planner/SKILL.md": {
-      "version": "6",
+      "version": "7",
       "description": "Mandatory Scrum planner skill for creating pragmatic Epics and User Stories from approved feature and technical design docs.",
       "changes": [
-        "Adds a pipeline contract that clarifies required inputs, owned Epic and Story outputs, stop conditions, and stage boundaries for Scrum planning."
+        "Updates Scrum planning guidance to preserve Deep Module implementation boundaries from technical designs."
       ]
     },
     "skills/ai-implementation-planner/SKILL.md": {
-      "version": "9",
+      "version": "11",
       "description": "Mandatory AI implementation planner skill for turning one approved User Story into small, story-local implementation step files.",
       "changes": [
-        "Adds a pipeline contract that clarifies required inputs, owned implementation plan outputs, stop conditions, and stage boundaries for implementation planning."
+        "Adds a plan review gate so newly created implementation plans wait for user approval before execution.",
+        "Clarifies that next-story planning handoffs from the executor must stop after planning and wait for approval."
       ]
     },
     "skills/ai-implementation-plan-executor/SKILL.md": {
-      "version": "14",
-      "description": "Mandatory AI implementation plan executor skill for implementing existing story implementation plans one reviewed step at a time.",
+      "version": "16",
+      "description": "Mandatory AI implementation plan executor skill for implementing full story plans before story-level review and commit.",
       "changes": [
-        "Adds a pipeline contract that clarifies required inputs, current-step outputs, stop conditions, and review-gated execution boundaries."
+        "Changes execution from per-step approval to full-story execution followed by one story-level review gate.",
+        "Marks all completed steps approved and commits once after the completed story is approved.",
+        "Continues Epics automatically by implementing the next planned story or planning the next unplanned story and waiting for plan approval."
       ]
     },
     "skills/ai-prompt-engineer-master/SKILL.md": {
@@ -136,10 +147,10 @@
       ]
     },
     "skills/ux-expert/SKILL.md": {
-      "version": "5",
+      "version": "6",
       "description": "Selectable UX expert skill for UI-changing features, responsive design, flows, states, accessibility, and binding mockups.",
       "changes": [
-        "Adds a pipeline contract that clarifies required inputs, owned output, stop conditions, and UI-impact boundaries for UX design work."
+        "Updates boundary wording to use Deep Module Maps."
       ]
     }
   }

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

@@ -1,45 +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.
+- 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, step, or feature has UI impact.
-- Relevant repo files, validation output, and implementation skills needed for the current step.
+- `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 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.
+- 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 implementation plan is missing, empty, invalid, or has no ordered step files; direct the user to `ai-implementation-planner`.
+- 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, 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.
+- 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, 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.
+- 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
 
@@ -63,12 +67,12 @@ 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 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.
+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.
 
@@ -81,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
@@ -98,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.
@@ -112,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:
 
@@ -129,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
@@ -153,64 +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`.
+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`.
 
-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.
+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.
 
-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.
-
-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.
-
-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
-- 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
+- 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
-- stop and ask before moving work into an unrelated Product Context unless the approved step or technical design explicitly justifies it
+- 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
-- silently move work into unrelated or unapproved Product Contexts
+- 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,13 @@
 ---
 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
 
@@ -30,13 +30,15 @@ Turn one approved User Story into concrete Markdown step files an AI coding agen
 - 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, Product Context Maps, feature briefs, technical designs, UX specs, Epics, User Stories, or production code.
+- 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/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 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
 
@@ -62,7 +64,7 @@ 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.
+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.
 
@@ -132,8 +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 Product Contexts unless cross-context work is explicit in the source artifacts
-- call out cross-context ownership and coordination in the relevant step files
+- 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:
 
@@ -143,7 +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 Product Contexts; add a stop-and-ask condition instead
+- move work into unrelated or unapproved Deep Modules; add a stop-and-ask condition instead
 
 ## Workflow
 
@@ -163,12 +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, user value, and approved Product Context ownership when present.
+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
-- Product Context boundaries, ownership, and any explicit cross-context work
+- 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
@@ -219,7 +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 Product Context boundaries in `Scope`; call out cross-context work explicitly when required
+- 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
 
@@ -236,16 +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 Product Context boundaries and stop before unrelated context movement
+- 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.