pi-maestro-flow 0.2.0

package/skills/delegation-check/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: delegation-check
+description: "Check workflow delegation prompts against agent role definitions for content separation violations. Detects conflicts, duplication, boundary leaks, and missing contracts. Triggers on \"check delegation\", \"delegation conflict\", \"prompt vs role check\"."
+allowed-tools: Read Glob Grep Bash AskUserQuestion
+---
+
+<purpose>
+Validate that command delegation prompts (Agent() calls) and agent role definitions respect GSD content separation boundaries. Detects 7 conflict dimensions: role re-definition, domain expertise leaking into prompts, quality gate duplication, output format conflicts, process override, scope authority conflicts, and missing contracts.
+
+Invoked when user requests "check delegation", "delegation conflict", "prompt vs role check", or when reviewing workflow skill quality.
+</purpose>
+
+<required_reading>
+- @.claude/skills/delegation-check/specs/separation-rules.md
+</required_reading>
+
+<process>
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro load --type spec --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "skill design optimization" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## 1. Determine Scan Scope
+
+Parse `$ARGUMENTS` to identify what to check.
+
+| Signal | Scope |
+|--------|-------|
+| File path to command `.md` | Single command + its agents |
+| File path to agent `.md` | Single agent + commands that spawn it |
+| Directory path (e.g., `.claude/skills/team-*/`) | All commands + agents in that skill |
+| "all" or no args | Scan all `.claude/commands/`, `.claude/skills/*/`, `.claude/agents/` |
+
+If ambiguous, ask:
+
+```
+AskUserQuestion(
+  header: "Scan Scope",
+  question: "What should I check for delegation conflicts?",
+  options: [
+    { label: "Specific skill", description: "Check one skill directory" },
+    { label: "Specific command+agent pair", description: "Check one command and its spawned agents" },
+    { label: "Full scan", description: "Scan all commands, skills, and agents" }
+  ]
+)
+```
+
+## 2. Discover Command-Agent Pairs
+
+For each command file in scope:
+
+**2a. Extract Agent() calls from commands:**
+
+```bash
+# Search both Agent() (current) and Task() (legacy GSD) patterns
+grep -n "Agent(\|Task(" "$COMMAND_FILE"
+grep -n "subagent_type" "$COMMAND_FILE"
+```
+
+For each `Agent()` call, extract:
+- `subagent_type` → agent name
+- Full prompt content between the prompt markers (the string passed as `prompt=`)
+- Line range of the delegation prompt
+
+**2b. Locate agent definitions:**
+
+For each `subagent_type` found:
+```bash
+# Check standard locations
+ls .claude/agents/${AGENT_NAME}.md 2>/dev/null
+ls .claude/skills/*/agents/${AGENT_NAME}.md 2>/dev/null
+```
+
+**2c. Build pair map:**
+
+```
+$PAIRS = [
+  {
+    command: { path, agent_calls: [{ line, subagent_type, prompt_content }] },
+    agent: { path, role, sections, quality_gate, output_contract }
+  }
+]
+```
+
+If an agent file cannot be found, record as `MISSING_AGENT` — this is itself a finding.
+
+## 3. Parse Delegation Prompts
+
+For each Agent() call, extract structured blocks from the prompt content:
+
+| Block | What It Contains |
+|-------|-----------------|
+| `<objective>` | What to accomplish |
+| `<files_to_read>` | Input file paths |
+| `<additional_context>` / `<planning_context>` / `<verification_context>` | Runtime parameters |
+| `<output>` / `<expected_output>` | Output format/location expectations |
+| `<quality_gate>` | Per-invocation quality checklist |
+| `<deep_work_rules>` / `<instructions>` | Cross-cutting policy or revision instructions |
+| `<downstream_consumer>` | Who consumes the output |
+| `<success_criteria>` | Success conditions |
+| Free-form text | Unstructured instructions |
+
+Also detect ANTI-PATTERNS in prompt content:
+- Role identity statements ("You are a...", "Your role is...")
+- Domain expertise (decision tables, heuristics, comparison examples)
+- Process definitions (numbered steps, step-by-step instructions beyond scope)
+- Philosophy statements ("always prefer...", "never do...")
+- Anti-pattern lists that belong in agent definition
+
+## 4. Parse Agent Definitions
+
+For each agent file, extract:
+
+| Section | Key Content |
+|---------|------------|
+| `<role>` | Identity, spawner, responsibilities, mandatory read |
+| `<philosophy>` | Guiding principles |
+| `<upstream_input>` | How agent interprets input |
+| `<output_contract>` | Return markers (COMPLETE/BLOCKED/CHECKPOINT) |
+| `<quality_gate>` | Self-check criteria |
+| Domain sections | All `<section_name>` tags with their content |
+| YAML frontmatter | name, description, tools |
+
+## 5. Run Conflict Checks (7 Dimensions)
+
+### Dimension 1: Role Re-definition
+
+**Question:** Does the delegation prompt redefine the agent's identity?
+
+**Check:** Scan prompt content for:
+- "You are a..." / "You are the..." / "Your role is..."
+- "Your job is to..." / "Your responsibility is..."
+- "Core responsibilities:" lists
+- Any content that contradicts agent's `<role>` section
+
+**Allowed:** References to mode ("standard mode", "revision mode") that the agent's `<role>` already lists in "Spawned by:".
+
+**Severity:** `error` if prompt redefines role; `warning` if prompt adds responsibilities not in agent's `<role>`.
+
+### Dimension 2: Domain Expertise Leak
+
+**Question:** Does the delegation prompt embed domain knowledge that belongs in the agent?
+
+**Check:** Scan prompt content for:
+- Decision/routing tables (`| Condition | Action |`)
+- Good-vs-bad comparison examples (`| TOO VAGUE | JUST RIGHT |`)
+- Heuristic rules ("If X then Y", "Always prefer Z")
+- Anti-pattern lists ("DO NOT...", "NEVER...")
+- Detailed process steps beyond task scope
+
+**Exception:** `<deep_work_rules>` is an acceptable cross-cutting policy pattern from GSD — flag as `info` only.
+
+**Severity:** `error` if prompt contains domain tables/examples that duplicate agent content; `warning` if prompt contains heuristics not in agent.
+
+### Dimension 3: Quality Gate Duplication
+
+**Question:** Do the prompt's quality checks overlap or conflict with the agent's own `<quality_gate>`?
+
+**Check:** Compare prompt `<quality_gate>` / `<success_criteria>` items against agent's `<quality_gate>` items:
+- **Duplicate:** Same check appears in both → `warning` (redundant, may diverge)
+- **Conflict:** Contradictory criteria (e.g., prompt says "max 3 tasks", agent says "max 5 tasks") → `error`
+- **Missing:** Prompt expects quality checks agent doesn't have → `info`
+
+**Severity:** `error` for contradictions; `warning` for duplicates; `info` for gaps.
+
+### Dimension 4: Output Format Conflict
+
+**Question:** Does the prompt's expected output format conflict with the agent's `<output_contract>`?
+
+**Check:**
+- Prompt `<expected_output>` markers vs agent's `<output_contract>` return markers
+- Prompt expects specific format agent doesn't define
+- Prompt expects file output but agent's contract only defines markers (or vice versa)
+- Return marker names differ (prompt expects `## DONE`, agent returns `## TASK COMPLETE`)
+
+**Severity:** `error` if return markers conflict; `warning` if format expectations unspecified on either side.
+
+### Dimension 5: Process Override
+
+**Question:** Does the delegation prompt dictate HOW the agent should work?
+
+**Check:** Scan prompt for:
+- Numbered step-by-step instructions ("Step 1:", "First..., Then..., Finally...")
+- Process flow definitions beyond `<objective>` scope
+- Tool usage instructions ("Use grep to...", "Run bash command...")
+- Execution ordering that conflicts with agent's own execution flow
+
+**Allowed:** `<instructions>` block for revision mode (telling agent what changed, not how to work).
+
+**Severity:** `error` if prompt overrides agent's process; `warning` if prompt suggests process hints.
+
+### Dimension 6: Scope Authority Conflict
+
+**Question:** Does the prompt make decisions that belong to the agent's domain?
+
+**Check:**
+- Prompt specifies implementation choices (library selection, architecture patterns) when agent's `<philosophy>` or domain sections own these decisions
+- Prompt overrides agent's discretion areas
+- Prompt locks decisions that agent's `<context_fidelity>` says are "Claude's Discretion"
+
+**Allowed:** Passing through user-locked decisions from CONTEXT.md — this is proper delegation, not authority conflict.
+
+**Severity:** `error` if prompt makes domain decisions agent should own; `info` if prompt passes through user decisions (correct behavior).
+
+### Dimension 7: Missing Contracts
+
+**Question:** Are the delegation handoff points properly defined?
+
+**Check:**
+- Agent has `<output_contract>` with return markers → command handles all markers?
+- Command's return handling covers COMPLETE, BLOCKED, CHECKPOINT
+- Agent lists "Spawned by:" — does command actually spawn it?
+- Agent expects `<files_to_read>` — does prompt provide it?
+- Agent has `<upstream_input>` — does prompt provide matching input structure?
+
+**Severity:** `error` if return marker handling is missing; `warning` if agent expects input the prompt doesn't provide.
+
+## 6. Aggregate and Report
+
+### 6a. Per-pair summary
+
+For each command-agent pair, aggregate findings:
+
+```
+{command_path} → {agent_name}
+  Agent() at line {N}:
+    D1 (Role Re-def):      {PASS|WARN|ERROR} — {detail}
+    D2 (Domain Leak):       {PASS|WARN|ERROR} — {detail}
+    D3 (Quality Gate):      {PASS|WARN|ERROR} — {detail}
+    D4 (Output Format):     {PASS|WARN|ERROR} — {detail}
+    D5 (Process Override):  {PASS|WARN|ERROR} — {detail}
+    D6 (Scope Authority):   {PASS|WARN|ERROR} — {detail}
+    D7 (Missing Contract):  {PASS|WARN|ERROR} — {detail}
+```
+
+### 6b. Overall verdict
+
+| Verdict | Condition |
+|---------|-----------|
+| **CLEAN** | 0 errors, 0-2 warnings |
+| **REVIEW** | 0 errors, 3+ warnings |
+| **CONFLICT** | 1+ errors |
+
+### 6c. Fix recommendations
+
+For each finding, provide:
+- **Location:** file:line
+- **What's wrong:** concrete description
+- **Fix:** move content to correct owner (command or agent)
+- **Example:** before/after snippet if applicable
+
+## 7. Present Results
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DELEGATION-CHECK ► SCAN COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Scope: {description}
+Pairs checked: {N} command-agent pairs
+Findings: {E} errors, {W} warnings, {I} info
+
+Verdict: {CLEAN | REVIEW | CONFLICT}
+
+| Pair | D1 | D2 | D3 | D4 | D5 | D6 | D7 |
+|------|----|----|----|----|----|----|-----|
+| {cmd} → {agent} | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ | ✅ |
+| ... | | | | | | | |
+
+{If CONFLICT: detailed findings with fix recommendations}
+
+───────────────────────────────────────────────────────
+
+## Fix Priority
+
+1. {Highest severity fix}
+2. {Next fix}
+...
+
+───────────────────────────────────────────────────────
+```
+
+</process>
+
+<success_criteria>
+- [ ] Scan scope determined and all files discovered
+- [ ] All Agent() calls extracted from commands with full prompt content
+- [ ] All corresponding agent definitions located and parsed
+- [ ] 7 conflict dimensions checked for each command-agent pair
+- [ ] No false positives on legitimate patterns (mode references, user decision passthrough, `<deep_work_rules>`)
+- [ ] Fix recommendations provided for every error/warning
+- [ ] Summary table with per-pair dimension results displayed
+- [ ] Overall verdict determined (CLEAN/REVIEW/CONFLICT)
+</success_criteria>

package/skills/domain-add/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: domain-add
+description: "Register a domain term into project glossary Arguments: <canonical> \\\"<definition>\\\""
+allowed-tools: Read Write Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Register a domain term into `.workflow/domain/glossary.yaml`. Domain terms are automatically injected into agent context via hooks (domain-compact for all prompts, domain-expanded on keyword match).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/domain-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<canonical> "<definition>"`
+
+**Examples:**
+```bash
+/domain-add auth-token "Short-lived credential for API authentication"
+/domain-add event-bus "Central pub-sub message broker for cross-module communication"
+/domain-add 会话上下文 "Runtime state container for active workflow session"
+```
+
+Domain term lifecycle: discover/manual → register → active → (optional) deprecated → removed.
+
+**Related commands:**
+- `maestro domain list` — list all registered terms
+- `maestro domain discover` — scan codebase for term candidates
+- `maestro domain show <canonical>` — show term details
+- `maestro domain deprecate <canonical> --successor <new>` — deprecate a term
+</context>
+
+<invariants>
+1. **Single-term atomic operation** — each invocation registers exactly ONE term; NEVER batch-write multiple terms in a single execution
+2. **Glossary append-only** — existing terms in `glossary.yaml` SHALL NOT be modified or removed; only new entries are appended
+3. **Duplicate guard** — MUST check for exact canonical name match AND near-matches before writing; NEVER create duplicate entries
+4. **Confirmation mandatory** — MUST present term details (canonical, definition, aliases, tier, path) via AskUserQuestion before any glossary write; NEVER write without user confirmation
+5. **Schema compliance** — every term entry MUST include canonical name, definition, tier, and at least one alias/keyword; incomplete entries SHALL NOT be persisted
+6. **Domain directory prerequisite** — `.workflow/domain/` MUST exist before writing; NEVER auto-create the directory (E002 if missing)
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/domain-add.md' completely.
+
+**Confirmation gate**: Before writing to glossary.yaml, AskUserQuestion showing the term canonical name, definition, extracted aliases/keywords, tier, and target file path. Proceed only on user confirm.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Canonical name and definition are both required | parse_input |
+| E002 | fatal | `.workflow/domain/` not initialized — run `maestro domain init` first | validate |
+| E003 | fatal | Term already registered with same canonical name | duplicate_check |
+| E004 | warning | Near-match found — confirm merge or create new | duplicate_check |
+</error_codes>
+
+<success_criteria>
+- [ ] Canonical name and definition parsed and validated
+- [ ] No duplicate term in glossary (or user confirmed near-match)
+- [ ] Aliases and keywords auto-extracted from definition
+- [ ] Term written to glossary.yaml with tier and relationships
+- [ ] Confirmation displayed with term details and verify command
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verify term added | `maestro domain show <canonical>` |
+| Add more terms | `/domain-add <canonical> "<definition>"` |
+| Discover candidates | `maestro domain discover` |
+| List all terms | `maestro domain list` |
+</completion>

package/skills/insight-challenge/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: insight-challenge
+description: "Adversarial review of code quality findings. Challenges insights with counter-evidence, verifies claims against source code, and produces structured verdicts. Triggers on 'insight-challenge', 'challenge finding', '审查发现'."
+allowed-tools: Read Glob Grep Bash Write
+---
+
+# Insight Challenge
+
+Adversarial review of code quality findings. Challenges insights with counter-evidence, verifies claims against source code, and produces structured verdicts.
+
+**适用场景**: 当需要对代码审查、质量分析、或架构评估中的发现进行对抗性验证时使用。
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Insight Challenge (SKILL.md) — Adversarial Review          │
+│  → Parse finding → Read source → Challenge → Verdict        │
+└─────────────────────────────────────────────────────────────┘
+                           │
+    ┌──────────┬───────────┼───────────┬──────────┐
+    ↓          ↓           ↓           ↓          │
+┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐      │
+│Phase 1 │ │Phase 2 │ │Phase 3 │ │Phase 4 │      │
+│ Parse  │ │ Source │ │Challenge│ │Verdict │      │
+│Finding │ │ Review │ │Analysis │ │Report  │      │
+└───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘      │
+    │          │          │          │             │
+ finding    source     counter-   structured      │
+ parsed     code       evidence   verdict         │
+```
+
+## Key Design Principles
+
+1. **Adversarial by Default**: Assume findings may be incorrect; seek counter-evidence first
+2. **Source-Code Anchored**: All claims must be verified against actual code, not assumptions
+3. **Structured Output**: Verdicts follow a fixed schema for downstream consumption
+4. **Fair Challenge**: If evidence supports the finding, confirm it; don't manufacture doubt
+5. **Transparent Reasoning**: Show the chain of evidence and reasoning
+
+## Finding Input Format
+
+Findings can be provided as JSON or structured text:
+
+```json
+{
+  "id": "HIGH-01",
+  "title": "知识边类型 resolves/documents 未在 types.ts 声明",
+  "severity": "high",
+  "file": "src/graph/kg/db/types.ts",
+  "line": 58,
+  "description": "issue-extractor 使用 'resolves' 边类型...",
+  "evidence": "types.ts KnowledgeEdgeKind: defines, constrains...",
+  "suggestion": "补齐缺失的边类型声明",
+  "design_ref": "Gap 2 — 12 CodeEdgeKind + 9 KnowledgeEdgeKind"
+}
+```
+
+Or structured text:
+```
+HIGH-01: 知识边类型 resolves/documents 未在 types.ts 声明
+Severity: high
+File: src/graph/kg/db/types.ts:58
+Claim: issue-extractor 使用 'resolves' 边类型但未在类型系统中声明
+Evidence: types.ts KnowledgeEdgeKind 列表中缺少 'resolves'
+```
+
+## Execution Flow
+
+### Phase 1: Parse Finding
+
+1. Extract finding ID, title, severity, file reference, and claims
+2. Identify all verifiable assertions:
+   - File existence claims
+   - Code structure claims (types, functions, variables)
+   - Behavioral claims (usage patterns, dependencies)
+   - Design conformance claims
+3. Create verification checklist
+
+### Phase 2: Source Review
+
+1. Read the referenced file(s) at the specified lines
+2. Search for related code using Grep/Glob
+3. Document actual state of the code:
+   - What types/functions actually exist
+   - What values are actually declared
+   - What the actual implementation looks like
+4. Compare claims against reality
+
+### Phase 3: Challenge Analysis
+
+For each claim in the finding:
+
+1. **Seek confirming evidence**: Does the source code support this claim?
+2. **Seek disconfirming evidence**: Does the source code contradict this claim?
+3. **Check for misinterpretation**: Could the claim be based on outdated code or misunderstanding?
+4. **Verify design references**: Are cited design docs accurate?
+
+Challenge strategies:
+- **Direct contradiction**: Source code explicitly shows the opposite
+- **Context omission**: Finding omits relevant context that changes the interpretation
+- **Stale reference**: Finding references code that has been updated
+- **Miscounted**: Numeric claims (missing N types) are incorrect
+- **Scope error**: Finding applies wrong scope (e.g., confuses edge types with language types)
+
+### Phase 4: Verdict Report
+
+Produce structured output:
+
+```json
+{
+  "finding_id": "HIGH-01",
+  "challenge_result": "overturned|weakened|confirmed",
+  "confidence": 95,
+  "reasoning": "Detailed explanation of why the finding was challenged or confirmed",
+  "counter_evidence": [
+    "Source file line 64: 'resolves' IS declared in KnowledgeEdgeKind",
+    "Design doc specifies 20 edge types, not 28"
+  ],
+  "supporting_evidence": [],
+  "adjusted_severity": "none|high|medium|low",
+  "recommendation": "Dismiss this finding; the claimed gap does not exist"
+}
+```
+
+## Verdict Definitions
+
+| Verdict | Meaning | When to Use |
+|---------|---------|-------------|
+| **overturned** | Finding is factually incorrect | Source code directly contradicts the claim |
+| **weakened** | Finding is partially correct but overstated | Some evidence supports it, but severity/scope is wrong |
+| **confirmed** | Finding is accurate | Source code supports all claims |
+
+## Challenge Patterns
+
+### Pattern 1: Type Declaration Check
+```
+Claim: "Type X is not declared"
+Challenge: Read the type file → check if X exists in type union/enum
+Counter: "Line N shows X IS declared in the type definition"
+```
+
+### Pattern 2: Design Reference Verification
+```
+Claim: "Design requires N items, implementation has M"
+Challenge: Read design doc → verify the claimed requirement
+Counter: "Design doc actually specifies K items, not N"
+```
+
+### Pattern 3: Usage Verification
+```
+Claim: "Code uses type X but X is not defined"
+Challenge: Check both usage site AND definition site
+Counter: "X is defined at line N in file Y"
+```
+
+### Pattern 4: Scope Confusion
+```
+Claim: "Missing 7 edge types (total should be 28)"
+Challenge: Check what the "28" actually refers to
+Counter: "The 28 refers to language types, not edge types; edge types are 21"
+```
+
+## Output Format
+
+The challenge produces a markdown report:
+
+```markdown
+## Challenge Report: <finding_id>
+
+**Verdict**: <overturned|weakened|confirmed>
+**Confidence**: <0-100>%
+**Adjusted Severity**: <none|high|medium|low>
+
+### Original Finding
+<finding summary>
+
+### Counter-Evidence
+- <evidence point 1>
+- <evidence point 2>
+
+### Supporting Evidence
+- <evidence point 1> (if any)
+
+### Reasoning
+<detailed explanation>
+
+### Recommendation
+<action recommendation>
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Referenced file not found | Report file missing; verdict = weakened (potentially stale) |
+| Line number out of range | Search for the claimed content; adjust line reference |
+| Design doc not found | Skip design verification; note in report |
+| Ambiguous evidence | Present both sides; lower confidence score |
+| Multiple findings batch | Process each independently; produce per-finding verdicts |
+
+## Usage Examples
+
+### Single Finding Challenge
+```
+Skill(skill="insight-challenge", args='{"id":"HIGH-01","title":"...","file":"src/types.ts","line":58,...}')
+```
+
+### Batch Challenge
+```
+Skill(skill="insight-challenge", args='findings.json')
+```
+
+### Inline Challenge
+```
+Challenge this finding:
+Claim: Function X is not exported
+File: src/utils.ts:45
+Evidence: grep shows no export keyword
+```
+
+## Related Skills
+
+- **team-adversarial-swarm**: Multi-agent adversarial analysis
+- **team-quality-assurance**: QA pipeline with issue discovery
+- **codify-to-knowhow**: Capturing verified knowledge