siesa-agents 2.1.78 → 2.1.80

package/claude/skills/bmad-validate-prd/steps-v/step-v-13-report-complete.md

@@ -0,0 +1,230 @@
+---
+# File references (ONLY variables used in this step)
+validationReportPath: '{validation_report_path}'
+prdFile: '{prd_file_path}'
+---
+
+# Step 13: Validation Report Complete
+
+## STEP GOAL:
+
+Finalize validation report, summarize all findings from steps 1-12, present summary to user conversationally, and offer actionable next steps.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring synthesis and summary expertise
+- ✅ This is the FINAL step - requires user interaction
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on summarizing findings and presenting options
+- 🚫 FORBIDDEN to perform additional validation
+- 💬 Approach: Conversational summary with clear next steps
+- 🚪 This is the final step - no next step after this
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load complete validation report
+- 🎯 Summarize all findings from steps 1-12
+- 🎯 Update report frontmatter with final status
+- 💬 Present summary to user conversationally
+- 💬 Offer menu options for next actions
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete validation report with findings from all validation steps
+- Focus: Summary and presentation only (no new validation)
+- Limits: Don't add new findings, just synthesize existing
+- Dependencies: Steps 1-12 completed - all validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Complete Validation Report
+
+Read the entire validation report from {validationReportPath}
+
+Extract all findings from:
+- Format Detection (Step 2)
+- Parity Analysis (Step 2B, if applicable)
+- Information Density (Step 3)
+- Product Brief Coverage (Step 4)
+- Measurability (Step 5)
+- Traceability (Step 6)
+- Implementation Leakage (Step 7)
+- Domain Compliance (Step 8)
+- Project-Type Compliance (Step 9)
+- SMART Requirements (Step 10)
+- Holistic Quality (Step 11)
+- Completeness (Step 12)
+
+### 2. Update Report Frontmatter with Final Status
+
+Update validation report frontmatter:
+
+```yaml
+---
+validationTarget: '{prd_path}'
+validationDate: '{current_date}'
+inputDocuments: [list of documents]
+validationStepsCompleted: ['step-v-01-discovery', 'step-v-02-format-detection', 'step-v-03-density-validation', 'step-v-04-brief-coverage-validation', 'step-v-05-measurability-validation', 'step-v-06-traceability-validation', 'step-v-07-implementation-leakage-validation', 'step-v-08-domain-compliance-validation', 'step-v-09-project-type-validation', 'step-v-10-smart-validation', 'step-v-11-holistic-quality-validation', 'step-v-12-completeness-validation']
+validationStatus: COMPLETE
+holisticQualityRating: '{rating from step 11}'
+overallStatus: '{Pass/Warning/Critical based on all findings}'
+---
+```
+
+### 3. Create Summary of Findings
+
+**Overall Status:**
+- Determine from all validation findings
+- **Pass:** All critical checks pass, minor warnings acceptable
+- **Warning:** Some issues found but PRD is usable
+- **Critical:** Major issues that prevent PRD from being fit for purpose
+
+**Quick Results Table:**
+- Format: [classification]
+- Information Density: [severity]
+- Measurability: [severity]
+- Traceability: [severity]
+- Implementation Leakage: [severity]
+- Domain Compliance: [status]
+- Project-Type Compliance: [compliance score]
+- SMART Quality: [percentage]
+- Holistic Quality: [rating/5]
+- Completeness: [percentage]
+
+**Critical Issues:** List from all validation steps
+**Warnings:** List from all validation steps
+**Strengths:** List positives from all validation steps
+
+**Holistic Quality Rating:** From step 11
+**Top 3 Improvements:** From step 11
+
+**Recommendation:** Based on overall status
+
+### 4. Present Summary to User Conversationally
+
+Display:
+
+"**✓ PRD Validation Complete**
+
+**Overall Status:** {Pass/Warning/Critical}
+
+**Quick Results:**
+{Present quick results table with key findings}
+
+**Critical Issues:** {count or "None"}
+{If any, list briefly}
+
+**Warnings:** {count or "None"}
+{If any, list briefly}
+
+**Strengths:**
+{List key strengths}
+
+**Holistic Quality:** {rating}/5 - {label}
+
+**Top 3 Improvements:**
+1. {Improvement 1}
+2. {Improvement 2}
+3. {Improvement 3}
+
+**Recommendation:**
+{Based on overall status:
+- Pass: "PRD is in good shape. Address minor improvements to make it great."
+- Warning: "PRD is usable but has issues that should be addressed. Review warnings and improve where needed."
+- Critical: "PRD has significant issues that should be fixed before use. Focus on critical issues above."}
+
+**What would you like to do next?**"
+
+### 5. Present MENU OPTIONS
+
+Display:
+
+**[R] Review Detailed Findings** - Walk through validation report section by section
+**[E] Use Edit Workflow** - Use validation report with Edit workflow for systematic improvements
+**[F] Fix Simpler Items** - Immediate fixes for simple issues (anti-patterns, leakage, missing headers)
+**[X] Exit** - Exit and Suggest Next Steps.
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- **IF R (Review Detailed Findings):**
+  - Walk through validation report section by section
+  - Present findings from each validation step
+  - Allow user to ask questions
+  - After review, return to menu
+
+- **IF E (Use Edit Workflow):**
+  - Explain: "The Edit workflow can use this validation report to systematically address issues. Edit mode will guide you through discovering what to edit, reviewing the PRD, and applying targeted improvements."
+  - Offer: "Would you like to launch Edit mode now? It will help you fix validation findings systematically."
+  - If yes: Invoke the `bmad-edit-prd` skill, passing the validation report path as context
+  - If no: Return to menu
+
+- **IF F (Fix Simpler Items):**
+  - Offer immediate fixes for:
+    - Template variables (fill in with appropriate content)
+    - Conversational filler (remove wordy phrases)
+    - Implementation leakage (remove technology names from FRs/NFRs)
+    - Missing section headers (add ## headers)
+  - Ask: "Which simple fixes would you like me to make?"
+  - If user specifies fixes, make them and update validation report
+  - Return to menu
+
+- **IF X (Exit):**
+  - Display: "**Validation Report Saved:** {validationReportPath}"
+  - Display: "**Summary:** {overall status} - {recommendation}"
+  - PRD Validation complete. Invoke the `bmad-help` skill.
+  - Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.
+
+- **IF Any other:** Help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Complete validation report loaded successfully
+- All findings from steps 1-12 summarized
+- Report frontmatter updated with final status
+- Overall status determined correctly (Pass/Warning/Critical)
+- Quick results table presented
+- Critical issues, warnings, and strengths listed
+- Holistic quality rating included
+- Top 3 improvements presented
+- Clear recommendation provided
+- Menu options presented with clear explanations
+- User can review findings, get help, or exit
+
+### ❌ SYSTEM FAILURE:
+
+- Not loading complete validation report
+- Missing summary of findings
+- Not updating report frontmatter
+- Not determining overall status
+- Missing menu options
+- Unclear next steps
+
+**Master Rule:** User needs clear summary and actionable next steps. Edit workflow is best for complex issues; immediate fixes available for simpler ones.

package/claude/skills/sa-check-implementation-readiness/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-check-implementation-readiness
+description: 'Custom Siesa extension of bmad-check-implementation-readiness. Injects project-specific context via workflow_ext.md before delegating to the base skill. Use when the user says "check implementation readiness".'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: 
+
+1. FIRST, LOAD and READ the FULL contents of the custom extension file at: `_siesa-agents/bmm/workflows/3-solutioning/check-implementation-readiness/workflow_ext.md ` — This contains mandatory pre-workflow context injection rules. Execute its steps BEFORE proceeding.
+
+2. LOAD the FULL @.claude/skills/bmad-check-implementation-readiness/SKILL.md, READ its entire contents and follow its directions exactly!

package/claude/skills/sa-code-review/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-code-review
+description: 'Custom perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS 
+
+1. FIRST: LOAD and READ the FULL `@_siesa-agents/bmm/workflows/4-implementation/code-review/workflow_ext.md` — This contains mandatory context injection rules. Apply them throughout the workflow execution.
+
+2. Always LOAD the FULL `@_siesa-agents/bmm/workflows/4-implementation/code-review/workflow.md`. Follow all instructions in the task file exactly as written.

package/claude/skills/sa-correct-course/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-correct-course
+description: 'Custom Siesa extension of bmad-correct-course. Loads company-specific workflow standards before delegating to the base skill. Use when the user says "correct course" or "propose sprint change"'
+---
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+
+1. ALWAYS Load and read the workflow extension from `@{project-root}/_siesa-agents/bmm/workflows/4-implementation/correct-course/workflow_ext.md` to understand the Company Standards Context.
+
+2. Follow the instructions in `.claude/skills/bmad-correct-course/SKILL.md`

package/claude/skills/sa-create-architecture/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-create-architecture
+description: 'Customization of Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design"'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: 
+
+1. FIRST, LOAD and READ the FULL contents of the custom extension file at: `_siesa-agents/bmm/workflows/3-solutioning/create-architecture/workflow_ext.md ` — This contains mandatory pre-workflow context injection rules. Execute its steps BEFORE proceeding.
+
+2. Follow the instructions in `.claude/skills/bmad-create-architecture/SKILL.md`

package/claude/skills/sa-create-epics-and-stories/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-create-epics-and-stories
+description: 'Custom SIESA extension of bmad-create-epics-and-stories. Injects context from _siesa-agents workflow extension before delegating to the base skill. Use when the user says "create the epics and stories list".'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: 
+
+1. FIRST, LOAD and READ the FULL contents of the custom extension file at: `_siesa-agents/bmm/workflows/3-solutioning/create-epics-and-stories/workflow_ext.md` — This contains mandatory pre-workflow context injection rules. Execute its steps BEFORE proceeding.
+
+2. Follow the instructions in `.claude/skills/bmad-create-epics-and-stories/SKILL.md`

package/claude/skills/sa-create-prd/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-create-prd
+description: 'SIESA custom version of bmad-create-prd. Creates a comprehensive PRD through collaborative step-by-step discovery, extended with SIESA-specific prerequisites (feature list sharding, workflow extensions). Use instead of bmad-create-prd when working on SIESA projects.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND IN THIS EXACT ORDER:
+
+1. FIRST, LOAD and READ the FULL contents of the custom extension file at: `_siesa-agents/bmm/workflows/2-plan-workflows/prd/workflow_ext.md`. You MUST assimilate these pre-requisites (especially asking for the feature list for sharding) before doing anything else.
+
+2. LOAD the FULL @.claude/skills/bmad-create-prd/SKILL.md, READ its entire contents and follow its directions exactly!

package/claude/skills/sa-create-story/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-create-story
+description: 'SIESA-specific story creation workflow. Analyzes epics, architecture, and project context to generate implementation-ready user stories following SIESA standards. Use when the user says "create the next story" or "create story [identifier]"'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS 
+
+1. FIRST: LOAD and READ the FULL `@_siesa-agents/bmm/workflows/4-implementation/create-story/workflow_ext.md` — This contains mandatory context injection rules. Apply them throughout the workflow execution.
+
+2. Always LOAD the FULL `@_siesa-agents/bmm/workflows/4-implementation/create-story/workflow.md`. Follow all instructions in the task file exactly as written.

package/claude/skills/sa-create-user-guide/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: sa-create-user-guide
+description: 'Genera guías de usuario comprehensivas en español e inglés desde épicas y PRDs, con diagramas Mermaid y trazabilidad completa'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_siesa-agents/bmm/workflows/5-documentation/create-user-guide/workflow.md, READ its entire contents and follow its directions exactly!

package/claude/skills/sa-create-ux-design/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-create-ux-design
+description: 'Custom extension of bmad-create-ux-design: Plan UX patterns and design specifications with Siesa-specific customizations. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: 
+
+1. FIRST, LOAD and READ the FULL contents of the custom extension file at: `_siesa-agents/bmm/workflows/2-plan-workflows/create-ux-design/workflow_ext.md ` — This contains mandatory pre-workflow context injection rules. Execute its steps BEFORE proceeding.
+
+2. Follow the instructions in `.claude/skills/bmad-create-ux-design/SKILL.md`

package/claude/skills/sa-dev-story/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-dev-story
+description: "Executes the SIESA dev-story workflow: branches, injects shared-artifact context, implements tasks, writes tests, and marks the story ready for review."
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS 
+
+1. FIRST: LOAD and READ the FULL `@_siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md` — This contains mandatory context injection rules. Apply them throughout the workflow execution.
+
+2. Always LOAD the FULL `@_siesa-agents/bmm/workflows/4-implementation/dev-story/workflow.md`. Follow all instructions in the task file exactly as written.

package/claude/skills/sa-generate-project-context/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-generate-project-context
+description: 'Custom version of bmad-generate-project-context. Extends the base skill by injecting additional context rules from _siesa-agents before delegating execution to the standard workflow. Use when the user says "generate project context" or "create project context"'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+1. FIRST: LOAD and READ the FULL @_siesa-agents/bmm/workflows/generate-project-context/workflow_ext.md — This contains mandatory context injection rules and an interactive menu. Apply them BEFORE proceeding.
+
+2. Follow the instructions in @.claude/skills/bmad-generate-project-context/Skill.md

package/claude/skills/sa-init-observability/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: sa-init-observability
+description: 'Initialize a `.siesa-project` file that consolidates observability metrics across multi-repo logical projects (docs/backend/frontend sub-repos cloned side by side). Use whenever the user wants to set up observability for a new project, mentions `.siesa-project`, asks how to consolidate fragmented `project_id` values in GCP, sees metrics split across `business-*-docs-*`/`business-*-backend-*`/`business-*-frontend-*` repos, or starts working in a project that follows the multi-repo convention. Run this once per logical project, before workflows emit telemetry, so `sa-emit.js` reports a unified `project_id` instead of one per sub-repo.'
+---
+
+# Init Observability — `.siesa-project` Setup
+
+**Goal:** Create a `.siesa-project` file in the correct parent directory so `sa-emit.js` reports a single, stable `project_id` for every workflow that runs inside any sub-repo of the same logical project.
+
+**When this matters:** Projects following the Siesa multi-repo convention split docs, backend and frontend into separate GitHub repos (`business-pos-docs-pdv`, `business-pos-backend-pdv`, `business-pos-frontend-pdv`). Without `.siesa-project`, `sa-emit.js` falls back to `git remote get-url origin` and emits three different `project_id` values for what is conceptually one project. That fragments dashboards in GCP and inflates per-engineer epic counts because the same epic gets counted once per sub-repo it touches.
+
+## When to use this skill
+
+Trigger immediately when the user:
+
+- Says "initialize observability", "set up observability", "init `.siesa-project`", or "configure metrics" for a project
+- Mentions that GCP shows the same engineer/epic across multiple `business-*-docs-*` / `business-*-backend-*` / `business-*-frontend-*` rows
+- Asks how to make several sub-repos report under one logical project name
+- Has just cloned a multi-repo project (e.g. `docs/` + `apps/backend/` + `apps/frontend/`) and is about to run BMAD workflows that emit telemetry
+- References the `.siesa-project` file by name
+
+Do **not** trigger for: editing existing skills, changing OTLP endpoints, debugging a specific event payload (that is `sa-emit.js` territory), or anything unrelated to the `.siesa-project` mechanism.
+
+## Prerequisites
+
+- The user is sitting inside a git repository that belongs to a logical Siesa project (typically a clone of `business-*-{docs|backend|frontend}-*`).
+- Node.js is on the PATH (the scripts are invoked via `node`).
+- Two helper scripts live in the observability scripts dir and are mirrored to the npm copy:
+  - `sa-init-env.js` — ensures `~/.claude/observability/.env` has the OTLP variables sa-emit needs.
+  - `sa-init-project.js` — detects the multi-repo convention and writes `.siesa-project`.
+- Source-of-truth path is `_siesa-agents/observability/scripts/`; the npm mirror is `siesa-agents/observability/scripts/`. Prefer the source-of-truth path when both exist.
+
+If a script is missing, stop and tell the user — do not improvise the logic inline. The scripts are the authoritative source for slug derivation and env scaffolding.
+
+## Workflow
+
+The skill is a three-step orchestration: **ensure global env → detect → write**. Step 0 is idempotent and almost always silent. Steps 1 and 2 do the real work for the `.siesa-project` file.
+
+### Step 0 — Ensure global env
+
+Run `sa-init-env.js` first, every time the skill is invoked:
+
+```bash
+node <observability-scripts>/sa-init-env.js
+```
+
+The script verifies that `~/.claude/observability/.env` exists and declares both `SA_OTLP_ENDPOINT` and `SA_OTLP_HEADERS`. It does **not** modify `sa-emit.js` and does **not** copy values from any project `.env` — it only seeds clearly-fake placeholders that the user must replace before workflows emit real telemetry.
+
+Parse the JSON `status` field:
+
+- **`status: "already-configured"`** — Both variables are already present. Do not mention this to the user unless they explicitly asked about env setup; it is the silent happy path. Continue to Step 1.
+- **`status: "created"`** — The file did not exist; the script wrote a fresh template at `env_path`. Tell the user once: "Created `~/.claude/observability/.env` with placeholder values. Edit it with your real OTLP endpoint and headers before running workflows that emit telemetry." Then continue to Step 1.
+- **`status: "updated"`** — The file existed but was missing one of the two variables; placeholders were appended for `appended_vars`. Tell the user which vars were added and remind them to replace the placeholders. Continue to Step 1.
+- **`status: "error"`** — Surface the error verbatim and stop. Do not proceed to Step 1 — if the env scaffolding is broken, the project-level setup is the wrong place to spend the user's attention.
+
+The placeholders the script writes are intentionally bogus (`https://your-otel-collector.example.com`, `Authorization=Bearer YOUR_TOKEN_HERE`). They will not connect to anything. The user is expected to receive real values from the observability team and paste them in.
+
+### Step 1 — Detect
+
+Run `sa-init-project.js` from the user's current directory (or from any directory inside the target sub-repo if the user told you where they want to initialize):
+
+```bash
+node <observability-scripts>/sa-init-project.js --detect
+```
+
+Parse the JSON object printed to stdout. The `status` field selects the next branch.
+
+**`status: "ready"`** — Multi-repo convention detected. The JSON contains everything needed to act:
+
+- `proposed_slug` — the logical project name to write (e.g. `pos-pdv`)
+- `recommended_dir` — the parent directory chosen by the script (1 level up for `docs` clones, 2 levels up for `backend`/`frontend` clones)
+- `convention_breakdown` — how the slug was derived (`module`, `role`, `rest`)
+
+Proceed straight to Step 2 with `proposed_slug` and `recommended_dir`. Do **not** ask the user to confirm — the user has already accepted the auto-detection policy by invoking this skill.
+
+**`status: "single-repo"`** — The repo name has no `docs`/`backend`/`frontend` segment, so the git remote already produces an unambiguous `project_id`. Stop and tell the user no `.siesa-project` is needed (mention the `fallback_project_id` value so they know what GCP will see). Do not write anything. If they later say "no, write one anyway with slug X", run Step 2 with that explicit slug and the directory they specify.
+
+**`status: "already-configured"`** — A `.siesa-project` exists above the current git root. Stop and report `existing_siesa_project.path` and `existing_siesa_project.value` to the user. Do not overwrite implicitly. If the user replies that they want it changed, run `--write` with `--force`, the new slug, and the same directory.
+
+**`status: "no-git-repo"`** — The cwd is not inside a git repo. Tell the user to `cd` into the clone they want to initialize and re-run. Do not invent a directory.
+
+**`status: "no-remote"`** — Git repo without an `origin` remote. Stop and ask the user for a slug + directory before proceeding, since the script has no signal to auto-derive a name.
+
+### Step 2 — Write
+
+When `status == "ready"`, run write immediately with the values from the detect output — no user prompt in between:
+
+```bash
+node <observability-scripts>/sa-init-project.js --write --slug "<proposed_slug>" --dir "<recommended_dir>"
+```
+
+Parse the JSON response:
+
+- **`status: "written"`** — Success. Report a single concise line to the user: the absolute `path` and the slug that was written. Optionally suggest the verification command from Step 3.
+- **`status: "exists"`** — A file is already there with a different value (the detect step missed it because the user pointed at a non-default dir, or a race). Show `current_value` vs `requested_slug` and ask the user whether to overwrite. If yes, re-run with `--force`.
+- **`status: "error"`** — Surface the error message verbatim and stop.
+
+For the `single-repo`, `already-configured` and `no-remote` branches where the user explicitly opts into writing, gather slug + directory inline and run the same `--write` command.
+
+### Step 3 — Verify (optional)
+
+Suggest the user run a quick sanity check from any sub-repo of the project:
+
+```bash
+node <observability-scripts>/sa-emit.js --event workflow.started --story "0-verify" --phase create-story 2>&1 | grep project_id
+```
+
+If the buffered event shows `project_id=<confirmed-slug>`, the consolidation works. If it still shows the git-remote-derived value, the user is running from a directory that is **not** a descendant of the chosen parent — point them at the right cwd.
+
+## Edge cases
+
+- **Nested logical projects.** If the user runs the skill inside a directory that is already under an existing `.siesa-project`, the script reports `already-configured`. Do not stack `.siesa-project` files — the lowest one wins during walk-up, which can silently mask the consolidation.
+- **Slugs with dots, underscores or uppercase.** The script rejects them. Stick to lowercase + dashes (`pos-pdv`, `finance-billing`). If the user pushes back, explain that GCP labels work best with kebab-case and that other Siesa scripts assume this shape.
+- **Convention without `business-` prefix.** The parser handles both `business-pos-backend-pdv` and a hypothetical `pos-backend-pdv` — both produce `pos-pdv`. Future modules (`finance-*`, `hcm-*`) work without any code change.
+- **Parent dir that is itself a git repo.** Sometimes the docs repo *is* the logical parent (e.g. `comercial/` is a git repo and `comercial/apps/{backend,frontend}/` are clones inside it). That is fine — writing `.siesa-project` in `comercial/` will (a) commit-able in the docs repo, and (b) walked up correctly by `sa-emit.js` from `comercial/apps/backend/`. Mention this to the user so they can decide whether to commit the file (recommended, since it documents the convention for teammates).
+- **Windows path separators.** The script uses `path.join`, so output paths may contain backslashes. Treat them as opaque and pass them back to `--write --dir` verbatim.
+
+## Convention reference
+
+The Siesa multi-repo naming convention is:
+
+```
+business-<module>-<role>-<rest>
+        └ org prefix
+              └ logical module (pos, finance, hcm, …)
+                    └ role: docs | backend | frontend
+                          └ project-specific suffix (pdv, tomapedido, billing, …)
+```
+
+The logical slug collapses `<role>` away: `business-pos-backend-pdv` → `pos-pdv`.
+
+For repo names that do not contain `docs`/`backend`/`frontend`, the script returns `single-repo` and no `.siesa-project` is needed.
+
+## Examples
+
+**Example 1 — Happy path on a `pos-pdv` clone (env already configured)**
+
+```
+User: I just cloned business-pos-backend-pdv into comercial/apps/backend. Set up observability.
+Model: <runs sa-init-env.js — status "already-configured", silent>
+       <runs sa-init-project.js --detect from comercial/apps/backend/>
+       <reads proposed_slug="pos-pdv", recommended_dir=C:\…\comercial>
+       <runs --write --slug pos-pdv --dir C:\…\comercial without asking>
+       Wrote C:\…\comercial\.siesa-project. sa-emit.js will now report project_id="pos-pdv".
+```
+
+**Example 1b — Same flow on a fresh machine (env missing)**
+
+```
+User: Set up observability for this clone.
+Model: <runs sa-init-env.js — status "created">
+       Created ~/.claude/observability/.env with placeholder values. Edit it with your real OTLP endpoint and headers before running workflows that emit telemetry.
+       <continues with detect + write as in Example 1>
+```
+
+**Example 2 — Single-repo project**
+
+```
+User: Set up .siesa-project for Siesa-Agents.
+Model: <runs --detect from Siesa-Agents/>
+       Repo name "Siesa-Agents" has no docs/backend/frontend segment, so the git remote already produces an unambiguous project_id ("SiesaTeams/Siesa-Agents"). No .siesa-project is needed.
+       Want to set a custom slug anyway?
+User: no, thanks
+Model: Nothing written. Existing fallback (SiesaTeams/Siesa-Agents) will continue to be reported.
+```
+
+**Example 3 — Already configured**
+
+```
+User: Init observability here.
+Model: <runs --detect>
+       A .siesa-project already exists at C:\…\comercial\.siesa-project with value "pos-pdv". sa-emit.js is already consolidating under that slug. No action needed unless you want to change the value.
+```
+
+## Reminders
+
+- Step 0 (`sa-init-env.js`) always runs first and is idempotent. Skip the user-facing message when its status is `already-configured`; surface it only on `created` / `updated` / `error`.
+- On `status: "ready"` from `sa-init-project.js --detect`, write immediately using `proposed_slug` and `recommended_dir` — no confirmation prompt. The user invoked this skill knowing it auto-creates the file.
+- Never invent a slug. If the detect step returns `single-repo`, `no-remote`, or any branch other than `ready`, stop and let the user drive the next decision.
+- Never call `--write --force` automatically. Overwriting an existing `.siesa-project` always requires an explicit user request.
+- Do not modify `sa-emit.js` or other observability scripts from this skill — its only side effects are (a) creating `~/.claude/observability/.env` with placeholders if absent and (b) creating or overwriting (with consent) a single `.siesa-project` file.
+- The scripts' JSON output is the contract. If a future field appears (e.g. an extra status), surface it to the user rather than guessing what it means.

package/claude/skills/sa-product-brief/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: sa-product-brief
+description: "SIESA custom version of bmad-product-brief. Creates or updates product briefs through guided or autonomous discovery, injecting SIESA-specific extension context (workflow_ext.md) before executing the base workflow. Use this instead of bmad-product-brief when working on SIESA projects."
+model: claude-sonnet-4-6
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: 
+
+1. FIRST, LOAD and READ the FULL contents of the custom extension file at: `_siesa-agents/bmm/workflows/1-analysis/create-product-brief/workflow_ext.md ` — This contains mandatory pre-workflow context injection rules. Execute its steps BEFORE proceeding.
+
+2. LOAD the FULL @.claude/skills/bmad-product-brief/SKILL.md, READ its entire contents and follow its directions exactly!

package/claude/skills/sa-quality-process/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: sa-quality-process
+description: 'QA Quality Process — Phase 1 Planning or Phase 2 Design (QA Test Plan & Strategy). Asks at startup which phase to execute.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_siesa-agents/bmm/workflows/3-solutioning/quality-process/workflow.md, READ its entire contents and follow its directions exactly!

package/claude/skills/sa-shard-doc/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: 'sa-shard-doc'
+description: 'Custom skill to splits large markdown documents into smaller, organized files based on level 2 (default) sections'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: 
+
+Read the entire task file at: `{project-root}/_siesa-agents/core/tasks/shard-doc.md`.Follow all instructions in the task file exactly as written.

package/claude/skills/sa-sprint-planning/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sa-sprint-planning
+description: 'Custom Siesa extension of bmad-sprint-planning. Injects mandatory Siesa-specific context via workflow_ext.md before delegating to the base bmad-sprint-planning skill. Use when the user says "run sprint planning" or "generate sprint plan".'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS 
+
+1. FIRST: LOAD and READ the FULL `@_siesa-agents/bmm/workflows/4-implementation/sprint-planning/workflow_ext.md` — This contains mandatory context injection rules. Apply them throughout the workflow execution.
+
+2. Always LOAD the FULL `@.claude/skills/bmad-sprint-planning/SKILL.md`.Follow all instructions in the task file exactly as written.

package/claude/skills/sa-sprint-status/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: sa-sprint-status
+description: 'Custom extension of bmad-sprint-status that injects Siesa-specific context before delegating to the base workflow. Use when the user says "check sprint status" or "show sprint status"'
+---
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS 
+
+1. FIRST: LOAD and READ the FULL `@_siesa-agents/bmm/workflows/4-implementation/sprint-status/workflow_ext.md` — This contains mandatory context injection rules. Apply them throughout the workflow execution.
+
+2. Always LOAD the FULL `@.claude/skills/bmad-sprint-status/SKILL.md`.Follow all instructions in the task file exactly as written.