maestro-flow 0.4.9 → 0.4.10

package/.agy/skills/maestro-brainstorm/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: maestro-brainstorm
+description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
+argument-hint: [topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/brainstorm.md
+</required_reading>
+
+<deferred_reading>
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
+- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
+
+**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
+**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
+**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
+**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
+
+**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--style-skill PKG`: Style package for ui-designer role
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
+2. Optional — proceed without if unavailable.
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `maestro wiki list --category arch`
+2. Analyze the index, identify entries relevant to the current task
+3. Load selected documents:
+   `maestro wiki load <id1> [id2] [id3...]`
+4. Review loaded knowledge before proceeding
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → view_file(AbsolutePath="<agy-skills-dir>/maestro-init/SKILL.md") + execute inline
+- Project initialized, need spec package → view_file(AbsolutePath="<agy-skills-dir>/maestro-roadmap/SKILL.md") + execute inline (args: "--mode full --from-brainstorm {session_id}")
+- Project initialized, quick roadmap → view_file(AbsolutePath="<agy-skills-dir>/maestro-roadmap/SKILL.md") + execute inline (args: "--from-brainstorm {session_id}")
+- Need deeper analysis first → view_file(AbsolutePath="<agy-skills-dir>/maestro-analyze/SKILL.md") + execute inline (args: "{topic}")
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
+
+Single role mode:
+- More roles needed → view_file(AbsolutePath="<agy-skills-dir>/maestro-brainstorm/SKILL.md") + execute inline (args: "{next_role} --session {session_id}")
+- All roles done, run synthesis → view_file(AbsolutePath="<agy-skills-dir>/maestro-brainstorm/SKILL.md") + execute inline (args: "{topic} --session {session_id}")
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
+| E002 | error | No active session for single role mode | Guide user to run auto mode first |
+| E003 | error | Invalid role name | Show valid roles list |
+| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
+| W002 | warning | Project context (.workflow/) not found | Continue without project context |
+| W003 | warning | Role template not found | Use generic analysis structure |
+| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
+| W005 | warning | External research agent failed | Continue without designResearchContext |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
+- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
+- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
+- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
+- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists with UX analysis (interaction flows, state design, information architecture)
+- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints in Section 3 (Interface Contract)
+- [ ] feature-index.json and synthesis-changelog.md
+- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
+- [ ] All user decisions captured with Decision Recording Protocol
+- [ ] Session metadata updated with completion status
+- [ ] Confidence scored per role completion and after cross-role analysis
+- [ ] Readiness gate checked before spec generation
+- [ ] Pressure pass completed on at least 1 feature spec
+- [ ] Confidence summary appended to synthesis-changelog.md
+
+**Single role mode**:
+- [ ] analysis.md written to `{output_dir}/{role}/`
+- [ ] Feature-point organization used when feature list available
+- [ ] Framework reference included when guidance-specification.md exists
+- [ ] Session metadata updated
+</success_criteria>

package/.agy/skills/maestro-collab/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: maestro-collab
+description: Use when a question needs cross-verification from multiple CLI tools or diverse analytical perspectives
+argument-hint: <requirement> [--tools gemini,qwen,claude] [--mode analysis|write] [--rule <template>] [-y]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+
+<purpose>
+Fan-out requirement to multiple CLI tools in parallel → cross-verify for consensus/conflicts → synthesize into unified report with downstream artifacts (context.md + conclusions.json).
+</purpose>
+
+<context>
+$ARGUMENTS — requirement text and optional flags.
+
+**Flags**:
+- `--tools <list>`: Comma-separated CLI tools (default: first 3 enabled)
+- `--mode analysis|write`: Delegate mode (default: analysis)
+- `--rule <template>`: Shared rule template for all delegates
+- `-y`: Skip plan confirmation
+
+**Pre-load** (optional): `maestro spec load --category arch` + `maestro wiki list --category arch` → include in delegate prompts.
+
+**Output**: `.workflow/scratch/{YYYYMMDD}-collab-{slug}/`
+- `collab-report.md` — merged findings with consensus/conflict/unique tags
+- `context.md` — Locked/Free/Deferred decisions (plan compatible)
+- `conclusions.json` — structured: session_id, tools[], consensus_level, recommendation, confidence, dimensions[], decisions[]
+- `per-tool/{tool}-output.md` — raw outputs
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE           — 解析参数、提取 flags                      PERSIST: —
+S_DISCOVER        — 发现可用 CLI 工具                          PERSIST: —
+S_CONFIRM         — 展示计划、用户确认（-y 跳过）              PERSIST: —
+S_FANOUT          — 构建 prompt、并行启动 delegate、STOP       PERSIST: —
+S_COLLECT         — 回调到达、收集结果                          PERSIST: per-tool outputs
+S_CROSS_VERIFY    — 分类发现（共识/冲突/独有）                  PERSIST: —
+S_SYNTHESIZE      — 解决冲突、生成 3 个输出文件                 PERSIST: outputs
+S_REGISTER        — 注册 CLB artifact                          PERSIST: state.json
+S_REPORT          — 显示摘要 + next-step routing               PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_DISCOVER    WHEN: requirement non-empty              DO: extract requirement, tools, mode, rule, autoYes
+  → S_PARSE       WHEN: requirement empty                  DO: ask_question for requirement
+
+S_DISCOVER:
+  → S_CONFIRM     WHEN: eligible tools >= 2                DO: A_DISCOVER_TOOLS
+  → ERROR(E002)   WHEN: eligible tools < 2
+
+S_CONFIRM:
+  → S_FANOUT      WHEN: autoYes                            DO: A_SETUP_SESSION
+  → S_FANOUT      WHEN: user confirms "执行"               DO: A_SETUP_SESSION
+  → S_DISCOVER    WHEN: user selects "修改工具选择"         DO: re-select tools, validate >= 2
+  → END           WHEN: user cancels
+
+S_FANOUT:
+  → S_COLLECT     DO: A_PARALLEL_DELEGATE then STOP — wait for callbacks
+
+S_COLLECT:
+  → S_CROSS_VERIFY  WHEN: all callbacks arrived            DO: A_COLLECT_OUTPUTS
+  → ERROR(E004)     WHEN: all delegates failed
+  GUARD: 1+ succeeded → continue with partial results (W001)
+
+S_CROSS_VERIFY:
+  → S_SYNTHESIZE    DO: A_CLASSIFY_FINDINGS
+
+S_SYNTHESIZE:
+  → S_REGISTER      DO: A_GENERATE_OUTPUTS
+
+S_REGISTER:
+  → S_REPORT        DO: append CLB artifact to state.json (type: collab, scope: adhoc)
+
+S_REPORT:
+  → END             DO: display summary (requirement, tools, consensus_level, per-tool status, artifact id, output dir)
+
+</transitions>
+
+<actions>
+
+### A_DISCOVER_TOOLS
+
+```
+run_command("maestro tools list --json 2>/dev/null || cat ~/.maestro/cli-tools.json")
+```
+Filter: enabled == true. If --mode write: exclude type == "api-endpoint".
+Auto-select (no --tools): first 3 eligible in config order.
+
+### A_SETUP_SESSION
+
+Create: `.workflow/scratch/{YYYYMMDD}-collab-{slug}/` + `per-tool/`.
+
+### A_PARALLEL_DELEGATE
+
+1. Build shared prompt:
+   ```
+   PURPOSE: {requirement}; success = actionable findings with evidence
+   TASK: {auto-decomposed into 3-5 specific verbs}
+   MODE: {delegateMode}
+   CONTEXT: @**/*
+   EXPECTED: Structured findings with file:line refs, confidence (0-100), prioritized recommendations
+   CONSTRAINTS: {from requirement}
+   ```
+2. Launch ALL delegates in ONE message — multiple `run_command(run_in_background: true)`:
+   ```
+   maestro delegate "${prompt}" --to {tool} --mode ${mode} [--rule ${rule}]
+   ```
+3. **STOP immediately after launch. Wait for background callbacks.**
+
+### A_COLLECT_OUTPUTS
+
+On each callback: `maestro delegate output <id>` → write `per-tool/{tool}-output.md`.
+
+### A_CLASSIFY_FINDINGS
+
+Read all per-tool outputs. For each finding:
+
+| Condition | Tag |
+|-----------|-----|
+| 2+ tools agree | CONSENSUS |
+| Tools disagree | CONFLICT |
+| 1 tool only | UNIQUE |
+
+consensus_level = consensus_count / total_findings * 100.
+If consensus_level < 40%: W003.
+
+### A_GENERATE_OUTPUTS
+
+Resolve conflicts via evidence-weighted voting:
+- Higher confidence wins; more specific evidence (file:line) wins over general; tied → SUGGESTED
+
+Write 3 files:
+1. **collab-report.md**: Summary, Consensus Findings, Resolved Conflicts, Unresolved Items, Unique Insights, Recommendations, Per-Tool Confidence table
+2. **context.md**: Locked (CONSENSUS items), Free (UNIQUE with strong evidence), Deferred (UNRESOLVED conflicts). Standard Locked/Free/Deferred format for plan compatibility.
+3. **conclusions.json**: session_id, subject, mode, tools[], consensus_level, recommendation (Go/No-Go/Conditional), confidence, dimensions[{name, score, findings}], decisions[{title, classification, source_tools, rationale}]
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | Fewer than 2 eligible tools | Check cli-tools.json, enable more tools |
+| E004 | All delegates failed | Abort with per-tool error details |
+| W001 | One tool failed | Continue with remaining (partial degradation) |
+| W003 | consensus_level < 40% | Flag in summary, recommend manual review |
+</error_codes>
+
+<success_criteria>
+- [ ] All delegates launched in parallel via run_command(run_in_background: true), STOP after launch
+- [ ] Cross-verification: consensus/conflict/unique classification with consensus_level
+- [ ] 3 output files produced (collab-report.md, context.md, conclusions.json)
+- [ ] CLB artifact registered in state.json
+- [ ] Partial degradation: continued if 1+ tools succeeded
+</success_criteria>
+
+<next_step_routing>
+- Deep feasibility → `/maestro-analyze "{topic}"`
+- Plan from conclusions → `/maestro-plan --dir {dir}`
+- Expand → `/maestro-brainstorm "{topic}"`
+</next_step_routing>

package/.agy/skills/maestro-composer/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: maestro-composer
+description: Compose reusable workflow templates from natural language
+argument-hint: <workflow-description> [--resume] [--edit <template-path>]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Interactive workflow template composer. Parse natural language → resolve executors → inject checkpoints → build DAG → persist to `~/.maestro/templates/workflows/`. Progressive disclosure — specs loaded only when phase needs them.
+
+Three entry modes: **New design** (default), **Resume** (`--resume`), **Edit** (`--edit <path>`).
+</purpose>
+
+<deferred_reading>
+- [node-catalog](~/.maestro/templates/workflows/specs/node-catalog.md) — read at Phase 2 (Resolve)
+- [template-schema](~/.maestro/templates/workflows/specs/template-schema.md) — read at Phase 5 (Persist)
+</deferred_reading>
+
+<context>
+$ARGUMENTS — natural language description, or flags.
+
+**Flags**: `--resume` (resume in-progress design), `--edit <path>` (edit existing template)
+
+**Constants**:
+- Template dir: `~/.maestro/templates/workflows/`
+- Template index: `~/.maestro/templates/workflows/index.json`
+- Design drafts: `.workflow/templates/design-drafts/`
+- Template ID: `wft-<slug>-<YYYYMMDD>`, Node ID: `N-<seq>`, Checkpoint: `CP-<seq>`
+- Max nodes: 20
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+3. Optional — proceed without if unavailable.
+</context>
+
+<state_machine>
+
+<states>
+S_ROUTE        — 入口路由（new/resume/edit）               PERSIST: —
+S_PARSE        — 语义意图提取                               PERSIST: intent.json
+S_CONFIRM_1    — 确认解析结果                               PERSIST: —
+S_RESOLVE      — 映射步骤到 executor 节点                   PERSIST: nodes.json
+S_CONFIRM_2    — 确认节点映射                               PERSIST: —
+S_ENRICH       — 注入 checkpoint + 构建 DAG                 PERSIST: dag.json
+S_CONFIRM_3    — 可视化 pipeline + 用户审批                  PERSIST: —
+S_PERSIST      — 组装 JSON + 保存模板                       PERSIST: template file + index
+</states>
+
+<transitions>
+
+S_ROUTE:
+  → S_PARSE       WHEN: no flags (new design)
+  → S_RESOLVE     WHEN: --resume                           DO: load draft, skip to last incomplete phase
+  → S_CONFIRM_3   WHEN: --edit <path>                      DO: load template, show pipeline, ask edits
+
+S_PARSE:
+  → S_CONFIRM_1   DO: A_PARSE_INTENT
+
+S_CONFIRM_1:
+  → S_RESOLVE     WHEN: user confirms "Looks good"
+  → S_PARSE       WHEN: user selects "Edit steps" or "Add step"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_RESOLVE:
+  → S_CONFIRM_2   DO: A_RESOLVE_NODES (read deferred: node-catalog)
+
+S_CONFIRM_2:
+  → S_ENRICH      WHEN: user confirms "Continue"
+  → S_RESOLVE     WHEN: user changes executor or node type
+  → S_PARSE       WHEN: user selects "Back to intent"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_ENRICH:
+  → S_CONFIRM_3   DO: A_BUILD_DAG
+
+S_CONFIRM_3:
+  → S_PERSIST     WHEN: user confirms "Confirm & Save"
+  → S_CONFIRM_3   WHEN: user edits/adds/removes node       DO: apply change, re-render
+  → S_ENRICH      WHEN: user selects "Re-run checkpoints"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_PERSIST:
+  → END           DO: A_SAVE_TEMPLATE (read deferred: template-schema)
+
+</transitions>
+
+<actions>
+
+### A_PARSE_INTENT
+
+1. Parse description (if empty: ask_question for workflow description)
+2. Extract candidate nodes via semantic signals:
+
+| Signal | Type hint |
+|--------|-----------|
+| "analyze", "review", "explore" | analysis (cli) |
+| "plan", "design", "spec" | planning (skill) |
+| "implement", "build", "code", "fix" | execution (skill) |
+| "test", "validate", "verify" | testing (skill) |
+| "then", "next", "after" | sequential edge |
+| "parallel", "simultaneously" | parallel edge |
+
+3. Extract variables (inputs that vary per run)
+4. Classify: task type + complexity (simple 1-3 / medium 4-7 / complex 8+)
+5. Write `intent.json` to design drafts dir
+6. Display: parsed steps, variables, task type, complexity
+
+### A_RESOLVE_NODES
+
+Read deferred `node-catalog.md` (fallback to built-in mapping):
+
+| Type hint | Default executor |
+|-----------|-----------------|
+| planning | `maestro-plan` |
+| execution | `maestro-execute` |
+| testing | `quality-test` |
+| review | `quality-review` |
+| brainstorm | `maestro-brainstorm` |
+| analysis | `maestro delegate --role analyze` |
+| verify | `maestro-verify` |
+| refactor | `quality-refactor` |
+| debug | `quality-debug` |
+
+Build `args_template` with variable placeholders. Context injection: planning-after-analysis → `--context {prev_output_path}`, execution-after-planning → `--resume-session {prev_session_id}`.
+Write `nodes.json`. Display resolved node list.
+
+### A_BUILD_DAG
+
+1. Build sequential edges (fan-out/fan-in for parallel groups)
+2. Auto-inject checkpoints:
+
+| Rule | Condition |
+|------|-----------|
+| Artifact boundary | Source outputs plan/spec/analysis/review |
+| Execution gate | Target contains `execute` |
+| Long-running | Target is maestro-plan, maestro-roadmap --mode full |
+| Post-testing | Source contains `test` or `auto-test` |
+| User-defined | type_hint == checkpoint |
+
+3. Finalize context_schema from {variable} references
+4. Validate: no cycles, no orphans, all reachable
+5. Write `dag.json`
+6. Display ASCII pipeline visualization
+
+### A_SAVE_TEMPLATE
+
+Read deferred `template-schema.md` (fallback to built-in structure).
+Assemble template JSON: template_id, name, nodes, edges, checkpoints, context_schema, execution_mode.
+Write to `~/.maestro/templates/workflows/<slug>.json`. Update index.json.
+Display: path, ID, node count, variables, execute/edit commands. Clean up draft dir.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | 0 steps extracted | Ask user to rephrase with action verbs |
+| E003 | Node count > 20 | Suggest splitting into sub-workflows |
+| E005 | DAG cycle detected | Show cycle, ask user to resolve |
+| E006 | Edit template not found (--edit) | Show available templates |
+| W001 | Ambiguous step→executor mapping | Show candidates, let user choose |
+</error_codes>
+
+<success_criteria>
+- [ ] Each phase has interactive confirmation gate
+- [ ] Template JSON written with nodes, edges, checkpoints, context_schema
+- [ ] Index updated; deferred specs loaded only when phase needs them
+</success_criteria>

package/.agy/skills/maestro-execute/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: maestro-execute
+description: Use when a confirmed plan is ready for implementation
+argument-hint: [phase] [--auto-commit] [--method agent|cli|auto] [--executor <tool>] [--dir <path>] [-y]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Execute all tasks in a plan using wave-based parallel execution with dependency-aware ordering. Each plan is executed independently (plans串行, plan内wave并行). Task summaries are written to the plan's scratch directory under `.summaries/`. Registers EXC artifact in state.json.
+
+Invoked after /maestro-plan produces a confirmed plan. When called without args on a milestone, finds all pending plans and executes them sequentially.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/execute.md
+</required_reading>
+
+<deferred_reading>
+- [task.json](~/.maestro/templates/task.json) — read when reading task definitions
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number, or no args for milestone-wide execution, with optional flags.
+
+Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental knowhow extraction are defined in workflow `execute.md`.
+
+### Pre-load context (before task execution)
+
+1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
+2. **Wiki knowledge**: Run `maestro wiki search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
+3. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
+4. **UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains keywords like component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro spec load --category ui` and include in agent context.
+5. All are optional — proceed without if unavailable (log warning).
+
+### Role Knowledge
+`maestro wiki list --category coding` → select relevant → `maestro wiki load`
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before any task execution, run:
+```
+run_command("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/execute.md' completely.
+
+### Post-task Knowledge Inquiry
+
+After each task completion, check triggers:
+
+| Condition | Ask | Route |
+|-----------|-----|-------|
+| Summary mentions approach change / plan deviation | "Record as arch constraint?" | spec-add arch |
+| retry_count >= 2 | "Document fix pattern?" | spec-add debug |
+| Summary contains design rationale ("chose X because") | "Record as knowhow?" | spec-add learning |
+
+On confirm → `Skill("spec-add", "<category> <content>")`.
+
+### Issue Status Sync
+
+On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
+
+```
+For each completed/failed TASK with issue_id:
+  Read issue from issues.jsonl by issue_id
+  Collect all task_refs[] statuses for that issue:
+    all task_refs completed → issue.status = "resolved"
+    any task_ref failed    → issue.status = "in_progress"
+  Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
+  Write updated issue back to issues.jsonl
+```
+
+**Report format on completion:**
+
+```
+=== EXECUTION COMPLETE ===
+Plans executed: {plans_count}
+Completed: {completed_count}/{total_count} tasks
+Failed:    {failed_count} tasks
+
+Summaries: {plan_dir}/.summaries/
+Tasks:     {plan_dir}/.task/
+
+Next steps:
+  /maestro-verify              -- Verify execution results
+  /maestro-verify --dir {dir}  -- Verify specific plan
+  /manage-status               -- View project dashboard
+```
+
+**Completion status:**
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {failed_count} tasks failed (if any)
+NEXT: /maestro-verify
+--- END STATUS ---
+```
+
+If failed tasks exist, suggest /quality-debug for investigation.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No pending plans found | Verify plans exist, run maestro-plan first |
+| E002 | error | Plan directory not found | Check --dir path |
+| E003 | error | plan.json not found in directory | Verify plan.json exists, run maestro-plan first |
+| E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
+| W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
+</error_codes>
+
+<success_criteria>
+- [ ] All pending plans identified and executed sequentially
+- [ ] Within each plan: waves executed in parallel, waves串行
+- [ ] `.summaries/TASK-{NNN}-summary.md` written for each completed task
+- [ ] `.task/TASK-{NNN}.json` statuses updated (completed|blocked)
+- [ ] EXC artifact registered in state.json for each plan executed
+- [ ] Incremental knowhow extracted to specs/learnings.md
+- [ ] state.json updated with execution progress
+</success_criteria>