claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-perf-opt/roles/coordinator/commands/monitor.md

@@ -0,0 +1,320 @@
+# Command: Monitor
+
+Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, and completion. Supports single, fan-out, and independent parallel modes with per-branch/pipeline tracking.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session state | <session>/session.json | Yes |
+| Task list | Read `<session>/tasks.json` | Yes |
+| Trigger event | From Entry Router detection | Yes |
+| Pipeline definition | From SKILL.md | Yes |
+
+1. Load session.json for current state, `parallel_mode`, `branches`, `fix_cycles`
+2. Read `<session>/tasks.json` to get current task statuses
+3. Identify trigger event type from Entry Router
+
+## Phase 3: Event Handlers
+
+### handleCallback
+
+Triggered when a worker sends completion message.
+
+1. Parse message to identify role, task ID, and **branch/pipeline label**:
+
+| Message Pattern | Branch Detection |
+|----------------|-----------------|
+| `[optimizer-B01]` or task ID `IMPL-B01` | Branch `B01` (fan-out) |
+| `[profiler-A]` or task ID `PROFILE-A01` | Pipeline `A` (independent) |
+| `[profiler]` or task ID `PROFILE-001` | No branch (single) |
+
+2. Mark task as completed:
+
+Read `<session>/tasks.json`, find entry by id `<task-id>`, set `"status": "completed"`, write back.
+
+3. Record completion in session state
+
+4. **CP-2.5 check** (auto/fan-out mode only):
+   - If completed task is STRATEGY-001 AND `parallel_mode` is `auto` or `fan-out`:
+   - Execute **CP-2.5 Branch Creation** subroutine from dispatch.md
+   - After branch creation, proceed to handleSpawnNext (spawns all IMPL-B* in parallel)
+   - STOP after spawning
+
+5. Check if checkpoint feedback is configured for this stage:
+
+| Completed Task | Checkpoint | Action |
+|---------------|------------|--------|
+| PROFILE-001 / PROFILE-{P}01 | CP-1 | Notify user: bottleneck report ready for review |
+| STRATEGY-001 / STRATEGY-{P}01 | CP-2 | Notify user: optimization plan ready for review |
+| STRATEGY-001 (auto/fan-out) | CP-2.5 | Execute branch creation, then notify user with branch count |
+| BENCH-* or REVIEW-* | CP-3 | Check verdicts per branch (see Review-Fix Cycle below) |
+
+6. Proceed to handleSpawnNext
+
+### handleSpawnNext
+
+Find and spawn the next ready tasks.
+
+1. Scan tasks.json for tasks where:
+   - Status is "pending"
+   - All blockedBy tasks have status "completed"
+
+2. For each ready task, spawn team-worker:
+
+```
+spawn_agent({
+  agent_type: "team_worker",
+  items: [{
+    description: "Spawn <role> worker for <task-id>",
+    team_name: "perf-opt",
+    name: "<role>",
+    prompt: `## Role Assignment
+role: <role>
+role_spec: ~  or <project>/.codex/skills/team-perf-opt/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: perf-opt
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
+  }]
+})
+```
+
+3. **Parallel spawn rules by mode**:
+
+| Mode | Scenario | Spawn Behavior |
+|------|----------|---------------|
+| Single | Stage 4 ready | Spawn BENCH-001 + REVIEW-001 in parallel |
+| Fan-out (CP-2.5 done) | All IMPL-B* unblocked | Spawn ALL IMPL-B* in parallel |
+| Fan-out (IMPL-B{NN} done) | BENCH-B{NN} + REVIEW-B{NN} ready | Spawn both for that branch in parallel |
+| Independent | Any unblocked task | Spawn all ready tasks across all pipelines in parallel |
+
+4. STOP after spawning -- use `wait_agent({ ids: [<spawned-agent-ids>] })` to wait for next callback
+
+### Review-Fix Cycle (CP-3)
+
+**Per-branch/pipeline scoping**: Each branch/pipeline has its own independent fix cycle.
+
+#### Single Mode (unchanged)
+
+When both BENCH-001 and REVIEW-001 are completed:
+
+1. Read benchmark verdict from shared-memory (benchmarker namespace)
+2. Read review verdict from shared-memory (reviewer namespace)
+
+| Bench Verdict | Review Verdict | Action |
+|--------------|----------------|--------|
+| PASS | APPROVE | -> handleComplete |
+| PASS | REVISE | Create FIX task entry with review feedback |
+| FAIL | APPROVE | Create FIX task entry with benchmark feedback |
+| FAIL | REVISE/REJECT | Create FIX task entry with combined feedback |
+| Any | REJECT | Create FIX task entry + flag for strategist re-evaluation |
+
+#### Fan-out Mode (per-branch)
+
+When both BENCH-B{NN} and REVIEW-B{NN} are completed for a specific branch:
+
+1. Read benchmark verdict from `benchmarker.B{NN}` namespace
+2. Read review verdict from `reviewer.B{NN}` namespace
+3. Apply same verdict matrix as single mode, but scoped to this branch only
+4. **Other branches are unaffected** -- they continue independently
+
+#### Independent Mode (per-pipeline)
+
+When both BENCH-{P}01 and REVIEW-{P}01 are completed for a specific pipeline:
+
+1. Read verdicts from `benchmarker.{P}` and `reviewer.{P}` namespaces
+2. Apply same verdict matrix, scoped to this pipeline only
+
+#### Fix Cycle Count Tracking
+
+Fix cycles are tracked per branch/pipeline in `session.json`:
+
+```json
+// Single mode
+{ "fix_cycles": { "main": 0 } }
+
+// Fan-out mode
+{ "fix_cycles": { "B01": 0, "B02": 1, "B03": 0 } }
+
+// Independent mode
+{ "fix_cycles": { "A": 0, "B": 2 } }
+```
+
+| Cycle Count | Action |
+|-------------|--------|
+| < 3 | Add FIX task entry to tasks.json, increment cycle count for this branch/pipeline |
+| >= 3 | Escalate THIS branch/pipeline to user. Other branches continue |
+
+#### FIX Task Creation (branched)
+
+**Fan-out mode** -- add new entry to `<session>/tasks.json`:
+```json
+{
+  "id": "FIX-B{NN}-{cycle}",
+  "subject": "FIX-B{NN}-{cycle}",
+  "description": "PURPOSE: Fix issues in branch B{NN} from review/benchmark | Success: All flagged issues resolved\nTASK:\n  - Address review findings: <specific-findings>\n  - Fix benchmark regressions: <specific-regressions>\n  - Re-validate after fixes\nCONTEXT:\n  - Session: <session-folder>\n  - Branch: B{NN}\n  - Upstream artifacts: branches/B{NN}/review-report.md, branches/B{NN}/benchmark-results.json\n  - Shared memory: <session>/.msg/meta.json (namespace: optimizer.B{NN})\nEXPECTED: Fixed source files for B{NN} only\nCONSTRAINTS: Targeted fixes only | Do not touch other branches\n---\nInnerLoop: false\nBranchId: B{NN}",
+  "status": "pending",
+  "owner": "optimizer",
+  "blockedBy": []
+}
+```
+
+Create new BENCH and REVIEW entries with retry suffix:
+- `BENCH-B{NN}-R{cycle}` blocked on `FIX-B{NN}-{cycle}`
+- `REVIEW-B{NN}-R{cycle}` blocked on `FIX-B{NN}-{cycle}`
+
+**Independent mode** -- add new entry to `<session>/tasks.json`:
+```json
+{
+  "id": "FIX-{P}01-{cycle}",
+  "...same pattern with pipeline prefix...",
+  "status": "pending",
+  "owner": "optimizer",
+  "blockedBy": []
+}
+```
+
+Create `BENCH-{P}01-R{cycle}` and `REVIEW-{P}01-R{cycle}` entries.
+
+### handleCheck
+
+Output current pipeline status grouped by branch/pipeline.
+
+**Single mode** (unchanged):
+```
+Pipeline Status:
+  [DONE]  PROFILE-001  (profiler)    -> bottleneck-report.md
+  [DONE]  STRATEGY-001 (strategist)  -> optimization-plan.md
+  [RUN]   IMPL-001     (optimizer)   -> implementing...
+  [WAIT]  BENCH-001    (benchmarker) -> blocked by IMPL-001
+  [WAIT]  REVIEW-001   (reviewer)    -> blocked by IMPL-001
+
+Fix Cycles: 0/3
+Session: <session-id>
+```
+
+**Fan-out mode**:
+```
+Pipeline Status (fan-out, 3 branches):
+  Shared Stages:
+    [DONE]  PROFILE-001  (profiler)    -> bottleneck-report.md
+    [DONE]  STRATEGY-001 (strategist)  -> optimization-plan.md (4 OPT-IDs)
+
+  Branch B01 (OPT-001: <title>):
+    [RUN]   IMPL-B01     (optimizer)   -> implementing...
+    [WAIT]  BENCH-B01    (benchmarker) -> blocked by IMPL-B01
+    [WAIT]  REVIEW-B01   (reviewer)    -> blocked by IMPL-B01
+    Fix Cycles: 0/3
+
+  Branch B02 (OPT-002: <title>):
+    [DONE]  IMPL-B02     (optimizer)   -> done
+    [RUN]   BENCH-B02    (benchmarker) -> benchmarking...
+    [RUN]   REVIEW-B02   (reviewer)    -> reviewing...
+    Fix Cycles: 0/3
+
+  Branch B03 (OPT-003: <title>):
+    [FAIL]  IMPL-B03     (optimizer)   -> failed
+    Fix Cycles: 0/3 [BRANCH FAILED]
+
+Session: <session-id>
+```
+
+**Independent mode**:
+```
+Pipeline Status (independent, 2 pipelines):
+  Pipeline A (target: optimize rendering):
+    [DONE]  PROFILE-A01  -> [DONE]  STRATEGY-A01 -> [RUN] IMPL-A01 -> ...
+    Fix Cycles: 0/3
+
+  Pipeline B (target: optimize API):
+    [DONE]  PROFILE-B01  -> [DONE]  STRATEGY-B01 -> [DONE] IMPL-B01 -> ...
+    Fix Cycles: 1/3
+
+Session: <session-id>
+```
+
+Output status -- do NOT advance pipeline.
+
+### handleResume
+
+Resume pipeline after user pause or interruption.
+
+1. Audit tasks.json for inconsistencies:
+   - Tasks stuck in "in_progress" -> reset to "pending"
+   - Tasks with completed blockers but still "pending" -> include in spawn list
+2. For fan-out/independent: check each branch/pipeline independently
+3. Proceed to handleSpawnNext
+
+### handleConsensus
+
+Handle consensus_blocked signals from discuss rounds.
+
+| Severity | Action |
+|----------|--------|
+| HIGH | Pause pipeline (or branch), notify user with findings summary |
+| MEDIUM | Create revision task entry for the blocked role (scoped to branch if applicable) |
+| LOW | Log finding, continue pipeline |
+
+### handleComplete
+
+Triggered when all pipeline tasks are completed and no fix cycles remain.
+
+**Completion check varies by mode**:
+
+| Mode | Completion Condition |
+|------|---------------------|
+| Single | All 5 tasks (+ any FIX/retry tasks) have status "completed" |
+| Fan-out | ALL branches have BENCH + REVIEW completed with PASS/APPROVE (or escalated), shared stages done |
+| Independent | ALL pipelines have BENCH + REVIEW completed with PASS/APPROVE (or escalated) |
+
+**Aggregate results** before transitioning to Phase 5:
+
+1. For fan-out mode: collect per-branch benchmark results into `<session>/artifacts/aggregate-results.json`:
+   ```json
+   {
+     "branches": {
+       "B01": { "opt_id": "OPT-001", "bench_verdict": "PASS", "review_verdict": "APPROVE", "improvement": "..." },
+       "B02": { "opt_id": "OPT-002", "bench_verdict": "PASS", "review_verdict": "APPROVE", "improvement": "..." },
+       "B03": { "status": "failed", "reason": "IMPL failed" }
+     },
+     "overall": { "total_branches": 3, "passed": 2, "failed": 1 }
+   }
+   ```
+
+2. For independent mode: collect per-pipeline results similarly
+
+3. If any tasks not completed, return to handleSpawnNext
+4. If all completed (allowing for failed branches marked as such), transition to coordinator Phase 5
+
+### handleRevise
+
+Triggered by user "revise <TASK-ID> [feedback]" command.
+
+1. Parse target task ID and optional feedback
+2. Detect branch/pipeline from task ID pattern
+3. Add revision task entry to tasks.json with same role but updated requirements, scoped to branch
+4. Skip blockedBy (no dependencies, immediate execution)
+5. Cascade: create new downstream task entries within same branch only
+6. Proceed to handleSpawnNext
+
+### handleFeedback
+
+Triggered by user "feedback <text>" command.
+
+1. Analyze feedback text to determine impact scope
+2. Identify which pipeline stage, role, and branch/pipeline should handle the feedback
+3. Add targeted revision task entry to tasks.json (scoped to branch if applicable)
+4. Proceed to handleSpawnNext
+
+## Phase 4: State Persistence
+
+After every handler execution:
+
+1. Update session.json with current state (active tasks, fix cycle counts per branch, last event, resolved parallel_mode)
+2. Verify tasks.json consistency
+3. STOP and wait for next event

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

@@ -0,0 +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: read `<session>/tasks.json`
+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, request_user_input 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 `Bash({ 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. Initialize session folder structure (replaces TeamCreate)
+
+---
+
+## 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/.codex/skills/team-perf-opt/roles/optimizer/role.md

@@ -0,0 +1,97 @@
+---
+role: optimizer
+prefix: IMPL
+inner_loop: true
+additional_prefixes: [FIX]
+message_types:
+  success: impl_complete
+  error: error
+  fix: fix_required
+---
+
+# Code Optimizer
+
+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 | ccw cli --tool 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}/`

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

@@ -0,0 +1,73 @@
+---
+role: profiler
+prefix: PROFILE
+inner_loop: false
+message_types:
+  success: profile_complete
+  error: error
+---
+
+# 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
+
+## 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