@juancr11/sibu 0.18.0 → 0.20.0

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

@@ -7,6 +7,14 @@ export const MANDATORY_SKILLS = [
             claude: '.agents/skills/clean-code/SKILL.md',
         },
     },
+    {
+        templateRelativePath: 'skills/structured-logging/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/structured-logging/SKILL.md',
+            gemini: '.agents/skills/structured-logging/SKILL.md',
+            claude: '.agents/skills/structured-logging/SKILL.md',
+        },
+    },
     {
         templateRelativePath: 'skills/product-vision-writer/SKILL.md',
         targetRelativePathsByAgent: {

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

@@ -103,7 +103,7 @@ export function renderWorkerToolboxRouting({ profile, selectedLanguageSkills, se
 - 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'}.
 
 ### Optional installed skills relevant to ${profile} work
-${selectedSkillsSection}`;
+${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}`;
 }
 export function renderWorkerToolboxRoutingPlaceholders(contents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = []) {
     const placeholderProfiles = [

package/package.json

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

package/templates/AGENTS.md

@@ -48,6 +48,7 @@ Keep responses concise by default, but spend the context needed for correctness,
 For planned product/feature work, use this pipeline: product vision -> business domain model -> capabilities map -> deep module map / feature brief -> technical design -> optional UX -> epics/stories -> AI executor. Business Domain Model work sits after Product Vision and before the Capabilities Map. Deep Module Map and Feature Brief work are sibling downstream artifacts from Product Vision, Business Domain Model, and Capabilities Map. Technical Design remains downstream of both Feature Brief and Deep Module Map, with Scrum planning and AI executor flows after Technical Design. 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 code-writing tasks that introduce or modify logging, workflows, handlers, jobs, external calls, errors, retries, long-running operations, state changes, or other observability-relevant behavior, also use `structured-logging`.
 - For requests to create, revise, or clarify a product vision, product strategy narrative, product north star, positioning, product principles, product voice, target user definition, product boundaries, or success signals, use `product-vision-writer`.
 - For requests to create, revise, or clarify a Business Domain Model, `docs/business-domain-model.md`, business/domain vocabulary, ubiquitous language, domain concepts, relationships, rules, lifecycles, workflows, domain events, boundaries, or hard parts, use `business-domain-model-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`.

package/templates/manifest.json

@@ -1,13 +1,11 @@
 {
-  "templateVersion": "133",
+  "templateVersion": "136",
   "templates": {
     "AGENTS.md": {
-      "version": "34",
+      "version": "35",
       "description": "Project-level agent instructions and Sibu maintenance guidance.",
       "changes": [
-        "Adds judgment and honesty guidance for direct, non-condescending collaboration.",
-        "Clarifies that agents should state uncertainty, ask focused questions, or verify instead of inventing certainty.",
-        "Defines when agents should challenge users for clear factual, safety, quality, instruction, product, or context-reliability reasons."
+        "Routes observability-relevant code-writing tasks to the structured logging skill."
       ]
     },
     ".codex/config.toml": {
@@ -46,10 +44,10 @@
       ]
     },
     "skills/clean-code/SKILL.md": {
-      "version": "5",
+      "version": "6",
       "description": "Mandatory clean-code skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Adds guidance to validate required function inputs before doing work instead of silently continuing with partial defaults."
+        "Adds concise observability guidance that delegates detailed logging policy to structured-logging."
       ]
     },
     "skills/product-vision-writer/SKILL.md": {
@@ -100,17 +98,17 @@
       ]
     },
     "skills/typescript/SKILL.md": {
-      "version": "1",
+      "version": "2",
       "description": "Selectable TypeScript skill installed when TypeScript language support is selected.",
       "changes": [
-        "Adds an optional TypeScript skill for projects that use .ts or .tsx files."
+        "Routes observability-relevant TypeScript changes to the structured logging skill."
       ]
     },
     "skills/golang/SKILL.md": {
-      "version": "1",
+      "version": "2",
       "description": "Selectable Go skill installed when Go language support is selected.",
       "changes": [
-        "Adds an optional Go skill with concise, Effective Go\u2013style guidance for .go files, package APIs, interfaces, errors, receivers, concurrency, and tests."
+        "Routes observability-relevant Go changes to the structured logging skill."
       ]
     },
     "skills/postgresql-expert/SKILL.md": {
@@ -128,10 +126,10 @@
       ]
     },
     "skills/architecture/command-pattern/SKILL.md": {
-      "version": "6",
+      "version": "7",
       "description": "Selectable architecture skill for command-oriented vertical slices using Command Pattern, Hexagonal Architecture, and DDD principles.",
       "changes": [
-        "Adds a framework-agnostic entrypoint dependency rule requiring delivery adapters to create commands and call handlers or dispatchers instead of infrastructure, SDKs, repositories, or domain workflow internals."
+        "Routes workflow, handler, entrypoint, job, and operational outcome logging concerns to the structured logging skill."
       ]
     },
     "skills/nextjs/SKILL.md": {
@@ -142,10 +140,10 @@
       ]
     },
     "skills/react/SKILL.md": {
-      "version": "3",
+      "version": "4",
       "description": "Selectable React skill for component design, props, state ownership, and presentational boundaries.",
       "changes": [
-        "Adds broadly applicable React screen componentization guidance so route and feature entry files stay thin while meaningful UI regions move into focused nearby files."
+        "Strengthens React guidance to require one component per nearby file by default, disallow same-file helper subcomponents, and add a before-finish component-boundary self-check."
       ]
     },
     "skills/scrum-master-planner/SKILL.md": {
@@ -170,17 +168,17 @@
       ]
     },
     "skills/ai-implementation-plan-executor/SKILL.md": {
-      "version": "24",
+      "version": "25",
       "description": "Mandatory AI implementation plan executor gatekeeper for story execution, review, approval metadata, commit, and feature continuation.",
       "changes": [
-        "Requires the executor to spawn the Sibu implementation executor sub-agent whenever spawning is available and limits inline fallback to host capability blockers."
+        "Updates executor packet guidance to include structured logging when implementation stories touch observability-relevant code."
       ]
     },
     "skills/ai-implementation-executor-toolbox/SKILL.md": {
-      "version": "1",
+      "version": "2",
       "description": "Worker-only executor toolbox skill for fresh-context Sibu implementation executor sub-agents.",
       "changes": [
-        "Adds an executor toolbox skill with focused worker routing, ordered step execution, validation, Interactive Review Gate, and git-safety rules."
+        "Guides executor workers to load structured logging for observability-relevant implementation stories."
       ]
     },
     "skills/feature-idea-capture/SKILL.md": {
@@ -330,6 +328,15 @@
       "changes": [
         "Adds a managed Gemini SessionStart hook that checks the latest Sibu version and runs sibu doctor automatically."
       ]
+    },
+    "skills/structured-logging/SKILL.md": {
+      "version": "1",
+      "description": "Mandatory structured logging skill for safe, useful, storytelling logs in code-writing workflows.",
+      "changes": [
+        "Adds required structured logging guidance for code-writing workflows.",
+        "Defines safe, structured, storytelling log expectations while avoiding noisy logs in trivial code.",
+        "Guides agents to follow project logging conventions and use concise local logging helpers when useful."
+      ]
     }
   }
 }

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

@@ -18,7 +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
-- required skill paths, including `clean-code`
+- 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
 - approval and commit rules from the main executor workflow
@@ -31,6 +31,7 @@ If a required source artifact or required skill path is missing, stop and report
 ## Execution rules
 
 - Read the story, ordered step files, required source artifacts, required skills, 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.
 - Execute all unapproved step files in filename order.
 - Keep changes inside the story scope, step scope, source artifacts, and distilled constraints.
 - Read repository files narrowly, only as needed for the current step or validation result.

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

@@ -20,7 +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.
-- Required and relevant installed skill paths for the executor packet, including `clean-code`.
+- 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
 
@@ -84,13 +84,13 @@ Build a narrow executor packet for the worker. The packet must include:
 - exactly one User Story path or story-local `.impl_plan/` folder
 - 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`
+- 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”
 - 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 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.
 

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

@@ -112,6 +112,9 @@ entrypoint / framework adapter -> domain workflow internals that bypass the Hand
 
 If dependency wiring needs infrastructure implementations, prefer a composition/bootstrap module or small factory that constructs the Handler. Keep request handling, command creation, and result translation separate from infrastructure behavior.
 
+### Rule 6: Operational Behavior Uses Structured Logging
+When workflows, command handlers, entrypoints, jobs, external calls, retries, state changes, or operational outcomes need logging, also use `structured-logging`. Keep this architecture guidance focused on boundaries and delegate logging policy to that skill.
+
 ---
 
 ## 4. Implementation Workflow

package/templates/skills/clean-code/SKILL.md

@@ -100,6 +100,10 @@ if (!(playlist = await playlistRepository.findById(playlistId))) {
 - Match the surrounding style when it is already reasonable.
 - Use existing project conventions unless there is a strong reason not to.
 
+### 12. Keep operational behavior observable
+- When code changes affect logs, workflows, handlers, jobs, external calls, errors, retries, long-running operations, state changes, or important outcomes, keep logging useful, concise, and safe.
+- Use `structured-logging` for detailed logging guidance instead of duplicating that policy here.
+
 ## Decision rule
 
 When unsure, prefer:

package/templates/skills/golang/SKILL.md

@@ -72,6 +72,9 @@ Apply this skill together with `clean-code`. Keep this skill focused on Go-speci
 - Keep test cases named so failures explain themselves.
 - Test exported behavior and important package contracts, not private implementation trivia.
 
+### 10. Use structured logging for operational behavior
+- When Go changes affect logs, workflows, handlers, jobs, external calls, errors, retries, state changes, or important outcomes, also use `structured-logging`.
+
 ## Decision rule
 
 When unsure, prefer:

package/templates/skills/react/SKILL.md

@@ -61,19 +61,21 @@ This skill covers React componentization, component responsibility, state owners
 ### 7. Prefer composition over configuration-heavy components
 - Compose smaller components instead of building one component with many modes and flags.
 - If a component needs many boolean props, consider whether it is doing too much.
-- Use `children` or named subcomponents when composition makes the API clearer.
+- Use `children` or named child component APIs when composition makes the API clearer, but keep each component implementation in its own nearby file.
 
 ### 8. Make component boundaries visible
 - Name components by what they represent in the UI or product.
 - Keep server-interacting, stateful, and presentational responsibilities easy to identify from the component shape.
 - Avoid mixing data fetching, mutation, layout, formatting, and low-level UI rendering in one component.
-- Each component should live in its own file by default; do not define multiple components in the same file just because they are currently small.
-- If a helper component is only temporary, promote it to its own file as soon as it represents a meaningful UI responsibility.
+- Each React component belongs in its own nearby file by default.
+- Do not define helper subcomponents in a parent component file, even when they are small, file-local, currently unreused, named only for readability, or part of a compound component API.
+- Same-file helpers are acceptable only when they are not React components, do not return JSX, and do not represent a UI responsibility. Constants, type aliases, and pure non-JSX helpers such as `formatStatusLabel()` may stay when they support the component without becoming UI.
+- A function that returns JSX, represents a named UI region, renders a repeated unit, or owns UI state/interaction is a component. Move it to its own nearby file before finishing.
 
 ### 9. Build screens as composition roots, not component dumping grounds
 - Treat page-level components, route-level containers, and major feature components as composition roots: they should assemble focused child components, not define every section, repeated item, overlay, menu, state, helper, and interaction inline.
 - A top-level screen component may own data loading, high-level layout, route states, and wiring, but should delegate meaningful UI regions to named components.
-- If a UI region has its own state, interaction, repeated rendering, overlay, menu, empty/error/loading state, or domain formatting concern, strongly prefer extracting it to a focused nearby file.
+- If a UI region has its own state, interaction, repeated rendering, overlay, menu, empty/error/loading state, or domain formatting concern, extract it to a focused nearby file.
 - Keep route entry files especially thin: they should fetch or prepare data, handle route-level states, and compose the screen. Avoid placing substantial presentational or interactive subcomponents directly inside them.
 - Route-local or feature-local components are good defaults for UI that belongs to one screen or feature. Shared components should be extracted only when reuse is real, not speculative.
 
@@ -103,6 +105,59 @@ feature-format.ts
 feature-types.ts
 ```
 
+Prefer separated component files:
+
+```tsx
+// feature-shell.tsx
+export function FeatureShell() {
+  return <FeatureList />;
+}
+
+// feature-list.tsx
+export function FeatureList() {
+  return <FeatureListItem />;
+}
+
+// feature-list-item.tsx
+export function FeatureListItem() {
+  return <li>Item</li>;
+}
+```
+
+Avoid multiple component implementations in one parent file:
+
+```tsx
+export function FeatureShell() {
+  return <FeatureList />;
+}
+
+function FeatureList() {
+  return <FeatureListItem />;
+}
+
+function FeatureListItem() {
+  return <li>Item</li>;
+}
+```
+
+Allowed same-file helpers are non-components:
+
+```tsx
+const statusLabels = { active: "Active" };
+
+function formatStatusLabel(status: string) {
+  return statusLabels[status] ?? "Unknown";
+}
+```
+
+Avoid same-file JSX helpers:
+
+```tsx
+function StatusBadge({ status }: { status: string }) {
+  return <span>{formatStatusLabel(status)}</span>;
+}
+```
+
 ## Decision rule
 
 When unsure, prefer:
@@ -110,7 +165,7 @@ When unsure, prefer:
 2. route-level or feature-level containers that own only the interaction state they coordinate
 3. one clear responsibility per component
 4. more focused components instead of fewer overloaded components
-5. one meaningful component per file by default
+5. one React component per nearby file by default
 6. nearby component files before shared abstractions
 7. stateless presentational components that render from props
 8. stateful components only where local interaction state is genuinely owned
@@ -121,10 +176,12 @@ When unsure, prefer:
 
 ## Componentization self-review
 
-Before finishing a React change, ask:
+Before finishing a React change, inspect every changed React file and ask:
 
 - Can I understand the screen structure from the top-level file without reading repeated item, action surface, overlay, state, or formatting internals?
 - Are meaningful UI regions and repeated units in named components?
 - Does each file have one obvious reason to change?
+- Does any changed file define more than one React component implementation, including small, file-local, currently unreused, named helper, or compound subcomponents?
+- If multiple component implementations remain, did I split them into nearby files before finishing or explicitly explain why the remaining same-file helper is not a React component, does not return JSX, and does not represent UI responsibility?
 - Are server/client boundaries still as small as practical?
 - Did I avoid creating shared abstractions before there is real reuse?

package/templates/skills/structured-logging/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: structured-logging
+description: Use when writing or modifying code that affects logging or meaningful operational behavior, so logs stay structured, safe, useful, and concise.
+---
+
+# Structured Logging
+
+Use this skill when writing or modifying code that emits logs or changes meaningful operational behavior: workflows, command handlers, jobs, external calls, retries, errors, long-running operations, state changes, important outcomes, or other observability-relevant paths.
+
+Do not add logs to trivial pure logic, noisy implementation details, or paths where a log would not help someone diagnose what happened.
+
+## Logging approach
+
+- Follow the repository's existing logging conventions first.
+- If the project has no clear convention, choose a widely accepted logger for the current language, framework, and runtime.
+- Do not introduce a new logging dependency when the repository already has a reasonable logging approach.
+- Prefer a small first-party project-local helper or wrapper around the chosen logger when it keeps log calls concise and centralizes names, levels, formatting, or shared fields.
+
+## Structured logs
+
+- Use structured, machine-readable logs for meaningful events; prefer JSON when the logger/runtime supports it.
+- Use clear event names and consistent field names.
+- Make logs tell an operational story: what started, what decision was made, what external interaction happened, what outcome occurred, and what failed or was retried.
+- Include useful safe metadata when available, such as operation or workflow name, request or correlation id, safe entity ids, counts, timings, state transitions, outcomes, and safe error context.
+- Keep individual log calls small; move repeated fields or formatting into a local helper instead of spreading boilerplate through business logic.
+
+## Safety
+
+Never log secrets, credentials, tokens, API keys, session cookies, raw personal data, full prompts or model responses, or large user payloads. If context is useful but sensitive, log a safe identifier, count, type, or redacted summary instead.

package/templates/skills/typescript/SKILL.md

@@ -101,6 +101,9 @@ type LoadState = {
 - Do not try to force every runtime guarantee into the type system.
 - Balance safety with readability and development speed.
 
+### 10. Use structured logging for operational behavior
+- When TypeScript changes affect logs, workflows, handlers, jobs, external calls, errors, retries, state changes, or important outcomes, also use `structured-logging`.
+
 ## Decision rule
 
 When unsure, prefer: