@orchestrator-claude/definitions 3.30.2 → 3.31.1

package/skills/artifact-generator/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: artifact-generator
+description: Generate client-facing deliverable files (xlsx schedules, pdf decks, csv issue trees, jinja2-templated docs). Load when: "generate xlsx", "build pdf", "compile deliverable pack", "jinja2 template". Do NOT use for code generation.
+allowed-tools: Read, Write, Bash
+---
+
+# Artifact Generator Skill
+
+## When to Use This Skill
+
+Load this skill when:
+
+- A request contains any of these trigger phrases: "generate xlsx", "build pdf", "compile deliverable pack", "jinja2 template", "export to excel", "produce pdf report", "render template", "convert to docx"
+- An operational-artifact-builder agent dispatches a deliverable generation task
+- A PME workflow enters its **FRAMEWORK**, **OPERATIONAL**, or **DELIVER** phase and requires client-facing output
+- The user requests a multi-format output pack (xlsx + pdf + csv bundled together)
+
+**Scope boundary — what this skill does NOT cover:**
+
+- Code generation (TypeScript, Python source files for the orchestrator itself)
+- Markdown spec/plan/task artifacts — use `/artifact-production` for those
+- Internal reports stored only in MinIO — use `artifactStore` directly
+- Presentation slide decks authored in Slidev — those live in a separate `slidev-build` skill
+
+Client-facing deliverable formats in scope: `.xlsx`, `.pdf`, `.docx`, `.csv`, `.html` (rendered from template).
+
+---
+
+## Pre-flight Python Environment Check
+
+Before running any generation script, verify the runtime stack is present:
+
+```bash
+# Python version — must be 3.11 or above
+python3 --version
+
+# Required libraries
+pip list | grep -E "openpyxl|jinja2"
+
+# Pandoc system binary
+pandoc --version | head -1
+```
+
+**S178-validated versions** (Red Bull Big Battle Consultoria, 10/05/2026):
+
+| Tool | Validated version |
+|------|------------------|
+| openpyxl | 3.1.x |
+| jinja2 | 3.1.x |
+| Pandoc | 3.9.0.2 (user-local binary at `~/.local/bin/pandoc`) |
+
+**Install missing Python libraries:**
+
+```bash
+pip install openpyxl jinja2
+```
+
+**Install Pandoc (choose one):**
+
+```bash
+# Debian/Ubuntu
+sudo apt install pandoc
+
+# macOS
+brew install pandoc
+
+# User-local (no sudo) — download from GitHub releases
+# https://github.com/jgm/pandoc/releases
+# Extract binary to ~/.local/bin/ and add to PATH
+```
+
+**If `python3` is not found**, the generation script must not proceed. Surface a CRITICAL blocker to the orchestrating agent and halt.
+
+---
+
+## Pattern Catalog
+
+### Pattern 1 — xlsx Multi-Sheet (openpyxl)
+
+Use for: schedule grids, issue-tree exports, data tables with multiple perspectives.
+
+```python
+import openpyxl
+from openpyxl.styles import Font, PatternFill, Alignment
+from pathlib import Path
+
+def generate_workbook(output_path: str, workflow_id: str) -> None:
+    wb = openpyxl.Workbook()
+
+    # Sheet 1: Overview
+    ws_overview = wb.active
+    ws_overview.title = "Overview"
+    headers = ["ID", "Topic", "Owner", "Status", "Due Date"]
+    for col, header in enumerate(headers, start=1):
+        cell = ws_overview.cell(row=1, column=col, value=header)
+        cell.font = Font(bold=True, name="Calibri", size=11)
+        cell.alignment = Alignment(horizontal="center")
+
+    # Sheet 2: Issue Tree
+    ws_tree = wb.create_sheet("Issue Tree")
+    tree_headers = ["id", "parent_id", "depth", "branch", "hypothesis", "evidence_status"]
+    for col, header in enumerate(tree_headers, start=1):
+        cell = ws_tree.cell(row=1, column=col, value=header)
+        cell.font = Font(bold=True, name="Calibri", size=11)
+
+    # Sheet 3: Timeline
+    ws_timeline = wb.create_sheet("Timeline")
+    ws_timeline.cell(row=1, column=1, value="Sprint").font = Font(bold=True)
+    ws_timeline.cell(row=1, column=2, value="Milestone").font = Font(bold=True)
+
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    wb.save(str(out))
+    print(f"Saved: {out}")
+
+generate_workbook(f"deliverables/{workflow_id}/main/report.xlsx", "wf-001")
+```
+
+**Font override note:** openpyxl defaults to Calibri 11. Override to match client brand:
+
+```python
+cell.font = Font(bold=True, name="Inter", size=12, color="1F2937")
+```
+
+---
+
+### Pattern 2 — PDF via Pandoc
+
+Use for: narrative reports, executive memos, final deliverable documents.
+
+**Primary path (requires LaTeX / xelatex):**
+
+```bash
+pandoc input.md \
+  -o deliverables/<workflow-id>/<persona-set>/report.pdf \
+  --pdf-engine=xelatex \
+  --variable=mainfont:"Inter" \
+  --variable=geometry:margin=2.5cm \
+  --variable=fontsize:11pt \
+  --toc \
+  --toc-depth=2
+```
+
+**Alternative path (headless Chrome — no LaTeX dependency):**
+
+```bash
+# Step 1: convert md to self-contained HTML
+pandoc input.md -o /tmp/orchestrator-artifact-gen/report.html --standalone
+
+# Step 2: render HTML to PDF with Chromium headless
+chromium-browser --headless --disable-gpu \
+  --print-to-pdf=deliverables/<workflow-id>/<persona-set>/report.pdf \
+  /tmp/orchestrator-artifact-gen/report.html
+```
+
+Choose the Chromium alternative when the environment lacks LaTeX or when the client brand uses web fonts unavailable in TeX font registries.
+
+---
+
+### Pattern 3 — CSV Issue Tree (Python csv module)
+
+Use for: machine-readable issue trees, structured hypothesis logs, evidence tracking.
+
+Row schema: `id, parent_id, depth, branch, hypothesis, evidence_status`
+
+Valid `evidence_status` values: `validated`, `pending`, `disproven`
+
+```python
+import csv
+from pathlib import Path
+
+ISSUE_TREE_SCHEMA = ["id", "parent_id", "depth", "branch", "hypothesis", "evidence_status"]
+
+def write_issue_tree(rows: list[dict], output_path: str) -> None:
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    with out.open("w", newline="", encoding="utf-8") as fh:
+        writer = csv.DictWriter(fh, fieldnames=ISSUE_TREE_SCHEMA)
+        writer.writeheader()
+        for row in rows:
+            # Validate evidence_status before writing
+            if row["evidence_status"] not in ("validated", "pending", "disproven"):
+                raise ValueError(f"Invalid evidence_status: {row['evidence_status']}")
+            writer.writerow(row)
+
+    print(f"Issue tree written: {out} ({len(rows)} rows)")
+
+# Example usage
+sample_rows = [
+    {"id": "H1",    "parent_id": "",   "depth": 0, "branch": "root",     "hypothesis": "Revenue gap is structural", "evidence_status": "pending"},
+    {"id": "H1.1",  "parent_id": "H1", "depth": 1, "branch": "market",   "hypothesis": "Addressable market is shrinking", "evidence_status": "disproven"},
+    {"id": "H1.2",  "parent_id": "H1", "depth": 1, "branch": "pricing",  "hypothesis": "Price elasticity is negative", "evidence_status": "validated"},
+]
+write_issue_tree(sample_rows, "deliverables/wf-001/squad1/issue-tree.csv")
+```
+
+---
+
+### Pattern 4 — Jinja2 Master Template
+
+Use for: parametric Word-like docs, email templates, markdown reports with injected data blocks.
+
+```python
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+from pathlib import Path
+
+def render_template(
+    template_dir: str,
+    template_name: str,
+    context: dict,
+    output_path: str,
+) -> None:
+    # autoescape=False is intentional for markdown/plain-text templates.
+    # Set autoescape=True only when rendering HTML destined for a browser.
+    env = Environment(
+        loader=FileSystemLoader(template_dir),
+        undefined=StrictUndefined,   # raises on missing variables — no silent blanks
+        autoescape=False,
+    )
+    template = env.get_template(template_name)
+    rendered = template.render(**context)
+
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(rendered, encoding="utf-8")
+    print(f"Template rendered: {out}")
+
+# Template file convention: .claude/skills/artifact-generator/templates/<name>.md.j2
+render_template(
+    template_dir=".claude/skills/artifact-generator/templates",
+    template_name="executive-summary.md.j2",
+    context={
+        "workflow_id": "wf-001",
+        "client_name": "Acme Corp",
+        "date": "2026-05-12",
+        "findings": ["Finding A", "Finding B"],
+    },
+    output_path="deliverables/wf-001/main/executive-summary.md",
+)
+```
+
+**Template file path convention:** `<skill-dir>/templates/<name>.md.j2`
+
+**Escaping rules:**
+
+| Scenario | `autoescape` setting |
+|----------|---------------------|
+| Markdown / plain text output | `False` |
+| HTML output to browser | `True` |
+| Jinja tags inside strings | Use `{% raw %}...{% endraw %}` blocks |
+
+**`StrictUndefined` is mandatory.** It turns missing template variables into errors instead of silent empty strings, which would corrupt client deliverables.
+
+---
+
+## Validation Post-Generation
+
+Run these checks after every generated artifact before calling `artifactStore`.
+
+### xlsx integrity
+
+```bash
+python3 -c "
+import openpyxl, sys
+path = sys.argv[1]
+wb = openpyxl.load_workbook(path)
+print(f'Sheets: {wb.sheetnames}')
+print('OK — workbook valid')
+" deliverables/<workflow-id>/<persona-set>/report.xlsx
+```
+
+The command must exit 0 and print sheet names. Any exception indicates a corrupt file — regenerate before storing.
+
+### PDF integrity
+
+```bash
+# pdfinfo is part of poppler-utils
+pdfinfo deliverables/<workflow-id>/<persona-set>/report.pdf | grep Pages
+# Expected output: Pages: N  (where N > 0)
+```
+
+If `pdfinfo` is unavailable, fall back to:
+
+```bash
+python3 -c "
+import pathlib, sys
+p = pathlib.Path(sys.argv[1])
+assert p.exists() and p.stat().st_size > 1024, 'PDF missing or suspiciously small'
+print(f'Size: {p.stat().st_size} bytes — plausible PDF')
+" deliverables/<workflow-id>/<persona-set>/report.pdf
+```
+
+### CSV issue tree completeness
+
+```python
+import csv
+
+REQUIRED_FIELDS = {"id", "parent_id", "depth", "branch", "hypothesis", "evidence_status"}
+
+with open("deliverables/<workflow-id>/<persona-set>/issue-tree.csv", encoding="utf-8") as fh:
+    reader = csv.DictReader(fh)
+    assert set(reader.fieldnames or []) >= REQUIRED_FIELDS, "Missing required columns"
+    rows = list(reader)
+    assert len(rows) > 0, "Issue tree is empty"
+    print(f"CSV valid — {len(rows)} rows, all required columns present")
+```
+
+### Jinja2 rendered output
+
+After rendering, assert that expected section headers are present:
+
+```python
+text = pathlib.Path("deliverables/<workflow-id>/main/executive-summary.md").read_text()
+required_sections = ["## Executive Summary", "## Key Findings", "## Recommendations"]
+for section in required_sections:
+    assert section in text, f"Missing section: {section}"
+print("All required sections present")
+```
+
+---
+
+## Output Location Conventions
+
+| Category | Path pattern |
+|----------|-------------|
+| Client-facing deliverable | `deliverables/<workflow-id>/<persona-set>/<artifact-name>.<ext>` |
+| Working scratch / intermediates | `/tmp/orchestrator-artifact-gen/<workflow-id>/` |
+
+**Path rules:**
+
+- `<workflow-id>` is the active workflow UUID (e.g., `7c28e523-14c9-4807-be56-f9e1ed52ff38`)
+- `<persona-set>` is a short slug grouping by audience (e.g., `executive`, `squad1`, `main`)
+- `<artifact-name>` is kebab-case, descriptive (e.g., `issue-tree`, `executive-summary`, `sprint-schedule`)
+
+**Cleanup scratch directory** at skill completion:
+
+```bash
+rm -rf /tmp/orchestrator-artifact-gen/<workflow-id>/
+```
+
+Do not leave intermediate files in `/tmp` after the deliverable is stored in MinIO.
+
+---
+
+## Audit Trail Requirements
+
+Every generated client-facing artifact MUST be persisted via `mcp__orchestrator-extended__artifactStore` with `artifact_kind: deliverable`. The local file under `deliverables/` is a convenience copy only — it may be deleted; the MinIO record is authoritative.
+
+```
+# Step 1: load the tool schema (deferred-load pattern — TD-098)
+ToolSearch("select:mcp__orchestrator-extended__artifactStore")
+
+# Step 2: store the artifact
+mcp__orchestrator-extended__artifactStore({
+  workflowId: "<workflow-id>",
+  phase: "implement",          # or the PME phase that produced this artifact
+  type: "deliverable",
+  content: "<base64 or text content>",
+  metadata: {
+    artifact_kind: "deliverable",
+    format: "xlsx",            # or pdf, csv, docx, html
+    persona_set: "<persona-set>",
+    local_path: "deliverables/<workflow-id>/<persona-set>/<name>.<ext>",
+    generated_by: "artifact-generator",
+    s178_stack: "openpyxl+pandoc+jinja2"
+  }
+})
+```
+
+**Never skip this step.** Deliverables that exist only on disk are lost at container restart and leave no traceability in the workflow audit log.
+
+---
+
+## Common Gotchas
+
+| Gotcha | Symptom | Fix |
+|--------|---------|-----|
+| Pandoc + non-ASCII chars crash xelatex | PDF generation exits non-zero; log shows `! Package inputenc Error` | Add `--pdf-engine=xelatex` and `--variable=mainfont:"Noto Serif"`. Latin Modern (LaTeX default) chokes on Unicode outside Latin-1. |
+| openpyxl default font differs from brand | Client notices font mismatch (Calibri instead of Inter/Helvetica) | Explicitly set `Font(name="Inter", size=11)` on all header and body cells; openpyxl does not inherit theme fonts. |
+| Jinja2 silently blanks missing variables | Template renders with empty sections, no error thrown | Use `StrictUndefined` — this turns missing vars into `UndefinedError` at render time (see Pattern 4). |
+| jinja2 escaping corrupts Markdown | Underscores and angle brackets get HTML-entity-encoded (`&lt;`, `_`) | Pass `autoescape=False` for Markdown/plain-text templates. Only enable `autoescape=True` for HTML browser output. |
+| Pandoc Chromium path varies by OS | `--print-to-pdf` fails because `chromium-browser` not in PATH | Try `chromium`, `google-chrome`, or `google-chrome-stable` depending on distro; check with `which chromium chromium-browser google-chrome`. |
+| xlsx saved before directory exists | `FileNotFoundError` on `wb.save()` | Always call `Path(output_path).parent.mkdir(parents=True, exist_ok=True)` before saving. |
+| Large xlsx hits memory limit | `MemoryError` on files with 100k+ rows | Use `openpyxl.Workbook(write_only=True)` and `ws.append()` in streaming mode. |

package/skills/brainstorm-formalize/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: brainstorm-formalize
+description: Transform brainstorm output into formal documents (RFC/ADR/TD). Use after brainstorm completion when user approves the design.
+---
+
+# Skill: brainstorm-formalize
+
+## When to Load
+
+Load this skill when:
+- A brainstorm session has just completed AND the user approves formalizing the result
+- The user says "formalize this brainstorm" or "turn this into an RFC/ADR/TD"
+- The user explicitly invokes `/brainstorm-formalize`
+
+Do NOT load automatically during a brainstorm — wait for explicit user approval.
+
+---
+
+## Step 1 — Classification
+
+Ask the user which document type fits the brainstorm output:
+
+```
+AskUserQuestion({
+  question: "Brainstorm complete. What type of formal document should this become?",
+  options: [
+    "RFC — Request for Comments (proposal BEFORE implementation, requires community review)",
+    "ADR — Architecture Decision Record (documents a decision ALREADY made)",
+    "TD — Technical Debt item (tracks a known issue or improvement needed)",
+    "Keep as design.md — informal design note, no registry entry needed"
+  ]
+})
+```
+
+Wait for user selection before proceeding.
+
+---
+
+## Step 2 — Document Creation
+
+### Auto-ID Assignment
+
+Before creating any document, check the last used ID:
+- For RFC: Read `project-guidelines/rfcs/index.md`, find the highest `RFC-NNN` in the table, increment by 1
+- For ADR: Read `project-guidelines/adrs/index.md`, find the highest `ADR-NNN` in the Operational ADRs table, increment by 1
+- For TD: Check `project-guidelines/BACKLOG.md` for the highest `TD-NNN` in use
+
+### RFC Frontmatter Template
+
+```markdown
+---
+type: rfc
+id: RFC-NNN
+title: "[Title from brainstorm]"
+status: PROPOSED
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+layers:
+  - [domain|application|infrastructure|presentation]
+sub_layers:
+  - [hooks|skills|agents|memory|api|cli]
+related:
+  - [RFC-XXX|ADR-XXX if relevant]
+implements: []
+resolves: []
+supersedes: []
+absorbs: []
+depends_on:
+  - [RFC-XXX|ADR-XXX if relevant]
+health:
+  last_scan:
+  lims: []
+  score:
+---
+
+# RFC-NNN: [Title]
+
+**Status:** PROPOSED
+**Version:** 1.0.0
+**Date:** YYYY-MM-DD
+**Author:** Main Orchestrator + User (brainstorm)
+**Target Version:** vX.Y.Z+
+**Depends On:** [or None]
+**Brainstorm:** `docs/superpowers/specs/YYYY-MM-DD-rfcNNN-[slug].md`
+```
+
+File location: `project-guidelines/rfcs/RFC-NNN-TITLE-SLUG.md`
+
+### ADR Frontmatter Template
+
+```markdown
+---
+type: adr
+id: ADR-NNN
+title: "[Title from brainstorm]"
+status: proposed
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+layers: []
+sub_layers: []
+related: []
+depends_on: []
+health:
+  last_scan:
+  lims: []
+  score:
+---
+
+# ADR-NNN: [Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Proposed
+```
+
+Follow with standard ADR sections: Contexto, Decisão, Consequências (Positivas / Negativas), Alternativas Consideradas.
+
+File location: `project-guidelines/adrs/ADR-NNN-TITLE-SLUG.md`
+
+### TD Entry Template
+
+TD items live in `project-guidelines/BACKLOG.md`. Add a new entry in the appropriate priority section:
+
+```markdown
+### TD-NNN — [Short Title] (MEDIUM|HIGH|LOW, Nh)
+**Symptom:** [What is observed]
+**Root cause:** [Why it happens]
+**Fix:** [Proposed solution]
+**Origin:** Brainstorm `docs/superpowers/specs/YYYY-MM-DD-[slug].md`
+```
+
+### design.md Template
+
+If the user chooses to keep it informal:
+
+```markdown
+# Design: [Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Draft
+**Origin:** `docs/superpowers/specs/YYYY-MM-DD-[slug].md`
+
+## Summary
+[Key decisions from the brainstorm]
+
+## Open Questions
+[Items that need resolution before implementation]
+```
+
+File location: `docs/designs/YYYY-MM-DD-[title-slug].md`
+Create the directory if it does not exist: `mkdir -p docs/designs/`
+
+---
+
+## Step 3 — Auto-Indexation
+
+After creating the document file, add a line to the appropriate index.
+
+### RFC Index Line Format
+
+Open `project-guidelines/rfcs/index.md` and add a new row to the "RFCs Ativas" table:
+
+```
+| [RFC-NNN](./RFC-NNN-TITLE-SLUG.md) | [Title] | **PROPOSED** | vX.Y.Z+ |
+```
+
+The table has 4 columns: RFC | Título | Status | Versão Target.
+Add the new row AFTER the last existing RFC row (before the closing `---`).
+
+### ADR Index Line Format
+
+Open `project-guidelines/adrs/index.md` and add a new row to the "Operational ADRs" table:
+
+```
+| [ADR-NNN](./ADR-NNN-TITLE-SLUG.md) | [Title] | YYYY-MM-DD | **Proposed** |
+```
+
+The table has 4 columns: ADR | Título | Data | Status.
+
+### TD / design.md
+
+No index entry needed — TDs live in BACKLOG.md directly, and design.md files are self-contained.
+
+---
+
+## Step 4 — Sprint Decomposition
+
+If the brainstorm produced a multi-sprint implementation plan, add a sprint table to the new document:
+
+```markdown
+## Sprint Decomposition
+
+| Sprint | Scope | Estimate | Status | Deliverables |
+|--------|-------|----------|--------|--------------|
+| S1 | [Scope of sprint 1] | Xh | PROPOSED | [Key deliverable] |
+| S2 | [Scope of sprint 2] | Xh | PROPOSED | [Key deliverable] |
+| SN | [Scope of sprint N] | Xh | PROPOSED | [Key deliverable] |
+```
+
+Guidelines for sprint sizing:
+- Target 4-8h per sprint for a single implementer session
+- Each sprint should have at least one concrete, testable deliverable
+- Dependent sprints must be ordered (no circular dependencies)
+
+---
+
+## Step 5 — Reference Link
+
+Add a `## Brainstorm Reference` section at the END of the new formal document linking back to the brainstorm source:
+
+```markdown
+## Brainstorm Reference
+
+**Source:** `docs/superpowers/specs/YYYY-MM-DD-[slug].md`
+
+The brainstorm session that originated this document is preserved at the path above.
+This allows tracing design decisions back to the original exploration.
+```
+
+This creates a bidirectional link: formal doc → brainstorm source.
+
+---
+
+## Step 6 — Sprint Context Seed
+
+After the formal document is created and indexed, seed the sprint context file so that future brainstorm sessions for this RFC's sprints automatically receive parent document context.
+
+Create `.claude/sprint-context/{workflowId}.json` with this exact schema:
+
+```json
+{
+  "schema": "1.0",
+  "parentDocument": "project-guidelines/rfcs/RFC-NNN-TITLE-SLUG.md",
+  "sprintIndex": 1,
+  "sprintScope": "[Sprint 1 scope from Step 4 table]",
+  "previousSprints": [],
+  "workflowId": "{currentWorkflowId}",
+  "createdAt": "{ISO-8601 timestamp}"
+}
+```
+
+Field notes:
+- `schema`: always `"1.0"` for this version
+- `parentDocument`: relative path from project root to the RFC/ADR file
+- `sprintIndex`: the NEXT sprint to be executed (start at 1 for a new document)
+- `sprintScope`: copy from the Sprint Decomposition table (Step 4)
+- `previousSprints`: empty array for a brand-new document
+- `workflowId`: the current active workflow ID (from MCP tools or workflow state)
+- `createdAt`: current UTC timestamp in ISO-8601 format
+
+The file is written to `.claude/sprint-context/` in the project root. The `writeSprintContext` helper in `.claude/hooks/lib/sprint-context.ts` can be called programmatically if running in a hook context. Otherwise, create the JSON file directly.
+
+**Update for subsequent sprints:** When a sprint completes, update this file:
+- Increment `sprintIndex` to the next sprint
+- Update `sprintScope` to the next sprint scope
+- Append the completed sprint to `previousSprints`:
+  ```json
+  { "index": N, "status": "complete", "deliverables": ["file1.ts", "SKILL.md"] }
+  ```
+
+---
+
+## Completion Checklist
+
+Before considering formalization complete:
+
+- [ ] Document file created with correct frontmatter
+- [ ] Correct ID assigned (no collision with existing IDs)
+- [ ] Added to index.md (RFC or ADR)
+- [ ] Sprint Decomposition table included (if multi-sprint)
+- [ ] Brainstorm Reference section added
+- [ ] `.claude/sprint-context/{workflowId}.json` seeded
+- [ ] User notified of file path and next step (e.g. "Start Sprint 1 workflow")