catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-03 15:43:11 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
e54d76f7becda863f710ebdd10e3f828d6e9086a
Claude-Code-Workflow/.claude/skills/team-perf-opt/SKILL.md

15 KiB
Raw Blame History

name, description, allowed-tools
name description allowed-tools
team-perf-opt Unified team skill for performance optimization. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team perf-opt". Task, TaskCreate, TaskList, TaskGet, TaskUpdate, TeamCreate, TeamDelete, SendMessage, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context

Team Performance Optimization

Unified team skill: Profile application performance, identify bottlenecks, design optimization strategies, implement changes, benchmark improvements, and review code quality. Built on team-worker agent architecture -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from markdown specs.

Architecture

+---------------------------------------------------+
|  Skill(skill="team-perf-opt")                      |
|  args="<task-description>"                         |
+-------------------+-------------------------------+
                    |
         Orchestration Mode (auto -> coordinator)
                    |
              Coordinator (inline)
              Phase 0-5 orchestration
                    |
    +-------+-------+-------+-------+
    v       v       v       v       v
 [tw]    [tw]    [tw]    [tw]    [tw]
profiler strate- optim-  bench-  review-
         gist    izer    marker  er

  Subagents (callable by workers, not team members):
    [explore]  [discuss]

(tw) = team-worker agent

Role Router

This skill is coordinator-only. Workers do NOT invoke this skill -- they are spawned as team-worker agents directly.

Input Parsing

Parse $ARGUMENTS. No --role needed -- always routes to coordinator.

Role Registry

Role Spec Task Prefix Type Inner Loop
coordinator roles/coordinator/role.md (none) orchestrator -
profiler role-specs/profiler.md PROFILE-* orchestration false
strategist role-specs/strategist.md STRATEGY-* orchestration false
optimizer role-specs/optimizer.md IMPL-* / FIX-* code_generation true
benchmarker role-specs/benchmarker.md BENCH-* validation false
reviewer role-specs/reviewer.md REVIEW-* / QUALITY-* read_only_analysis false

Subagent Registry

Subagent Spec Callable By Purpose
explore subagents/explore-subagent.md profiler, optimizer Shared codebase exploration for performance-critical code paths
discuss subagents/discuss-subagent.md strategist, reviewer Multi-perspective discussion for optimization approaches and review findings

Dispatch

Always route to coordinator. Coordinator reads roles/coordinator/role.md and executes its phases.

Orchestration Mode

User just provides task description.

Invocation: Skill(skill="team-perf-opt", args="<task-description>")

Lifecycle:

User provides task description
  -> coordinator Phase 1-3: Requirement clarification -> TeamCreate -> Create task chain
  -> coordinator Phase 4: spawn first batch workers (background) -> STOP
  -> Worker (team-worker agent) executes -> SendMessage callback -> coordinator advances
  -> Loop until pipeline complete -> Phase 5 report + completion action

User Commands (wake paused coordinator):

Command Action
check / status Output execution status graph, no advancement
resume / continue Check worker states, advance next step
revise <TASK-ID> [feedback] Create revision task + cascade downstream
feedback <text> Analyze feedback impact, create targeted revision chain
recheck Re-run quality check
improve [dimension] Auto-improve weakest dimension

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

Example:

Phase 3 needs task dispatch
  -> Read roles/coordinator/commands/dispatch.md
  -> Execute Phase 2 (Context Loading)
  -> Execute Phase 3 (Task Chain Creation)
  -> Execute Phase 4 (Validation)
  -> Continue to Phase 4

Coordinator Spawn Template

v5 Worker Spawn (all roles)

When coordinator spawns workers, use team-worker agent with role-spec path:

Task({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: <team-name>,
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-perf-opt/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>

Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
})

Inner Loop roles (optimizer): Set inner_loop: true. The team-worker agent handles the loop internally.

Single-task roles (profiler, strategist, benchmarker, reviewer): Set inner_loop: false.

Pipeline Definitions

Pipeline Diagram

Pipeline: Linear with Review-Fix Cycle
=====================================================================
Stage 1           Stage 2           Stage 3           Stage 4
(W:1)             (W:2)             (W:3)             (W:4)
                                                   +-----------+
PROFILE-001  -->  STRATEGY-001 -->  IMPL-001   --> | BENCH-001 |
[profiler]        [strategist]      [optimizer]    | [bench]   |
                                        ^          +-----------+
                                        |               |
                                        |          +-----------+
                                        +<--FIX--->| REVIEW-001|
                                        |          | [reviewer]|
                                        |          +-----------+
                                        |               |
                                  (max 3 iterations)    v
                                                   COMPLETE
=====================================================================

Cadence Control

Beat model: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.

Beat Cycle (single beat)
======================================================================
  Event                   Coordinator              Workers
----------------------------------------------------------------------
  callback/resume --> +- handleCallback -+
                      |  mark completed   |
                      |  check pipeline   |
                      +- handleSpawnNext -+
                      |  find ready tasks |
                      |  spawn workers ---+--> [team-worker A] Phase 1-5
                      |  (parallel OK)  --+--> [team-worker B] Phase 1-5
                      +- STOP (idle) -----+         |
                                                     |
  callback <-----------------------------------------+
  (next beat)              SendMessage + TaskUpdate(completed)
======================================================================

  Fast-Advance (skips coordinator for simple linear successors)
======================================================================
  [Worker A] Phase 5 complete
    +- 1 ready task? simple successor?
    |   --> spawn team-worker B directly
    |   --> log fast_advance to message bus (coordinator syncs on next wake)
    +- complex case? --> SendMessage to coordinator
======================================================================

Beat View: Performance Optimization Pipeline
======================================================================
  Event                   Coordinator              Workers
----------------------------------------------------------------------
  new task         --> +- Phase 1-3: clarify -+
                       |  TeamCreate           |
                       |  create PROFILE-001   |
                       +- Phase 4: spawn ------+--> [profiler] Phase 1-5
                       +- STOP (idle) ---------+         |
                                                          |
  callback <----------------------------------------------+
  (profiler done)  --> +- handleCallback ------+    profile_complete
                       |  mark PROFILE done    |
                       |  spawn strategist ----+--> [strategist] Phase 1-5
                       +- STOP ----------------+         |
                                                          |
  callback <----------------------------------------------+
  (strategist done)--> +- handleCallback ------+    strategy_complete
                       |  mark STRATEGY done   |
                       |  spawn optimizer -----+--> [optimizer] Phase 1-5
                       +- STOP ----------------+         |
                                                          |
  callback <----------------------------------------------+
  (optimizer done) --> +- handleCallback ------+    impl_complete
                       |  mark IMPL done       |
                       |  spawn bench+reviewer-+--> [benchmarker] Phase 1-5
                       |  (parallel)    -------+--> [reviewer] Phase 1-5
                       +- STOP ----------------+    |           |
                                                     |           |
  callback x2 <--------------------------------------+-----------+
                  --> +- handleCallback ------+
                       |  both done?           |
                       |  YES + pass -> Phase 5|
                       |  NO / fail -> FIX task|
                       |  spawn optimizer -----+--> [optimizer] FIX-001
                       +- STOP or Phase 5 -----+
======================================================================

Checkpoints:

Checkpoint Trigger Location Behavior
CP-1 PROFILE-001 complete After Stage 1 User reviews bottleneck report, can refine scope
CP-2 STRATEGY-001 complete After Stage 2 User reviews optimization plan, can adjust priorities
CP-3 REVIEW/BENCH fail Stage 4 Auto-create FIX task, re-enter Stage 3 (max 3x)
CP-4 All tasks complete Phase 5 Interactive completion action

Task Metadata Registry

Task ID Role Phase Dependencies Description
PROFILE-001 profiler Stage 1 (none) Profile application, identify bottlenecks
STRATEGY-001 strategist Stage 2 PROFILE-001 Design optimization plan from bottleneck report
IMPL-001 optimizer Stage 3 STRATEGY-001 Implement highest-priority optimizations
BENCH-001 benchmarker Stage 4 IMPL-001 Run benchmarks, compare vs baseline
REVIEW-001 reviewer Stage 4 IMPL-001 Review optimization code for correctness
FIX-001 optimizer Stage 3 (cycle) REVIEW-001 or BENCH-001 Fix issues found in review/benchmark

Completion Action

When the pipeline completes (all tasks done, coordinator Phase 5):

AskUserQuestion({
  questions: [{
    question: "Team pipeline complete. What would you like to do?",
    header: "Completion",
    multiSelect: false,
    options: [
      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
      { label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
      { label: "Export Results", description: "Export deliverables to a specified location, then clean" }
    ]
  }]
})
Choice Action
Archive & Clean Update session status="completed" -> TeamDelete(perf-opt) -> output final summary
Keep Active Update session status="paused" -> output resume instructions: Skill(skill="team-perf-opt", args="resume")
Export Results AskUserQuestion for target path -> copy deliverables -> Archive & Clean

Session Directory

.workflow/<session-id>/
+-- session.json                    # Session metadata + status
+-- artifacts/
|   +-- baseline-metrics.json       # Profiler: before-optimization metrics
|   +-- bottleneck-report.md        # Profiler: ranked bottleneck findings
|   +-- optimization-plan.md        # Strategist: prioritized optimization plan
|   +-- benchmark-results.json      # Benchmarker: after-optimization metrics
|   +-- review-report.md            # Reviewer: code review findings
+-- explorations/
|   +-- cache-index.json            # Shared explore cache
|   +-- <hash>.md                   # Cached exploration results
+-- wisdom/
|   +-- patterns.md                 # Discovered patterns and conventions
|   +-- shared-memory.json          # Cross-role structured data
+-- discussions/
|   +-- DISCUSS-OPT.md              # Strategy discussion record
|   +-- DISCUSS-REVIEW.md           # Review discussion record

Session Resume

Coordinator supports --resume / --continue for interrupted sessions:

  1. Scan session directory for sessions with status "active" or "paused"
  2. Multiple matches -> AskUserQuestion for selection
  3. Audit TaskList -> reconcile session state <-> task status
  4. Reset in_progress -> pending (interrupted tasks)
  5. Rebuild team and spawn needed workers only
  6. Create missing tasks with correct blockedBy
  7. Kick first executable task -> Phase 4 coordination loop

Shared Resources

Resource Path Usage
Performance Baseline [/artifacts/baseline-metrics.json](/artifacts/baseline-metrics.json) Before-optimization metrics for comparison
Bottleneck Report [/artifacts/bottleneck-report.md](/artifacts/bottleneck-report.md) Profiler output consumed by strategist
Optimization Plan [/artifacts/optimization-plan.md](/artifacts/optimization-plan.md) Strategist output consumed by optimizer
Benchmark Results [/artifacts/benchmark-results.json](/artifacts/benchmark-results.json) Benchmarker output consumed by reviewer

Error Handling

Scenario Resolution
Role spec file not found Error with expected path (role-specs/.md)
Command file not found Fallback to inline execution in coordinator role.md
Subagent spec not found Error with expected path (subagents/-subagent.md)
Fast-advance orphan detected Coordinator resets task to pending on next check
consensus_blocked HIGH Coordinator creates revision task or pauses pipeline
team-worker agent unavailable Error: requires .claude/agents/team-worker.md
Completion action timeout Default to Keep Active
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
Reference in New Issue View Git Blame Copy Permalink