@orchestrator-claude/definitions 3.30.2 → 3.31.1

package/skills/orchestrator/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: orchestrator
+description: Workflow coordination runtime — phase dispatch call signatures, sub-agent prompt template, gate-check template, stack context, error recovery. Loaded on demand when starting or advancing a workflow. Greeting and orchestrator identity live in the Skin (.claude/agents/orchestrator.md); universal invariants live in CLAUDE.md. See ADR-019.
+---
+
+# Skill: /orchestrator (Layer B — On-Demand Coordination Runtime)
+
+> **Scope:** this skill is loaded by the main-with-skin-orchestrator **when a workflow is being started, advanced, or completed**. It does NOT handle greeting (Skin + hook data) and does NOT restate identity or universal invariants (those live in Skin and `CLAUDE.md` respectively). See **ADR-019** for the three-layer rationale.
+
+## Step 1 — Start a Workflow
+
+```
+mcp__orchestrator-tools__detectWorkflow({ prompt: "user's request" })
+mcp__orchestrator-tools__startWorkflow({
+  type: "feature_development" | "bug_fix" | "refactoring" | "emergency_debug" | "project_management_enterprise",
+  prompt: "...",
+  variant: "consultoria-externa" | "consultoria-interna" | "software-handoff" | "cirurgico" | undefined, // optional, defaults to "full"
+  inputs: { ... } // optional, required_inputs per variant (validated by PreFlightValidator)
+})
+```
+
+## Step 2 — Phase Dispatch Loop
+
+For each phase (research → specify → plan → tasks → implement → review), run this cycle.
+
+### 2a. Build Stack Context (RFC-026 Sprint 2)
+
+Before dispatching an agent, build stack context if auto-detection has produced a result:
+
+```
+const context = await stackContextBuilder.build(patternSet, agentRole);
+```
+
+Role-appropriate slicing:
+- **Implementers** get full context (commands + assets + conventions + patterns).
+- **Specifiers** get minimal context (stack label only).
+- **All agents** can deep-dive via `mcp__orchestrator-extended__getStackConventions`.
+
+If no detection result, skip — agents fall back to universal conventions.
+
+### 2b. Variant-Aware Phase Dispatch (RFC-031 §4)
+
+When a workflow has a `variant`, the phase-skip mechanic applies at each phase boundary. Before dispatching an agent, resolve the variant matrix cell:
+
+```
+cell = VariantResolver.resolvePhaseCell(modes, variant, phase)
+```
+
+- **cell = EXEC** → dispatch agent normally (proceed to 2c).
+- **cell = SKIP** → mark phase complete without dispatching any agent; call `advancePhase` and continue loop.
+- **cell = PARTIAL** → dispatch agent but only require the artifacts listed in the cell; gate check still applies.
+
+If no variant is set (or variant resolves to `"full"`), all phases execute normally — skip this check.
+
+### 2c. Dispatch Phase Sub-Agent
+
+| Phase | Agent | Artifact |
+|-------|-------|----------|
+| research | `researcher` | research findings |
+| specify | `specifier` | spec.md → `artifactStore` |
+| plan | `planner` | plan.md → `artifactStore` |
+| tasks | `task-generator` | tasks.md → `artifactStore` |
+| implement | `implementer` | code + tests |
+| review | `reviewer` | review feedback |
+
+**Dispatch template:**
+
+```
+Agent(subagent_type: "{phase_agent}", prompt: "
+  [Workflow] Type: {type}, Phase: {phase}, Project: {projectId}
+
+  [Stack Context]
+  {stack_context_from_builder}
+
+  [Previous artifact] {summary of previous phase artifact, if any}
+  [Task] {phase-specific instructions from user's original request}
+
+  Store your output artifact via mcp__orchestrator-extended__artifactStore.
+")
+```
+
+Sub-agents MUST persist artifacts to MinIO via `artifactStore` (universal rule, see `CLAUDE.md`).
+
+<!-- TODO S182 (OQ-4): per-phase agent override (.phases[n].agent) deferred — S182 will resolve permissive vs registry-validated vs KnownAgent-enum strategy after agent list complete -->
+
+#### 2c.1 Implementer-specific dispatch addenda (TD-S188-002)
+
+When dispatching `implementer` (phase=`implement`), the generic template above is **insufficient**. The S188 implement phase surfaced an ambiguity: the implementer interpreted `createCheckpoint` as requiring a git commit beforehand, producing 4 unsolicited commits per dispatch (commit prefix also leaked from BACKLOG context: `feat(s186)` instead of `feat(s188)`). To prevent recurrence, append the following **commit policy block** to every implementer dispatch prompt:
+
+```
+[Commit Policy]
+- createCheckpoint (mcp__orchestrator-tools__createCheckpoint) is a PostgreSQL state snapshot per RFC-012. It is INDEPENDENT of git. You do NOT need to commit before calling it. Calling createCheckpoint with no uncommitted changes is the normal path.
+- Commit policy for this dispatch: <one of>
+    a) "DO NOT commit — orchestrator owns the closure commit at review gate."
+    b) "Commit per-phase using prefix `<feat|fix|refactor>(s<N>): <subject>` — confirm prefix before commit." (use when implement phase exceeds 80k tokens or spans multiple fases)
+- If you commit, the prefix MUST be: `<feat|fix|refactor>(s<CURRENT_SESSION>):` — do NOT infer from BACKLOG examples or previous session context.
+```
+
+Substitute `<CURRENT_SESSION>` with the active session number (e.g., `s189`) and pick **exactly one** of (a) or (b) — never leave both options visible. The block goes **after** `[Task]` and **before** the artifactStore instruction.
+
+If the orchestrator (main) wants to own all commits, prefer option (a) + call `createCheckpoint` itself after the implement phase completes — do NOT delegate that call to implementer.
+
+### 2d. Gate Check
+
+After each sub-agent completes, present the artifact summary and ask for approval:
+
+```
+AskUserQuestion({
+  question: "Phase '{phase}' complete.\n\n{artifact_summary}\n\nApprove to proceed to next phase?",
+  options: ["Approve", "Request changes", "Abort workflow"]
+})
+```
+
+- **Approve** → call `advancePhase`, dispatch next phase agent.
+- **Request changes** → re-dispatch same sub-agent with the user's feedback.
+- **Abort** → call `completeWorkflow` with `cancelled` status.
+
+### 2e. Advance Phase
+
+```
+mcp__orchestrator-tools__advancePhase({ workflowId: "..." })
+```
+
+Loop back to 2a for the next phase.
+
+## Step 3 — Complete Workflow
+
+After all phases are done:
+
+```
+mcp__orchestrator-extended__completeWorkflow({ workflowId: "..." })
+```
+
+Summarize what was accomplished and any follow-up items.
+
+## Operational SHOULDs
+
+1. SHOULD keep sub-agent prompts focused — workflow context + previous artifact summary + task description, nothing else.
+2. SHOULD summarize, not dump — at gate checks, present a concise artifact summary, not full content.
+3. SHOULD use `/workflow-status` to diagnose stuck workflows.
+
+## Phase-Specific Skills
+
+Load these for phase-specific guidance when needed:
+
+| Skill | When |
+|-------|------|
+| `/artifact-production` | Before dispatching specify / plan / tasks agents |
+| `/tdd-discipline` | Before dispatching implementer |
+| `/project-conventions` | Before implementation (stack-agnostic; stack-specific context via StackContextBuilder) |
+| `/checkpoint-protocol` | After completing task groups |
+
+## Error Recovery
+
+- **Sub-agent fails** → read the error, fix the issue, re-dispatch.
+- **MCP tool not found** → call `ToolSearch` to load the schema, then retry (deferred loading, see `CLAUDE.md`).
+- **Workflow stuck** → call `getStatus` to diagnose, present options to user via `AskUserQuestion`.
+- **Context getting large** → sub-agents carry heavy work; main stays lean with summaries.

package/skills/persona-library/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: persona-library
+description: Catalog navigation for `.claude/personas/`. Load when: "find persona", "list personas", "select reviewer persona", "persona by industry", "persona for X industry", "create new persona", or when methodology-researcher / adversarial-reviewer / operational-artifact-builder need persona selection guidance. Provides search/filter/select-for-review primitives + scaffold for new persona authoring.
+allowed-tools: Read, Grep, Glob, Write
+---
+
+# Skill: /persona-library - Persona Catalog Navigation
+
+## When to Use This Skill
+
+Load when any of the following triggers appear:
+
+- "find persona", "list personas", "list personas by industry", "select reviewer persona"
+- "persona for X industry", "persona by role", "which persona should I use"
+- "create new persona", "add a persona to the library"
+- methodology-researcher needs persona vocabulary before shortlisting methodologies
+- adversarial-reviewer needs persona biases before executing a critique pass
+- operational-artifact-builder needs persona demands before formatting a deliverable
+- explicit `/persona-library` invocation from orchestrator or any sub-agent
+
+**Out of scope:** adversarial review execution, methodology selection, artifact formatting,
+persona file authoring beyond the scaffold template here.
+
+---
+
+## Catalog Overview
+
+Canonical entry point: `.claude/personas/INDEX.md`. Seed library (S183):
+
+| id | role | industry | adversarial_intensity | validated_in |
+|----|------|----------|-----------------------|--------------|
+| diretor-cetico-fmcg | Diretor de Marketing / Brand Director | FMCG | high | S178 |
+| cfo-conservador | CFO / VP Finance | cross-industry | high | S183 |
+| auditor-compliance | Auditor de Compliance / Compliance Officer | cross-industry (financeiro, saude, governo) | medium | - |
+| designer-perfeccionista | Senior Designer / Design Lead | cross-industry (product, marketing, brand) | medium | - |
+| engenheiro-cetico-construcao | Engenheiro Civil Senior / Construction Project Engineer | construcao civil | medium | - |
+
+Each persona file: `.claude/personas/<id>.md`. Schema: YAML frontmatter (10 required fields) +
+Markdown body (3 sections: Narrative, Sample Objections, Adversarial Review Behavior).
+For stacking guidance, read `.claude/personas/INDEX.md` directly.
+
+---
+
+## Search Patterns
+
+Use these grep patterns to filter the library when INDEX.md alone is insufficient
+(e.g., a newly scaffolded persona not yet in the table).
+
+### By Industry
+
+```bash
+# FMCG
+grep -l "industry:.*FMCG" .claude/personas/*.md
+# -> diretor-cetico-fmcg.md
+
+# Compliance-regulated sectors (financeiro, saude, governo)
+grep -l "industry:.*compliance\|industry:.*financeiro\|industry:.*governo\|industry:.*saude" .claude/personas/*.md
+# -> auditor-compliance.md
+
+# Construction / civil engineering
+grep -l "industry:.*construcao" .claude/personas/*.md
+# -> engenheiro-cetico-construcao.md
+
+# Cross-industry (applies to any sector)
+grep -l "industry:.*cross-industry" .claude/personas/*.md
+# -> cfo-conservador.md, auditor-compliance.md
+
+# Design / product / brand
+grep -l "industry:.*product\|industry:.*marketing\|industry:.*brand" .claude/personas/*.md
+# -> designer-perfeccionista.md
+```
+
+Default to the INDEX.md table for the full filterable list. Use grep only when INDEX.md may be
+stale relative to freshly-authored persona files.
+
+### By Role
+
+```bash
+# CFO / finance executive
+grep -l "role:.*CFO\|role:.*VP Finance" .claude/personas/*.md
+# -> cfo-conservador.md
+
+# Marketing / brand director
+grep -l "role:.*Diretor de Marketing\|role:.*Brand Director" .claude/personas/*.md
+# -> diretor-cetico-fmcg.md
+
+# Compliance / audit
+grep -l "role:.*Compliance\|role:.*Auditor" .claude/personas/*.md
+# -> auditor-compliance.md
+
+# Design lead
+grep -l "role:.*Designer\|role:.*Design Lead" .claude/personas/*.md
+# -> designer-perfeccionista.md
+
+# Civil engineer
+grep -l "role:.*Engenheiro" .claude/personas/*.md
+# -> engenheiro-cetico-construcao.md
+```
+
+### By Bias (Semantic)
+
+When the caller knows the dominant objection type but not the persona name, map bias to persona:
+
+| Bias / Objection Axis | Persona |
+|-----------------------|---------|
+| audit-trail obsession, regulatory compliance, sign-off chain | auditor-compliance |
+| TCO / NPV / cash flow obsession, exit cost transparency | cfo-conservador |
+| pixel-level scrutiny, typography, spacing, visual consistency | designer-perfeccionista |
+| critical-path integrity, NBR norms, structural risk | engenheiro-cetico-construcao |
+| data-driven but skeptical, FMCG sell-out velocity, shelf ROI | diretor-cetico-fmcg |
+
+To search frontmatter biases directly:
+
+```bash
+# Find personas that mention cash flow in their bias list
+grep -l "cash flow" .claude/personas/*.md
+
+# Find personas that mention audit trail
+grep -l "audit.trail\|audit trail" .claude/personas/*.md
+
+# Find personas with pixel or visual scrutiny
+grep -l "pixel\|visual consistency" .claude/personas/*.md
+```
+
+### By Adversarial Intensity
+
+```bash
+# High-intensity personas (block approval on structural gaps)
+grep -rl "^adversarial_intensity: high" .claude/personas/
+# -> diretor-cetico-fmcg.md, cfo-conservador.md
+
+# Medium-intensity personas (flag issues, allow progression with remediation plan)
+grep -rl "^adversarial_intensity: medium" .claude/personas/
+# -> auditor-compliance.md, designer-perfeccionista.md, engenheiro-cetico-construcao.md
+
+# Low-intensity (none in seed library - extensibility hook for future addition)
+grep -rl "^adversarial_intensity: low" .claude/personas/
+```
+
+**Intensity semantics:** `high` = blocks approval without evidence; `medium` = flags issues,
+allows progression with remediation plan; `low` = none in seed library (extensibility hook).
+
+**Stacking rule:** when multiple personas apply, run high-intensity first, then medium.
+
+---
+
+## Select-for-Review Primitive
+
+Algorithm for programmatic persona selection:
+
+```
+function selectReviewerPersona(artifactKind, clientIndustry, riskTolerance) {
+  // 1. Filter personas matching clientIndustry
+  //    - exact match on industry field, OR
+  //    - industry field contains "cross-industry" (applies everywhere)
+  candidates = personas.filter(p =>
+    p.industry.includes(clientIndustry) || p.industry.includes("cross-industry")
+  )
+
+  // 2. Filter by adversarial_intensity matching riskTolerance
+  //    riskTolerance: "high" => prefer high-intensity personas
+  //    riskTolerance: "medium" => prefer medium-intensity personas
+  //    riskTolerance: "low" => prefer low-intensity (fall back to medium if none)
+  if (candidates.some(p => p.adversarial_intensity === riskTolerance)) {
+    candidates = candidates.filter(p => p.adversarial_intensity === riskTolerance)
+  }
+
+  // 3. If multiple remain, prefer validated persona (validated_in != "-" or empty)
+  if (candidates.some(p => p.validated_in && p.validated_in !== "-")) {
+    candidates = candidates.filter(p => p.validated_in && p.validated_in !== "-")
+  }
+
+  // 4. Return persona id for adversarial-reviewer dispatch
+  return candidates[0].id
+}
+```
+
+**Quick decision table for common scenarios:**
+
+| Scenario | Recommended persona | Rationale |
+|----------|--------------------|-----------|
+| Financial proposal, any sector | cfo-conservador | Cross-industry, high intensity, TCO lens |
+| Marketing / brand strategy, FMCG | diretor-cetico-fmcg | Exact industry match, high intensity |
+| Regulatory or compliance audit | auditor-compliance | Cross-industry, compliance lens |
+| Product / UX deliverable review | designer-perfeccionista | Visual and UX scrutiny |
+| Construction or infrastructure plan | engenheiro-cetico-construcao | Domain-specific, NBR/technical norms |
+| Multi-stakeholder review (finance + ops) | cfo-conservador + auditor-compliance | Stack sequentially; high before medium |
+
+---
+
+## Scaffold for New Persona
+
+Create `.claude/personas/<id>.md` using the templates below. All 10 frontmatter fields
+required. Body must contain the 3 section headings shown. Run audit script before committing.
+
+### Frontmatter Template
+
+```yaml
+---
+id: <kebab-case-identifier>
+role: <Job Title / Role Name>
+industry: <target industry or "cross-industry (applicable sectors list)">
+seniority: <seniority level, e.g., C-level | Senior | Director | Manager>
+biases:
+  - <bias or cognitive tendency 1 - phrase as a behavioral pattern>
+  - <bias or cognitive tendency 2>
+  - <bias or cognitive tendency 3>
+vocabulary:
+  - <domain term, acronym, or signature phrase 1>
+  - <domain term, acronym, or signature phrase 2>
+  - <domain term, acronym, or signature phrase 3>
+demands:
+  - <concrete deliverable or evidence requirement 1>
+  - <concrete deliverable or evidence requirement 2>
+  - <concrete deliverable or evidence requirement 3>
+adversarial_intensity: <high | medium | low>
+validated_in:
+  - <sprint ref, e.g., S183> # or use "-" if not yet exercised in a live workflow
+---
+```
+
+10 required fields: `id`, `role`, `industry`, `seniority`, `biases`, `vocabulary`, `demands`,
+`adversarial_intensity`, `validated_in`. Each list field must have >= 3 items.
+
+### Body Template
+
+```markdown
+# <Persona Display Name>
+
+## Narrative
+
+<2-4 paragraphs. Cover: professional background, years of experience, formative incidents
+that shaped current skepticism, core approval criteria. Write in third person. Make the
+persona's dominant fear and dominant approval signal explicit.>
+
+## Sample Objections
+
+<Numbered or bulleted list of 4-8 verbatim challenge phrases this persona would voice during
+a review. These should be direct quotes, not descriptions. Examples:
+- "Where is the 3-year TCO? I am not approving without seeing the all-in number."
+- "This timeline assumes perfect execution. What is the contingency plan?"
+- "You have cited a 2019 case study. I need evidence from the last 24 months.">
+
+## Adversarial Review Behavior
+
+<Structured rubric the adversarial-reviewer agent applies when embodying this persona.
+Organize by severity: CRITICAL blockers (will reject), HIGH flags (must remediate before
+next phase), MEDIUM observations (document and address). Each item should name the
+gap and the evidence that would satisfy it.>
+```
+
+### Validation After Authoring
+
+After writing the persona file, run the audit script and verify it exits 0:
+
+```bash
+bash scripts/audit-personas.sh
+```
+
+The script checks:
+- All 10 required frontmatter fields are present
+- `adversarial_intensity` value is one of: `high`, `medium`, `low`
+- Each of `biases`, `vocabulary`, `demands` has at least 3 items
+- Body contains all 3 required section headings: `Narrative`, `Sample Objections`,
+  `Adversarial Review Behavior`
+
+**The persona MUST pass `scripts/audit-personas.sh` with exit 0 before any commit.**
+
+After the persona passes, add it to `.claude/personas/INDEX.md` by inserting a row in the
+Persona Table with its id, role, industry, adversarial_intensity, and `validated_in: -`
+(until it survives a live workflow dry-run).
+
+---
+
+## Validation Requirements
+
+Every persona file in `.claude/personas/` MUST satisfy all of the following:
+
+1. **10 required frontmatter fields present:** `id`, `role`, `industry`, `seniority`,
+   `biases`, `vocabulary`, `demands`, `adversarial_intensity`, `validated_in`.
+
+2. **List field minimums:** `biases`, `vocabulary`, and `demands` each contain >= 3 items.
+
+3. **adversarial_intensity value:** must be exactly one of `high`, `medium`, or `low`.
+   Any other value (or missing value) causes `audit-personas.sh` to fail.
+
+4. **Body section completeness:** the Markdown body must contain all three section headings
+   in this exact form: `## Narrative`, `## Sample Objections`, `## Adversarial Review Behavior`.
+
+5. **Audit script exit 0:** `bash scripts/audit-personas.sh` must exit 0 before any commit
+   that adds or modifies a persona file. This is a hard gate - do not bypass with `--no-verify`.
+
+6. **INDEX.md registration:** after a new persona passes the audit, add a row to the INDEX.md
+   Persona Table. The `validated_in` column starts as `-`; update it to the sprint reference
+   once the persona is exercised in a live workflow dry-run.
+
+---
+
+## Common Use Cases
+
+### methodology-researcher
+
+Load persona BEFORE shortlisting methodologies. Extract `vocabulary` to scope language
+register; extract `demands` to confirm the methodology produces required outputs.
+
+```
+1. Load /persona-library -> select persona by industry + risk tolerance
+2. Read .claude/personas/<id>.md -> extract vocabulary and demands
+3. Use vocabulary to constrain methodology naming; verify methodology satisfies demands
+```
+
+### adversarial-reviewer
+
+Load persona BEFORE the critique pass. Apply `biases` as lens; use `adversarial_intensity`
+to set severity threshold; log persona id in artifact metadata.
+
+```
+1. Load /persona-library -> selectReviewerPersona(artifactKind, clientIndustry, riskTolerance)
+2. Read .claude/personas/<id>.md -> full file including Adversarial Review Behavior section
+3. Embody persona: raise objections in persona vocabulary; classify CRITICAL / HIGH / MEDIUM
+4. Log persona_id in artifact metadata (audit trail)
+```
+
+### operational-artifact-builder
+
+Load persona BEFORE formatting. Map `demands` to required deliverable sections.
+
+```
+1. Load /persona-library -> select persona(s) for target audience
+2. Read demands field -> map each demand to a required deliverable section
+3. Build artifact satisfying all demands; log persona_id(s) in metadata
+```
+
+---
+
+## Audit Trail
+
+Record persona usage in artifact metadata at every phase where a persona was loaded.
+
+When calling `mcp__orchestrator-extended__artifactStore`, include in `metadata`:
+
+```json
+{
+  "persona_id": "<id of persona used>",
+  "persona_intensity": "<high|medium|low>",
+  "persona_validated_in": "<sprint ref or ->",
+  "review_phase": "<workflow phase where persona was applied>"
+}
+```
+
+### Updating INDEX.md validated_in
+
+After a persona survives a live workflow dry-run, update `validated_in` in both the persona
+file (YAML sequence) and the INDEX.md table row. Until then, leave it as `-`. Prefer validated
+personas for high-stakes review passes; treat unvalidated personas as draft.
+
+---
+
+## References
+
+- Persona catalog index: `.claude/personas/INDEX.md`
+- Individual persona files: `.claude/personas/<id>.md`
+- Audit validation script: `scripts/audit-personas.sh`
+- Persona schema established: TASK-007, commit cc7a4724, S183 Wave 3
+- This skill created: TASK-017, S183 Wave 4