Skip to content

Commit 5763604

Browse files
author
catlog22
committed
Refactor workflow-lite-planex documentation to standardize phase naming and improve clarity
- Updated phase references in SKILL.md and 01-lite-plan.md to use "LP-Phase" prefix for consistency. - Added critical context isolation note in 01-lite-plan.md to clarify phase invocation rules. - Enhanced execution process descriptions to reflect updated phase naming conventions. Improve error handling in frontend routing - Introduced ChunkErrorBoundary component to handle lazy-loaded chunk load failures. - Wrapped lazy-loaded routes with error boundary and suspense for better user experience. - Created PageSkeleton component for loading states in lazy-loaded routes. Sanitize header values in notification routes - Added regex validation for header values to prevent XSS attacks by allowing only printable ASCII characters. Enhance mobile responsiveness in documentation styles - Updated CSS breakpoints to use custom properties for better maintainability. - Improved layout styles across various components to ensure consistent behavior on mobile devices.
1 parent 980be3d commit 5763604

22 files changed

Lines changed: 1149 additions & 383 deletions

File tree

‎.claude/commands/workflow/analyze-with-file.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -589,7 +589,17 @@ CONSTRAINTS: ${perspective.constraints}
589589
if (findings.length) contextLines.push(`**Key Findings**:\n${findings.map(f => `- ${f}`).join('\n')}`)
590590
}
591591

592-
// 3. Hand off to lite-plan — analyze-with-file COMPLETE, do NOT return to any analyze phase
592+
// 3. ⛔ SESSION TERMINATION — output explicit boundary
593+
console.log(`
594+
---
595+
## ⛔ ANALYZE-WITH-FILE SESSION COMPLETE
596+
All Phase 1-4 of analyze-with-file are FINISHED.
597+
Session: ${sessionId} — concluded at ${new Date().toISOString()}
598+
DO NOT reference any analyze-with-file phase instructions beyond this point.
599+
---
600+
`)
601+
602+
// 4. Hand off to lite-plan — analyze-with-file COMPLETE, do NOT return to any analyze phase
593603
Skill(skill="workflow-lite-planex", args=`"${taskDescription}\n\n${contextLines.join('\n')}"`)
594604
return // ⛔ analyze-with-file terminates here
595605
}

‎.claude/skills/team-perf-opt/SKILL.md‎

Lines changed: 150 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -67,24 +67,42 @@ Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and e
6767

6868
User just provides task description.
6969

70-
**Invocation**: `Skill(skill="team-perf-opt", args="<task-description>")`
70+
**Invocation**:
71+
```bash
72+
Skill(skill="team-perf-opt", args="<task-description>") # auto mode
73+
Skill(skill="team-perf-opt", args="--parallel-mode=fan-out <task-description>") # force fan-out
74+
Skill(skill="team-perf-opt", args='--parallel-mode=independent "target1" "target2"') # independent
75+
Skill(skill="team-perf-opt", args="--max-branches=3 <task-description>") # limit branches
76+
```
77+
78+
**Parallel Modes**:
79+
80+
| Mode | Description | When to Use |
81+
|------|-------------|------------|
82+
| `auto` (default) | count <= 2 -> single, count >= 3 -> fan-out | General optimization requests |
83+
| `single` | Linear pipeline, no branching | Simple or tightly coupled optimizations |
84+
| `fan-out` | Shared PROFILE+STRATEGY, then N parallel IMPL->BENCH+REVIEW branches | Multiple independent bottlenecks |
85+
| `independent` | M fully independent pipelines from profiling to review | Separate optimization targets |
7186

7287
**Lifecycle**:
7388
```
74-
User provides task description
75-
-> coordinator Phase 1-3: Requirement clarification -> TeamCreate -> Create task chain
89+
User provides task description + optional --parallel-mode / --max-branches
90+
-> coordinator Phase 1-3: Parse flags -> TeamCreate -> Create task chain (mode-aware)
7691
-> coordinator Phase 4: spawn first batch workers (background) -> STOP
7792
-> Worker (team-worker agent) executes -> SendMessage callback -> coordinator advances
78-
-> Loop until pipeline complete -> Phase 5 report + completion action
93+
-> [auto/fan-out] CP-2.5: Strategy complete -> create N branch tasks -> spawn all IMPL-B* in parallel
94+
-> [independent] All pipelines run in parallel from the start
95+
-> Per-branch/pipeline fix cycles run independently
96+
-> All branches/pipelines complete -> AGGREGATE -> Phase 5 report + completion action
7997
```
8098

8199
**User Commands** (wake paused coordinator):
82100

83101
| Command | Action |
84102
|---------|--------|
85-
| `check` / `status` | Output execution status graph, no advancement |
103+
| `check` / `status` | Output execution status graph (branch-grouped), no advancement |
86104
| `resume` / `continue` | Check worker states, advance next step |
87-
| `revise <TASK-ID> [feedback]` | Create revision task + cascade downstream |
105+
| `revise <TASK-ID> [feedback]` | Create revision task + cascade downstream (scoped to branch) |
88106
| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
89107
| `recheck` | Re-run quality check |
90108
| `improve [dimension]` | Auto-improve weakest dimension |
@@ -147,28 +165,52 @@ Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Pha
147165

148166
## Pipeline Definitions
149167

150-
### Pipeline Diagram
168+
### Pipeline Diagrams
151169

170+
**Single Mode** (linear, backward compatible):
152171
```
153-
Pipeline: Linear with Review-Fix Cycle
172+
Pipeline: Single (Linear with Review-Fix Cycle)
154173
=====================================================================
155174
Stage 1 Stage 2 Stage 3 Stage 4
156-
(W:1) (W:2) (W:3) (W:4)
157-
+-----------+
158-
PROFILE-001 --> STRATEGY-001 --> IMPL-001 --> | BENCH-001 |
159-
[profiler] [strategist] [optimizer] | [bench] |
160-
^ +-----------+
161-
| |
162-
| +-----------+
163-
+<--FIX--->| REVIEW-001|
164-
| | [reviewer]|
165-
| +-----------+
166-
| |
167-
(max 3 iterations) v
175+
PROFILE-001 --> STRATEGY-001 --> IMPL-001 --> BENCH-001
176+
[profiler] [strategist] [optimizer] [benchmarker]
177+
^ |
178+
+<--FIX-001---->+
179+
| REVIEW-001
180+
+<--------> [reviewer]
181+
(max 3 iterations) |
168182
COMPLETE
169183
=====================================================================
170184
```
171185

186+
**Fan-out Mode** (shared stages 1-2, parallel branches 3-4):
187+
```
188+
Pipeline: Fan-out (N parallel optimization branches)
189+
=====================================================================
190+
Stage 1 Stage 2 CP-2.5 Stage 3+4 (per branch)
191+
(branch creation)
192+
PROFILE-001 --> STRATEGY-001 --+-> IMPL-B01 --> BENCH-B01 + REVIEW-B01 (fix cycle)
193+
[profiler] [strategist] | [optimizer] [bench] [reviewer]
194+
+-> IMPL-B02 --> BENCH-B02 + REVIEW-B02 (fix cycle)
195+
| [optimizer] [bench] [reviewer]
196+
+-> IMPL-B0N --> BENCH-B0N + REVIEW-B0N (fix cycle)
197+
|
198+
AGGREGATE -> Phase 5
199+
=====================================================================
200+
```
201+
202+
**Independent Mode** (M fully independent pipelines):
203+
```
204+
Pipeline: Independent (M complete pipelines)
205+
=====================================================================
206+
Pipeline A: PROFILE-A01 --> STRATEGY-A01 --> IMPL-A01 --> BENCH-A01 + REVIEW-A01
207+
Pipeline B: PROFILE-B01 --> STRATEGY-B01 --> IMPL-B01 --> BENCH-B01 + REVIEW-B01
208+
Pipeline C: PROFILE-C01 --> STRATEGY-C01 --> IMPL-C01 --> BENCH-C01 + REVIEW-C01
209+
|
210+
AGGREGATE -> Phase 5
211+
=====================================================================
212+
```
213+
172214
### Cadence Control
173215

174216
**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
@@ -247,11 +289,14 @@ Beat View: Performance Optimization Pipeline
247289
|------------|---------|----------|----------|
248290
| CP-1 | PROFILE-001 complete | After Stage 1 | User reviews bottleneck report, can refine scope |
249291
| CP-2 | STRATEGY-001 complete | After Stage 2 | User reviews optimization plan, can adjust priorities |
250-
| CP-3 | REVIEW/BENCH fail | Stage 4 | Auto-create FIX task, re-enter Stage 3 (max 3x) |
251-
| CP-4 | All tasks complete | Phase 5 | Interactive completion action |
292+
| CP-2.5 | STRATEGY-001 complete (auto/fan-out) | After Stage 2 | Auto-create N branch tasks from optimization plan, spawn all IMPL-B* in parallel |
293+
| CP-3 | REVIEW/BENCH fail | Stage 4 (per-branch) | Auto-create FIX task for that branch only (max 3x per branch) |
294+
| CP-4 | All tasks/branches complete | Phase 5 | Aggregate results, interactive completion action |
252295

253296
### Task Metadata Registry
254297

298+
**Single mode** (backward compatible):
299+
255300
| Task ID | Role | Phase | Dependencies | Description |
256301
|---------|------|-------|-------------|-------------|
257302
| PROFILE-001 | profiler | Stage 1 | (none) | Profile application, identify bottlenecks |
@@ -261,6 +306,38 @@ Beat View: Performance Optimization Pipeline
261306
| REVIEW-001 | reviewer | Stage 4 | IMPL-001 | Review optimization code for correctness |
262307
| FIX-001 | optimizer | Stage 3 (cycle) | REVIEW-001 or BENCH-001 | Fix issues found in review/benchmark |
263308

309+
**Fan-out mode** (branch tasks created at CP-2.5):
310+
311+
| Task ID | Role | Phase | Dependencies | Description |
312+
|---------|------|-------|-------------|-------------|
313+
| PROFILE-001 | profiler | Stage 1 (shared) | (none) | Profile application |
314+
| STRATEGY-001 | strategist | Stage 2 (shared) | PROFILE-001 | Design plan with discrete OPT-IDs |
315+
| IMPL-B{NN} | optimizer | Stage 3 (branch) | STRATEGY-001 | Implement OPT-{NNN} only |
316+
| BENCH-B{NN} | benchmarker | Stage 4 (branch) | IMPL-B{NN} | Benchmark branch B{NN} |
317+
| REVIEW-B{NN} | reviewer | Stage 4 (branch) | IMPL-B{NN} | Review branch B{NN} |
318+
| FIX-B{NN}-{cycle} | optimizer | Fix (branch) | (none) | Fix issues in branch B{NN} |
319+
| BENCH-B{NN}-R{cycle} | benchmarker | Retry (branch) | FIX-B{NN}-{cycle} | Re-benchmark after fix |
320+
| REVIEW-B{NN}-R{cycle} | reviewer | Retry (branch) | FIX-B{NN}-{cycle} | Re-review after fix |
321+
322+
**Independent mode**:
323+
324+
| Task ID | Role | Phase | Dependencies | Description |
325+
|---------|------|-------|-------------|-------------|
326+
| PROFILE-{P}01 | profiler | Stage 1 | (none) | Profile for pipeline {P} target |
327+
| STRATEGY-{P}01 | strategist | Stage 2 | PROFILE-{P}01 | Strategy for pipeline {P} |
328+
| IMPL-{P}01 | optimizer | Stage 3 | STRATEGY-{P}01 | Implement pipeline {P} optimizations |
329+
| BENCH-{P}01 | benchmarker | Stage 4 | IMPL-{P}01 | Benchmark pipeline {P} |
330+
| REVIEW-{P}01 | reviewer | Stage 4 | IMPL-{P}01 | Review pipeline {P} |
331+
| FIX-{P}01-{cycle} | optimizer | Fix | (none) | Fix issues in pipeline {P} |
332+
333+
### Task Naming Rules
334+
335+
| Mode | Stage 3 | Stage 4 | Fix | Retry |
336+
|------|---------|---------|-----|-------|
337+
| Single | IMPL-001 | BENCH-001, REVIEW-001 | FIX-001 | BENCH-001-R1, REVIEW-001-R1 |
338+
| Fan-out | IMPL-B01 | BENCH-B01, REVIEW-B01 | FIX-B01-1 | BENCH-B01-R1, REVIEW-B01-R1 |
339+
| Independent | IMPL-A01 | BENCH-A01, REVIEW-A01 | FIX-A01-1 | BENCH-A01-R1, REVIEW-A01-R1 |
340+
264341
---
265342

266343
## Completion Action
@@ -292,9 +369,10 @@ AskUserQuestion({
292369

293370
## Session Directory
294371

372+
**Single mode**:
295373
```
296374
.workflow/<session-id>/
297-
+-- session.json # Session metadata + status
375+
+-- session.json # Session metadata + status + parallel_mode
298376
+-- artifacts/
299377
| +-- baseline-metrics.json # Profiler: before-optimization metrics
300378
| +-- bottleneck-report.md # Profiler: ranked bottleneck findings
@@ -312,6 +390,47 @@ AskUserQuestion({
312390
| +-- DISCUSS-REVIEW.md # Review discussion record
313391
```
314392

393+
**Fan-out mode** (adds branches/ directory):
394+
```
395+
.workflow/<session-id>/
396+
+-- session.json # + parallel_mode, branches, fix_cycles
397+
+-- artifacts/
398+
| +-- baseline-metrics.json # Shared baseline (all branches use this)
399+
| +-- bottleneck-report.md # Shared bottleneck report
400+
| +-- optimization-plan.md # Shared plan with discrete OPT-IDs
401+
| +-- aggregate-results.json # Aggregated results from all branches
402+
| +-- branches/
403+
| +-- B01/
404+
| | +-- optimization-detail.md # Extracted OPT-001 detail
405+
| | +-- benchmark-results.json # Branch B01 benchmark
406+
| | +-- review-report.md # Branch B01 review
407+
| +-- B02/
408+
| | +-- optimization-detail.md
409+
| | +-- benchmark-results.json
410+
| | +-- review-report.md
411+
| +-- B0N/
412+
+-- explorations/ wisdom/ discussions/ # Same as single
413+
```
414+
415+
**Independent mode** (adds pipelines/ directory):
416+
```
417+
.workflow/<session-id>/
418+
+-- session.json # + parallel_mode, independent_targets, fix_cycles
419+
+-- artifacts/
420+
| +-- aggregate-results.json # Aggregated results from all pipelines
421+
| +-- pipelines/
422+
| +-- A/
423+
| | +-- baseline-metrics.json
424+
| | +-- bottleneck-report.md
425+
| | +-- optimization-plan.md
426+
| | +-- benchmark-results.json
427+
| | +-- review-report.md
428+
| +-- B/
429+
| +-- baseline-metrics.json
430+
| +-- ...
431+
+-- explorations/ wisdom/ discussions/ # Same as single
432+
```
433+
315434
## Session Resume
316435

317436
Coordinator supports `--resume` / `--continue` for interrupted sessions:
@@ -345,5 +464,11 @@ Coordinator supports `--resume` / `--continue` for interrupted sessions:
345464
| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md |
346465
| Completion action timeout | Default to Keep Active |
347466
| Profiling tool not available | Fallback to static analysis methods |
348-
| Benchmark regression detected | Auto-create FIX task with regression details |
349-
| Review-fix cycle exceeds 3 iterations | Escalate to user with summary of remaining issues |
467+
| Benchmark regression detected | Auto-create FIX task with regression details (scoped to branch/pipeline) |
468+
| Review-fix cycle exceeds 3 iterations | Escalate to user with summary of remaining issues (per-branch/pipeline scope) |
469+
| One branch IMPL fails | Mark that branch failed, other branches continue to completion |
470+
| Branch scope overlap detected | Strategist constrains non-overlapping target files; IMPL logs warning on detection |
471+
| Shared-memory concurrent writes | Each worker writes only its own namespace key (e.g., `optimizer.B01`) |
472+
| Branch fix cycle >= 3 | Escalate only that branch to user, other branches continue independently |
473+
| max_branches exceeded | Coordinator truncates to top N optimizations by priority at CP-2.5 |
474+
| Independent pipeline partial failure | Failed pipeline marked, others continue; aggregate reports partial results |

‎.claude/skills/team-perf-opt/role-specs/benchmarker.md‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,30 @@ Run benchmarks comparing before/after optimization metrics. Validate that improv
1515

1616
| Input | Source | Required |
1717
|-------|--------|----------|
18-
| Baseline metrics | <session>/artifacts/baseline-metrics.json | Yes |
19-
| Optimization plan | <session>/artifacts/optimization-plan.md | Yes |
18+
| Baseline metrics | <session>/artifacts/baseline-metrics.json (shared) | Yes |
19+
| Optimization plan / detail | Varies by mode (see below) | Yes |
2020
| shared-memory.json | <session>/wisdom/shared-memory.json | Yes |
2121

2222
1. Extract session path from task description
23-
2. Read baseline metrics -- extract pre-optimization performance numbers
24-
3. Read optimization plan -- extract success criteria and target thresholds
25-
4. Load shared-memory.json for project type and optimization scope
26-
5. Detect available benchmark tools from project:
23+
2. **Detect branch/pipeline context** from task description:
24+
25+
| Task Description Field | Value | Context |
26+
|----------------------|-------|---------|
27+
| `BranchId: B{NN}` | Present | Fan-out branch -- benchmark only this branch's metrics |
28+
| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline |
29+
| Neither present | - | Single mode -- full benchmark |
30+
31+
3. **Load baseline metrics**:
32+
- Single / Fan-out: Read `<session>/artifacts/baseline-metrics.json` (shared baseline)
33+
- Independent: Read `<session>/artifacts/pipelines/{P}/baseline-metrics.json`
34+
35+
4. **Load optimization context**:
36+
- Single: Read `<session>/artifacts/optimization-plan.md` -- all success criteria
37+
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md` -- only this branch's criteria
38+
- Independent: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md`
39+
40+
5. Load shared-memory.json for project type and optimization scope
41+
6. Detect available benchmark tools from project:
2742

2843
| Signal | Benchmark Tool | Method |
2944
|--------|---------------|--------|
@@ -34,7 +49,10 @@ Run benchmarks comparing before/after optimization metrics. Validate that improv
3449
| Makefile with bench target | Custom benchmarks | make bench |
3550
| No tooling detected | Manual measurement | Timed execution via Bash |
3651

37-
6. Get changed files scope from shared-memory (optimizer namespace)
52+
7. Get changed files scope from shared-memory:
53+
- Single: `optimizer` namespace
54+
- Fan-out: `optimizer.B{NN}` namespace
55+
- Independent: `optimizer.{P}` namespace
3856

3957
## Phase 3: Benchmark Execution
4058

@@ -60,6 +78,10 @@ Run benchmarks matching detected project type:
6078
- Collect post-optimization metrics matching baseline format
6179
- Calculate improvement percentages per metric
6280

81+
**Branch-scoped benchmarking** (fan-out mode):
82+
- Only benchmark metrics relevant to this branch's optimization (from optimization-detail.md)
83+
- Still check for regressions across all metrics (not just branch-specific ones)
84+
6385
## Phase 4: Result Analysis
6486

6587
Compare against baseline and plan criteria:
@@ -73,13 +95,16 @@ Compare against baseline and plan criteria:
7395
| Regression detected | Any unrelated metric degrades > 5% | FAIL -> fix_required |
7496
| Plan criteria not met | Any criterion not satisfied | FAIL -> fix_required |
7597

76-
1. Write benchmark results to `<session>/artifacts/benchmark-results.json`:
77-
- Per-metric: name, baseline value, current value, improvement %, verdict
78-
- Overall verdict: PASS / WARN / FAIL
79-
- Regression details (if any)
98+
1. Write benchmark results to output path:
99+
- Single: `<session>/artifacts/benchmark-results.json`
100+
- Fan-out: `<session>/artifacts/branches/B{NN}/benchmark-results.json`
101+
- Independent: `<session>/artifacts/pipelines/{P}/benchmark-results.json`
102+
- Content: Per-metric: name, baseline value, current value, improvement %, verdict; Overall verdict: PASS / WARN / FAIL; Regression details (if any)
80103

81-
2. Update `<session>/wisdom/shared-memory.json` under `benchmarker` namespace:
82-
- Read existing -> merge `{ "benchmarker": { verdict, improvements, regressions } }` -> write back
104+
2. Update `<session>/wisdom/shared-memory.json` under scoped namespace:
105+
- Single: merge `{ "benchmarker": { verdict, improvements, regressions } }`
106+
- Fan-out: merge `{ "benchmarker.B{NN}": { verdict, improvements, regressions } }`
107+
- Independent: merge `{ "benchmarker.{P}": { verdict, improvements, regressions } }`
83108

84109
3. If verdict is FAIL, include detailed feedback in message for FIX task creation:
85110
- Which metrics failed, by how much, suggested investigation areas

0 commit comments

Comments
 (0)