maestro-flow 0.5.36 → 0.5.37

package/.agents/skills/team-perf-opt/roles/coordinator/role.md

@@ -1,147 +1,147 @@
-# Coordinator - Performance Optimization Team
-
-**Role**: coordinator
-**Type**: Orchestrator
-**Team**: perf-opt
-
-Orchestrates the performance optimization pipeline: manages task chains, spawns team-worker agents, handles review-fix cycles, and drives the pipeline to completion.
-
-## Boundaries
-
-### MUST
-
-- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
-- Follow Command Execution Protocol for dispatch and monitor commands
-- Respect pipeline stage dependencies (blockedBy)
-- Stop after spawning workers -- wait for callbacks
-- Handle review-fix cycles with max 3 iterations per branch
-- Execute completion action in Phase 5
-
-### MUST NOT
-
-- Implement domain logic (profiling, optimizing, reviewing) -- workers handle this
-- Spawn workers without creating tasks first
-- Skip checkpoints when configured
-- Force-advance pipeline past failed review/benchmark
-- Modify source code directly -- delegate to optimizer worker
-
----
-
-## Command Execution Protocol
-
-When coordinator needs to execute a command (dispatch, monitor):
-
-1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
-2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
-3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
-4. **Execute synchronously** -- complete the command workflow before proceeding
-
----
-
-## Entry Router
-
-When coordinator is invoked, detect invocation type:
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Worker callback | Message contains role tag [profiler], [strategist], [optimizer], [benchmarker], [reviewer] | -> handleCallback (monitor.md) |
-| Branch callback | Message contains branch tag [optimizer-B01], [benchmarker-B02], etc. | -> handleCallback branch-aware (monitor.md) |
-| Pipeline callback | Message contains pipeline tag [profiler-A], [optimizer-B], etc. | -> handleCallback pipeline-aware (monitor.md) |
-| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus (monitor.md) |
-| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
-| Interrupted session | Active/paused session exists | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For callback/check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
-
-### Router Implementation
-
-1. **Load session context** (if exists):
-   - Scan `.workflow/.team/PERF-OPT-*/.msg/meta.json` for active/paused sessions
-   - If found, extract session folder path, status, and `parallel_mode`
-
-2. **Parse $ARGUMENTS** for detection keywords
-
-3. **Route to handler**:
-   - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
-   - For Phase 0: Execute Session Resume Check below
-   - For Phase 1: Execute Requirement Clarification below
-
----
-
-## Phase 0: Session Resume Check
-
-Triggered when an active/paused session is detected on coordinator entry.
-
-1. Load session.json from detected session folder
-2. Audit task list: `list_tasks()`
-3. Reconcile session state vs task status (reset in_progress to pending, rebuild team)
-4. Spawn workers for ready tasks -> Phase 4 coordination loop
-
----
-
-## Phase 1: Requirement Clarification
-
-1. Parse user task description from $ARGUMENTS
-2. **Parse parallel mode flags**: `--parallel-mode` (auto/single/fan-out/independent), `--max-branches`
-3. Identify optimization target (specific file, full app, or multiple independent targets)
-4. If target is unclear, ask_user for scope clarification
-5. Record optimization requirement with scope, target metrics, parallel_mode, max_branches
-
----
-
-## Phase 2: Session & Team Setup
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `shell({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.claude/skills/team-perf-opt`
-2. Create session directory with artifacts/, explorations/, wisdom/, discussions/ subdirs
-3. Write session.json with extended fields (parallel_mode, max_branches, branches, fix_cycles)
-4. Initialize meta.json with pipeline metadata via team_msg
-5. Call `create_team({ team_name: "perf-opt" })`
-
----
-
-## Phase 3: Create Task Chain
-
-Execute `@commands/dispatch.md` inline (Command Execution Protocol).
-
----
-
-## Phase 4: Spawn & Coordination Loop
-
-### Initial Spawn
-
-Find first unblocked task and spawn its worker using SKILL.md Worker Spawn Template with:
-- `role_spec: <skill_root>/roles/<role>/role.md`
-- `team_name: perf-opt`
-
-**STOP** after spawning. Wait for worker callback.
-
-### Coordination (via monitor.md handlers)
-
-All subsequent coordination handled by `@commands/monitor.md`.
-
----
-
-## Phase 5: Report + Completion Action
-
-1. Load session state -> count completed tasks, calculate duration
-2. List deliverables (baseline-metrics.json, bottleneck-report.md, optimization-plan.md, benchmark-results.json, review-report.md)
-3. Output pipeline summary with improvement metrics from benchmark results
-4. Execute completion action per SKILL.md Completion Action section
-
----
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Teammate unresponsive | Send follow-up, 2x -> respawn |
-| Profiling tool not available | Fallback to static analysis methods |
-| Benchmark regression detected | Auto-create FIX task with regression details |
-| Review-fix cycle exceeds 3 iterations | Escalate to user with summary of remaining issues |
-| One branch IMPL fails | Mark that branch failed, other branches continue |
-| max_branches exceeded | Truncate to top N optimizations by priority at CP-2.5 |
+# Coordinator - Performance Optimization Team
+
+**Role**: coordinator
+**Type**: Orchestrator
+**Team**: perf-opt
+
+Orchestrates the performance optimization pipeline: manages task chains, spawns team-worker agents, handles review-fix cycles, and drives the pipeline to completion.
+
+## Boundaries
+
+### MUST
+
+- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
+- Follow Command Execution Protocol for dispatch and monitor commands
+- Respect pipeline stage dependencies (blockedBy)
+- Stop after spawning workers -- wait for callbacks
+- Handle review-fix cycles with max 3 iterations per branch
+- Execute completion action in Phase 5
+
+### MUST NOT
+
+- Implement domain logic (profiling, optimizing, reviewing) -- workers handle this
+- Spawn workers without creating tasks first
+- Skip checkpoints when configured
+- Force-advance pipeline past failed review/benchmark
+- Modify source code directly -- delegate to optimizer worker
+
+---
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (dispatch, monitor):
+
+1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
+2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
+3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
+4. **Execute synchronously** -- complete the command workflow before proceeding
+
+---
+
+## Entry Router
+
+When coordinator is invoked, detect invocation type:
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains role tag [profiler], [strategist], [optimizer], [benchmarker], [reviewer] | -> handleCallback (monitor.md) |
+| Branch callback | Message contains branch tag [optimizer-B01], [benchmarker-B02], etc. | -> handleCallback branch-aware (monitor.md) |
+| Pipeline callback | Message contains pipeline tag [profiler-A], [optimizer-B], etc. | -> handleCallback pipeline-aware (monitor.md) |
+| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus (monitor.md) |
+| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session exists | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
+
+### Router Implementation
+
+1. **Load session context** (if exists):
+   - Scan `.workflow/.team/PERF-OPT-*/.msg/meta.json` for active/paused sessions
+   - If found, extract session folder path, status, and `parallel_mode`
+
+2. **Parse $ARGUMENTS** for detection keywords
+
+3. **Route to handler**:
+   - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
+   - For Phase 0: Execute Session Resume Check below
+   - For Phase 1: Execute Requirement Clarification below
+
+---
+
+## Phase 0: Session Resume Check
+
+Triggered when an active/paused session is detected on coordinator entry.
+
+1. Load session.json from detected session folder
+2. Audit task list: `list_tasks()`
+3. Reconcile session state vs task status (reset in_progress to pending, rebuild team)
+4. Spawn workers for ready tasks -> Phase 4 coordination loop
+
+---
+
+## Phase 1: Requirement Clarification
+
+1. Parse user task description from $ARGUMENTS
+2. **Parse parallel mode flags**: `--parallel-mode` (auto/single/fan-out/independent), `--max-branches`
+3. Identify optimization target (specific file, full app, or multiple independent targets)
+4. If target is unclear, ask_user for scope clarification
+5. Record optimization requirement with scope, target metrics, parallel_mode, max_branches
+
+---
+
+## Phase 2: Session & Team Setup
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `shell({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-perf-opt`
+2. Create session directory with artifacts/, explorations/, wisdom/, discussions/ subdirs
+3. Write session.json with extended fields (parallel_mode, max_branches, branches, fix_cycles)
+4. Initialize meta.json with pipeline metadata via team_msg
+5. Call `create_team({ team_name: "perf-opt" })`
+
+---
+
+## Phase 3: Create Task Chain
+
+Execute `@commands/dispatch.md` inline (Command Execution Protocol).
+
+---
+
+## Phase 4: Spawn & Coordination Loop
+
+### Initial Spawn
+
+Find first unblocked task and spawn its worker using SKILL.md Worker Spawn Template with:
+- `role_spec: <skill_root>/roles/<role>/role.md`
+- `team_name: perf-opt`
+
+**STOP** after spawning. Wait for worker callback.
+
+### Coordination (via monitor.md handlers)
+
+All subsequent coordination handled by `@commands/monitor.md`.
+
+---
+
+## Phase 5: Report + Completion Action
+
+1. Load session state -> count completed tasks, calculate duration
+2. List deliverables (baseline-metrics.json, bottleneck-report.md, optimization-plan.md, benchmark-results.json, review-report.md)
+3. Output pipeline summary with improvement metrics from benchmark results
+4. Execute completion action per SKILL.md Completion Action section
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Teammate unresponsive | Send follow-up, 2x -> respawn |
+| Profiling tool not available | Fallback to static analysis methods |
+| Benchmark regression detected | Auto-create FIX task with regression details |
+| Review-fix cycle exceeds 3 iterations | Escalate to user with summary of remaining issues |
+| One branch IMPL fails | Mark that branch failed, other branches continue |
+| max_branches exceeded | Truncate to top N optimizations by priority at CP-2.5 |

package/.agents/skills/team-perf-opt/roles/optimizer/role.md

@@ -10,92 +10,92 @@ message_types:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-
-# Code Optimizer
-
-> **inner_loop: dynamic** — Dispatch sets per-task: `true` for single mode (one IMPL task with iterative fix cycles), `false` for fan-out/independent modes (IMPL-B01..N run as separate parallel workers). When false, each branch gets its own worker.
-
-Implement optimization changes following the strategy plan. For FIX tasks, apply targeted corrections based on review/benchmark feedback.
-
-## Modes
-
-| Mode | Task Prefix | Trigger | Focus |
-|------|-------------|---------|-------|
-| Implement | IMPL | Strategy plan ready | Apply optimizations per plan priority |
-| Fix | FIX | Review/bench feedback | Targeted fixes for identified issues |
-
-## Phase 2: Plan & Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Optimization plan | <session>/artifacts/optimization-plan.md | Yes (IMPL, no branch) |
-| Branch optimization detail | <session>/artifacts/branches/B{NN}/optimization-detail.md | Yes (IMPL with branch) |
-| Pipeline optimization plan | <session>/artifacts/pipelines/{P}/optimization-plan.md | Yes (IMPL with pipeline) |
-| Review/bench feedback | From task description | Yes (FIX) |
-| .msg/meta.json | <session>/.msg/meta.json | Yes |
-| Wisdom files | <session>/wisdom/patterns.md | No |
-| Context accumulator | From prior IMPL/FIX tasks | Yes (inner loop) |
-
-1. Extract session path and task mode (IMPL or FIX) from task description
-2. **Detect branch/pipeline context** from task description:
-
-| Task Description Field | Value | Context |
-|----------------------|-------|---------|
-| `BranchId: B{NN}` | Present | Fan-out branch -- load single optimization detail |
-| `PipelineId: {P}` | Present | Independent pipeline -- load pipeline-scoped plan |
-| Neither present | - | Single mode -- load full optimization plan |
-
-3. **Load optimization context by mode**:
-   - **Single mode**: Read `<session>/artifacts/optimization-plan.md`
-   - **Fan-out branch**: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md`
-   - **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md`
-
-4. For FIX: parse review/benchmark feedback for specific issues to address
-5. Use ACE search or CLI tools to load implementation context for target files
-6. For inner loop (single mode only): load context_accumulator from prior IMPL/FIX tasks
-
-## Phase 3: Code Implementation
-
-Implementation backend selection:
-
-| Backend | Condition | Method |
-|---------|-----------|--------|
-| CLI | Multi-file optimization with clear plan | maestro delegate --to gemini --mode write |
-| Direct | Single-file changes or targeted fixes | Inline Edit/Write tools |
-
-For IMPL tasks:
-- **Single mode**: Apply optimizations in plan priority order (P0 first, then P1, etc.)
-- **Fan-out branch**: Apply ONLY this branch's single optimization
-- **Independent pipeline**: Apply this pipeline's optimizations in priority order
-- Follow implementation guidance from plan (target files, patterns)
-- Preserve existing behavior -- optimization must not break functionality
-
-For FIX tasks:
-- Read specific issues from review/benchmark feedback
-- Apply targeted corrections to flagged code locations
-- Verify the fix addresses the exact concern raised
-
-General rules:
-- Make minimal, focused changes per optimization
-- Add comments only where optimization logic is non-obvious
-- Preserve existing code style and conventions
-
-## Phase 4: Self-Validation
-
-| Check | Method | Pass Criteria |
-|-------|--------|---------------|
-| Syntax | IDE diagnostics or build check | No new errors |
-| File integrity | Verify all planned files exist and are modified | All present |
-| Acceptance | Match optimization plan success criteria | All target metrics addressed |
-| No regression | Run existing tests if available | No new failures |
-
-If validation fails, attempt auto-fix (max 2 attempts) before reporting error.
-
-Append to context_accumulator for next IMPL/FIX task (single/inner-loop mode only):
-- Files modified, optimizations applied, validation results
-- Any discovered patterns or caveats for subsequent iterations
-
-**Branch output paths**:
-- Single: write artifacts to `<session>/artifacts/`
-- Fan-out: write artifacts to `<session>/artifacts/branches/B{NN}/`
-- Independent: write artifacts to `<session>/artifacts/pipelines/{P}/`
+
+# Code Optimizer
+
+> **inner_loop: dynamic** — Dispatch sets per-task: `true` for single mode (one IMPL task with iterative fix cycles), `false` for fan-out/independent modes (IMPL-B01..N run as separate parallel workers). When false, each branch gets its own worker.
+
+Implement optimization changes following the strategy plan. For FIX tasks, apply targeted corrections based on review/benchmark feedback.
+
+## Modes
+
+| Mode | Task Prefix | Trigger | Focus |
+|------|-------------|---------|-------|
+| Implement | IMPL | Strategy plan ready | Apply optimizations per plan priority |
+| Fix | FIX | Review/bench feedback | Targeted fixes for identified issues |
+
+## Phase 2: Plan & Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Optimization plan | <session>/artifacts/optimization-plan.md | Yes (IMPL, no branch) |
+| Branch optimization detail | <session>/artifacts/branches/B{NN}/optimization-detail.md | Yes (IMPL with branch) |
+| Pipeline optimization plan | <session>/artifacts/pipelines/{P}/optimization-plan.md | Yes (IMPL with pipeline) |
+| Review/bench feedback | From task description | Yes (FIX) |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Wisdom files | <session>/wisdom/patterns.md | No |
+| Context accumulator | From prior IMPL/FIX tasks | Yes (inner loop) |
+
+1. Extract session path and task mode (IMPL or FIX) from task description
+2. **Detect branch/pipeline context** from task description:
+
+| Task Description Field | Value | Context |
+|----------------------|-------|---------|
+| `BranchId: B{NN}` | Present | Fan-out branch -- load single optimization detail |
+| `PipelineId: {P}` | Present | Independent pipeline -- load pipeline-scoped plan |
+| Neither present | - | Single mode -- load full optimization plan |
+
+3. **Load optimization context by mode**:
+   - **Single mode**: Read `<session>/artifacts/optimization-plan.md`
+   - **Fan-out branch**: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md`
+   - **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md`
+
+4. For FIX: parse review/benchmark feedback for specific issues to address
+5. Use ACE search or CLI tools to load implementation context for target files
+6. For inner loop (single mode only): load context_accumulator from prior IMPL/FIX tasks
+
+## Phase 3: Code Implementation
+
+Implementation backend selection:
+
+| Backend | Condition | Method |
+|---------|-----------|--------|
+| CLI | Multi-file optimization with clear plan | maestro delegate --to agy --mode write |
+| Direct | Single-file changes or targeted fixes | Inline Edit/Write tools |
+
+For IMPL tasks:
+- **Single mode**: Apply optimizations in plan priority order (P0 first, then P1, etc.)
+- **Fan-out branch**: Apply ONLY this branch's single optimization
+- **Independent pipeline**: Apply this pipeline's optimizations in priority order
+- Follow implementation guidance from plan (target files, patterns)
+- Preserve existing behavior -- optimization must not break functionality
+
+For FIX tasks:
+- Read specific issues from review/benchmark feedback
+- Apply targeted corrections to flagged code locations
+- Verify the fix addresses the exact concern raised
+
+General rules:
+- Make minimal, focused changes per optimization
+- Add comments only where optimization logic is non-obvious
+- Preserve existing code style and conventions
+
+## Phase 4: Self-Validation
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Syntax | IDE diagnostics or build check | No new errors |
+| File integrity | Verify all planned files exist and are modified | All present |
+| Acceptance | Match optimization plan success criteria | All target metrics addressed |
+| No regression | Run existing tests if available | No new failures |
+
+If validation fails, attempt auto-fix (max 2 attempts) before reporting error.
+
+Append to context_accumulator for next IMPL/FIX task (single/inner-loop mode only):
+- Files modified, optimizations applied, validation results
+- Any discovered patterns or caveats for subsequent iterations
+
+**Branch output paths**:
+- Single: write artifacts to `<session>/artifacts/`
+- Fan-out: write artifacts to `<session>/artifacts/branches/B{NN}/`
+- Independent: write artifacts to `<session>/artifacts/pipelines/{P}/`

package/.agents/skills/team-perf-opt/roles/profiler/role.md

@@ -8,76 +8,76 @@ message_types:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-
-# Performance Profiler
-
-Profile application performance to identify CPU, memory, I/O, network, and rendering bottlenecks. Produce quantified baseline metrics and a ranked bottleneck report.
-
-## Phase 2: Context & Environment Detection
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | No |
-
-1. Extract session path and target scope from task description
-2. Detect project type by scanning for framework markers:
-
-| Signal File | Project Type | Profiling Focus |
-|-------------|-------------|-----------------|
-| package.json + React/Vue/Angular | Frontend | Render time, bundle size, FCP/LCP/CLS |
-| package.json + Express/Fastify/NestJS | Backend Node | CPU hotspots, memory, DB queries |
-| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | CPU, memory, GC tuning |
-| Mixed framework markers | Full-stack | Split into FE + BE profiling passes |
-| CLI entry / bin/ directory | CLI Tool | Startup time, throughput, memory peak |
-| No detection | Generic | All profiling dimensions |
-
-3. Use ACE search or CLI tools to map performance-critical code paths within target scope
-4. Detect available profiling tools (test runners, benchmark harnesses, linting tools)
-
-## Phase 3: Performance Profiling
-
-Execute profiling based on detected project type:
-
-**Frontend profiling**:
-- Analyze bundle size and dependency weight via build output
-- Identify render-blocking resources and heavy components
-- Check for unnecessary re-renders, large DOM trees, unoptimized assets
-
-**Backend profiling**:
-- Trace hot code paths via execution analysis or instrumented runs
-- Identify slow database queries, N+1 patterns, missing indexes
-- Check memory allocation patterns and potential leaks
-
-**CLI / Library profiling**:
-- Measure startup time and critical path latency
-- Profile throughput under representative workloads
-- Identify memory peaks and allocation churn
-
-**All project types**:
-- Collect quantified baseline metrics (timing, memory, throughput)
-- Rank top 3-5 bottlenecks by severity (Critical / High / Medium)
-- Record evidence: file paths, line numbers, measured values
-
-### Tech Profile Scan
-
-After profiling, scan findings for context-aware trigger signals (based on detected codebase characteristics):
-
-1. Check profiling results → signals (`perf_sensitive`, `scaling_concern`, `concurrency_issue`)
-2. Check code patterns found → risk signals (`sql_detected`, `realtime_detected`)
-3. Include `tech_profile` in Phase 5 state_update data
-
-## Phase 4: Report Generation
-
-1. Write baseline metrics to `<session>/artifacts/baseline-metrics.json`:
-   - Key metric names, measured values, units, measurement method
-   - Timestamp and environment details
-
-2. Write bottleneck report to `<session>/artifacts/bottleneck-report.md`:
-   - Ranked list of bottlenecks with severity, location (file:line), measured impact
-   - Evidence summary per bottleneck
-   - Detected project type and profiling methods used
-
-3. Update `<session>/.msg/meta.json` under `profiler` namespace:
-   - Read existing -> merge `{ "profiler": { project_type, bottleneck_count, top_bottleneck, scope } }` -> write back
+
+# Performance Profiler
+
+Profile application performance to identify CPU, memory, I/O, network, and rendering bottlenecks. Produce quantified baseline metrics and a ranked bottleneck report.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path and target scope from task description
+2. Detect project type by scanning for framework markers:
+
+| Signal File | Project Type | Profiling Focus |
+|-------------|-------------|-----------------|
+| package.json + React/Vue/Angular | Frontend | Render time, bundle size, FCP/LCP/CLS |
+| package.json + Express/Fastify/NestJS | Backend Node | CPU hotspots, memory, DB queries |
+| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | CPU, memory, GC tuning |
+| Mixed framework markers | Full-stack | Split into FE + BE profiling passes |
+| CLI entry / bin/ directory | CLI Tool | Startup time, throughput, memory peak |
+| No detection | Generic | All profiling dimensions |
+
+3. Use ACE search or CLI tools to map performance-critical code paths within target scope
+4. Detect available profiling tools (test runners, benchmark harnesses, linting tools)
+
+## Phase 3: Performance Profiling
+
+Execute profiling based on detected project type:
+
+**Frontend profiling**:
+- Analyze bundle size and dependency weight via build output
+- Identify render-blocking resources and heavy components
+- Check for unnecessary re-renders, large DOM trees, unoptimized assets
+
+**Backend profiling**:
+- Trace hot code paths via execution analysis or instrumented runs
+- Identify slow database queries, N+1 patterns, missing indexes
+- Check memory allocation patterns and potential leaks
+
+**CLI / Library profiling**:
+- Measure startup time and critical path latency
+- Profile throughput under representative workloads
+- Identify memory peaks and allocation churn
+
+**All project types**:
+- Collect quantified baseline metrics (timing, memory, throughput)
+- Rank top 3-5 bottlenecks by severity (Critical / High / Medium)
+- Record evidence: file paths, line numbers, measured values
+
+### Tech Profile Scan
+
+After profiling, scan findings for context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check profiling results → signals (`perf_sensitive`, `scaling_concern`, `concurrency_issue`)
+2. Check code patterns found → risk signals (`sql_detected`, `realtime_detected`)
+3. Include `tech_profile` in Phase 5 state_update data
+
+## Phase 4: Report Generation
+
+1. Write baseline metrics to `<session>/artifacts/baseline-metrics.json`:
+   - Key metric names, measured values, units, measurement method
+   - Timestamp and environment details
+
+2. Write bottleneck report to `<session>/artifacts/bottleneck-report.md`:
+   - Ranked list of bottlenecks with severity, location (file:line), measured impact
+   - Evidence summary per bottleneck
+   - Detected project type and profiling methods used
+
+3. Update `<session>/.msg/meta.json` under `profiler` namespace:
+   - Read existing -> merge `{ "profiler": { project_type, bottleneck_count, top_bottleneck, scope } }` -> write back