| name | maister:performance |
| description | Orchestrates performance optimization workflows using static code analysis to identify bottlenecks (N+1 queries, missing indexes, O(n^2) algorithms, blocking I/O, memory leaks). Accepts optional user-provided profiling data. Reuses standard specification, planning, implementation, and verification phases. |
| user-invocable | true |
Performance Orchestrator
Static-analysis-first performance optimization workflow. Identifies bottlenecks by reading code, then uses the standard specification/planning/implementation/verification pipeline to fix them.
Initialization
BEFORE executing any phase, you MUST complete these steps:
Step 0: Session-reminder conflict resolution (decide ONCE)
Before doing anything else, settle this policy now and do not re-litigate it at any gate:
→ **MANDATORY GATE** — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1). / → MANDATORY GATE markers fire regardless of session-reminders, permission mode, or prior approval patterns. Auto / acceptEdits / bypassPermissions modes, reminders saying "work without stopping" / "continue without asking" / "minimize clarifying questions," and compaction summaries showing the user approving every prior gate do NOT exempt you from invoking AskUserQuestion at a gate. They apply only to your discretionary clarifications.
If you find yourself reasoning "the user has been approving everything, so I can skip this gate" or "auto-mode is on, so I should minimize questions" — that reasoning IS the failure mode. STOP and fire the gate.
Full framework rule: ../orchestrator-framework/references/orchestrator-patterns.md § 2 and § 2.1.
Step 1: Load Framework Patterns
Read the framework reference file NOW using the Read tool:
../orchestrator-framework/references/orchestrator-patterns.md - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution
Step 2: Initialize Workflow
- Capture the clock: run
date -u +"%Y-%m-%dT%H:%M:%SZ" via Bash NOW — you do NOT know the time from context. Every timestamp written this turn (created, updated, generated, phases[].started) uses this value. Date-only or T00:00:00Z values are the documented failure mode (orchestrator-patterns.md § 4 Timestamp Rule). Re-run date in later turns before writing timestamps.
- Create Task Items: Use
TaskCreate for all phases (see Phase Configuration), then set dependencies with TaskUpdate addBlockedBy
- Create Task Directory:
.maister/tasks/performance/YYYY-MM-DD-task-name/
- Create Subdirectories:
analysis/, analysis/user-profiling-data/, implementation/, verification/
- Initialize State: Create
orchestrator-state.yml with performance context
- Set up Operator Dashboard (orchestrator-patterns.md § 8) — first read
.maister/config.yml and set orchestrator.options.html_output (default true if the file/key is absent). When html_output is false, SKIP this entire step — no dashboard.html, no dashboard-data.js, no browser auto-open — and proceed. Otherwise: copy ../orchestrator-framework/assets/dashboard.html to the task root as dashboard.html, write the initial dashboard-data.js (all phases pending, task.type: "performance"), then auto-open it in the user's browser (open / xdg-open / start per platform, passing the plain absolute filesystem path — NEVER a hand-built file:// URL; on failure just print the path — never block). On resume: re-copy dashboard.html only if missing; regenerate dashboard-data.js from state; then auto-open it in the browser again (same opener as a new task — the OS focuses an already-open tab rather than duplicating).
- Discover project documentation: Read
.maister/docs/INDEX.md (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs. Store as project_context.project_doc_paths in state.
Output:
Performance Orchestrator Started
Task: [performance issue description]
Directory: [task-path]
Dashboard: open [task-path]/dashboard.html in a browser to monitor progress
Starting Phase 1: Codebase Analysis...
Operator Visibility (applies to every phase)
Config gate: these rules assume options.html_output is true (read from .maister/config.yml at init, default true). When false: skip the Dashboard-upkeep rule entirely (no dashboard files, no browser open, no rewrites) and the HTML-companions rule (do NOT pass html_style_guide_path; subagents write md only). The Artifact Summary Contract (§ 7 TL;DR blocks) and phase_summaries in state stay active either way.
Cross-cutting rules from orchestrator-patterns.md (same as the development orchestrator):
- Artifact Summary Contract (§ 7): every artifact-writing subagent prompt MUST include the contract instruction (artifacts open with TL;DR / Key Decisions / Open Questions & Risks). At context extraction, lift
decisions, risks, and artifacts into phase_summaries.[phase] — verbatim, never re-summarized.
- Dashboard upkeep (§ 8): rewrite
dashboard-data.js at every phase START (mark in_progress before delegating), BEFORE firing every exit gate (register the finished phase's artifacts/summary/decisions/risks — the operator reviews them on the dashboard while answering; status stays in_progress until the gate passes), after every phase completion (including skipped phases, with reason), every gate decision, every verification cycle, and at finalization. Every rewrite starts with date -u (one call per turn). It is a terse projection of state — never duplicate artifact content into it.
- HTML companions (§ 9): pass
html_style_guide_path (absolute path to ../orchestrator-framework/references/html-report-style.md) to specification-creator, implementation-planner, and implementation-verifier. Register returned html_path values in phase_summaries.[phase].artifacts[].html so the dashboard hero cards link HTML first.
- icon_hint values per phase: 1
analysis, 2 analysis, 3 spec, 4 verify, 5 plan, 6 code, 7 verify, 8 verify, 9 done.
When to Use
Use for:
- Application slow (response time issues, high latency)
- Need systematic bottleneck identification and resolution
- Want static code analysis for performance anti-patterns
- Have user-provided profiling data to act on
- Database query optimization needed
- Algorithm or I/O inefficiencies suspected
DO NOT use for: New features, bug fixes, refactoring without performance goals.
Core Principles
- Static Analysis First: Read code to detect patterns. Don't try to run profiling tools.
- User Data Welcome: Incorporate user-provided profiling data when available
- Reuse Standard Phases: Use proven specification/planning/implementation/verification pipeline
- Conservative Estimates: Provide improvement ranges, not false precision
- Practical Optimizations: Focus on patterns the agent CAN detect and fix
Phase Configuration
| Phase | content | activeForm | Agent/Skill |
|---|
| 1 | "Analyze codebase" | "Analyzing codebase" | codebase-analyzer |
| 2 | "Analyze performance bottlenecks" | "Analyzing performance bottlenecks" | bottleneck-analyzer |
| 3 | "Gather requirements & create specification" | "Gathering requirements & creating specification" | specification-creator |
| 4 | "Audit specification" | "Auditing specification" | spec-auditor (conditional) |
| 5 | "Plan implementation" | "Planning implementation" | implementation-planner |
| 6 | "Execute implementation" | "Executing implementation" | implementation-plan-executor |
| 7 | "Prompt verification options" | "Prompting verification options" | Direct |
| 8 | "Verify implementation & resolve issues" | "Verifying implementation" | implementation-verifier |
| 9 | "Finalize workflow" | "Finalizing workflow" | Direct |
Workflow Phases
Phase 1: Codebase Analysis & Clarifications
Purpose: Comprehensive codebase exploration for performance context, followed by scope/requirements clarification
Execute:
- Skill tool -
maister:codebase-analyzer
- Update state with analysis results
- Direct - use AskUserQuestion for max 5 critical clarifying questions about performance concerns, hotspots, and optimization goals
- Save clarifications to
analysis/clarifications.md
Output: analysis/codebase-analysis.md, analysis/clarifications.md
State: Update performance_context.phase_summaries.codebase_analysis, task_context.clarifications_resolved
Pass task_type="enhancement" and the performance-focused description. The codebase-analyzer adaptively selects parallel Explore agents based on task complexity. For performance tasks, the description should guide agents toward: database query patterns, hot code paths, I/O operations, caching layers, connection management, schema/migration files.
→ AUTO-CONTINUE — Do NOT end turn, do NOT prompt user. Proceed immediately to Phase 2.
Phase 2: Static Performance Analysis
Purpose: Identify bottlenecks through static code analysis + optional user profiling data
Execute: Task tool - maister:bottleneck-analyzer subagent
Output: analysis/performance-analysis.md
State: Update performance_context.bottlenecks_identified, performance_context.user_data_available, performance_context.bottleneck_priorities
Process:
- Check if
analysis/user-profiling-data/ contains any files
- If empty, use AskUserQuestion:
- Question: "Do you have profiling data to provide (flame graphs, APM screenshots, slow query logs)?"
- Options: "Yes, let me add files to analysis/user-profiling-data/" | "No, proceed with static analysis only"
- If user chooses to add files, wait for them, then proceed
ANTI-PATTERN — DO NOT DO THIS:
- ❌ "Let me analyze the bottlenecks myself..." — STOP. Delegate to bottleneck-analyzer.
- ❌ "I'll grep for N+1 patterns..." — STOP. Delegate to bottleneck-analyzer.
INVOKE NOW — Task tool call:
- Task tool -
maister:bottleneck-analyzer subagent
Context to pass: task_path, description, codebase analysis summary from Phase 1, user data paths (if any)
SELF-CHECK: Did you just invoke the Task tool with maister:bottleneck-analyzer? Or did you start analyzing code yourself? If the latter, STOP and invoke the Task tool.
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1).
AskUserQuestion - "Performance analysis complete. [N] bottlenecks identified ([P0 count] P0, [P1 count] P1). Continue to specification?"
Phase 3: Requirements & Specification
Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 2 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding AskUserQuestion call are protocol violations — never paper over a missed gate by updating state.
Purpose: Gather optimization requirements and create specification
Output: analysis/requirements.md, implementation/spec.md
State: Update performance_context.phase_summaries.specification
Part A — Requirements Gathering (inline):
- Present bottleneck summary from Phase 2 to user
- Use AskUserQuestion for optimization priorities:
- Which bottleneck priorities to address? (All P0+P1, P0 only, specific ones)
- Any constraints? (backward compatibility, memory limits, no new dependencies)
- Performance targets? (specific response time goals, if known)
- Save gathered requirements to
analysis/requirements.md with: performance issue description, bottleneck analysis summary, optimization priorities, constraints, targets
Part B — Specification Creation (subagent):
📋 Standards Discovery: Read .maister/docs/INDEX.md before creating spec.
ANTI-PATTERN — DO NOT DO THIS:
- ❌ "Let me create the specification..." — STOP. Delegate to specification-creator.
- ❌ "I'll write the spec based on the analysis..." — STOP. Delegate to specification-creator.
INVOKE NOW — Task tool call:
- Task tool -
maister:specification-creator subagent
Context to pass: task_path, task_type="performance", task_description, requirements_path (analysis/requirements.md), project_context_paths (INDEX.md + project_doc_paths from state — all discovered project docs), phase_summaries (codebase_analysis, bottleneck_analysis), html_style_guide_path (for the spec.html companion)
SELF-CHECK: Did you just invoke the Task tool with maister:specification-creator? Or did you start writing spec.md yourself? If the latter, STOP and invoke the Task tool.
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1).
AskUserQuestion - Display executive summary before asking. Read implementation/spec.md and extract: optimization targets, approach chosen, number of changes planned, expected impact. Format as brief overview then "Continue to specification audit?"
Phase 4: Specification Audit (Conditional)
Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 3 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding AskUserQuestion call are protocol violations — never paper over a missed gate by updating state.
Purpose: Independent review of optimization specification
Execute: Task tool - maister:spec-auditor subagent
Output: verification/spec-audit.md
State: Update options.spec_audit_enabled
Run if: >5 optimizations planned, spec >50 lines, or user requests
Skip if: Simple optimization (1-3 changes)
AskUserQuestion to decide - "Run specification audit?"
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1).
AskUserQuestion - Display executive summary before asking. Read verification/spec-audit.md and extract: overall verdict, issue counts by severity, top findings. Format as brief overview then "Continue to implementation planning?"
Phase 5: Implementation Planning
Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 4 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding AskUserQuestion call are protocol violations — never paper over a missed gate by updating state.
Purpose: Break optimization specification into implementation steps
📋 Standards Discovery: Read .maister/docs/INDEX.md before planning.
ANTI-PATTERN — DO NOT DO THIS:
- ❌ "Let me create the implementation plan..." — STOP. Delegate to implementation-planner.
- ❌ "I'll break this into optimization steps..." — STOP. Delegate to implementation-planner.
INVOKE NOW — Task tool call:
Execute: Task tool - maister:implementation-planner subagent
Output: implementation/implementation-plan.md
State: Update task groups and dependencies
Context to pass: task_path, task_type="performance", task_description, phase_summaries (specification, bottleneck_analysis, codebase_analysis), html_style_guide_path (for the implementation-plan.html companion)
SELF-CHECK: Did you just invoke the Task tool with maister:implementation-planner? Or did you start writing the plan yourself? If the latter, STOP and invoke the Task tool.
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1).
AskUserQuestion - Display executive summary before asking. Read implementation/implementation-plan.md and extract: number of task groups, total steps, key dependencies, optimization sequence. Format as brief overview then "Continue to implementation?"
Phase 6: Implementation
Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 5 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding AskUserQuestion call are protocol violations — never paper over a missed gate by updating state.
Purpose: Execute the optimization plan
📋 Standards Discovery: Implementation reads .maister/docs/INDEX.md continuously.
ANTI-PATTERN — DO NOT DO THIS:
- ❌ "Let me implement this directly..." — STOP. Delegate to implementation-plan-executor.
- ❌ "This is simple enough to code inline..." — STOP. Simplicity is NOT a reason to skip delegation.
INVOKE NOW — Skill tool call:
Execute: Skill tool - maister:implementation-plan-executor
Output: Implemented optimizations, implementation/work-log.md
State: Update implementation progress, extract phase_summaries.implementation
SELF-CHECK: Did you just invoke the Skill tool with maister:implementation-plan-executor? Or did you start writing code yourself? If the latter, STOP immediately and invoke the Skill tool instead.
⚠️ POST-IMPLEMENTATION CONTINUATION — After the skill completes and returns control:
- HTML plan reconciliation (backstop for syncs missed during waves): if
implementation/implementation-plan.html exists, for every group whose md checkboxes are all [x], run the executor's idempotent marker-flip command (sed flipping data-step="N\.[0-9]*" class="step todo" and data-group="N" class="group todo" to done). VERIFY: when all md steps are checked, grep -c 'class="step todo"' implementation/implementation-plan.html must return 0.
- Read
orchestrator-state.yml to confirm you are the orchestrator
- Update state: add Phase 6 to
completed_phases
- Proceed to Phase 7
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1).
AskUserQuestion - Display executive summary before asking. Extract from phase_summaries.implementation and implementation/work-log.md: optimizations applied, files changed, test results, any known issues. Format as brief overview then "Continue to verification?"
Phase 7: Verification Options
Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 6 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding AskUserQuestion call are protocol violations — never paper over a missed gate by updating state.
Purpose: Determine which verification checks to run
Execute: Direct - use AskUserQuestion for options
Output: Updated state with verification options
State: Set options.code_review_enabled, options.pragmatic_review_enabled, options.production_check_enabled, options.reality_check_enabled
Always enabled: Reality check, pragmatic review
Auto-set: skip_test_suite: true (full test suite already passed during implementation phase; cleared before re-verification if fixes are applied)
AskUserQuestion with multiselect - "Which additional verification checks?"
- "Code review" (recommended)
- "Production readiness check"
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1).
AskUserQuestion - "Options selected. Continue to Phase 8?"
Phase 8: Verification & Issue Resolution
Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 7 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding AskUserQuestion call are protocol violations — never paper over a missed gate by updating state.
Purpose: Comprehensive implementation verification with user-driven fix cycles
Output: verification/implementation-verification.md, optional review reports
State: Update verification_context
Execute:
Step 1: Invoke Skill tool - maister:implementation-verifier
Step 2: Display detailed issue breakdown grouped by category and severity (critical/warning/info), listing location, description, and fixability for each.
Step 3: Gate on verification status:
status: passed → skip to Pausestatus: passed_with_issues or failed → enter user-driven fix loop (Step 4)
Step 4: User-driven fix loop (max 3 iterations):
- Present all critical + warning issues as a numbered list
- AskUserQuestion — "Which issues should I fix?" with options: "Fix all fixable issues" / "Let me choose specific issues" / "Skip fixes, proceed as-is"
- Fix selected issues
- After fixes: set
skip_test_suite: false (code changed, tests must re-run)
- AskUserQuestion — "Re-run verification to check fixes?" with options: "Yes, re-run verification" / "No, proceed to next phase"
- If re-run → re-invoke
maister:implementation-verifier → return to Step 2
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1).
AskUserQuestion - Display executive summary: total issues found, issues fixed, issues remaining by severity. Then "Continue to finalization?"
Phase 9: Finalization
Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 8 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding AskUserQuestion call are protocol violations — never paper over a missed gate by updating state.
Purpose: Complete workflow and provide next steps
Execute: Direct - create summary, update state, guide commit
Output: Workflow summary
State: Set task.status: completed
Process:
- Create workflow summary (bottlenecks found, optimizations implemented, verification result)
- Update task status to "completed"
- Provide commit message template
- Guide performance-specific next steps:
- Run the application and verify improvements manually
- Consider profiling with runtime tools to measure actual impact
- Monitor production metrics after deployment
- Address remaining P2/P3 bottlenecks if needed
→ End of workflow
Domain Context (State Extensions)
Performance-specific fields in orchestrator-state.yml:
performance_context:
bottlenecks_identified: null
user_data_available: false
bottleneck_priorities:
p0: 0
p1: 0
p2: 0
p3: 0
phase_summaries:
codebase_analysis: {key_files: [], summary: null}
bottleneck_analysis: {bottlenecks: [], summary: null, user_data_incorporated: false}
specification: {summary: null}
verification_context:
last_status: null
issues_found: null
fixes_applied: []
decisions_made: []
reverify_count: 0
options:
html_output: true
spec_audit_enabled: null
skip_test_suite: true
code_review_enabled: true
pragmatic_review_enabled: true
reality_check_enabled: true
production_check_enabled: null
Task Structure
.maister/tasks/performance/YYYY-MM-DD-task-name/
├── orchestrator-state.yml
├── dashboard.html # Operator dashboard (copied plugin asset — never model-generated)
├── dashboard-data.js # Dashboard data projection (rewritten per phase/gate)
├── analysis/
│ ├── codebase-analysis.md # Phase 1
│ ├── performance-analysis.md # Phase 2
│ ├── user-profiling-data/ # Optional user-provided data
│ └── requirements.md # Phase 3
├── implementation/
│ ├── spec.md # Phase 3
│ ├── spec.html # Phase 3 (HTML companion)
│ ├── implementation-plan.md # Phase 5
│ ├── implementation-plan.html # Phase 5 (HTML companion)
│ └── work-log.md # Phase 6
└── verification/
├── spec-audit.md # Phase 4 (conditional)
├── implementation-verification.md # Phase 8
└── implementation-verification.html # Phase 8 (HTML companion)
Auto-Recovery
| Phase | Max Attempts | Strategy |
|---|
| 1 | 2 | Expand search scope, prompt user for hints |
| 2 | 2 | Re-analyze with broader patterns, ask user |
| 3 | 2 | Regenerate spec with adjusted requirements |
| 5 | 2 | Regenerate plan |
| 6 | 5 | Fix syntax, imports, tests |
| 8 | 3 | Fix-then-reverify cycles |
Command Integration
Invoked via:
/maister:performance [description] [--sequential] (new)/maister:performance [task-path] [--from=PHASE] [--sequential] (resume)
Flags:
--from=PHASE: Resume from specific phase--sequential: Disable parallel wave dispatch in implementation-plan-executor; run one task group at a time. Persisted as orchestrator.options.sequential: true in orchestrator-state.yml. Defaults to off (parallel waves).
Task directory: .maister/tasks/performance/YYYY-MM-DD-task-name/
