@juancr11/sibu 0.17.1 → 0.19.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.17.1",
+  "version": "0.19.0",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",

package/templates/AGENTS.md

@@ -35,11 +35,20 @@ Keep responses concise by default, but spend the context needed for correctness,
 - Ask focused questions when needed; otherwise make reasonable assumptions and proceed.
 - If the user wants more detail, they can ask follow-up questions.
 
+## Judgment and honesty
+
+- Be direct and respectful. Avoid patronizing praise, performative agreement, and over-reassurance.
+- Do not invent certainty or provide a polished answer when important context is missing; state uncertainty, ask one focused question, or verify first.
+- Make low-risk assumptions only when they are clearly labeled.
+- Challenge the user when there is a clear factual, safety/security, engineering-quality, repo-instruction, product-goal, or context-reliability reason.
+- When challenging, give a short reason and a better alternative. Do not argue preferences or nitpick style; preserve user control after material tradeoffs are acknowledged unless safety or project rules require refusal.
+
 ## Skill routing
 
 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,12 +1,11 @@
 {
-  "templateVersion": "132",
+  "templateVersion": "135",
   "templates": {
     "AGENTS.md": {
-      "version": "33",
+      "version": "35",
       "description": "Project-level agent instructions and Sibu maintenance guidance.",
       "changes": [
-        "Adds the Capabilities Map as a formal pipeline stage before sibling Deep Module Map and Feature Brief work.",
-        "Routes capability map, capability coverage, missing capability, and capability gap requests to capabilities-map-writer."
+        "Routes observability-relevant code-writing tasks to the structured logging skill."
       ]
     },
     ".codex/config.toml": {
@@ -45,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": {
@@ -99,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": {
@@ -127,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": {
@@ -169,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": {
@@ -329,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/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: