maestro-flow 0.5.2 → 0.5.31

package/workflows/debug.md

@@ -1,13 +1,8 @@
 # Debug Workflow
 
-Debug issues using scientific method with subagent isolation. Supports three modes:
+Scientific method debugging with subagent isolation. Three modes: **Standalone** (user describes issue), **From UAT** (`--from-uat`, pre-filled symptoms), **Parallel** (`--parallel`, concurrent agents per gap cluster).
 
-1. **Standalone**: User describes issue, gather symptoms via 5 questions
-2. **From UAT**: --from-uat reads uat.md gaps as pre-filled symptoms (skip gathering). Input-only: does not write back to uat.md/test artifacts (test workflow is the sole caller and owns uat.md writes).
-3. **Parallel**: --parallel spawns one debug agent per gap cluster concurrently
-
-Output: understanding.md + evidence.ndjson per investigation.
-When root causes found, auto-updates originating uat.md with diagnosis.
+Output: `understanding.md` + `evidence.ndjson` per investigation.
 
 ---
 
@@ -43,44 +38,37 @@ All of these mean: **return to Step 3/6 evidence gathering**.
 
 ## Rationalization Table
 
-| Excuse | Why It's Wrong |
-|--------|----------------|
-| "It's probably just a typo" | Typos cause cascading failures; verify before assuming |
-| "The error message says X so it must be X" | Error messages often point to symptoms, not causes |
-| "I fixed something similar before" | Similar symptoms can have completely different root causes |
+| Excuse | Reality |
+|--------|---------|
+| "It's probably just a typo" | Verify before assuming — typos cause cascading failures |
+| "The error message says X so it must be X" | Error messages point to symptoms, not causes |
+| "I fixed something similar before" | Similar symptoms can have different root causes |
 | "The fix works in my test" | One passing test doesn't prove root cause was found |
-| "We don't have time for full investigation" | Quick fixes under pressure create more bugs than they solve |
-| "The code looks correct so it must be something else" | Reading code is not the same as tracing execution |
+| "We don't have time for full investigation" | Quick fixes create more bugs than they solve |
+| "The code looks correct" | Reading code is not tracing execution |
 | "Let me just add a try-catch/null check" | Suppressing errors hides the real problem |
-| "3 failed hypotheses, let me try a 4th guess" | After 3 failures, stop guessing — escalate (see Escalation Rule) |
+| "3 failed hypotheses, let me try a 4th" | After 3 failures, STOP — escalate |
 
 ---
 
 ## Escalation Rule — 3-Strike Architecture Check
 
-After **3 failed hypotheses** (refuted with evidence), STOP proposing more fixes:
+After **3 failed hypotheses**, STOP:
 
-1. **Summarize** all failed hypotheses and their evidence
-2. **Question architecture**: "Is the problem at a deeper level than individual code?"
-3. **Present to user** via AskUserQuestion with the summary and ask:
-   - Continue investigating with different approach?
-   - Re-examine architecture assumptions?
-   - Bring in additional context/expertise?
+1. Summarize all failed hypotheses and evidence
+2. Question architecture: "Is the problem deeper than individual code?"
+3. AskUserQuestion: Continue with different approach? / Re-examine architecture? / Bring in additional context?
 
-Do NOT propose a 4th hypothesis without user confirmation.
+NEVER propose a 4th hypothesis without user confirmation.
 
 ---
 
 ## Backward Tracing Method
 
-When investigating root cause, trace **backward** from symptom to source:
-
-1. **Find** where the incorrect value/behavior first appears
-2. **Trace backward** through the call chain — what called this? What value was passed?
-3. **Continue backward** until you find where correct data becomes incorrect
-4. **Fix at the source**, not at the symptom location
-
-Example: UI shows wrong data → API returns wrong data → service queries wrong table → fix the query, NOT the UI rendering.
+1. **Find** where incorrect value/behavior first appears
+2. **Trace backward** through call chain — what called this? What value was passed?
+3. **Continue** until you find where correct data becomes incorrect
+4. **Fix at the source**, not the symptom location
 
 ---
 
@@ -127,17 +115,16 @@ If resuming: load understanding.md + evidence.ndjson, spawn continuation agent.
 
 ```
 specs_content = maestro spec load --category debug
+→ Pass to debug agents as prior knowledge
 ```
 
-Pass to debug agents as prior knowledge (known issues, root causes, workarounds).
-
 ---
 
 ### Step 2: Load UAT Gaps (if --from-uat)
 
-Skip if --from-uat is not set. Go to Step 3 instead.
+Skip if --from-uat not set → go to Step 3.
 
-Read `{artifact_dir}/uat.md` Gaps section (artifact_dir resolved from artifact registry). For each gap:
+Read `{artifact_dir}/uat.md` Gaps section. For each gap:
 ```yaml
 - test: T-003
   truth: "User can reply to comments"
@@ -158,18 +145,15 @@ Read `{artifact_dir}/uat.md` Gaps section (artifact_dir resolved from artifact r
 | Same flow | T-001 (login) + T-002 (session) -> "auth-flow" cluster |
 | Unrelated | T-005 (nav color) -> standalone "nav-styling" cluster |
 
-**Extract issue references for context enrichment:** For each gap with an `issue_id`, look up the matching issue in `.workflow/issues/issues.jsonl` and attach `issue_context` (severity, feedback, fix_direction, context) to the gap. Pass to debug agent prompts for richer diagnosis.
+**Issue enrichment:** For each gap with `issue_id`, look up in `.workflow/issues/issues.jsonl` and attach `issue_context` to the gap.
 
-If --parallel is set: go to Step 5: Spawn Parallel Debuggers.
-If --parallel is not set: investigate clusters sequentially (Step 6: Spawn Single Debugger per cluster).
+If `--parallel`: → Step 5. Else: → Step 6 (sequential).
 
 ---
 
 ### Step 3: Gather Symptoms (standalone mode only)
 
-Skip if --from-uat is set.
-
-Generate a slug from issue description (lowercase, hyphens, max 40 chars).
+Skip if `--from-uat`. Generate slug from issue description (lowercase, hyphens, max 40 chars).
 
 Ask 5 questions via AskUserQuestion:
 1. "What should happen? (expected behavior)"
@@ -178,14 +162,9 @@ Ask 5 questions via AskUserQuestion:
 4. "When did this start? Did it ever work?"
 5. "How do you trigger this? (reproduction steps)"
 
-Also gather automated context:
-```bash
-git log --oneline -10 2>/dev/null
-git diff --stat HEAD~3 2>/dev/null
-```
+Also gather: `git log --oneline -10`, `git diff --stat HEAD~3`.
 
-Store all responses. Confirm: "Symptoms gathered. Starting investigation..."
-Create debug session directory and proceed to Step 6.
+Store responses → create debug session directory → Step 6.
 
 ---
 
@@ -193,34 +172,26 @@ Create debug session directory and proceed to Step 6.
 
 | Mode | Directory |
 |------|-----------|
-| Phase-scoped (from UAT) | `{ARTIFACT_DIR}/.debug/{gap-slug}/` (ARTIFACT_DIR resolved from artifact registry) |
+| Phase-scoped (from UAT) | `{ARTIFACT_DIR}/.debug/{gap-slug}/` |
 | Standalone | `.workflow/scratch/{YYYYMMDD}-debug-{slug}/` |
 
-Resolve `DEBUG_DIR` from artifact registry:
-- Phase-scoped: look up phase in `.workflow/state.json` artifacts (type=execute), set `DEBUG_DIR = ".workflow/{art.path}/.debug/{gap-slug}/"`. Error if not found.
-- Standalone: `DEBUG_DIR = ".workflow/scratch/{YYYYMMDD}-debug-{slug}/"`
-
 Create the directory.
 
 ---
 
 ### Step 5: Spawn Parallel Debug Agents
 
-For each cluster, spawn concurrently as general-purpose agent (`run_in_background: false`):
+For each cluster, spawn concurrently (`run_in_background: false`):
 
 - **Input**: cluster name, phase, all gaps (test_id, truth, reason, severity). Mode: `symptoms_prefilled`.
-- **Process**: read source files, form 2-3 hypotheses per gap ranked by likelihood, search code for evidence, log each as NDJSON line, confirm/refute.
-- **Output per gap**: `root_cause`, `fix_direction`, `affected_files` (file:line), `confidence` (multi-factor; also include legacy `confidence_level`: high/medium/low for backward compat), `evidence` summary.
+- **Process**: form 2-3 hypotheses per gap, search code for evidence, log NDJSON, confirm/refute.
+- **Output per gap**: `root_cause`, `fix_direction`, `affected_files` (file:line), `confidence` (multi-factor + legacy `confidence_level`), `evidence` summary.
 - **Files**: `{debug_dir}/evidence-{cluster_slug}.ndjson`, `{debug_dir}/understanding-{cluster_slug}.md`
 
-All agents run concurrently. Collect all results.
-
 ---
 
 ### Step 5.5: CLI Supplementary Evidence Gathering (optional)
 
-**Purpose:** Use external CLI tool for broad codebase evidence collection before spawning debug agents. Provides agents with richer context without consuming their token budget on exploration.
-
 **Skip if** no enabled CLI tools or standalone mode with minimal context.
 
 ```
@@ -254,27 +225,18 @@ Pass cli_evidence as supplementary_context to debug agent prompts in Step 5/6
 
 ### Step 6: Spawn Single Debug Agent (sequential mode)
 
-Spawn general-purpose agent (`run_in_background: false`) with:
+Spawn agent (`run_in_background: false`):
 
-- **Input**: slug, description, symptoms (expected, actual, errors, reproduction, timeline). `symptoms_prefilled: {true if from UAT}`, goal: `find_and_fix`.
-- **Process**: form hypotheses ranked by likelihood, test each (design test, execute, log NDJSON evidence, update understanding.md).
-- **Return one of**: `## ROOT CAUSE FOUND` (+ cause, evidence, fix), `## CHECKPOINT REACHED` (+ what's needed from user), `## INVESTIGATION INCONCLUSIVE` (+ what was checked/eliminated).
+- **Input**: slug, description, symptoms. `symptoms_prefilled: {true if from UAT}`, goal: `find_and_fix`.
+- **Process**: form hypotheses, test each, log NDJSON evidence, update understanding.md.
+- **Return**: `## ROOT CAUSE FOUND` | `## CHECKPOINT REACHED` | `## INVESTIGATION INCONCLUSIVE`
 - **Files**: `{$DEBUG_DIR}/understanding.md`, `{$DEBUG_DIR}/evidence.ndjson`
 
-Handle result based on agent output type.
-
 ---
 
 ### Step 7: Collect and Unify Results
 
-For each agent result, extract:
-- root_cause per gap
-- fix_direction per gap
-- affected_files per gap
-- confidence (multi-factor, see 7.1)
-- evidence summary
-
-Build unified diagnosis:
+Build unified diagnosis from all agent results:
 ```json
 {
   "session_id": "{debug session ID}",
@@ -307,19 +269,15 @@ Readiness Gate (blocks Step 9): evidence_completeness ≥ 40% | pressure pass do
 
 ### Step 7.1: Update Issues with Diagnosis
 
-For each diagnosed gap with an `issue_id`, update the corresponding issue in `.workflow/issues/issues.jsonl`:
-- Set `status: "diagnosed"`, `context.suggested_fix: fix_direction`, `context.notes: root_cause`, `updated_at: now()`
+For each diagnosed gap with `issue_id`, update in `.workflow/issues/issues.jsonl`:
+- Set `status: "diagnosed"`, `context.suggested_fix: fix_direction`, `context.notes: root_cause`
 - Append to `issue_history`: `{ from: previous_status, to: "diagnosed", changed_at: now(), actor: "debug-agent" }`
 
-Display: "Updated {count} issues with diagnosis results"
-
 ---
 
 ### Step 8: Update UAT (if --from-uat)
 
-Skip if standalone mode.
-
-For each diagnosed gap, update the uat.md Gaps section:
+Skip if standalone. For each diagnosed gap, update uat.md Gaps:
 ```yaml
 - test: T-003
   truth: "User can reply to comments"
@@ -331,14 +289,10 @@ For each diagnosed gap, update the uat.md Gaps section:
   affected_files: ["src/components/Comments.tsx:42", "src/api/comments.ts:78"]
 ```
 
-This closes the UAT -> debug feedback loop.
-
 ---
 
 ### Step 9: Handle Root Cause Found
 
-Display root cause, evidence, and fix recommendation.
-
 ```
 ------------------------------------------------------------
   ROOT CAUSE IDENTIFIED
@@ -364,26 +318,19 @@ Options:
 
 ### Step 10: Handle Checkpoint
 
-Parse checkpoint type and details. Present to user via AskUserQuestion.
-If user provides input: spawn continuation agent with prior state + user response.
-If user wants to pause: save state, exit.
+Present checkpoint to user via AskUserQuestion. Input → spawn continuation agent. Pause → save state, exit.
 
 ---
 
 ### Step 11: Handle Inconclusive
 
-Display what was checked and eliminated. Offer:
-1. Continue investigating (fresh agent with prior state)
-2. Add more context (gather additional symptoms)
-3. Manual investigation (pause session)
+Display what was checked/eliminated. Offer: 1) Continue (fresh agent with prior state) 2) Add context 3) Manual investigation.
 
 ---
 
 ### Step 12: Spawn Continuation Agent
 
-Load prior state (understanding.md + evidence.ndjson).
-Build continuation prompt with user's checkpoint response.
-Handle return the same way (root cause / checkpoint / inconclusive).
+Load prior state (understanding.md + evidence.ndjson) + user checkpoint response. Handle return same as Step 6.
 
 ---
 
@@ -421,14 +368,12 @@ Next steps:
 
 ## Evidence Format
 
-**evidence.ndjson -- one JSON object per line:**
+**evidence.ndjson** — one JSON object per line, append-only:
 
 ```json
 {"timestamp":"2026-03-14T10:30:00+08:00","hypothesis":"JWT token not refreshed on 401","action":"grep for 401 handler","result":"Found handler but no refresh call","conclusion":"confirmed"}
 ```
 
-Each line is a self-contained investigation step. Append-only.
-
 ---
 
 ## Understanding Template

package/workflows/delegate-usage.md

@@ -1,151 +1,43 @@
-# Delegate Execution Specification
-
-<purpose>
-Unified reference for `maestro delegate` — synchronous task delegation with broker-managed lifecycle, message injection, and MCP notifications.
-</purpose>
-
-**References**: `~/.maestro/cli-tools.json` (tool config), `~/.maestro/templates/cli/` (protocol + prompt templates)
-
----
-
-## 1. Quick Reference
-
-<context>
-
-### Command Syntax
+# Delegate Usage
 
 ```bash
 maestro delegate "<PROMPT>" [options]
 ```
 
-### Options
+## Options
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--to <tool>` | Explicit tool: gemini, qwen, codex, claude, opencode | First enabled in config |
-| `--role <role>` | Capability role: analyze, explore, review, implement, plan, brainstorm, research | — (resolves via config) |
-| `--mode <mode>` | `analysis` (read-only) or `write` (create/modify/delete) | `analysis` |
+| `--to <tool>` | gemini, qwen, codex, claude, opencode | First enabled |
+| `--role <role>` | analyze, explore, review, implement, plan, brainstorm, research | — |
+| `--mode <mode>` | `analysis` (read-only) / `write` (modify) | `analysis` |
 | `--model <model>` | Model override | Tool's `primaryModel` |
-| `--cd <dir>` | Working directory | Current directory |
-| `--rule <template>` | Load protocol + prompt template | — (optional) |
+| `--cd <dir>` | Working directory | Current |
+| `--rule <template>` | Protocol + prompt template | — |
 | `--id <id>` | Execution ID | Auto: `{prefix}-{HHmmss}-{rand4}` |
-| `--resume [id]` | Resume previous session (last if no id) | — |
+| `--resume [id]` | Resume previous session | — |
 | `--includeDirs <dirs>` | Additional directories (comma-separated) | — |
-| `--backend <type>` | Adapter backend: `direct` or `terminal` (tmux/wezterm) | `direct` |
-
-### Tool Resolution Priority
-
-1. `--to <tool>` — explicit tool selection (backward compat, highest priority)
-2. `--role <role>` — capability-based auto-selection via config
-3. No flag — first enabled tool in config
-
-### Role-Based Tool Selection
-
-Roles map to tools via `cli-tools.json` configuration:
-- User-defined roles in `roles` section override built-in defaults
-- Workspace `.maestro/cli-tools.json` overrides global `~/.maestro/cli-tools.json`
-- Built-in roles: `analyze`, `explore`, `review`, `implement`, `plan`, `brainstorm`, `research`
-
-### Mode Definition (Authoritative)
-
-| Mode | Permission | Auto-Invoke Safe | Use For |
-|------|-----------|------------------|---------|
-| `analysis` | Read-only | Yes | Review, exploration, diagnosis, architecture analysis |
-| `write` | Create/Modify/Delete | No — requires explicit intent | Implementation, bug fixes, refactoring |
-
-> `--mode` is the **authoritative** permission control. The `MODE:` field inside prompt text is a hint for the agent — both should be consistent, but `--mode` governs actual behavior.
-</context>
-
----
-
-## 2. Configuration
-
-<context>
-
-### Config File: `~/.maestro/cli-tools.json`
-
-| Field | Description |
-|-------|-------------|
-| `enabled` | Tool availability |
-| `primaryModel` | Default model |
-| `secondaryModel` | Fallback model |
-| `tags` | Capability tags (for caller-side routing) |
-| `type` | `builtin` / `cli-wrapper` / `api-endpoint` |
-
-> `api-endpoint` tools support **analysis only** — no file write capability.
-
-### Tool Selection
-
-1. Explicit `--to` specified → use it (validate enabled)
-2. No `--to` → first enabled tool in config order
 
-### Fallback Chain
+Tool resolution: `--to` > `--role` > first enabled in config.
 
-Primary model fails → `secondaryModel` → next enabled tool → first enabled (default).
+**`--mode` is authoritative** — `MODE:` in prompt text is a hint only.
 
-### MCP Server Startup
-
-```bash
-# Claude Code — load Maestro as development MCP server
-claude --dangerously-load-development-channels server:maestro --dangerously-skip-permissions
-```
-
-With MCP connected, all delegate tools are available programmatically.
-</context>
-
----
-
-## 3. Prompt Construction
-
-<context>
-
-### Assembly Order
-
-`maestro delegate` builds the final prompt as:
-
-1. **Mode protocol** — `~/.maestro/templates/cli/protocols/{mode}-protocol.md`
-2. **User prompt** — the positional `"<PROMPT>"` value
-3. **Rule template** — `~/.maestro/templates/cli/prompts/{rule}.txt` (if `--rule` specified)
-
-### Prompt Template (6 Fields)
+## Prompt Template
 
 ```
-PURPOSE: [goal] + [why] + [success criteria]
+PURPOSE: [goal] + [success criteria]
 TASK: [step 1] | [step 2] | [step 3]
 MODE: analysis|write
-CONTEXT: @[file patterns] | Memory: [prior work context]
-EXPECTED: [output format] + [quality criteria]
-CONSTRAINTS: [scope limits] | [special requirements]
-```
-
-- **PURPOSE**: What + Why + Success. Not "Analyze code" but "Identify auth vulnerabilities; success = OWASP Top 10 covered"
-- **TASK**: Specific verbs. Not "Review code" but "Scan for SQL injection | Check XSS | Verify CSRF"
-- **MODE**: Must match `--mode` flag
-- **CONTEXT**: File scope + memory from prior work
-- **EXPECTED**: Deliverable format, not just "Report"
-- **CONSTRAINTS**: Task-specific limits (vs `--rule` which loads generic templates)
-
-### CONTEXT: File Patterns + Directory
-
-- `@**/*` — all files in working directory (default)
-- `@src/**/*.ts` — scoped pattern
-- `@../shared/**/*` — sibling directory (**requires `--includeDirs`**)
-
-**Rule**: If CONTEXT uses `@../dir/**/*`, must add `--includeDirs ../dir`.
-
-```bash
-maestro delegate "CONTEXT: @**/* @../shared/**/*" --to gemini --mode analysis \
-  --cd "src/auth" --includeDirs "../shared"
+CONTEXT: @[file patterns] | Memory: [prior work]
+EXPECTED: [output format]
+CONSTRAINTS: [scope limits]
 ```
 
-### CONTEXT: Memory
+### CONTEXT Patterns
 
-Include when building on previous work:
-
-```
-Memory: Building on auth refactoring (commit abc123), implementing refresh tokens
-Memory: Integration with auth module, using shared error patterns
-```
+- `@**/*` — all files (default)
+- `@src/**/*.ts` — scoped
+- `@../shared/**/*` — sibling dir (**requires `--includeDirs ../shared`**)
 
 ### --rule Templates
 
@@ -157,93 +49,44 @@ Memory: Integration with auth module, using shared error patterns
 
 **Development**: `development-implement-feature`, `development-refactor-codebase`, `development-generate-tests`, `development-implement-component-ui`, `development-debug-runtime-issues`
 
-### Complete Example
-
-```bash
-maestro delegate "PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module; success = all critical/high documented with remediation
-TASK: Scan for injection flaws | Check auth bypass vectors | Evaluate session management | Assess data exposure
-MODE: analysis
-CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt + JWT
-EXPECTED: Severity matrix, file:line references, remediation snippets, priority ranking
-CONSTRAINTS: Focus on authentication | Ignore test files
-" --to gemini --mode analysis --rule analysis-assess-security-risks --cd "src/auth"
-```
-</context>
-
----
+## Execution Rules
 
-## 4. Execution
-
-<execution>
-
-### Calling Convention
-
-`maestro delegate` runs synchronously. Status summary and output are **auto-appended** on completion — no manual `output` or `status` commands needed.
-
-**Always** use `run_in_background: true` and **end your response immediately**:
+**ALWAYS** use `run_in_background: true`, then **stop immediately**:
 
 ```
 Bash({ command: "maestro delegate \"...\" --to gemini --mode analysis", run_in_background: true })
 ```
 
-When the background callback arrives, the result is already included:
-```
-[MAESTRO_EXEC_ID=gem-143022-a7f2]                             ← at start
-[DELEGATE COMPLETED] gem-143022-a7f2 gemini/analysis           ← status, on completion
---- Output ---
-<actual output content>                                        ← output, on completion
-```
-
-**Rules:**
 - NEVER use foreground Bash for delegate calls
-- NEVER output text or tool calls after the `run_in_background` Bash call
-- When the callback arrives, output is already included — directly use it
-
-### Execution ID
+- NEVER output text or tool calls after the background Bash call
+- Callback includes status + output — use it directly
 
-ID prefix: gemini→`gem`, qwen→`qwn`, codex→`cdx`, claude→`cld`, opencode→`opc`
+### Execution ID Prefix
 
-```bash
-maestro delegate "<PROMPT>" --to gemini --mode analysis    # auto-ID: gem-143022-a7f2
-maestro delegate "<PROMPT>" --to gemini --mode write --id my-task-1  # custom ID
-```
+gemini→`gem`, qwen→`qwn`, codex→`cdx`, claude→`cld`, opencode→`opc`
 
-### Session Resume
+### Resume
 
 ```bash
-maestro delegate "<PROMPT>" --to gemini --resume              # last session
-maestro delegate "<PROMPT>" --to gemini --mode write --resume <id>  # specific
-maestro delegate "<PROMPT>" --to gemini --resume <id1>,<id2>     # merge multiple
-```
-
-Resume auto-assembles previous conversation context. Warning emitted when context exceeds 32KB.
-
-### Job Lifecycle
-
-```
-queued → running → completed
-                 → failed
-                 → cancelled
-              ↗
-         input_required
+maestro delegate "<PROMPT>" --to gemini --resume           # last session
+maestro delegate "<PROMPT>" --to gemini --resume <id>      # specific
 ```
 
 ### Message Delivery
 
-| Mode | Behavior | Use For |
-|------|----------|---------|
-| `inject` | Routes to running worker stdin; non-interactive adapters auto cancel + relaunch | Supplementary context, course correction |
-| `after_complete` | Queues message; relaunches delegate with queued message on completion | Chained tasks, post-processing |
+| Mode | Use For |
+|------|---------|
+| `inject` | Supplementary context to running worker |
+| `after_complete` | Chained tasks after completion |
 
-</execution>
-
----
-
-## 5. Auto-Invoke Triggers
+```bash
+maestro delegate message <exec-id> "additional context"
+maestro delegate message <exec-id> "next task" --delivery after_complete
+```
 
-<execution>
+## Auto-Invoke Triggers
 
-Proactively invoke `maestro delegate` when these conditions are met — no user confirmation needed for `analysis` mode:
+Proactively invoke for `analysis` mode — no user confirmation needed:
 
 | Trigger | Suggested Rule |
 |---------|---------------|
@@ -253,49 +96,4 @@ Proactively invoke `maestro delegate` when these conditions are met — no user
 | Pattern uncertainty | `analysis-analyze-code-patterns` |
 | Critical/security code paths | `analysis-assess-security-risks` |
 
-### Principles
-
-- Default `--mode analysis` (safe, read-only)
-- Always `Bash(run_in_background: true)` — stop immediately, wait for callback
-- Use `--role` for capability-based tool selection; fallback chain is config-driven
-- Rule suggestions are guidelines — choose the best fit
-- Use `inject` for supplementary context mid-execution; `after_complete` for chained multi-step tasks
-</execution>
-
----
-
-## 6. Workflows
-
-<execution>
-
-### Basic Usage
-
-```
-Bash({
-  command: 'maestro delegate "analyze auth module" --to gemini',
-  run_in_background: true
-})
-// → STOP, wait for callback
-// → callback includes status + output automatically
-```
-
-### Inject Supplementary Context
-
-```bash
-maestro delegate message gem-143022-a7f2 "Also check src/utils/sanitize.ts"
-# → accepted: true, delivery: inject
-```
-
-### Chain: Analyze → Fix
-
-```
-Bash({
-  command: 'maestro delegate "find SQL injection vulnerabilities" --to gemini',
-  run_in_background: true
-})
-// → STOP, wait for callback
-// → on callback: chain next step
-maestro delegate message gem-143022-a7f2 "Fix all critical vulnerabilities" --delivery after_complete
-// → queued, relaunches after analysis completes
-```
-</execution>
+**Always** `run_in_background: true`, default `--mode analysis`.