@juancr11/sibu 0.20.0 → 0.21.0

package/bin/modules/template-catalog/templates.js

@@ -89,6 +89,15 @@ export function renderWorkerToolboxRouting({ profile, selectedLanguageSkills, se
         selectedWorkflowSkills,
         selectedDatabaseSkills,
     });
+    const selectedArchitectureSection = selectedArchitectureSkill
+        ? `### Selected architecture guidance
+- Required: read \`${getSharedSkillTargetPath(selectedArchitectureSkill)}\` before ${profile === 'planner' ? 'writing implementation plan steps' : 'executing or reviewing implementation steps'}.
+- Treat this selected architecture guidance as binding for boundaries, dependency direction, sequencing, and reviewable constraints.
+- If the selected architecture skill path is missing or unavailable, stop and tell the main agent to direct the user to run \`sibu sync\`; do not choose, infer, or substitute architecture guidance.`
+        : `### Selected architecture guidance
+- No selected architecture skill was provided to this worker routing profile.
+- Hard-stop architecture-dependent ${profile} work and tell the main agent to direct the user to run \`sibu sync\` to repair workflow configuration.
+- Do not choose, infer, or substitute architecture guidance from repository structure.`;
     const selectedSkillLines = selectedSkills.map((skill) => `- ${skill.name}: read \`${getSharedSkillTargetPath(skill)}\` when relevant. ${skill.routingInstruction}`);
     const selectedSkillsSection = selectedSkillLines.length > 0
         ? selectedSkillLines.join('\n')
@@ -102,6 +111,8 @@ export function renderWorkerToolboxRouting({ profile, selectedLanguageSkills, se
 - Treat distilled skill constraints from the packet as binding task constraints.
 - If an optional relevant skill is not installed and you encounter an unmapped language, framework, database, or architecture pattern, do not guess silently; continue only when safe and flag the gap as a ${profile === 'planner' ? 'plan risk' : 'Review Gate risk'}.
 
+${selectedArchitectureSection}
+
 ### Optional installed skills relevant to ${profile} work
 ${profile === 'executor' ? '- Structured Logging: read `.agents/skills/structured-logging/SKILL.md` when the story involves logs, workflows, handlers, jobs, external calls, errors, retries, long-running operations, state changes, or other observability-relevant behavior.\n' : ''}${selectedSkillsSection}`;
 }
@@ -132,7 +143,6 @@ function collectWorkerRelevantSkills({ selectedLanguageSkills, selectedFramework
         ...selectedLanguageSkills,
         ...selectedFrameworkSkills,
         ...selectedDatabaseSkills,
-        ...(selectedArchitectureSkill ? [selectedArchitectureSkill] : []),
         ...implementationRelevantWorkflowSkills,
     ];
 }

package/bin/modules/workflow-configuration-manager/stop-managing-file/handler.js

@@ -61,6 +61,13 @@ export function stopSelectedSkill({ rootPath, state, skillName }) {
     if (!isSkillSelected(state, resolution.resolved)) {
         return { status: 'noop', message: `${resolution.resolved.skill.name} is not selected.` };
     }
+    if (resolution.resolved.kind === 'architecture') {
+        return {
+            status: 'blocked',
+            message: `Cannot stop ${resolution.resolved.skill.name} because every healthy Sibu workflow requires one selected architecture skill.`,
+            hint: 'Architecture skill replacement is not supported yet; keep the existing architecture skill.',
+        };
+    }
     const stoppedPaths = getSkillManagedPaths(rootPath, state, resolution.resolved);
     if (stoppedPaths.length === 0) {
         return { status: 'blocked', message: `${resolution.resolved.skill.name} does not have a managed target for the selected agents.` };

package/bin/modules/workflow-configuration-manager/use-skill/handler.js

@@ -91,7 +91,7 @@ export function getNextSkillSelection(state, skillName) {
                 return {
                     status: 'blocked',
                     message: `Cannot select ${resolution.resolved.skill.name} because another architecture skill is already selected.`,
-                    hint: 'Architecture skill replacement is not supported yet. Keep the existing architecture skill or stop managing it first.',
+                    hint: 'Every healthy Sibu workflow requires one selected architecture skill. Architecture skill replacement is not supported yet; keep the existing architecture skill.',
                 };
             }
             return {

package/bin/modules/workflow-health-inspector/handler.js

@@ -114,7 +114,14 @@ function addUnsupportedSelectionIssues(state, issues) {
             issues.push({ severity: 'warning', message: `State references unsupported framework skill: ${selectedFrameworkSkill}.` });
         }
     }
-    if (state.selectedArchitectureSkill && !SELECTABLE_ARCHITECTURE_SKILLS.some((skill) => skill.id === state.selectedArchitectureSkill)) {
+    if (!state.selectedArchitectureSkill) {
+        issues.push({
+            severity: 'error',
+            message: 'State is missing a selected architecture skill.',
+            hint: 'Run `sibu sync` to choose required architecture guidance for this workflow.',
+        });
+    }
+    else if (!SELECTABLE_ARCHITECTURE_SKILLS.some((skill) => skill.id === state.selectedArchitectureSkill)) {
         issues.push({ severity: 'warning', message: `State references unsupported architecture skill: ${state.selectedArchitectureSkill}.` });
     }
     for (const selectedDatabaseSkill of state.selectedDatabaseSkills ?? []) {

package/bin/support/interactive-guidance/index.js

@@ -1 +1 @@
-export { askForArchitectureSkill, askForDatabaseSkills, askForFrameworkSkills, askForLanguageSkills, askForMcpServers, askForNotionDocsParentPage, askForMissingFrameworkSkills, askForNewArchitectureSkill, askForNewLanguageSkills, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, MCP_SERVER_SELECTION_MESSAGE, getPromptableWorkflowSkills, renderIntro, shouldAskForNewLanguageSkills, } from './prompts.js';
+export { askForArchitectureSkill, askForDatabaseSkills, askForFrameworkSkills, askForLanguageSkills, askForMcpServers, askForNotionDocsParentPage, askForMissingFrameworkSkills, askForNewArchitectureSkill, askForNewLanguageSkills, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, getPromptableWorkflowSkills, getInitArchitectureSkillOptions, getSyncArchitectureSkillOptions, MCP_SERVER_SELECTION_MESSAGE, renderIntro, shouldAskForNewLanguageSkills, } from './prompts.js';

package/bin/support/interactive-guidance/prompts.js

@@ -127,26 +127,33 @@ async function askForFrameworkSkillSelection({ message, cancelMessage, }) {
     }
     return SELECTABLE_FRAMEWORK_SKILLS.filter((skill) => selectedFrameworkSkillIds.includes(skill.id));
 }
+export function getInitArchitectureSkillOptions() {
+    return SELECTABLE_ARCHITECTURE_SKILLS.map((skill) => ({
+        value: skill.id,
+        label: skill.name,
+        hint: skill.description,
+    }));
+}
+export function getSyncArchitectureSkillOptions() {
+    return getInitArchitectureSkillOptions();
+}
 export async function askForArchitectureSkill() {
     const selectedArchitectureSkillId = await select({
         message: 'Select an architecture style for this project.',
-        options: [
-            { value: 'none', label: 'None', hint: 'Do not install opinionated architecture guidance.' },
-            ...SELECTABLE_ARCHITECTURE_SKILLS.map((skill) => ({
-                value: skill.id,
-                label: skill.name,
-                hint: skill.description,
-            })),
-        ],
+        options: getInitArchitectureSkillOptions(),
     });
     if (isCancel(selectedArchitectureSkillId)) {
         cancel('Initialization cancelled.');
         process.exit(0);
     }
-    if (selectedArchitectureSkillId === 'none') {
-        return undefined;
+    return getSelectableArchitectureSkill(selectedArchitectureSkillId);
+}
+function getSelectableArchitectureSkill(selectedArchitectureSkillId) {
+    const selectedArchitectureSkill = SELECTABLE_ARCHITECTURE_SKILLS.find((skill) => skill.id === selectedArchitectureSkillId);
+    if (!selectedArchitectureSkill) {
+        throw new Error(`Unknown architecture skill selected: ${selectedArchitectureSkillId}`);
     }
-    return SELECTABLE_ARCHITECTURE_SKILLS.find((skill) => skill.id === selectedArchitectureSkillId);
+    return selectedArchitectureSkill;
 }
 export function getPromptableWorkflowSkills(excludedWorkflowSkillIds = []) {
     const excludedIds = new Set(excludedWorkflowSkillIds);
@@ -232,28 +239,19 @@ export async function askForNewArchitectureSkill(state) {
     }
     const selectedArchitectureSkillId = await select({
         message: 'Select an architecture style for this project.',
-        options: [
-            { value: 'none', label: 'None', hint: 'Do not install opinionated architecture guidance.' },
-            ...SELECTABLE_ARCHITECTURE_SKILLS.map((skill) => ({
-                value: skill.id,
-                label: skill.name,
-                hint: skill.description,
-            })),
-        ],
+        options: getSyncArchitectureSkillOptions(),
     });
     if (isCancel(selectedArchitectureSkillId)) {
         cancel('Sync cancelled.');
         process.exit(0);
     }
     return {
-        state: selectedArchitectureSkillId === 'none'
-            ? state
-            : {
-                ...state,
-                selectedArchitectureSkill: selectedArchitectureSkillId,
-                updatedAt: new Date().toISOString(),
-            },
-        changedState: selectedArchitectureSkillId !== 'none',
+        state: {
+            ...state,
+            selectedArchitectureSkill: selectedArchitectureSkillId,
+            updatedAt: new Date().toISOString(),
+        },
+        changedState: true,
     };
 }
 export async function askForProjectOverview() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "templateVersion": "136",
+  "templateVersion": "138",
   "templates": {
     "AGENTS.md": {
       "version": "35",
@@ -90,11 +90,10 @@
       ]
     },
     "skills/technical-design-writer/SKILL.md": {
-      "version": "21",
+      "version": "22",
       "description": "Mandatory technical design writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Treats Feature Brief and Deep Module Map as sibling upstream inputs for technical design.",
-        "Allows newer feature briefs to omit a Deep Module section while still requiring technical design to map the feature to existing Deep Modules."
+        "Requires selected architecture guidance before technical design, applies it to implementation boundaries, and directs missing guidance repair to `sibu sync`."
       ]
     },
     "skills/typescript/SKILL.md": {
@@ -119,17 +118,17 @@
       ]
     },
     "skills/architecture/ddd-hexagonal/SKILL.md": {
-      "version": "8",
+      "version": "9",
       "description": "Selectable back-end architecture skill for DDD and Hexagonal Architecture.",
       "changes": [
-        "Adds a framework-agnostic adapter dependency rule requiring delivery entrypoints to call application/orchestration boundaries instead of infrastructure or domain workflow internals."
+        "Adds downstream handoff guidance for applying DDD + Hexagonal Architecture during technical design, implementation planning, execution, and review."
       ]
     },
     "skills/architecture/command-pattern/SKILL.md": {
-      "version": "7",
+      "version": "8",
       "description": "Selectable architecture skill for command-oriented vertical slices using Command Pattern, Hexagonal Architecture, and DDD principles.",
       "changes": [
-        "Routes workflow, handler, entrypoint, job, and operational outcome logging concerns to the structured logging skill."
+        "Adds downstream handoff guidance for applying command-oriented vertical slices during technical design, implementation planning, execution, and review."
       ]
     },
     "skills/nextjs/SKILL.md": {
@@ -154,31 +153,31 @@
       ]
     },
     "skills/ai-implementation-planner/SKILL.md": {
-      "version": "17",
+      "version": "18",
       "description": "Mandatory AI implementation planner gatekeeper for routing one User Story into story-local implementation step files.",
       "changes": [
-        "Requires the planner to spawn the Sibu implementation planner sub-agent whenever spawning is available and limits inline fallback to host capability blockers."
+        "Requires selected architecture guidance before implementation planning and passes architecture constraints into story-local planning context."
       ]
     },
     "skills/ai-implementation-planner-toolbox/SKILL.md": {
-      "version": "1",
+      "version": "2",
       "description": "Worker-only planner toolbox skill for fresh-context Sibu implementation planner sub-agents.",
       "changes": [
-        "Adds a planner toolbox skill with focused worker routing, skill-loading rules, and story-local implementation plan format guidance."
+        "Requires planner worker packets to include selected architecture guidance and stops missing guidance work for `sibu sync` repair."
       ]
     },
     "skills/ai-implementation-plan-executor/SKILL.md": {
-      "version": "25",
+      "version": "26",
       "description": "Mandatory AI implementation plan executor gatekeeper for story execution, review, approval metadata, commit, and feature continuation.",
       "changes": [
-        "Updates executor packet guidance to include structured logging when implementation stories touch observability-relevant code."
+        "Requires selected architecture guidance before execution and passes architecture constraints into executor review context."
       ]
     },
     "skills/ai-implementation-executor-toolbox/SKILL.md": {
-      "version": "2",
+      "version": "3",
       "description": "Worker-only executor toolbox skill for fresh-context Sibu implementation executor sub-agents.",
       "changes": [
-        "Guides executor workers to load structured logging for observability-relevant implementation stories."
+        "Requires executor worker packets to include selected architecture guidance and apply it during implementation and review."
       ]
     },
     "skills/feature-idea-capture/SKILL.md": {
@@ -204,10 +203,10 @@
       ]
     },
     "skills/architecture/layered-architecture/SKILL.md": {
-      "version": "1",
+      "version": "2",
       "description": "Selectable lightweight architecture skill for pragmatic controllers, services, models, and repositories guidance.",
       "changes": [
-        "Adds a Layered Architecture skill for smaller apps that need simple separation of concerns."
+        "Adds downstream handoff guidance for applying Layered Architecture during technical design, implementation planning, execution, and review."
       ]
     },
     "skills/export-to-github/SKILL.md": {

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

@@ -18,6 +18,7 @@ Use only the narrow packet from the main agent. The packet must include:
 - exactly one User Story path or one story-local `.impl_plan/` folder
 - required source artifact paths: story, Epic brief, feature brief, technical design, and UX spec when the story, plan, or feature has UI impact
 - this toolbox skill path
+- selected architecture skill path and distilled architecture constraints
 - required skill paths, including `clean-code` and `structured-logging` when the story touches observability-relevant code
 - optional installed skill paths relevant to the story
 - distilled skill constraints that are binding for this execution task
@@ -26,14 +27,17 @@ Use only the narrow packet from the main agent. The packet must include:
 
 If the packet names multiple stories, multiple plans, an Epic without one selected story, or no executable target, stop and ask the main agent for exactly one story or `.impl_plan/` path.
 
+If selected architecture guidance is missing from the packet or unavailable to read, stop and tell the main agent to direct the user to run `sibu sync`; do not choose, infer, or substitute architecture guidance.
+
 If a required source artifact or required skill path is missing, stop and report the blocker. Do not invent scope from partial context.
 
 ## Execution rules
 
-- Read the story, ordered step files, required source artifacts, required skills, and relevant optional installed skills before execution.
+- Read the story, ordered step files, required source artifacts, required skills, the selected architecture skill, and relevant optional installed skills before execution.
 - If `structured-logging` is provided in the packet, apply it only to observability-relevant code paths and do not duplicate its policy in other skill guidance.
+- Apply selected architecture guidance during implementation and review, including boundaries, dependency direction, sequencing, and architecture-specific risks.
 - Execute all unapproved step files in filename order.
-- Keep changes inside the story scope, step scope, source artifacts, and distilled constraints.
+- Keep changes inside the story scope, step scope, source artifacts, selected architecture constraints, and distilled constraints.
 - Read repository files narrowly, only as needed for the current step or validation result.
 - Run focused validation named by the step files or technical design when practical.
 - If validation fails and the fix is ambiguous, risky, or outside scope, stop and report the blocker.

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

@@ -20,6 +20,7 @@ When a compatible sub-agent spawn capability is available and permitted by the h
 - 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.
 - The executor toolbox skill at `.agents/skills/ai-implementation-executor-toolbox/SKILL.md` when sub-agent spawning is available.
+- Selected architecture guidance for the workflow.
 - Required and relevant installed skill paths for the executor packet, including `clean-code` and `structured-logging` when the story touches observability-relevant code.
 
 ### What this skill writes
@@ -34,6 +35,7 @@ When a compatible sub-agent spawn capability is available and permitted by the h
 - The user does not provide or clearly identify exactly one User Story file or `.impl_plan/` folder.
 - 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`.
+- Selected architecture guidance is missing, unavailable, or ambiguous; stop and tell the user to run `sibu sync` to repair workflow configuration before implementation execution. Do not choose, infer, or substitute architecture guidance yourself.
 - 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.
 
@@ -45,6 +47,14 @@ When a compatible sub-agent spawn capability is available and permitted by the h
 - 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 let the executor worker write approval metadata or run `git commit`, `git stash`, or `git reset`.
+- Do not choose or infer architecture guidance when it is missing; selected architecture is repo-owned workflow configuration repaired through `sibu sync`.
+
+
+## Selected architecture guidance gate
+
+Before execution, identify and read the workflow's selected architecture skill. If selected architecture guidance is missing, unavailable, or ambiguous, hard-stop and tell the user to run `sibu sync` to repair Sibu workflow configuration. Do not choose architecture guidance, infer it from repository structure, or continue with generic architecture assumptions.
+
+When selected architecture guidance is present, treat it as binding execution and review context. Pass the selected architecture skill path and distilled architecture constraints to the executor worker, and apply them when evaluating step order, implementation boundaries, dependency direction, and review risks.
 
 ## Required source context gate
 
@@ -85,14 +95,15 @@ Build a narrow executor packet for the worker. The packet must include:
 - story, Epic brief, feature brief, technical design, and UX path when relevant
 - executor toolbox path: `.agents/skills/ai-implementation-executor-toolbox/SKILL.md`
 - required skill paths, always including `.agents/skills/clean-code/SKILL.md`, and including `.agents/skills/structured-logging/SKILL.md` when the story involves logs, workflows, handlers, jobs, external calls, errors, retries, long-running operations, state changes, or other observability-relevant behavior
-- relevant optional installed skill paths only when applicable, such as TypeScript, React, Next.js, UX Expert, Command Pattern, DDD/Hexagonal, Layered Architecture, PostgreSQL Expert, or AI Prompt Engineer Master
-- distilled skill constraints, including story scope, validation expectations, Deep Module boundaries, UX constraints when relevant, and “do not write approval metadata or run git commit/stash/reset”
+- selected architecture skill path as required architecture context
+- relevant optional installed skill paths only when applicable, such as TypeScript, React, Next.js, UX Expert, PostgreSQL Expert, or AI Prompt Engineer Master
+- distilled skill constraints, including story scope, validation expectations, Deep Module boundaries, selected architecture constraints, UX constraints when relevant, and “do not write approval metadata or run git commit/stash/reset”
 - approval and commit rules: the worker may edit the working tree and run validation, but final approval metadata and commit execution remain with the main agent after explicit user approval
 - expected output format: changed files, completed steps, validation commands/results, risks, follow-up questions, and approval state
 
 Do not include exporter skills such as `export-to-github` or `export-to-notion` in the executor packet. Do not include `structured-logging` for stories limited to trivial pure logic with no observability-relevant behavior.
 
-The worker must use only the packet, the toolbox, listed skill files, source artifacts, and narrow repo inspection required for the story. Do not pass the full main conversation context.
+The worker must use only the packet, the toolbox, listed skill files including the selected architecture skill, source artifacts, and narrow repo inspection required for the story. Do not pass the full main conversation context.
 
 ## Fallback matrix
 

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

@@ -21,6 +21,7 @@ This planner is normally an internal helper for `ai-implementation-plan-executor
 - The feature's `technical_design.md`.
 - `docs/features/<feature-slug>/ux.md` only when the story or feature has UI impact.
 - The planner toolbox skill at `.agents/skills/ai-implementation-planner-toolbox/SKILL.md` when sub-agent spawning is available.
+- Selected architecture guidance for the workflow.
 - Required and relevant installed skill paths for the planner packet, including `clean-code`.
 
 ### What this skill writes
@@ -33,6 +34,7 @@ This planner is normally an internal helper for `ai-implementation-plan-executor
 - 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 belongs to another pipeline stage, such as writing production code, executing an existing implementation plan, creating stories, or performing another pipeline stage.
+- Selected architecture guidance is missing, unavailable, or ambiguous; stop and tell the user to run `sibu sync` to repair workflow configuration before implementation planning. Do not choose, infer, or substitute architecture guidance yourself.
 - Worker delegation is requested but required worker packet context cannot be assembled.
 
 ### What this skill must not do
@@ -42,6 +44,14 @@ This planner is normally an internal helper for `ai-implementation-plan-executor
 - 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 ask for a plan-approval gate before executor handoff unless the user explicitly requested planning-only.
+- Do not choose or infer architecture guidance when it is missing; selected architecture is repo-owned workflow configuration repaired through `sibu sync`.
+
+
+## Selected architecture guidance gate
+
+Before delegating or planning inline, identify and read the workflow's selected architecture skill. If selected architecture guidance is missing, unavailable, or ambiguous, hard-stop and tell the user to run `sibu sync` to repair Sibu workflow configuration. Do not choose architecture guidance, infer it from repository structure, or continue with generic architecture assumptions.
+
+When selected architecture guidance is present, treat it as binding planning context. Apply it to story-local implementation step sequencing, boundaries, dependency direction, and reviewable constraints while still trusting `technical_design.md` for feature-specific Deep Module boundaries.
 
 ## Required input
 
@@ -83,8 +93,9 @@ Build a narrow planner packet for the worker. The packet must include:
 - Epic brief, feature brief, technical design, and UX path when relevant
 - planner toolbox path: `.agents/skills/ai-implementation-planner-toolbox/SKILL.md`
 - required skill paths, always including `.agents/skills/clean-code/SKILL.md`
-- relevant optional installed skill paths only when applicable, such as TypeScript, React, Next.js, UX Expert, Command Pattern, DDD/Hexagonal, Layered Architecture, PostgreSQL Expert, or AI Prompt Engineer Master
-- distilled skill constraints, such as “create only `.impl_plan/*.md` files,” “do not write production code,” “inspect narrowly,” and any story-specific architecture or UX constraints
+- selected architecture skill path as required architecture context
+- relevant optional installed skill paths only when applicable, such as TypeScript, React, Next.js, UX Expert, PostgreSQL Expert, or AI Prompt Engineer Master
+- distilled skill constraints, such as “create only `.impl_plan/*.md` files,” “do not write production code,” “inspect narrowly,” selected architecture constraints, and any story-specific architecture or UX constraints
 - expected output format: plan folder, ordered step files created or updated, source artifacts and skills used, and risks/blockers
 
 Do not include exporter skills such as `export-to-github` or `export-to-notion` in the planner packet.
@@ -102,7 +113,7 @@ Before writing step files inline, read and apply:
 - `clean-code` always
 - relevant installed language skills such as `typescript` for `.ts` or `.tsx` work
 - relevant installed framework skills such as `react` or `nextjs`
-- relevant installed architecture skills such as `command-pattern`, `ddd-hexagonal`, or `layered-architecture`
+- the selected installed architecture skill such as `command-pattern`, `ddd-hexagonal`, or `layered-architecture`; if it is missing, stop and direct repair to `sibu sync`
 - relevant installed database skills such as `postgresql-expert`
 - `ux-expert` only when UI/UX implementation planning is in scope and the skill is installed
 - `ai-prompt-engineer-master` when prompt, agent, or reusable AI instruction templates are in scope

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

@@ -18,6 +18,7 @@ Use only the narrow packet from the main agent. The packet must include:
 - exactly one User Story path
 - required source artifact paths: Epic brief, feature brief, technical design, and UX spec when the story or feature has UI impact
 - this toolbox skill path
+- selected architecture skill path and distilled architecture constraints
 - required skill paths, including `clean-code`
 - optional installed skill paths relevant to the story
 - distilled skill constraints that are binding for this planning task
@@ -25,14 +26,17 @@ Use only the narrow packet from the main agent. The packet must include:
 
 If the packet names multiple stories, an Epic without one story, a feature without one story, or no story, stop and ask the main agent for exactly one User Story path.
 
+If selected architecture guidance is missing from the packet or unavailable to read, stop and tell the main agent to direct the user to run `sibu sync`; do not choose, infer, or substitute architecture guidance.
+
 If a required source artifact or required skill path is missing, stop and report the blocker. Do not invent scope from partial context.
 
 ## Planning rules
 
 - Read the story and required source artifacts before writing step files.
-- Read required skills and relevant optional installed skills from the packet before writing step files.
+- Read required skills, the selected architecture skill, and relevant optional installed skills from the packet before writing step files.
 - Inspect repository files narrowly, only enough to make the plan executable.
-- Preserve story scope, acceptance criteria, technical design boundaries, and UX constraints when applicable.
+- Preserve story scope, acceptance criteria, technical design boundaries, selected architecture constraints, and UX constraints when applicable.
+- Apply selected architecture guidance to story-local implementation step ordering, boundaries, dependency direction, and reviewable constraints.
 - Create ordered story-local implementation step files under `<story-slug>.impl_plan/*.md`.
 - Never write production code, tests, templates, or unrelated documentation.
 - Never create or change product vision, Deep Module Map, feature brief, technical design, UX, Epic, or User Story artifacts.

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

@@ -10,6 +10,27 @@ Use this skill to design and implement software features as independent, end-to-
 
 ---
 
+
+## Downstream Sibu workflow handoff
+
+Use this selected architecture model as binding guidance for technical design, implementation planning, execution, and review. Downstream artifacts should make the command boundary and execution flow explicit without adding ceremony that does not protect the slice.
+
+### Technical design
+
+Design the executable operation first. Name the owning Deep Module and feature slice, then define the Command intent, Result contract, Handler responsibilities, required Ports, driving entrypoints, and driven Adapters. Business rules and orchestration belong in the Handler or domain objects it coordinates; infrastructure behavior belongs behind Ports in adapters; entrypoints only adapt transport input into Commands and translate Results. Dependencies flow entrypoint -> Command -> Handler -> Ports, with adapters implementing Ports from outside the slice.
+
+### Implementation planning
+
+Plan each story as one or more end-to-end command slices. For each slice, sequence work as Command and Result shape first, Port contracts second, Handler orchestration and business validation third, Adapter implementations fourth, and entrypoint wiring last. Keep tests aligned to that sequence: handler tests with fake ports before adapter or transport tests.
+
+### Implementation execution
+
+Implementation agents should build vertical slices instead of technical-layer batches. Avoid handlers that instantiate databases, clients, or framework objects; entrypoints that call repositories directly; commands with behavior; ports shared too early across unrelated slices; and feature slices importing another slice's internals. Use composition/bootstrap code for wiring concrete adapters into handlers.
+
+### Review and compliance
+
+Reviewers should check that every operation has an explicit Command, focused Handler, Result, and required Ports; handlers are transport-agnostic; adapters implement ports without leaking SDK/database shapes inward; entrypoints are thin; and dependencies follow the command flow. A change that requires touching unrelated feature slices or framework code to alter handler business behavior signals a boundary problem.
+
 ## 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?”

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

@@ -27,6 +27,27 @@ This skill is backend-focused. It does not cover frontend component architecture
 
 If a simpler structure preserves clear boundaries, prefer the simpler structure.
 
+
+## Downstream Sibu workflow handoff
+
+Use this selected architecture model as binding guidance for technical design, implementation planning, execution, and review. Keep the guidance concise in downstream artifacts, but make the boundary decisions explicit.
+
+### Technical design
+
+Design use-case-first and domain-first. Name the owning Deep Module, then identify the domain concepts, invariants, and application use cases before choosing infrastructure details. Place business rules and invariants in `domain/**`; place orchestration, transaction coordination, input/output contracts, and outgoing ports in `application/**`; place repositories, SDK clients, persistence mappings, and anti-corruption translation in `infra/**`; keep entrypoints as driving adapters. Dependencies must point inward: entrypoint -> application -> domain + ports, and infrastructure -> application/domain contracts.
+
+### Implementation planning
+
+Plan slices around one externally meaningful use case at a time. For each slice, sequence the work as domain model/invariants first, application use case and ports second, infrastructure adapters third, and framework or CLI entrypoints last. Call out any cross-module dependency explicitly instead of sharing internals or inventing new modules.
+
+### Implementation execution
+
+Implementation agents should keep framework, database, filesystem, SDK, and transport types out of domain and application boundaries unless they are explicit adapter translations. Define application orchestration and ports before infrastructure adapters, then wire entrypoints last. Avoid direct entrypoint-to-database calls, infrastructure imports from the domain, anemic pass-through use cases that hide business rules in adapters, and broad shared services created only for convenience.
+
+### Review and compliance
+
+Reviewers should check that use cases and domain concepts were designed before adapters, invariants live in the domain, application orchestration owns the workflow, ports describe required external capabilities, adapters translate at the boundary, entrypoints stay thin, and all dependencies point inward. If a business rule changes because an external DTO, database row, or framework object changed, the hexagonal boundary is leaking.
+
 ## Deep Module compatibility
 
 Deep Modules answer “where does this implementation work belong?” DDD + Hexagonal answers “how is that module structured internally?”

package/templates/skills/architecture/layered-architecture/SKILL.md

@@ -15,6 +15,27 @@ This is Sibu's pragmatic layered architecture guidance. It is not the only valid
 
 Keep the layers useful, not ceremonial. If splitting a small function across layers makes the code harder to understand, prefer the simpler code.
 
+
+## Downstream Sibu workflow handoff
+
+Use this selected architecture model as binding guidance for technical design, implementation planning, execution, and review. Keep the design lightweight, but make layer ownership and dependency direction clear.
+
+### Technical design
+
+Design the user-facing operation and service responsibility first, then decide which models and repositories the service needs. Business rules and workflow orchestration belong in services, simple invariants and meaningful states belong in models, persistence details belong in repositories, and framework or transport adaptation belongs in controllers. Dependencies should flow controller -> service -> repository and service -> model; repositories may map storage records to models but should not own workflows.
+
+### Implementation planning
+
+Plan work by feature behavior, not by sweeping all controllers or all repositories at once. For each slice, sequence the service contract and business behavior first, model changes second, repository interface/implementation third, and controller wiring last. Keep the layer split proportional: use existing project folders when clear and avoid adding layers where a small function stays easier to understand.
+
+### Implementation execution
+
+Implementation agents should keep controllers thin, services framework-free, repositories persistence-focused, and models meaningful. Avoid controller-to-repository shortcuts, services that embed SQL/ORM/SDK calls, repositories that return raw storage details to services, models that import controllers or repositories, and miscellaneous service/helper bags that hide unrelated behavior.
+
+### Review and compliance
+
+Reviewers should check that controllers only adapt input/output and call services, services coordinate business behavior without framework objects, repositories hide data access and persistence mappings, models express useful concepts or states without over-modeling, and dependency flow follows the approved layer direction. If the layer split makes a small change harder to understand, simplify while preserving controller/service/repository boundaries.
+
 ## Layer responsibilities
 
 ### Controllers

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

@@ -16,7 +16,8 @@ Write the smallest useful technical design doc for an approved feature: enough f
 - Enough feature and module context to map the feature brief to one or more existing Deep Modules during technical design.
 - Relevant existing repo files and flows needed to make implementation direction concrete.
 - `docs/features/<feature-slug>/ux.md` only when the feature has UI impact.
-- Relevant implementation guidance skills such as `clean-code`, selected architecture skills, language skills, or framework skills.
+- Selected architecture guidance installed under `.agents/skills/architecture/` or rendered as the selected architecture skill path for this workflow.
+- Relevant implementation guidance skills such as `clean-code`, language skills, or framework skills.
 
 ### What this skill writes
 
@@ -28,6 +29,7 @@ Write the smallest useful technical design doc for an approved feature: enough f
 - `docs/deep-module-map.md` is missing; direct the user to `deep-module-map-writer`.
 - The feature brief and Deep Module Map cannot be reconciled to existing Deep Modules after focused clarification, or the selected modules are missing, ambiguous, or inconsistent with the map.
 - The feature has UI impact and `docs/features/<feature-slug>/ux.md` is missing; direct the user to `ux-expert`.
+- Selected architecture guidance is missing or cannot be identified; stop and tell the user to run `sibu sync` to repair workflow configuration before technical design. Do not choose, infer, or substitute architecture guidance yourself.
 - The request belongs to another pipeline stage, such as feature definition, UX design, Scrum planning, implementation planning, or implementation execution.
 
 ### What this skill must not do
@@ -36,6 +38,7 @@ Write the smallest useful technical design doc for an approved feature: enough f
 - Do not invent new Deep Modules or move work into modules that cannot be justified from the Feature Brief and Deep Module Map.
 - Do not redesign binding UX mockups.
 - Do not duplicate architecture, language, framework, or clean-code skill guidance.
+- Do not choose or infer architecture guidance when it is missing; selected architecture is repo-owned workflow configuration repaired through `sibu sync`.
 - Do not skip the interview or the final “I am clear; are you good?” check-in before writing. Once the user confirms there is nothing else to cover, write without requiring a recap, artifact approval, or separate summary confirmation.
 
 ## Grounding
@@ -47,11 +50,19 @@ Before writing, read:
 3. the feature brief
 4. `docs/features/<feature-slug>/ux.md` when the feature has UI impact
 5. `clean-code`
-6. any selected architecture, language, or framework skills that apply
-7. relevant existing repo files and flows
+6. the selected architecture skill for this workflow
+7. any selected language or framework skills that apply
+8. relevant existing repo files and flows
 
 Apply those inputs. Do not summarize them back into the technical design unless a specific implication changes the implementation.
 
+
+## Selected architecture guidance gate
+
+Before interviewing or writing, identify the workflow's selected architecture skill and read its installed guidance. If selected architecture guidance is missing, unavailable, or ambiguous, hard-stop and tell the user to run `sibu sync` to repair Sibu workflow configuration. Do not choose an architecture, infer one from the codebase, or proceed with generic architecture advice.
+
+When selected architecture guidance is present, treat it as binding for design order, module/layer boundaries, dependency direction, and concrete implementation boundaries. Apply it through the technical design by naming project-specific boundaries and sequencing decisions; do not paste or restate the architecture skill itself.
+
 ## Required input
 
 Require a Markdown feature brief. If the user only has a vague idea, route to `feature-brief-writer` first.
@@ -86,7 +97,7 @@ For UI-related features, `ux.md` is source context, not inspiration. If `ux.md`
 
 Translate product intent into implementation direction.
 
-Deep Modules answer “where does this implementation work belong?” Architecture guidance answers “how is that module structured internally?” Translate the existing Deep Modules selected or mapped from the Feature Brief plus Deep Module Map into implementation boundaries appropriate for the selected architecture. Capture those boundaries in the technical design so downstream Scrum planning, implementation planning, and execution can trust the technical design instead of rereading the Deep Module Map by default.
+Deep Modules answer “where does this implementation work belong?” Selected architecture guidance answers “how is that module structured internally?” Translate the existing Deep Modules selected or mapped from the Feature Brief plus Deep Module Map into implementation boundaries appropriate for the selected architecture. Capture those boundaries in the technical design so downstream Scrum planning, implementation planning, and execution can trust the technical design instead of rereading the Deep Module Map by default.
 
 When a feature crosses a framework or delivery boundary, include the allowed orchestration/application entrypoint and the forbidden lower-level dependencies. Keep this framework-agnostic: name roles like framework adapter, application/orchestration boundary, domain, port, and infrastructure, then add concrete project paths only where useful.