maestro-flow 0.5.35 → 0.5.37

package/.agy/skills/delegation-check/specs/separation-rules.md

@@ -11,251 +11,251 @@ Before any `invoke_subagent` call below, register each sub-agent type once per s
 **ConversationId tracking**: `invoke_subagent` returns a ConversationId per spawned instance. Subsequent `send_message(Recipient=<ConversationId>, Message=...)` calls require that ConversationId — never use the role name as the recipient.
 
 ---
-# GSD Content Separation Rules
-
-Rules for validating the boundary between **command delegation prompts** (invoke_subagent() calls) and **agent role definitions** (agent `.md` files). Derived from analysis of GSD's `plan-phase.md`, `execute-phase.md`, `research-phase.md` and their corresponding agents (`gsd-planner`, `gsd-plan-checker`, `gsd-executor`, `gsd-phase-researcher`, `gsd-verifier`).
-
-## Core Principle
-
-**Commands own WHEN and WHERE. Agents own WHO and HOW.**
-
-A delegation prompt tells the agent what to do *this time*. The agent definition tells the agent who it *always* is.
-
-## Ownership Matrix
-
-### Command Delegation Prompt Owns
-
-| Concern | XML Block | Example |
-|---------|-----------|---------|
-| What to accomplish | `<objective>` | "Execute plan 3 of phase 2" |
-| Input file paths | `<files_to_read>` | "- {state_path} (Project State)" |
-| Runtime parameters | `<additional_context>` | "Phase: 5, Mode: revision" |
-| Output location | `<output>` | "Write to: {phase_dir}/RESEARCH.md" |
-| Expected return format | `<expected_output>` | "## VERIFICATION PASSED or ## ISSUES FOUND" |
-| Who consumes output | `<downstream_consumer>` | "Output consumed by /gsd:execute-phase" |
-| Revision context | `<instructions>` | "Make targeted updates to address checker issues" |
-| Cross-cutting policy | `<deep_work_rules>` | Anti-shallow execution rules (applies to all agents) |
-| Per-invocation quality | `<quality_gate>` (in prompt) | Invocation-specific checks (e.g., "every task has `<read_first>`") |
-| Flow control | Revision loops, return routing | "If TASK COMPLETE → step 13. If BLOCKED → offer options" |
-| User interaction | `ask_question` | "Provide context / Skip / Abort" |
-| Banners | Status display | "━━━ GSD ► PLANNING PHASE {X} ━━━" |
-
-### Agent Role Definition Owns
-
-| Concern | XML Section | Example |
-|---------|-------------|---------|
-| Identity | `<role>` | "You are a GSD planner" |
-| Spawner list | `<role>` → Spawned by | "/gsd:plan-phase orchestrator" |
-| Responsibilities | `<role>` → Core responsibilities | "Decompose phases into parallel-optimized plans" |
-| Mandatory read protocol | `<role>` → Mandatory Initial Read | "MUST use Read tool to load every file in `<files_to_read>`" |
-| Project discovery | `<project_context>` | "Read CLAUDE.md, check .claude/skills/" |
-| Guiding principles | `<philosophy>` | Quality degradation curve by context usage |
-| Input interpretation | `<upstream_input>` | "Decisions → LOCKED, Discretion → freedom" |
-| Decision honoring | `<context_fidelity>` | "Locked decisions are NON-NEGOTIABLE" |
-| Core insight | `<core_principle>` | "Plan completeness ≠ Goal achievement" |
-| Domain expertise | Named domain sections | `<verification_dimensions>`, `<task_breakdown>`, `<dependency_graph>` |
-| Return protocol | `<output_contract>` | TASK COMPLETE / TASK BLOCKED / CHECKPOINT REACHED |
-| Self-check | `<quality_gate>` (in agent) | Permanent checks for every invocation |
-| Anti-patterns | `<anti_patterns>` | "DO NOT check code existence" |
-| Examples | `<examples>` | Scope exceeded analysis example |
-
-## Conflict Patterns
-
-### Pattern 1: Role Re-definition
-
-**Symptom:** Delegation prompt contains identity language.
-
-```
-# BAD — prompt redefines role
-invoke_subagent([{ TypeName: "gsd-plan-checker", Role: "<Role>", Prompt: "You are a code quality expert. Your job is to review plans...
-    <objective>Verify phase 5 plans</objective>", Workspace: "inherit" }])
-
-# GOOD — prompt states objective only
-invoke_subagent([{ TypeName: "gsd-plan-checker", Role: "<Role>", Prompt: "<verification_context>
-    <files_to_read>...</files_to_read>
-  </verification_context>
-  <expected_output>## VERIFICATION PASSED or ## ISSUES FOUND</expected_output>", Workspace: "inherit" }])
-```
-
-**Why it's wrong:** The agent's `<role>` section already defines identity. Re-definition in prompt can contradict, confuse, or override the agent's self-understanding.
-
-**Detection:** Regex for `You are a|Your role is|Your job is to|Your responsibility is|Core responsibilities:` in prompt content.
-
-### Pattern 2: Domain Expertise Leak
-
-**Symptom:** Delegation prompt contains decision tables, heuristics, or examples.
-
-```
-# BAD — prompt embeds domain knowledge
-invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "<objective>Create plans for phase 3</objective>
-    Remember: tasks should have 2-3 items max.
-    | TOO VAGUE | JUST RIGHT |
-    | ", Workspace: "inherit" }])
-
-# GOOD — agent's own <task_breakdown> section owns this knowledge
-invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "<planning_context>
-    <files_to_read>...</files_to_read>
-  </planning_context>", Workspace: "inherit" }])
-```
-
-**Why it's wrong:** Domain knowledge in prompts duplicates agent content. When agent evolves, prompt doesn't update — they diverge. Agent's domain sections are the single source of truth.
-
-**Exception — `<deep_work_rules>`:** GSD uses this as a cross-cutting policy block (not domain expertise per se) that applies anti-shallow-execution rules across all agents. This is acceptable because:
-1. It's structural policy, not domain knowledge
-2. It applies uniformly to all planning agents
-3. It supplements (not duplicates) agent's own quality gate
-
-**Detection:**
-- Tables with `|` in prompt content (excluding `<files_to_read>` path tables)
-- "Good:" / "Bad:" / "Example:" comparison pairs
-- "Always..." / "Never..." / "Prefer..." heuristic statements
-- Numbered rules lists (>3 items) that aren't revision instructions
-
-### Pattern 3: Quality Gate Duplication
-
-**Symptom:** Same quality check appears in both prompt and agent definition.
-
-```
-# PROMPT quality_gate
-- [ ] Every task has `<read_first>`
-- [ ] Every task has `<acceptance_criteria>`
-- [ ] Dependencies correctly identified
-
-# AGENT quality_gate
-- [ ] Every task has `<read_first>` with at least the file being modified
-- [ ] Every task has `<acceptance_criteria>` with grep-verifiable conditions
-- [ ] Dependencies correctly identified
-```
-
-**Analysis:**
-- "Dependencies correctly identified" → **duplicate** (exact match)
-- "`<read_first>`" in both → **overlap** (prompt is less specific than agent)
-- "`<acceptance_criteria>`" → **overlap** (same check, different specificity)
-
-**When duplication is OK:** Prompt's `<quality_gate>` adds *invocation-specific* checks not in agent's permanent gate (e.g., "Phase requirement IDs all covered" is specific to this phase, not general).
-
-**Detection:** Fuzzy match quality gate items between prompt and agent (>60% token overlap).
-
-### Pattern 4: Output Format Conflict
-
-**Symptom:** Command expects return markers the agent doesn't define.
-
-```
-# COMMAND handles:
-- "## VERIFICATION PASSED" → continue
-- "## ISSUES FOUND" → revision loop
-
-# AGENT <output_contract> defines:
-- "## TASK COMPLETE"
-- "## TASK BLOCKED"
-```
-
-**Why it's wrong:** Command routes on markers. If markers don't match, routing breaks silently — command may hang or misinterpret results.
-
-**Detection:** Extract return marker strings from both sides, compare sets.
-
-### Pattern 5: Process Override
-
-**Symptom:** Prompt dictates step-by-step process.
-
-```
-# BAD — prompt overrides agent's process
-invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "Step 1: Read the roadmap. Step 2: Extract requirements.
-    Step 3: Create task breakdown. Step 4: Assign waves...", Workspace: "inherit" }])
-
-# GOOD — prompt states objective, agent decides process
-invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "<objective>Create plans for phase 5</objective>
-    <files_to_read>...</files_to_read>", Workspace: "inherit" }])
-```
-
-**Exception — Revision instructions:** `<instructions>` block in revision prompts is acceptable because it tells the agent *what changed* (checker issues), not *how to work*.
-
-```
-# OK — revision context, not process override
-<instructions>
-Make targeted updates to address checker issues.
-Do NOT replan from scratch unless issues are fundamental.
-Return what changed.
-</instructions>
-```
-
-**Detection:** "Step N:" / "First..." / "Then..." / "Finally..." patterns in prompt content outside `<instructions>` blocks.
-
-### Pattern 6: Scope Authority Conflict
-
-**Symptom:** Prompt makes domain decisions the agent should own.
-
-```
-# BAD — prompt decides implementation details
-invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "Use React Query for data fetching. Use Zustand for state management.
-    <objective>Plan the frontend architecture</objective>", Workspace: "inherit" }])
-
-# GOOD — user decisions passed through from CONTEXT.md
-invoke_subagent({
-  subagent_type: "gsd-planner",
-  prompt: "<planning_context>
-    <files_to_read>
-    - {context_path} (USER DECISIONS - locked: React Query, Zustand)
-    </files_to_read>
-  </planning_context>"
-})
-```
-
-**Key distinction:**
-- **Prompt making decisions** = conflict (command shouldn't have domain opinion)
-- **Prompt passing through user decisions** = correct (user decisions flow through command to agent)
-- **Agent interpreting user decisions** = correct (agent's `<context_fidelity>` handles locked/deferred/discretion)
-
-**Detection:** Technical nouns (library names, architecture patterns) in prompt free text (not inside `<files_to_read>` path descriptions).
-
-### Pattern 7: Missing Contracts
-
-**Symptom:** Handoff points between command and agent are incomplete.
-
-| Missing Element | Impact |
-|-----------------|--------|
-| Agent has no `<output_contract>` | Command can't route on return markers |
-| Command doesn't handle all agent return markers | BLOCKED/CHECKPOINT silently ignored |
-| Agent expects `<files_to_read>` but prompt doesn't provide it | Agent starts without context |
-| Agent's "Spawned by:" doesn't list this command | Agent may not expect this invocation pattern |
-| Agent has `<upstream_input>` but prompt doesn't match structure | Agent misinterprets input |
-
-**Detection:** Cross-reference both sides for completeness.
-
-## The `<deep_work_rules>` Exception
-
-GSD's plan-phase uses `<deep_work_rules>` in delegation prompts. This is a deliberate design choice, not a violation:
-
-1. **It's cross-cutting policy**: applies to ALL planning agents equally
-2. **It's structural**: defines required fields (`<read_first>`, `<acceptance_criteria>`, `<action>` concreteness) — not domain expertise
-3. **It supplements agent quality**: agent's own `<quality_gate>` is self-check; deep_work_rules is command-imposed minimum standard
-4. **It's invocation-specific context**: different commands might impose different work rules
-
-**Rule:** `<deep_work_rules>` in a delegation prompt is `info` level, not error. Flag only if its content duplicates agent's domain sections verbatim.
-
-## Severity Classification
-
-| Severity | When | Action Required |
-|----------|------|-----------------|
-| `error` | Actual conflict: contradictory content between prompt and agent | Must fix — move content to correct owner |
-| `warning` | Duplication or boundary blur without contradiction | Should fix — consolidate to single source of truth |
-| `info` | Acceptable pattern that looks like violation but isn't | No action — document why it's OK |
-
-## Quick Reference: Is This Content in the Right Place?
-
-| Content | In Prompt? | In Agent? |
-|---------|-----------|-----------|
-| "You are a..." | ❌ Never | ✅ Always |
-| File paths for this invocation | ✅ Yes | ❌ No |
-| Phase number, mode | ✅ Yes | ❌ No |
-| Decision tables | ❌ Never | ✅ Always |
-| Good/bad examples | ❌ Never | ✅ Always |
-| "Write to: {path}" | ✅ Yes | ❌ No |
-| Return markers handling | ✅ Yes (routing) | ✅ Yes (definition) |
-| Quality gate | ✅ Per-invocation | ✅ Permanent self-check |
-| "MUST read files first" | ❌ Agent's `<role>` owns this | ✅ Always |
-| Anti-shallow rules | ⚠️ OK as cross-cutting policy | ✅ Preferred |
-| Revision instructions | ✅ Yes (what changed) | ❌ No |
-| Heuristics / philosophy | ❌ Never | ✅ Always |
-| Banner display | ✅ Yes | ❌ Never |
-| ask_question | ✅ Yes | ❌ Never |
+# GSD Content Separation Rules
+
+Rules for validating the boundary between **command delegation prompts** (invoke_subagent() calls) and **agent role definitions** (agent `.md` files). Derived from analysis of GSD's `plan-phase.md`, `execute-phase.md`, `research-phase.md` and their corresponding agents (`gsd-planner`, `gsd-plan-checker`, `gsd-executor`, `gsd-phase-researcher`, `gsd-verifier`).
+
+## Core Principle
+
+**Commands own WHEN and WHERE. Agents own WHO and HOW.**
+
+A delegation prompt tells the agent what to do *this time*. The agent definition tells the agent who it *always* is.
+
+## Ownership Matrix
+
+### Command Delegation Prompt Owns
+
+| Concern | XML Block | Example |
+|---------|-----------|---------|
+| What to accomplish | `<objective>` | "Execute plan 3 of phase 2" |
+| Input file paths | `<files_to_read>` | "- {state_path} (Project State)" |
+| Runtime parameters | `<additional_context>` | "Phase: 5, Mode: revision" |
+| Output location | `<output>` | "Write to: {phase_dir}/RESEARCH.md" |
+| Expected return format | `<expected_output>` | "## VERIFICATION PASSED or ## ISSUES FOUND" |
+| Who consumes output | `<downstream_consumer>` | "Output consumed by /gsd:execute-phase" |
+| Revision context | `<instructions>` | "Make targeted updates to address checker issues" |
+| Cross-cutting policy | `<deep_work_rules>` | Anti-shallow execution rules (applies to all agents) |
+| Per-invocation quality | `<quality_gate>` (in prompt) | Invocation-specific checks (e.g., "every task has `<read_first>`") |
+| Flow control | Revision loops, return routing | "If TASK COMPLETE → step 13. If BLOCKED → offer options" |
+| User interaction | `ask_question` | "Provide context / Skip / Abort" |
+| Banners | Status display | "━━━ GSD ► PLANNING PHASE {X} ━━━" |
+
+### Agent Role Definition Owns
+
+| Concern | XML Section | Example |
+|---------|-------------|---------|
+| Identity | `<role>` | "You are a GSD planner" |
+| Spawner list | `<role>` → Spawned by | "/gsd:plan-phase orchestrator" |
+| Responsibilities | `<role>` → Core responsibilities | "Decompose phases into parallel-optimized plans" |
+| Mandatory read protocol | `<role>` → Mandatory Initial Read | "MUST use Read tool to load every file in `<files_to_read>`" |
+| Project discovery | `<project_context>` | "Read CLAUDE.md, check .claude/skills/" |
+| Guiding principles | `<philosophy>` | Quality degradation curve by context usage |
+| Input interpretation | `<upstream_input>` | "Decisions → LOCKED, Discretion → freedom" |
+| Decision honoring | `<context_fidelity>` | "Locked decisions are NON-NEGOTIABLE" |
+| Core insight | `<core_principle>` | "Plan completeness ≠ Goal achievement" |
+| Domain expertise | Named domain sections | `<verification_dimensions>`, `<task_breakdown>`, `<dependency_graph>` |
+| Return protocol | `<output_contract>` | TASK COMPLETE / TASK BLOCKED / CHECKPOINT REACHED |
+| Self-check | `<quality_gate>` (in agent) | Permanent checks for every invocation |
+| Anti-patterns | `<anti_patterns>` | "DO NOT check code existence" |
+| Examples | `<examples>` | Scope exceeded analysis example |
+
+## Conflict Patterns
+
+### Pattern 1: Role Re-definition
+
+**Symptom:** Delegation prompt contains identity language.
+
+```
+# BAD — prompt redefines role
+invoke_subagent([{ TypeName: "gsd-plan-checker", Role: "<Role>", Prompt: "You are a code quality expert. Your job is to review plans...
+    <objective>Verify phase 5 plans</objective>", Workspace: "inherit" }])
+
+# GOOD — prompt states objective only
+invoke_subagent([{ TypeName: "gsd-plan-checker", Role: "<Role>", Prompt: "<verification_context>
+    <files_to_read>...</files_to_read>
+  </verification_context>
+  <expected_output>## VERIFICATION PASSED or ## ISSUES FOUND</expected_output>", Workspace: "inherit" }])
+```
+
+**Why it's wrong:** The agent's `<role>` section already defines identity. Re-definition in prompt can contradict, confuse, or override the agent's self-understanding.
+
+**Detection:** Regex for `You are a|Your role is|Your job is to|Your responsibility is|Core responsibilities:` in prompt content.
+
+### Pattern 2: Domain Expertise Leak
+
+**Symptom:** Delegation prompt contains decision tables, heuristics, or examples.
+
+```
+# BAD — prompt embeds domain knowledge
+invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "<objective>Create plans for phase 3</objective>
+    Remember: tasks should have 2-3 items max.
+    | TOO VAGUE | JUST RIGHT |
+    | ", Workspace: "inherit" }])
+
+# GOOD — agent's own <task_breakdown> section owns this knowledge
+invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "<planning_context>
+    <files_to_read>...</files_to_read>
+  </planning_context>", Workspace: "inherit" }])
+```
+
+**Why it's wrong:** Domain knowledge in prompts duplicates agent content. When agent evolves, prompt doesn't update — they diverge. Agent's domain sections are the single source of truth.
+
+**Exception — `<deep_work_rules>`:** GSD uses this as a cross-cutting policy block (not domain expertise per se) that applies anti-shallow-execution rules across all agents. This is acceptable because:
+1. It's structural policy, not domain knowledge
+2. It applies uniformly to all planning agents
+3. It supplements (not duplicates) agent's own quality gate
+
+**Detection:**
+- Tables with `|` in prompt content (excluding `<files_to_read>` path tables)
+- "Good:" / "Bad:" / "Example:" comparison pairs
+- "Always..." / "Never..." / "Prefer..." heuristic statements
+- Numbered rules lists (>3 items) that aren't revision instructions
+
+### Pattern 3: Quality Gate Duplication
+
+**Symptom:** Same quality check appears in both prompt and agent definition.
+
+```
+# PROMPT quality_gate
+- [ ] Every task has `<read_first>`
+- [ ] Every task has `<acceptance_criteria>`
+- [ ] Dependencies correctly identified
+
+# AGENT quality_gate
+- [ ] Every task has `<read_first>` with at least the file being modified
+- [ ] Every task has `<acceptance_criteria>` with grep-verifiable conditions
+- [ ] Dependencies correctly identified
+```
+
+**Analysis:**
+- "Dependencies correctly identified" → **duplicate** (exact match)
+- "`<read_first>`" in both → **overlap** (prompt is less specific than agent)
+- "`<acceptance_criteria>`" → **overlap** (same check, different specificity)
+
+**When duplication is OK:** Prompt's `<quality_gate>` adds *invocation-specific* checks not in agent's permanent gate (e.g., "Phase requirement IDs all covered" is specific to this phase, not general).
+
+**Detection:** Fuzzy match quality gate items between prompt and agent (>60% token overlap).
+
+### Pattern 4: Output Format Conflict
+
+**Symptom:** Command expects return markers the agent doesn't define.
+
+```
+# COMMAND handles:
+- "## VERIFICATION PASSED" → continue
+- "## ISSUES FOUND" → revision loop
+
+# AGENT <output_contract> defines:
+- "## TASK COMPLETE"
+- "## TASK BLOCKED"
+```
+
+**Why it's wrong:** Command routes on markers. If markers don't match, routing breaks silently — command may hang or misinterpret results.
+
+**Detection:** Extract return marker strings from both sides, compare sets.
+
+### Pattern 5: Process Override
+
+**Symptom:** Prompt dictates step-by-step process.
+
+```
+# BAD — prompt overrides agent's process
+invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "Step 1: Read the roadmap. Step 2: Extract requirements.
+    Step 3: Create task breakdown. Step 4: Assign waves...", Workspace: "inherit" }])
+
+# GOOD — prompt states objective, agent decides process
+invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "<objective>Create plans for phase 5</objective>
+    <files_to_read>...</files_to_read>", Workspace: "inherit" }])
+```
+
+**Exception — Revision instructions:** `<instructions>` block in revision prompts is acceptable because it tells the agent *what changed* (checker issues), not *how to work*.
+
+```
+# OK — revision context, not process override
+<instructions>
+Make targeted updates to address checker issues.
+Do NOT replan from scratch unless issues are fundamental.
+Return what changed.
+</instructions>
+```
+
+**Detection:** "Step N:" / "First..." / "Then..." / "Finally..." patterns in prompt content outside `<instructions>` blocks.
+
+### Pattern 6: Scope Authority Conflict
+
+**Symptom:** Prompt makes domain decisions the agent should own.
+
+```
+# BAD — prompt decides implementation details
+invoke_subagent([{ TypeName: "gsd-planner", Role: "<Role>", Prompt: "Use React Query for data fetching. Use Zustand for state management.
+    <objective>Plan the frontend architecture</objective>", Workspace: "inherit" }])
+
+# GOOD — user decisions passed through from CONTEXT.md
+invoke_subagent({
+  subagent_type: "gsd-planner",
+  prompt: "<planning_context>
+    <files_to_read>
+    - {context_path} (USER DECISIONS - locked: React Query, Zustand)
+    </files_to_read>
+  </planning_context>"
+})
+```
+
+**Key distinction:**
+- **Prompt making decisions** = conflict (command shouldn't have domain opinion)
+- **Prompt passing through user decisions** = correct (user decisions flow through command to agent)
+- **Agent interpreting user decisions** = correct (agent's `<context_fidelity>` handles locked/deferred/discretion)
+
+**Detection:** Technical nouns (library names, architecture patterns) in prompt free text (not inside `<files_to_read>` path descriptions).
+
+### Pattern 7: Missing Contracts
+
+**Symptom:** Handoff points between command and agent are incomplete.
+
+| Missing Element | Impact |
+|-----------------|--------|
+| Agent has no `<output_contract>` | Command can't route on return markers |
+| Command doesn't handle all agent return markers | BLOCKED/CHECKPOINT silently ignored |
+| Agent expects `<files_to_read>` but prompt doesn't provide it | Agent starts without context |
+| Agent's "Spawned by:" doesn't list this command | Agent may not expect this invocation pattern |
+| Agent has `<upstream_input>` but prompt doesn't match structure | Agent misinterprets input |
+
+**Detection:** Cross-reference both sides for completeness.
+
+## The `<deep_work_rules>` Exception
+
+GSD's plan-phase uses `<deep_work_rules>` in delegation prompts. This is a deliberate design choice, not a violation:
+
+1. **It's cross-cutting policy**: applies to ALL planning agents equally
+2. **It's structural**: defines required fields (`<read_first>`, `<acceptance_criteria>`, `<action>` concreteness) — not domain expertise
+3. **It supplements agent quality**: agent's own `<quality_gate>` is self-check; deep_work_rules is command-imposed minimum standard
+4. **It's invocation-specific context**: different commands might impose different work rules
+
+**Rule:** `<deep_work_rules>` in a delegation prompt is `info` level, not error. Flag only if its content duplicates agent's domain sections verbatim.
+
+## Severity Classification
+
+| Severity | When | Action Required |
+|----------|------|-----------------|
+| `error` | Actual conflict: contradictory content between prompt and agent | Must fix — move content to correct owner |
+| `warning` | Duplication or boundary blur without contradiction | Should fix — consolidate to single source of truth |
+| `info` | Acceptable pattern that looks like violation but isn't | No action — document why it's OK |
+
+## Quick Reference: Is This Content in the Right Place?
+
+| Content | In Prompt? | In Agent? |
+|---------|-----------|-----------|
+| "You are a..." | ❌ Never | ✅ Always |
+| File paths for this invocation | ✅ Yes | ❌ No |
+| Phase number, mode | ✅ Yes | ❌ No |
+| Decision tables | ❌ Never | ✅ Always |
+| Good/bad examples | ❌ Never | ✅ Always |
+| "Write to: {path}" | ✅ Yes | ❌ No |
+| Return markers handling | ✅ Yes (routing) | ✅ Yes (definition) |
+| Quality gate | ✅ Per-invocation | ✅ Permanent self-check |
+| "MUST read files first" | ❌ Agent's `<role>` owns this | ✅ Always |
+| Anti-shallow rules | ⚠️ OK as cross-cutting policy | ✅ Preferred |
+| Revision instructions | ✅ Yes (what changed) | ❌ No |
+| Heuristics / philosophy | ❌ Never | ✅ Always |
+| Banner display | ✅ Yes | ❌ Never |
+| ask_question | ✅ Yes | ❌ Never |

package/.agy/skills/domain-add/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: domain-add
+description: Register a domain term into project glossary
+argument-hint: <canonical> \"<definition>\"
+allowed-tools:
+  - grep_search
+  - run_command
+  - view_file
+  - write_to_file
+---
+<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>
+
+<execution>
+Follow '~/.maestro/workflows/domain-add.md' completely.
+</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>