mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-03 15:43:11 +08:00
feat: add multi-mode workflow planning skill with session management and task generation
This commit is contained in:
catlog22
349
.claude/skills/team-perf-opt/SKILL.md
Normal file
349
.claude/skills/team-perf-opt/SKILL.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
name: team-perf-opt
|
||||
description: 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".
|
||||
allowed-tools: 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](roles/coordinator/role.md) | (none) | orchestrator | - |
|
||||
| profiler | [role-specs/profiler.md](role-specs/profiler.md) | PROFILE-* | orchestration | false |
|
||||
| strategist | [role-specs/strategist.md](role-specs/strategist.md) | STRATEGY-* | orchestration | false |
|
||||
| optimizer | [role-specs/optimizer.md](role-specs/optimizer.md) | IMPL-* / FIX-* | code_generation | true |
|
||||
| benchmarker | [role-specs/benchmarker.md](role-specs/benchmarker.md) | BENCH-* | validation | false |
|
||||
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* / QUALITY-* | read_only_analysis | false |
|
||||
|
||||
### Subagent Registry
|
||||
|
||||
| Subagent | Spec | Callable By | Purpose |
|
||||
|----------|------|-------------|---------|
|
||||
| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | profiler, optimizer | Shared codebase exploration for performance-critical code paths |
|
||||
| discuss | [subagents/discuss-subagent.md](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 | [<session>/artifacts/baseline-metrics.json](<session>/artifacts/baseline-metrics.json) | Before-optimization metrics for comparison |
|
||||
| Bottleneck Report | [<session>/artifacts/bottleneck-report.md](<session>/artifacts/bottleneck-report.md) | Profiler output consumed by strategist |
|
||||
| Optimization Plan | [<session>/artifacts/optimization-plan.md](<session>/artifacts/optimization-plan.md) | Strategist output consumed by optimizer |
|
||||
| Benchmark Results | [<session>/artifacts/benchmark-results.json](<session>/artifacts/benchmark-results.json) | Benchmarker output consumed by reviewer |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Role spec file not found | Error with expected path (role-specs/<name>.md) |
|
||||
| Command file not found | Fallback to inline execution in coordinator role.md |
|
||||
| Subagent spec not found | Error with expected path (subagents/<name>-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
Block a user