mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-21 19:08:17 +08:00
fix: resolve team worker task discovery failures and clean up legacy role-specs
- Remove owner name exact-match filter from team-worker.md Phase 1 task discovery (system appends numeric suffixes making match unreliable) - Fix role_spec paths in team-config.json for perf-opt, arch-opt, ux-improve (role-specs/<role>.md → roles/<role>/role.md) - Fix stale role-specs path in perf-opt monitor.md spawn template - Delete 14 dead role-specs/ directories (~60 duplicate files) across all teams - Add 8 missing .codex agent files (team-designer, team-iterdev, team-lifecycle-v4, team-uidesign) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -99,8 +99,8 @@ Execute on every loop iteration:
|
|||||||
- Subject starts with this role's `prefix` + `-` (e.g., `DRAFT-`, `IMPL-`)
|
- Subject starts with this role's `prefix` + `-` (e.g., `DRAFT-`, `IMPL-`)
|
||||||
- Status is `pending`
|
- Status is `pending`
|
||||||
- `blockedBy` list is empty (all dependencies resolved)
|
- `blockedBy` list is empty (all dependencies resolved)
|
||||||
- **Owner matches** `agent_name` from prompt (e.g., task owner "explorer-1" matches agent_name "explorer-1"). This prevents parallel workers from claiming each other's tasks.
|
|
||||||
- If role has `additional_prefixes` (e.g., reviewer handles REVIEW-* + QUALITY-* + IMPROVE-*), check all prefixes
|
- If role has `additional_prefixes` (e.g., reviewer handles REVIEW-* + QUALITY-* + IMPROVE-*), check all prefixes
|
||||||
|
- **NOTE**: Do NOT filter by owner name. The system appends numeric suffixes to agent names (e.g., `profiler` → `profiler-4`), making exact owner matching unreliable. Prefix-based filtering is sufficient to prevent cross-role task claiming.
|
||||||
3. **No matching tasks?**
|
3. **No matching tasks?**
|
||||||
- If first iteration → report idle, SendMessage "No tasks found for [role]", STOP
|
- If first iteration → report idle, SendMessage "No tasks found for [role]", STOP
|
||||||
- If inner loop continuation → proceed to Phase 5-F (all done)
|
- If inner loop continuation → proceed to Phase 5-F (all done)
|
||||||
|
|||||||
@@ -1,80 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: ANALYZE
|
|
||||||
inner_loop: false
|
|
||||||
cli_tools: [explore]
|
|
||||||
message_types:
|
|
||||||
success: analyze_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Architecture Analyzer
|
|
||||||
|
|
||||||
Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture 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>/wisdom/.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 | Analysis Focus |
|
|
||||||
|-------------|-------------|----------------|
|
|
||||||
| package.json + React/Vue/Angular | Frontend | Component tree, prop drilling, state management, barrel exports |
|
|
||||||
| package.json + Express/Fastify/NestJS | Backend Node | Service layer boundaries, middleware chains, DB access patterns |
|
|
||||||
| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | Module boundaries, trait/interface usage, dependency injection |
|
|
||||||
| Mixed framework markers | Full-stack / Monorepo | Cross-package dependencies, shared types, API contracts |
|
|
||||||
| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering |
|
|
||||||
| No detection | Generic | All architecture dimensions |
|
|
||||||
|
|
||||||
3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope
|
|
||||||
4. Detect available analysis tools (linters, dependency analyzers, build tools)
|
|
||||||
|
|
||||||
## Phase 3: Architecture Analysis
|
|
||||||
|
|
||||||
Execute analysis based on detected project type:
|
|
||||||
|
|
||||||
**Dependency analysis**:
|
|
||||||
- Build import/require graph across modules
|
|
||||||
- Detect circular dependencies (direct and transitive cycles)
|
|
||||||
- Identify layering violations (e.g., UI importing from data layer, utils importing from domain)
|
|
||||||
- Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled)
|
|
||||||
|
|
||||||
**Structural analysis**:
|
|
||||||
- Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities)
|
|
||||||
- Calculate coupling metrics (afferent/efferent coupling per module)
|
|
||||||
- Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods)
|
|
||||||
- Detect code duplication (repeated logic blocks, copy-paste patterns)
|
|
||||||
- Identify missing abstractions (repeated conditionals, switch-on-type patterns)
|
|
||||||
|
|
||||||
**API surface analysis**:
|
|
||||||
- Count exported symbols per module (export bloat detection)
|
|
||||||
- Identify dead exports (exported but never imported elsewhere)
|
|
||||||
- Detect dead code (unreachable functions, unused variables, orphan files)
|
|
||||||
- Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling)
|
|
||||||
|
|
||||||
**All project types**:
|
|
||||||
- Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution)
|
|
||||||
- Rank top 3-7 architecture issues by severity (Critical / High / Medium)
|
|
||||||
- Record evidence: file paths, line numbers, measured values
|
|
||||||
|
|
||||||
## Phase 4: Report Generation
|
|
||||||
|
|
||||||
1. Write architecture baseline to `<session>/artifacts/architecture-baseline.json`:
|
|
||||||
- Module count, dependency count, cycle count, average coupling, average cohesion
|
|
||||||
- God Class candidates with LOC and method count
|
|
||||||
- Dead code file count, dead export count
|
|
||||||
- Timestamp and project type details
|
|
||||||
|
|
||||||
2. Write architecture report to `<session>/artifacts/architecture-report.md`:
|
|
||||||
- Ranked list of architecture issues with severity, location (file:line or module), measured impact
|
|
||||||
- Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT
|
|
||||||
- Evidence summary per issue
|
|
||||||
- Detected project type and analysis methods used
|
|
||||||
|
|
||||||
3. Update `<session>/wisdom/.msg/meta.json` under `analyzer` namespace:
|
|
||||||
- Read existing -> merge `{ "analyzer": { project_type, issue_count, top_issue, scope, categories } }` -> write back
|
|
||||||
@@ -1,118 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: DESIGN
|
|
||||||
inner_loop: false
|
|
||||||
discuss_rounds: [DISCUSS-REFACTOR]
|
|
||||||
cli_tools: [discuss]
|
|
||||||
message_types:
|
|
||||||
success: design_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Refactoring Designer
|
|
||||||
|
|
||||||
Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments.
|
|
||||||
|
|
||||||
## Phase 2: Analysis Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Architecture report | <session>/artifacts/architecture-report.md | Yes |
|
|
||||||
| Architecture baseline | <session>/artifacts/architecture-baseline.json | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
| Wisdom files | <session>/wisdom/patterns.md | No |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read architecture report -- extract ranked issue list with severities and categories
|
|
||||||
3. Read architecture baseline -- extract current structural metrics
|
|
||||||
4. Load .msg/meta.json for analyzer findings (project_type, scope)
|
|
||||||
5. Assess overall refactoring complexity:
|
|
||||||
|
|
||||||
| Issue Count | Severity Mix | Complexity |
|
|
||||||
|-------------|-------------|------------|
|
|
||||||
| 1-2 | All Medium | Low |
|
|
||||||
| 2-3 | Mix of High/Medium | Medium |
|
|
||||||
| 3+ or any Critical | Any Critical present | High |
|
|
||||||
|
|
||||||
## Phase 3: Strategy Formulation
|
|
||||||
|
|
||||||
For each architecture issue, select refactoring approach by type:
|
|
||||||
|
|
||||||
| Issue Type | Strategies | Risk Level |
|
|
||||||
|------------|-----------|------------|
|
|
||||||
| Circular dependency | Interface extraction, dependency inversion, mediator pattern | High |
|
|
||||||
| God Class/Module | SRP decomposition, extract class/module, delegate pattern | High |
|
|
||||||
| Layering violation | Move to correct layer, introduce Facade, add anti-corruption layer | Medium |
|
|
||||||
| Code duplication | Extract shared utility/base class, template method pattern | Low |
|
|
||||||
| High coupling | Introduce interface/abstraction, dependency injection, event-driven | Medium |
|
|
||||||
| API bloat / dead exports | Privatize internals, re-export only public API, barrel file cleanup | Low |
|
|
||||||
| Dead code | Safe removal with reference verification | Low |
|
|
||||||
| Missing abstraction | Extract interface/type, introduce strategy/factory pattern | Medium |
|
|
||||||
|
|
||||||
Prioritize refactorings by impact/effort ratio:
|
|
||||||
|
|
||||||
| Priority | Criteria |
|
|
||||||
|----------|----------|
|
|
||||||
| P0 (Critical) | High impact + Low effort -- quick wins (dead code removal, simple moves) |
|
|
||||||
| P1 (High) | High impact + Medium effort (cycle breaking, layer fixes) |
|
|
||||||
| P2 (Medium) | Medium impact + Low effort (duplication extraction) |
|
|
||||||
| P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) |
|
|
||||||
|
|
||||||
If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.
|
|
||||||
|
|
||||||
Define measurable success criteria per refactoring (target metric improvement or structural change).
|
|
||||||
|
|
||||||
## Phase 4: Plan Output
|
|
||||||
|
|
||||||
1. Write refactoring plan to `<session>/artifacts/refactoring-plan.md`:
|
|
||||||
|
|
||||||
Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
### REFACTOR-001: <title>
|
|
||||||
- Priority: P0
|
|
||||||
- Target issue: <issue from report>
|
|
||||||
- Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT>
|
|
||||||
- Target files: <file-list>
|
|
||||||
- Strategy: <selected approach>
|
|
||||||
- Expected improvement: <metric> by <description>
|
|
||||||
- Risk level: <Low/Medium/High>
|
|
||||||
- Success criteria: <specific structural change to verify>
|
|
||||||
- Implementation guidance:
|
|
||||||
1. <step 1>
|
|
||||||
2. <step 2>
|
|
||||||
3. <step 3>
|
|
||||||
|
|
||||||
### REFACTOR-002: <title>
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
Requirements:
|
|
||||||
- Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...)
|
|
||||||
- Each refactoring must be **non-overlapping** in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution)
|
|
||||||
- Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others
|
|
||||||
|
|
||||||
2. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
|
|
||||||
- Read existing -> merge -> write back:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"designer": {
|
|
||||||
"complexity": "<Low|Medium|High>",
|
|
||||||
"refactoring_count": 4,
|
|
||||||
"priorities": ["P0", "P0", "P1", "P2"],
|
|
||||||
"discuss_used": false,
|
|
||||||
"refactorings": [
|
|
||||||
{
|
|
||||||
"id": "REFACTOR-001",
|
|
||||||
"title": "<title>",
|
|
||||||
"issue_type": "<CYCLE|COUPLING|...>",
|
|
||||||
"priority": "P0",
|
|
||||||
"target_files": ["src/a.ts", "src/b.ts"],
|
|
||||||
"expected_improvement": "<metric> by <description>",
|
|
||||||
"success_criteria": "<threshold>"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
3. If DISCUSS-REFACTOR was triggered, record discussion summary in `<session>/discussions/DISCUSS-REFACTOR.md`
|
|
||||||
@@ -1,106 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: REFACTOR
|
|
||||||
inner_loop: true
|
|
||||||
additional_prefixes: [FIX]
|
|
||||||
cli_tools: [explore]
|
|
||||||
message_types:
|
|
||||||
success: refactor_complete
|
|
||||||
error: error
|
|
||||||
fix: fix_required
|
|
||||||
---
|
|
||||||
|
|
||||||
# Code Refactorer
|
|
||||||
|
|
||||||
Implement architecture refactoring changes following the design plan. For FIX tasks, apply targeted corrections based on review/validation feedback.
|
|
||||||
|
|
||||||
## Modes
|
|
||||||
|
|
||||||
| Mode | Task Prefix | Trigger | Focus |
|
|
||||||
|------|-------------|---------|-------|
|
|
||||||
| Refactor | REFACTOR | Design plan ready | Apply refactorings per plan priority |
|
|
||||||
| Fix | FIX | Review/validation feedback | Targeted fixes for identified issues |
|
|
||||||
|
|
||||||
## Phase 2: Plan & Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Refactoring plan | <session>/artifacts/refactoring-plan.md | Yes (REFACTOR, no branch) |
|
|
||||||
| Branch refactoring detail | <session>/artifacts/branches/B{NN}/refactoring-detail.md | Yes (REFACTOR with branch) |
|
|
||||||
| Pipeline refactoring plan | <session>/artifacts/pipelines/{P}/refactoring-plan.md | Yes (REFACTOR with pipeline) |
|
|
||||||
| Review/validation feedback | From task description | Yes (FIX) |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
| Wisdom files | <session>/wisdom/patterns.md | No |
|
|
||||||
| Context accumulator | From prior REFACTOR/FIX tasks | Yes (inner loop) |
|
|
||||||
|
|
||||||
1. Extract session path and task mode (REFACTOR 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 refactoring detail |
|
|
||||||
| `PipelineId: {P}` | Present | Independent pipeline -- load pipeline-scoped plan |
|
|
||||||
| Neither present | - | Single mode -- load full refactoring plan |
|
|
||||||
|
|
||||||
3. **Load refactoring context by mode**:
|
|
||||||
- **Single mode (no branch)**: Read `<session>/artifacts/refactoring-plan.md` -- extract ALL priority-ordered changes
|
|
||||||
- **Fan-out branch**: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- extract ONLY this branch's refactoring (single REFACTOR-ID)
|
|
||||||
- **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md` -- extract this pipeline's plan
|
|
||||||
|
|
||||||
4. For FIX: parse review/validation feedback for specific issues to address
|
|
||||||
5. Use `explore` CLI tool to load implementation context for target files
|
|
||||||
6. For inner loop (single mode only): load context_accumulator from prior REFACTOR/FIX tasks
|
|
||||||
|
|
||||||
**Meta.json namespace**:
|
|
||||||
- Single: write to `refactorer` namespace
|
|
||||||
- Fan-out: write to `refactorer.B{NN}` namespace
|
|
||||||
- Independent: write to `refactorer.{P}` namespace
|
|
||||||
|
|
||||||
## Phase 3: Code Implementation
|
|
||||||
|
|
||||||
Implementation backend selection:
|
|
||||||
|
|
||||||
| Backend | Condition | Method |
|
|
||||||
|---------|-----------|--------|
|
|
||||||
| CLI | Multi-file refactoring with clear plan | ccw cli --tool gemini --mode write |
|
|
||||||
| Direct | Single-file changes or targeted fixes | Inline Edit/Write tools |
|
|
||||||
|
|
||||||
For REFACTOR tasks:
|
|
||||||
- **Single mode**: Apply refactorings in plan priority order (P0 first, then P1, etc.)
|
|
||||||
- **Fan-out branch**: Apply ONLY this branch's single refactoring (from refactoring-detail.md)
|
|
||||||
- **Independent pipeline**: Apply this pipeline's refactorings in priority order
|
|
||||||
- Follow implementation guidance from plan (target files, patterns)
|
|
||||||
- **Preserve existing behavior -- refactoring must not change functionality**
|
|
||||||
- **Update ALL import references** when moving/renaming modules
|
|
||||||
- **Update ALL test files** that reference moved/renamed symbols
|
|
||||||
|
|
||||||
For FIX tasks:
|
|
||||||
- Read specific issues from review/validation feedback
|
|
||||||
- Apply targeted corrections to flagged code locations
|
|
||||||
- Verify the fix addresses the exact concern raised
|
|
||||||
|
|
||||||
General rules:
|
|
||||||
- Make minimal, focused changes per refactoring
|
|
||||||
- Add comments only where refactoring logic is non-obvious
|
|
||||||
- Preserve existing code style and conventions
|
|
||||||
- Verify no dangling imports after module moves
|
|
||||||
|
|
||||||
## 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 |
|
|
||||||
| Import integrity | Verify no broken imports after moves | All imports resolve |
|
|
||||||
| Acceptance | Match refactoring plan success criteria | All structural changes applied |
|
|
||||||
| 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 REFACTOR/FIX task (single/inner-loop mode only):
|
|
||||||
- Files modified, refactorings 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}/`
|
|
||||||
@@ -1,116 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: REVIEW
|
|
||||||
inner_loop: false
|
|
||||||
additional_prefixes: [QUALITY]
|
|
||||||
discuss_rounds: [DISCUSS-REVIEW]
|
|
||||||
cli_tools: [discuss]
|
|
||||||
message_types:
|
|
||||||
success: review_complete
|
|
||||||
error: error
|
|
||||||
fix: fix_required
|
|
||||||
---
|
|
||||||
|
|
||||||
# Architecture Reviewer
|
|
||||||
|
|
||||||
Review refactoring code changes for correctness, pattern consistency, completeness, migration safety, and adherence to best practices. Provide structured verdicts with actionable feedback.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Refactoring code changes | From REFACTOR task artifacts / git diff | Yes |
|
|
||||||
| Refactoring plan / detail | Varies by mode (see below) | Yes |
|
|
||||||
| Validation results | Varies by mode (see below) | No |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. **Detect branch/pipeline context** from task description:
|
|
||||||
|
|
||||||
| Task Description Field | Value | Context |
|
|
||||||
|----------------------|-------|---------
|
|
||||||
| `BranchId: B{NN}` | Present | Fan-out branch -- review only this branch's changes |
|
|
||||||
| `PipelineId: {P}` | Present | Independent pipeline -- review pipeline-scoped changes |
|
|
||||||
| Neither present | - | Single mode -- review all refactoring changes |
|
|
||||||
|
|
||||||
3. **Load refactoring context by mode**:
|
|
||||||
- Single: Read `<session>/artifacts/refactoring-plan.md`
|
|
||||||
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md`
|
|
||||||
- Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md`
|
|
||||||
|
|
||||||
4. Load .msg/meta.json for scoped refactorer namespace:
|
|
||||||
- Single: `refactorer` namespace
|
|
||||||
- Fan-out: `refactorer.B{NN}` namespace
|
|
||||||
- Independent: `refactorer.{P}` namespace
|
|
||||||
|
|
||||||
5. Identify changed files from refactorer context -- read ONLY files modified by this branch/pipeline
|
|
||||||
6. If validation results available, read from scoped path:
|
|
||||||
- Single: `<session>/artifacts/validation-results.json`
|
|
||||||
- Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json`
|
|
||||||
- Independent: `<session>/artifacts/pipelines/{P}/validation-results.json`
|
|
||||||
|
|
||||||
## Phase 3: Multi-Dimension Review
|
|
||||||
|
|
||||||
Analyze refactoring changes across five dimensions:
|
|
||||||
|
|
||||||
| Dimension | Focus | Severity |
|
|
||||||
|-----------|-------|----------|
|
|
||||||
| Correctness | No behavior changes, all references updated, no dangling imports | Critical |
|
|
||||||
| Pattern consistency | Follows existing patterns, naming consistent, language-idiomatic | High |
|
|
||||||
| Completeness | All related code updated (imports, tests, config, documentation) | High |
|
|
||||||
| Migration safety | No dangling references, backward compatible, public API preserved | Critical |
|
|
||||||
| Best practices | Clean Architecture / SOLID principles, appropriate abstraction level | Medium |
|
|
||||||
|
|
||||||
Per-dimension review process:
|
|
||||||
- Scan modified files for patterns matching each dimension
|
|
||||||
- Record findings with severity (Critical / High / Medium / Low)
|
|
||||||
- Include specific file:line references and suggested fixes
|
|
||||||
|
|
||||||
**Correctness checks**:
|
|
||||||
- Verify moved code preserves original behavior (no logic changes mixed with structural changes)
|
|
||||||
- Check all import/require statements updated to new paths
|
|
||||||
- Verify no orphaned files left behind after moves
|
|
||||||
|
|
||||||
**Pattern consistency checks**:
|
|
||||||
- New module names follow existing naming conventions
|
|
||||||
- Extracted interfaces/classes use consistent patterns with existing codebase
|
|
||||||
- File organization matches project conventions (e.g., index files, barrel exports)
|
|
||||||
|
|
||||||
**Completeness checks**:
|
|
||||||
- All test files updated for moved/renamed modules
|
|
||||||
- Configuration files updated if needed (e.g., path aliases, build configs)
|
|
||||||
- Type definitions updated for extracted interfaces
|
|
||||||
|
|
||||||
**Migration safety checks**:
|
|
||||||
- Public API surface unchanged (same exports available to consumers)
|
|
||||||
- No circular dependencies introduced by the refactoring
|
|
||||||
- Re-exports in place if module paths changed for backward compatibility
|
|
||||||
|
|
||||||
**Best practices checks**:
|
|
||||||
- Extracted modules have clear single responsibility
|
|
||||||
- Dependency direction follows layer conventions (dependencies flow inward)
|
|
||||||
- Appropriate abstraction level (not over-engineered, not under-abstracted)
|
|
||||||
|
|
||||||
If any Critical findings detected, invoke `discuss` CLI tool (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
|
|
||||||
|
|
||||||
## Phase 4: Verdict & Feedback
|
|
||||||
|
|
||||||
Classify overall verdict based on findings:
|
|
||||||
|
|
||||||
| Verdict | Condition | Action |
|
|
||||||
|---------|-----------|--------|
|
|
||||||
| APPROVE | No Critical or High findings | Send review_complete |
|
|
||||||
| REVISE | Has High findings, no Critical | Send fix_required with detailed feedback |
|
|
||||||
| REJECT | Has Critical findings or fundamental approach flaw | Send fix_required + flag for designer escalation |
|
|
||||||
|
|
||||||
1. Write review report to scoped output path:
|
|
||||||
- Single: `<session>/artifacts/review-report.md`
|
|
||||||
- Fan-out: `<session>/artifacts/branches/B{NN}/review-report.md`
|
|
||||||
- Independent: `<session>/artifacts/pipelines/{P}/review-report.md`
|
|
||||||
- Content: Per-dimension findings with severity, file:line, description; Overall verdict with rationale; Specific fix instructions for REVISE/REJECT verdicts
|
|
||||||
|
|
||||||
2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace:
|
|
||||||
- Single: merge `{ "reviewer": { verdict, finding_count, critical_count, dimensions_reviewed } }`
|
|
||||||
- Fan-out: merge `{ "reviewer.B{NN}": { verdict, finding_count, critical_count, dimensions_reviewed } }`
|
|
||||||
- Independent: merge `{ "reviewer.{P}": { verdict, finding_count, critical_count, dimensions_reviewed } }`
|
|
||||||
|
|
||||||
3. If DISCUSS-REVIEW was triggered, record discussion summary in `<session>/discussions/DISCUSS-REVIEW.md` (or `DISCUSS-REVIEW-B{NN}.md` for branch-scoped discussions)
|
|
||||||
@@ -1,117 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: VALIDATE
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: validate_complete
|
|
||||||
error: error
|
|
||||||
fix: fix_required
|
|
||||||
---
|
|
||||||
|
|
||||||
# Architecture Validator
|
|
||||||
|
|
||||||
Validate refactoring changes by running build checks, test suites, dependency metric comparisons, and API compatibility verification. Ensure refactoring improves architecture without breaking functionality.
|
|
||||||
|
|
||||||
## Phase 2: Environment & Baseline Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Architecture baseline | <session>/artifacts/architecture-baseline.json (shared) | Yes |
|
|
||||||
| Refactoring plan / detail | Varies by mode (see below) | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. **Detect branch/pipeline context** from task description:
|
|
||||||
|
|
||||||
| Task Description Field | Value | Context |
|
|
||||||
|----------------------|-------|---------
|
|
||||||
| `BranchId: B{NN}` | Present | Fan-out branch -- validate only this branch's changes |
|
|
||||||
| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline |
|
|
||||||
| Neither present | - | Single mode -- full validation |
|
|
||||||
|
|
||||||
3. **Load architecture baseline**:
|
|
||||||
- Single / Fan-out: Read `<session>/artifacts/architecture-baseline.json` (shared baseline)
|
|
||||||
- Independent: Read `<session>/artifacts/pipelines/{P}/architecture-baseline.json`
|
|
||||||
|
|
||||||
4. **Load refactoring context**:
|
|
||||||
- Single: Read `<session>/artifacts/refactoring-plan.md` -- all success criteria
|
|
||||||
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- only this branch's criteria
|
|
||||||
- Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md`
|
|
||||||
|
|
||||||
5. Load .msg/meta.json for project type and refactoring scope
|
|
||||||
6. Detect available validation tools from project:
|
|
||||||
|
|
||||||
| Signal | Validation Tool | Method |
|
|
||||||
|--------|----------------|--------|
|
|
||||||
| package.json + tsc | TypeScript compiler | Type-check entire project |
|
|
||||||
| package.json + vitest/jest | Test runner | Run existing test suite |
|
|
||||||
| package.json + eslint | Linter | Run lint checks for import/export issues |
|
|
||||||
| Cargo.toml | Rust compiler | cargo check + cargo test |
|
|
||||||
| go.mod | Go tools | go build + go test |
|
|
||||||
| Makefile with test target | Custom tests | make test |
|
|
||||||
| No tooling detected | Manual validation | File existence + import grep checks |
|
|
||||||
|
|
||||||
7. Get changed files scope from .msg/meta.json:
|
|
||||||
- Single: `refactorer` namespace
|
|
||||||
- Fan-out: `refactorer.B{NN}` namespace
|
|
||||||
- Independent: `refactorer.{P}` namespace
|
|
||||||
|
|
||||||
## Phase 3: Validation Execution
|
|
||||||
|
|
||||||
Run validations across four dimensions:
|
|
||||||
|
|
||||||
**Build validation**:
|
|
||||||
- Compile/type-check the project -- zero new errors allowed
|
|
||||||
- Verify all moved/renamed files are correctly referenced
|
|
||||||
- Check for missing imports or unresolved modules
|
|
||||||
|
|
||||||
**Test validation**:
|
|
||||||
- Run existing test suite -- all previously passing tests must still pass
|
|
||||||
- Identify any tests that need updating due to module moves (update, don't skip)
|
|
||||||
- Check for test file imports that reference old paths
|
|
||||||
|
|
||||||
**Dependency metric validation**:
|
|
||||||
- Recalculate architecture metrics post-refactoring
|
|
||||||
- Compare coupling scores against baseline (must improve or stay neutral)
|
|
||||||
- Verify no new circular dependencies introduced
|
|
||||||
- Check cohesion metrics for affected modules
|
|
||||||
|
|
||||||
**API compatibility validation**:
|
|
||||||
- Verify public API signatures are preserved (exported function/class/type names)
|
|
||||||
- Check for dangling references (imports pointing to removed/moved files)
|
|
||||||
- Verify no new dead exports introduced by the refactoring
|
|
||||||
- Check that re-exports maintain backward compatibility where needed
|
|
||||||
|
|
||||||
**Branch-scoped validation** (fan-out mode):
|
|
||||||
- Only validate metrics relevant to this branch's refactoring (from refactoring-detail.md)
|
|
||||||
- Still check for regressions across all metrics (not just branch-specific ones)
|
|
||||||
|
|
||||||
## Phase 4: Result Analysis
|
|
||||||
|
|
||||||
Compare against baseline and plan criteria:
|
|
||||||
|
|
||||||
| Metric | Threshold | Verdict |
|
|
||||||
|--------|-----------|---------|
|
|
||||||
| Build passes | Zero compilation errors | PASS |
|
|
||||||
| All tests pass | No new test failures | PASS |
|
|
||||||
| Coupling improved or neutral | No metric degradation > 5% | PASS |
|
|
||||||
| No new cycles introduced | Cycle count <= baseline | PASS |
|
|
||||||
| All plan success criteria met | Every criterion satisfied | PASS |
|
|
||||||
| Partial improvement | Some metrics improved, none degraded | WARN |
|
|
||||||
| Build fails | Compilation errors detected | FAIL -> fix_required |
|
|
||||||
| Test failures | Previously passing tests now fail | FAIL -> fix_required |
|
|
||||||
| New cycles introduced | Cycle count > baseline | FAIL -> fix_required |
|
|
||||||
| Dangling references | Unresolved imports detected | FAIL -> fix_required |
|
|
||||||
|
|
||||||
1. Write validation results to output path:
|
|
||||||
- Single: `<session>/artifacts/validation-results.json`
|
|
||||||
- Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json`
|
|
||||||
- Independent: `<session>/artifacts/pipelines/{P}/validation-results.json`
|
|
||||||
- Content: Per-dimension: name, baseline value, current value, improvement/regression, verdict; Overall verdict: PASS / WARN / FAIL; Failure details (if any)
|
|
||||||
|
|
||||||
2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace:
|
|
||||||
- Single: merge `{ "validator": { verdict, improvements, regressions, build_pass, test_pass } }`
|
|
||||||
- Fan-out: merge `{ "validator.B{NN}": { verdict, improvements, regressions, build_pass, test_pass } }`
|
|
||||||
- Independent: merge `{ "validator.{P}": { verdict, improvements, regressions, build_pass, test_pass } }`
|
|
||||||
|
|
||||||
3. If verdict is FAIL, include detailed feedback in message for FIX task creation:
|
|
||||||
- Which validations failed, specific errors, suggested investigation areas
|
|
||||||
@@ -23,7 +23,7 @@
|
|||||||
"name": "analyzer",
|
"name": "analyzer",
|
||||||
"type": "orchestration",
|
"type": "orchestration",
|
||||||
"description": "Analyzes architecture: dependency graphs, coupling/cohesion, layering violations, God Classes, dead code",
|
"description": "Analyzes architecture: dependency graphs, coupling/cohesion, layering violations, God Classes, dead code",
|
||||||
"role_spec": "role-specs/analyzer.md",
|
"role_spec": "roles/analyzer/role.md",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "ANALYZE",
|
"prefix": "ANALYZE",
|
||||||
@@ -43,7 +43,7 @@
|
|||||||
"name": "designer",
|
"name": "designer",
|
||||||
"type": "orchestration",
|
"type": "orchestration",
|
||||||
"description": "Designs refactoring strategies from architecture analysis, produces prioritized refactoring plan with discrete REFACTOR-IDs",
|
"description": "Designs refactoring strategies from architecture analysis, produces prioritized refactoring plan with discrete REFACTOR-IDs",
|
||||||
"role_spec": "role-specs/designer.md",
|
"role_spec": "roles/designer/role.md",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "DESIGN",
|
"prefix": "DESIGN",
|
||||||
@@ -63,7 +63,7 @@
|
|||||||
"name": "refactorer",
|
"name": "refactorer",
|
||||||
"type": "code_generation",
|
"type": "code_generation",
|
||||||
"description": "Implements architecture refactoring changes following the design plan",
|
"description": "Implements architecture refactoring changes following the design plan",
|
||||||
"role_spec": "role-specs/refactorer.md",
|
"role_spec": "roles/refactorer/role.md",
|
||||||
"inner_loop": true,
|
"inner_loop": true,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "REFACTOR",
|
"prefix": "REFACTOR",
|
||||||
@@ -84,7 +84,7 @@
|
|||||||
"name": "validator",
|
"name": "validator",
|
||||||
"type": "validation",
|
"type": "validation",
|
||||||
"description": "Validates refactoring: build checks, test suites, dependency metrics, API compatibility",
|
"description": "Validates refactoring: build checks, test suites, dependency metrics, API compatibility",
|
||||||
"role_spec": "role-specs/validator.md",
|
"role_spec": "roles/validator/role.md",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "VALIDATE",
|
"prefix": "VALIDATE",
|
||||||
@@ -105,7 +105,7 @@
|
|||||||
"name": "reviewer",
|
"name": "reviewer",
|
||||||
"type": "read_only_analysis",
|
"type": "read_only_analysis",
|
||||||
"description": "Reviews refactoring code for correctness, pattern consistency, completeness, migration safety, and best practices",
|
"description": "Reviews refactoring code for correctness, pattern consistency, completeness, migration safety, and best practices",
|
||||||
"role_spec": "role-specs/reviewer.md",
|
"role_spec": "roles/reviewer/role.md",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "REVIEW",
|
"prefix": "REVIEW",
|
||||||
|
|||||||
@@ -1,63 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: CHALLENGE
|
|
||||||
inner_loop: false
|
|
||||||
delegates_to: []
|
|
||||||
message_types:
|
|
||||||
success: critique_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Challenger
|
|
||||||
|
|
||||||
Devil's advocate role. Assumption challenging, feasibility questioning, risk identification. Acts as the Critic in the Generator-Critic loop.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Session folder | Task description (Session: line) | Yes |
|
|
||||||
| Ideas | <session>/ideas/*.md files | Yes |
|
|
||||||
| Previous critiques | <session>/.msg/meta.json critique_insights | No |
|
|
||||||
|
|
||||||
1. Extract session path from task description (match "Session: <path>")
|
|
||||||
2. Glob idea files from <session>/ideas/
|
|
||||||
3. Read all idea files for analysis
|
|
||||||
4. Read .msg/meta.json critique_insights to avoid repeating past challenges
|
|
||||||
|
|
||||||
## Phase 3: Critical Analysis
|
|
||||||
|
|
||||||
**Challenge Dimensions** (apply to each idea):
|
|
||||||
|
|
||||||
| Dimension | Focus |
|
|
||||||
|-----------|-------|
|
|
||||||
| Assumption Validity | Does the core assumption hold? Counter-examples? |
|
|
||||||
| Feasibility | Technical/resource/time feasibility? |
|
|
||||||
| Risk Assessment | Worst case scenario? Hidden risks? |
|
|
||||||
| Competitive Analysis | Better alternatives already exist? |
|
|
||||||
|
|
||||||
**Severity Classification**:
|
|
||||||
|
|
||||||
| Severity | Criteria |
|
|
||||||
|----------|----------|
|
|
||||||
| CRITICAL | Fundamental issue, idea may need replacement |
|
|
||||||
| HIGH | Significant flaw, requires revision |
|
|
||||||
| MEDIUM | Notable weakness, needs consideration |
|
|
||||||
| LOW | Minor concern, does not invalidate the idea |
|
|
||||||
|
|
||||||
**Generator-Critic Signal**:
|
|
||||||
|
|
||||||
| Condition | Signal |
|
|
||||||
|-----------|--------|
|
|
||||||
| Any CRITICAL or HIGH severity | REVISION_NEEDED |
|
|
||||||
| All MEDIUM or lower | CONVERGED |
|
|
||||||
|
|
||||||
**Output**: Write to `<session>/critiques/critique-<num>.md`
|
|
||||||
- Sections: Ideas Reviewed, Per-idea challenges with severity, Summary table with counts, GC Signal
|
|
||||||
|
|
||||||
## Phase 4: Severity Summary
|
|
||||||
|
|
||||||
1. Count challenges by severity level
|
|
||||||
2. Determine signal: REVISION_NEEDED if critical+high > 0, else CONVERGED
|
|
||||||
3. Update shared state:
|
|
||||||
- Append challenges to .msg/meta.json critique_insights
|
|
||||||
- Each entry: idea, severity, key_challenge, round
|
|
||||||
@@ -1,58 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: EVAL
|
|
||||||
inner_loop: false
|
|
||||||
delegates_to: []
|
|
||||||
message_types:
|
|
||||||
success: evaluation_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Evaluator
|
|
||||||
|
|
||||||
Scoring, ranking, and final selection. Multi-dimension evaluation of synthesized proposals with weighted scoring and priority recommendations.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Session folder | Task description (Session: line) | Yes |
|
|
||||||
| Synthesis results | <session>/synthesis/*.md files | Yes |
|
|
||||||
| All ideas | <session>/ideas/*.md files | No (for context) |
|
|
||||||
| All critiques | <session>/critiques/*.md files | No (for context) |
|
|
||||||
|
|
||||||
1. Extract session path from task description (match "Session: <path>")
|
|
||||||
2. Glob synthesis files from <session>/synthesis/
|
|
||||||
3. Read all synthesis files for evaluation
|
|
||||||
4. Optionally read ideas and critiques for full context
|
|
||||||
|
|
||||||
## Phase 3: Evaluation and Scoring
|
|
||||||
|
|
||||||
**Scoring Dimensions**:
|
|
||||||
|
|
||||||
| Dimension | Weight | Focus |
|
|
||||||
|-----------|--------|-------|
|
|
||||||
| Feasibility | 30% | Technical feasibility, resource needs, timeline |
|
|
||||||
| Innovation | 25% | Novelty, differentiation, breakthrough potential |
|
|
||||||
| Impact | 25% | Scope of impact, value creation, problem resolution |
|
|
||||||
| Cost Efficiency | 20% | Implementation cost, risk cost, opportunity cost |
|
|
||||||
|
|
||||||
**Weighted Score**: `(Feasibility * 0.30) + (Innovation * 0.25) + (Impact * 0.25) + (Cost * 0.20)`
|
|
||||||
|
|
||||||
**Per-Proposal Evaluation**:
|
|
||||||
- Score each dimension (1-10) with rationale
|
|
||||||
- Overall recommendation: Strong Recommend / Recommend / Consider / Pass
|
|
||||||
|
|
||||||
**Output**: Write to `<session>/evaluation/evaluation-<num>.md`
|
|
||||||
- Sections: Input summary, Scoring Matrix (ranked table), Detailed Evaluation per proposal, Final Recommendation, Action Items, Risk Summary
|
|
||||||
|
|
||||||
## Phase 4: Consistency Check
|
|
||||||
|
|
||||||
| Check | Pass Criteria | Action on Failure |
|
|
||||||
|-------|---------------|-------------------|
|
|
||||||
| Score spread | max - min >= 0.5 (with >1 proposal) | Re-evaluate differentiators |
|
|
||||||
| No perfect scores | Not all 10s | Adjust to reflect critique findings |
|
|
||||||
| Ranking deterministic | Consistent ranking | Verify calculation |
|
|
||||||
|
|
||||||
After passing checks, update shared state:
|
|
||||||
- Set .msg/meta.json evaluation_scores
|
|
||||||
- Each entry: title, weighted_score, rank, recommendation
|
|
||||||
@@ -1,71 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: IDEA
|
|
||||||
inner_loop: false
|
|
||||||
delegates_to: []
|
|
||||||
message_types:
|
|
||||||
success: ideas_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Ideator
|
|
||||||
|
|
||||||
Multi-angle idea generator. Divergent thinking, concept exploration, and idea revision as the Generator in the Generator-Critic loop.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Session folder | Task description (Session: line) | Yes |
|
|
||||||
| Topic | <session>/.msg/meta.json | Yes |
|
|
||||||
| Angles | <session>/.msg/meta.json | Yes |
|
|
||||||
| GC Round | <session>/.msg/meta.json | Yes |
|
|
||||||
| Previous critique | <session>/critiques/*.md | For revision tasks only |
|
|
||||||
| Previous ideas | <session>/.msg/meta.json generated_ideas | No |
|
|
||||||
|
|
||||||
1. Extract session path from task description (match "Session: <path>")
|
|
||||||
2. Read .msg/meta.json for topic, angles, gc_round
|
|
||||||
3. Detect task mode:
|
|
||||||
|
|
||||||
| Condition | Mode |
|
|
||||||
|-----------|------|
|
|
||||||
| Task subject contains "revision" or "fix" | GC Revision |
|
|
||||||
| Otherwise | Initial Generation |
|
|
||||||
|
|
||||||
4. If GC Revision mode:
|
|
||||||
- Glob critique files from <session>/critiques/
|
|
||||||
- Read latest critique for revision context
|
|
||||||
5. Read previous ideas from .msg/meta.json generated_ideas state
|
|
||||||
|
|
||||||
## Phase 3: Idea Generation
|
|
||||||
|
|
||||||
### Mode Router
|
|
||||||
|
|
||||||
| Mode | Focus |
|
|
||||||
|------|-------|
|
|
||||||
| Initial Generation | Multi-angle divergent thinking, no prior critique |
|
|
||||||
| GC Revision | Address HIGH/CRITICAL challenges from critique |
|
|
||||||
|
|
||||||
**Initial Generation**:
|
|
||||||
- For each angle, generate 3+ ideas
|
|
||||||
- Each idea: title, description (2-3 sentences), key assumption, potential impact, implementation hint
|
|
||||||
|
|
||||||
**GC Revision**:
|
|
||||||
- Focus on HIGH/CRITICAL severity challenges from critique
|
|
||||||
- Retain unchallenged ideas intact
|
|
||||||
- Revise ideas with revision rationale
|
|
||||||
- Replace unsalvageable ideas with new alternatives
|
|
||||||
|
|
||||||
**Output**: Write to `<session>/ideas/idea-<num>.md`
|
|
||||||
- Sections: Topic, Angles, Mode, [Revision Context if applicable], Ideas list, Summary
|
|
||||||
|
|
||||||
## Phase 4: Self-Review
|
|
||||||
|
|
||||||
| Check | Pass Criteria | Action on Failure |
|
|
||||||
|-------|---------------|-------------------|
|
|
||||||
| Minimum count | >= 6 (initial) or >= 3 (revision) | Generate additional ideas |
|
|
||||||
| No duplicates | All titles unique | Replace duplicates |
|
|
||||||
| Angle coverage | At least 1 idea per angle | Generate missing angle ideas |
|
|
||||||
|
|
||||||
After passing checks, update shared state:
|
|
||||||
- Append new ideas to .msg/meta.json generated_ideas
|
|
||||||
- Each entry: id, title, round, revised flag
|
|
||||||
@@ -1,59 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: SYNTH
|
|
||||||
inner_loop: false
|
|
||||||
delegates_to: []
|
|
||||||
message_types:
|
|
||||||
success: synthesis_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Synthesizer
|
|
||||||
|
|
||||||
Cross-idea integrator. Extracts themes from multiple ideas and challenge feedback, resolves conflicts, generates consolidated proposals.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Session folder | Task description (Session: line) | Yes |
|
|
||||||
| All ideas | <session>/ideas/*.md files | Yes |
|
|
||||||
| All critiques | <session>/critiques/*.md files | Yes |
|
|
||||||
| GC rounds completed | <session>/.msg/meta.json gc_round | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description (match "Session: <path>")
|
|
||||||
2. Glob all idea files from <session>/ideas/
|
|
||||||
3. Glob all critique files from <session>/critiques/
|
|
||||||
4. Read all idea and critique files for synthesis
|
|
||||||
5. Read .msg/meta.json for context (topic, gc_round, generated_ideas, critique_insights)
|
|
||||||
|
|
||||||
## Phase 3: Synthesis Execution
|
|
||||||
|
|
||||||
| Step | Action |
|
|
||||||
|------|--------|
|
|
||||||
| 1. Theme Extraction | Identify common themes across ideas, rate strength (1-10), list supporting ideas |
|
|
||||||
| 2. Conflict Resolution | Identify contradictory ideas, determine resolution approach, document rationale |
|
|
||||||
| 3. Complementary Grouping | Group complementary ideas together |
|
|
||||||
| 4. Gap Identification | Discover uncovered perspectives |
|
|
||||||
| 5. Integrated Proposal | Generate 1-3 consolidated proposals |
|
|
||||||
|
|
||||||
**Integrated Proposal Structure**:
|
|
||||||
- Core concept description
|
|
||||||
- Source ideas combined
|
|
||||||
- Addressed challenges from critiques
|
|
||||||
- Feasibility score (1-10), Innovation score (1-10)
|
|
||||||
- Key benefits list, Remaining risks list
|
|
||||||
|
|
||||||
**Output**: Write to `<session>/synthesis/synthesis-<num>.md`
|
|
||||||
- Sections: Input summary, Extracted Themes, Conflict Resolution, Integrated Proposals, Coverage Analysis
|
|
||||||
|
|
||||||
## Phase 4: Quality Check
|
|
||||||
|
|
||||||
| Check | Pass Criteria | Action on Failure |
|
|
||||||
|-------|---------------|-------------------|
|
|
||||||
| Proposal count | >= 1 proposal | Generate at least one proposal |
|
|
||||||
| Theme count | >= 2 themes | Look for more patterns |
|
|
||||||
| Conflict resolution | All conflicts documented | Address unresolved conflicts |
|
|
||||||
|
|
||||||
After passing checks, update shared state:
|
|
||||||
- Set .msg/meta.json synthesis_themes
|
|
||||||
- Each entry: name, strength, supporting_ideas
|
|
||||||
@@ -1,91 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: ANALYZE
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: analyze_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Requirements Analyst
|
|
||||||
|
|
||||||
Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Industry context | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path, industry type, and tech stack from task description
|
|
||||||
2. Detect existing design system:
|
|
||||||
|
|
||||||
| Signal | Detection Method |
|
|
||||||
|--------|-----------------|
|
|
||||||
| Token files | Glob `**/*token*.*` |
|
|
||||||
| CSS files | Glob `**/*.css` |
|
|
||||||
| Package.json | Read for framework dependencies |
|
|
||||||
|
|
||||||
3. Detect tech stack from package.json:
|
|
||||||
|
|
||||||
| Dependency | Stack |
|
|
||||||
|------------|-------|
|
|
||||||
| `next` | nextjs |
|
|
||||||
| `react` | react |
|
|
||||||
| `vue` | vue |
|
|
||||||
| `svelte` | svelte |
|
|
||||||
| `@shadcn/ui` | shadcn |
|
|
||||||
| (none) | html-tailwind |
|
|
||||||
|
|
||||||
4. Load .msg/meta.json for shared state
|
|
||||||
|
|
||||||
## Phase 3: Design Intelligence Retrieval
|
|
||||||
|
|
||||||
Retrieve design intelligence via ui-ux-pro-max skill integration.
|
|
||||||
|
|
||||||
**Step 1: Invoke ui-ux-pro-max** (primary path):
|
|
||||||
|
|
||||||
| Action | Invocation |
|
|
||||||
|--------|------------|
|
|
||||||
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
|
|
||||||
| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
|
|
||||||
| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
|
|
||||||
|
|
||||||
**Step 2: Fallback** (if skill unavailable):
|
|
||||||
- Generate design recommendations from LLM general knowledge
|
|
||||||
- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
|
|
||||||
|
|
||||||
**Step 3: Analyze existing codebase** (if token/CSS files found):
|
|
||||||
- Explore existing design patterns (color palette, typography scale, spacing, component patterns)
|
|
||||||
|
|
||||||
**Step 4: Competitive reference** (optional, if industry is not "Other"):
|
|
||||||
- `WebSearch({ query: "<industry> web design trends best practices" })`
|
|
||||||
|
|
||||||
**Step 5: Compile design-intelligence.json**:
|
|
||||||
|
|
||||||
| Field | Source |
|
|
||||||
|-------|--------|
|
|
||||||
| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
|
|
||||||
| `industry` | Task description |
|
|
||||||
| `detected_stack` | Phase 2 detection |
|
|
||||||
| `design_system` | Skill output (colors, typography, effects) |
|
|
||||||
| `ux_guidelines` | Skill UX domain output |
|
|
||||||
| `stack_guidelines` | Skill stack output |
|
|
||||||
| `recommendations` | Synthesized: style, anti-patterns, must-have |
|
|
||||||
|
|
||||||
**Output files**:
|
|
||||||
- `<session>/analysis/design-intelligence.json`
|
|
||||||
- `<session>/analysis/requirements.md`
|
|
||||||
|
|
||||||
## Phase 4: Self-Review
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| JSON validity | Parse design-intelligence.json | No parse errors |
|
|
||||||
| Required fields | Check _source, industry, design_system | All present |
|
|
||||||
| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array |
|
|
||||||
| Requirements doc exists | File check | requirements.md written |
|
|
||||||
|
|
||||||
Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys.
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: ARCH
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: arch_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Frontend Architect
|
|
||||||
|
|
||||||
Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
|
|
||||||
| Design intelligence | <session>/analysis/design-intelligence.json | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path and scope from task description
|
|
||||||
2. Load design intelligence from analyst output
|
|
||||||
3. Load .msg/meta.json for shared state (industry_context, design_intelligence)
|
|
||||||
4. Detect existing project structure via Glob `src/**/*`
|
|
||||||
|
|
||||||
**Fail-safe**: If design-intelligence.json not found, use default token values and log warning.
|
|
||||||
|
|
||||||
## Phase 3: Architecture Design
|
|
||||||
|
|
||||||
**Scope selection**:
|
|
||||||
|
|
||||||
| Scope | Output |
|
|
||||||
|-------|--------|
|
|
||||||
| `tokens` | Design token system only |
|
|
||||||
| `components` | Component specs only |
|
|
||||||
| `full` | Both tokens and components + project structure |
|
|
||||||
|
|
||||||
**Step 1: Design Token System** (scope: tokens or full):
|
|
||||||
|
|
||||||
Generate `<session>/architecture/design-tokens.json` with categories:
|
|
||||||
|
|
||||||
| Category | Content | Source |
|
|
||||||
|----------|---------|--------|
|
|
||||||
| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max |
|
|
||||||
| `typography` | Font families, font sizes (scale) | ui-ux-pro-max |
|
|
||||||
| `spacing` | xs through 2xl | Standard scale |
|
|
||||||
| `border-radius` | sm, md, lg, full | Standard scale |
|
|
||||||
| `shadow` | sm, md, lg | Standard elevation |
|
|
||||||
| `transition` | fast, normal, slow | Standard durations |
|
|
||||||
|
|
||||||
Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values.
|
|
||||||
|
|
||||||
**Step 2: Component Architecture** (scope: components or full):
|
|
||||||
|
|
||||||
Generate component specs in `<session>/architecture/component-specs/`:
|
|
||||||
- Design reference (style, stack)
|
|
||||||
- Props table (name, type, default, description)
|
|
||||||
- Variants table
|
|
||||||
- Accessibility requirements (role, keyboard, ARIA, contrast)
|
|
||||||
- Anti-patterns to avoid (from design intelligence)
|
|
||||||
|
|
||||||
**Step 3: Project Structure** (scope: full):
|
|
||||||
|
|
||||||
Generate `<session>/architecture/project-structure.md` with stack-specific layout:
|
|
||||||
|
|
||||||
| Stack | Key Directories |
|
|
||||||
|-------|----------------|
|
|
||||||
| react | src/components/, src/pages/, src/hooks/, src/styles/ |
|
|
||||||
| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ |
|
|
||||||
| vue | src/components/, src/views/, src/composables/, src/styles/ |
|
|
||||||
| html-tailwind | src/components/, src/pages/, src/styles/ |
|
|
||||||
|
|
||||||
## Phase 4: Self-Review
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| JSON validity | Parse design-tokens.json | No errors |
|
|
||||||
| Required categories | Check color, typography, spacing | All present |
|
|
||||||
| Anti-pattern compliance | Token values vs anti-patterns | No violations |
|
|
||||||
| Component specs complete | Each has props + accessibility | All complete |
|
|
||||||
| File existence | Verify all planned files | All present |
|
|
||||||
|
|
||||||
Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys.
|
|
||||||
@@ -1,92 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: DEV
|
|
||||||
inner_loop: true
|
|
||||||
message_types:
|
|
||||||
success: dev_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Frontend Developer
|
|
||||||
|
|
||||||
Consume architecture artifacts (design tokens, component specs, project structure) to implement frontend code. Reference design-intelligence.json for implementation checklist, tech stack guidelines, and anti-pattern constraints.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
|
|
||||||
| Design intelligence | <session>/analysis/design-intelligence.json | No |
|
|
||||||
| Design tokens | <session>/architecture/design-tokens.json | Yes |
|
|
||||||
| Component specs | <session>/architecture/component-specs/*.md | No |
|
|
||||||
| Project structure | <session>/architecture/project-structure.md | No |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path and scope from task description
|
|
||||||
2. Load design tokens (required -- if missing, report to coordinator)
|
|
||||||
3. Load design intelligence for anti-patterns and guidelines
|
|
||||||
4. Load component specs and project structure
|
|
||||||
5. Detect tech stack from design intelligence `detected_stack`
|
|
||||||
6. Load .msg/meta.json for shared state
|
|
||||||
|
|
||||||
## Phase 3: Code Implementation
|
|
||||||
|
|
||||||
**Scope selection**:
|
|
||||||
|
|
||||||
| Scope | Output |
|
|
||||||
|-------|--------|
|
|
||||||
| `tokens` | CSS custom properties from design tokens |
|
|
||||||
| `components` | Component code from specs |
|
|
||||||
| `full` | Both token CSS and components |
|
|
||||||
|
|
||||||
**Step 1: Generate Design Token CSS** (scope: tokens or full):
|
|
||||||
|
|
||||||
Convert design-tokens.json to `src/styles/tokens.css`:
|
|
||||||
|
|
||||||
| JSON Category | CSS Variable Prefix |
|
|
||||||
|---------------|---------------------|
|
|
||||||
| color | `--color-` |
|
|
||||||
| typography.font-family | `--font-` |
|
|
||||||
| typography.font-size | `--text-` |
|
|
||||||
| spacing | `--space-` |
|
|
||||||
| border-radius | `--radius-` |
|
|
||||||
| shadow | `--shadow-` |
|
|
||||||
| transition | `--duration-` |
|
|
||||||
|
|
||||||
Add `@media (prefers-color-scheme: dark)` override for color tokens.
|
|
||||||
|
|
||||||
**Step 2: Implement Components** (scope: components or full):
|
|
||||||
|
|
||||||
Implementation strategy by complexity:
|
|
||||||
|
|
||||||
| Condition | Strategy |
|
|
||||||
|-----------|----------|
|
|
||||||
| <= 2 components | Direct inline Edit/Write |
|
|
||||||
| 3-5 components | Single batch implementation |
|
|
||||||
| > 5 components | Group by module, implement per batch |
|
|
||||||
|
|
||||||
**Coding standards** (mandatory):
|
|
||||||
- Use design token CSS variables -- never hardcode colors/spacing
|
|
||||||
- All interactive elements: `cursor: pointer`
|
|
||||||
- Transitions: 150-300ms via `var(--duration-normal)`
|
|
||||||
- Text contrast: minimum 4.5:1 ratio
|
|
||||||
- Include `focus-visible` styles for keyboard navigation
|
|
||||||
- Support `prefers-reduced-motion`
|
|
||||||
- Responsive: mobile-first with md/lg breakpoints
|
|
||||||
- No emoji as functional icons
|
|
||||||
|
|
||||||
## Phase 4: Self-Review
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| Hardcoded colors | Scan for hex codes outside tokens.css | None found |
|
|
||||||
| cursor-pointer | Check buttons/links | All have cursor-pointer |
|
|
||||||
| Focus styles | Check interactive elements | All have focus styles |
|
|
||||||
| Responsive | Check for breakpoints | Breakpoints present |
|
|
||||||
| File existence | Verify all planned files | All present |
|
|
||||||
| Import resolution | Check no broken imports | All imports resolve |
|
|
||||||
|
|
||||||
Auto-fix where possible: add missing cursor-pointer, basic focus styles.
|
|
||||||
|
|
||||||
Update .msg/meta.json: merge `component_inventory` key with implemented file list.
|
|
||||||
@@ -1,78 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: QA
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: qa_passed
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# QA Engineer
|
|
||||||
|
|
||||||
Execute 5-dimension quality audit integrating ux-guidelines Do/Don't rules, pre-delivery checklist, and industry anti-pattern library. Perform CSS-level precise review on architecture artifacts and implementation code.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Review type | Extracted from task description | No (default: code-review) |
|
|
||||||
| Design intelligence | <session>/analysis/design-intelligence.json | No |
|
|
||||||
| Design tokens | <session>/architecture/design-tokens.json | No |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path and review type from task description
|
|
||||||
2. Load design intelligence (for anti-patterns, must-have rules)
|
|
||||||
3. Load design tokens (for compliance checks)
|
|
||||||
4. Load .msg/meta.json (for industry context, strictness level)
|
|
||||||
5. Collect files to review based on review type:
|
|
||||||
|
|
||||||
| Type | Files to Review |
|
|
||||||
|------|-----------------|
|
|
||||||
| architecture-review | `<session>/architecture/**/*` |
|
|
||||||
| token-review | `<session>/architecture/**/*` |
|
|
||||||
| code-review | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
|
|
||||||
| final | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
|
|
||||||
|
|
||||||
## Phase 3: 5-Dimension Audit
|
|
||||||
|
|
||||||
| Dimension | Weight | Focus |
|
|
||||||
|-----------|--------|-------|
|
|
||||||
| Code Quality | 0.20 | Structure, naming, maintainability |
|
|
||||||
| Accessibility | 0.25 | WCAG compliance, keyboard nav, screen reader |
|
|
||||||
| Design Compliance | 0.20 | Anti-pattern check, design token usage |
|
|
||||||
| UX Best Practices | 0.20 | Interaction patterns, responsive, animations |
|
|
||||||
| Pre-Delivery | 0.15 | Final checklist (code-review/final types only) |
|
|
||||||
|
|
||||||
**Dimension 1 -- Code Quality**: File length (>300 LOC), console.log, empty catch, unused imports.
|
|
||||||
|
|
||||||
**Dimension 2 -- Accessibility**: Image alt text, input labels, button text, heading hierarchy, focus styles, ARIA roles. Strict mode (medical/financial): prefers-reduced-motion required.
|
|
||||||
|
|
||||||
**Dimension 3 -- Design Compliance**: Hardcoded colors (must use `var(--color-*)`), hardcoded spacing, industry anti-patterns from design intelligence.
|
|
||||||
|
|
||||||
**Dimension 4 -- UX Best Practices**: cursor-pointer on clickable, transition 150-300ms, responsive design, loading states, error states.
|
|
||||||
|
|
||||||
**Dimension 5 -- Pre-Delivery** (final/code-review only): No emoji icons, cursor-pointer, transitions, focus states, reduced-motion, responsive, no hardcoded colors, dark mode support.
|
|
||||||
|
|
||||||
**Score calculation**: `score = sum(dimension_score * weight)`
|
|
||||||
|
|
||||||
**Verdict**:
|
|
||||||
|
|
||||||
| Condition | Verdict | Message Type |
|
|
||||||
|-----------|---------|-------------|
|
|
||||||
| score >= 8 AND critical == 0 | PASSED | `qa_passed` |
|
|
||||||
| score >= 6 AND critical == 0 | PASSED_WITH_WARNINGS | `qa_result` |
|
|
||||||
| score < 6 OR critical > 0 | FIX_REQUIRED | `fix_required` |
|
|
||||||
|
|
||||||
## Phase 4: Self-Review
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| All dimensions scored | Check 5 dimension scores | All present |
|
|
||||||
| Audit report written | File check | audit-NNN.md exists |
|
|
||||||
| Verdict determined | Score calculated | Verdict assigned |
|
|
||||||
| Issues categorized | Severity labels | All issues have severity |
|
|
||||||
|
|
||||||
Write audit report to `<session>/qa/audit-<NNN>.md` with: summary, dimension scores, issues by severity, passed dimensions.
|
|
||||||
|
|
||||||
Update .msg/meta.json: append to `qa_history` array.
|
|
||||||
@@ -1,95 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: EXPLORE
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: context_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Issue Explorer
|
|
||||||
|
|
||||||
Analyze issue context, explore codebase for relevant files, map dependencies and impact scope. Produce a shared context report for planner, reviewer, and implementer.
|
|
||||||
|
|
||||||
## Phase 2: Issue Loading & Context Setup
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
|
|
||||||
| Issue details | `ccw issue status <id> --json` | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract issue ID from task description via regex: `(?:GH-\d+|ISS-\d{8}-\d{6})`
|
|
||||||
2. If no issue ID found -> report error, STOP
|
|
||||||
3. Load issue details:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash("ccw issue status <issueId> --json")
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Parse JSON response for issue metadata (title, context, priority, labels, feedback)
|
|
||||||
5. Load wisdom files from `<session>/wisdom/` if available
|
|
||||||
|
|
||||||
## Phase 3: Codebase Exploration & Impact Analysis
|
|
||||||
|
|
||||||
**Complexity assessment determines exploration depth**:
|
|
||||||
|
|
||||||
| Signal | Weight | Keywords |
|
|
||||||
|--------|--------|----------|
|
|
||||||
| Structural change | +2 | refactor, architect, restructure, module, system |
|
|
||||||
| Cross-cutting | +2 | multiple, across, cross |
|
|
||||||
| Integration | +1 | integrate, api, database |
|
|
||||||
| High priority | +1 | priority >= 4 |
|
|
||||||
|
|
||||||
| Score | Complexity | Strategy |
|
|
||||||
|-------|------------|----------|
|
|
||||||
| >= 4 | High | Deep exploration via CLI tool |
|
|
||||||
| 2-3 | Medium | Hybrid: ACE search + selective CLI |
|
|
||||||
| 0-1 | Low | Direct ACE search only |
|
|
||||||
|
|
||||||
**Exploration execution**:
|
|
||||||
|
|
||||||
| Complexity | Execution |
|
|
||||||
|------------|-----------|
|
|
||||||
| Low | Direct ACE search: `mcp__ace-tool__search_context(project_root_path, query)` |
|
|
||||||
| Medium/High | CLI exploration: `Bash("ccw cli -p \"<exploration_prompt>\" --tool gemini --mode analysis", { run_in_background: false })` |
|
|
||||||
|
|
||||||
**CLI exploration prompt template**:
|
|
||||||
|
|
||||||
```
|
|
||||||
PURPOSE: Explore codebase for issue <issueId> to identify relevant files, dependencies, and impact scope; success = comprehensive context report written to <session>/explorations/context-<issueId>.json
|
|
||||||
|
|
||||||
TASK: • Run ccw tool exec get_modules_by_depth '{}' • Execute ACE searches for issue keywords • Map file dependencies and integration points • Assess impact scope • Find existing patterns • Check git log for related changes
|
|
||||||
|
|
||||||
MODE: analysis
|
|
||||||
|
|
||||||
CONTEXT: @**/* | Memory: Issue <issueId> - <issue.title> (Priority: <issue.priority>)
|
|
||||||
|
|
||||||
EXPECTED: JSON report with: relevant_files (path + relevance), dependencies, impact_scope (low/medium/high), existing_patterns, related_changes, key_findings, complexity_assessment
|
|
||||||
|
|
||||||
CONSTRAINTS: Focus on issue context | Write output to <session>/explorations/context-<issueId>.json
|
|
||||||
```
|
|
||||||
|
|
||||||
**Report schema**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"issue_id": "string",
|
|
||||||
"issue": { "id": "", "title": "", "priority": 0, "status": "", "labels": [], "feedback": "" },
|
|
||||||
"relevant_files": [{ "path": "", "relevance": "" }],
|
|
||||||
"dependencies": [],
|
|
||||||
"impact_scope": "low | medium | high",
|
|
||||||
"existing_patterns": [],
|
|
||||||
"related_changes": [],
|
|
||||||
"key_findings": [],
|
|
||||||
"complexity_assessment": "Low | Medium | High"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 4: Context Report & Wisdom Contribution
|
|
||||||
|
|
||||||
1. Write context report to `<session>/explorations/context-<issueId>.json`
|
|
||||||
2. If file not found from agent, build minimal report from ACE results
|
|
||||||
3. Update `<session>/wisdom/.msg/meta.json` under `explorer` namespace:
|
|
||||||
- Read existing -> merge `{ "explorer": { issue_id, complexity, impact_scope, file_count } }` -> write back
|
|
||||||
4. Contribute discoveries to `<session>/wisdom/learnings.md` if new patterns found
|
|
||||||
@@ -1,89 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: BUILD
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: impl_complete
|
|
||||||
failed: impl_failed
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Issue Implementer
|
|
||||||
|
|
||||||
Load solution plan, route to execution backend (Agent/Codex/Gemini), run tests, and commit. Execution method determined by coordinator during task creation. Supports parallel instances for batch mode.
|
|
||||||
|
|
||||||
## Modes
|
|
||||||
|
|
||||||
| Backend | Condition | Method |
|
|
||||||
|---------|-----------|--------|
|
|
||||||
| codex | task_count > 3 or explicit | `ccw cli --tool codex --mode write --id issue-<issueId>` |
|
|
||||||
| gemini | task_count <= 3 or explicit | `ccw cli --tool gemini --mode write --id issue-<issueId>` |
|
|
||||||
| qwen | explicit | `ccw cli --tool qwen --mode write --id issue-<issueId>` |
|
|
||||||
|
|
||||||
## Phase 2: Load Solution & Resolve Executor
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
|
|
||||||
| Bound solution | `ccw issue solutions <id> --json` | Yes |
|
|
||||||
| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
|
|
||||||
| Execution method | Task description (`execution_method: Codex|Gemini|Qwen|Auto`) | Yes |
|
|
||||||
| Code review | Task description (`code_review: Skip|Gemini Review|Codex Review`) | No |
|
|
||||||
|
|
||||||
1. Extract issue ID from task description
|
|
||||||
2. If no issue ID -> report error, STOP
|
|
||||||
3. Load bound solution: `Bash("ccw issue solutions <issueId> --json")`
|
|
||||||
4. If no bound solution -> report error, STOP
|
|
||||||
5. Load explorer context (if available)
|
|
||||||
6. Resolve execution method (Auto: task_count <= 3 -> gemini, else codex)
|
|
||||||
7. Update issue status: `Bash("ccw issue update <issueId> --status in-progress")`
|
|
||||||
|
|
||||||
## Phase 3: Implementation (Multi-Backend Routing)
|
|
||||||
|
|
||||||
**Execution prompt template** (all backends):
|
|
||||||
|
|
||||||
```
|
|
||||||
## Issue
|
|
||||||
ID: <issueId>
|
|
||||||
Title: <solution.bound.title>
|
|
||||||
|
|
||||||
## Solution Plan
|
|
||||||
<solution.bound JSON>
|
|
||||||
|
|
||||||
## Codebase Context (from explorer)
|
|
||||||
Relevant files: <explorerContext.relevant_files>
|
|
||||||
Existing patterns: <explorerContext.existing_patterns>
|
|
||||||
Dependencies: <explorerContext.dependencies>
|
|
||||||
|
|
||||||
## Implementation Requirements
|
|
||||||
1. Follow the solution plan tasks in order
|
|
||||||
2. Write clean, minimal code following existing patterns
|
|
||||||
3. Run tests after each significant change
|
|
||||||
4. Ensure all existing tests still pass
|
|
||||||
5. Do NOT over-engineer
|
|
||||||
|
|
||||||
## Quality Checklist
|
|
||||||
- All solution tasks implemented
|
|
||||||
- No TypeScript/linting errors
|
|
||||||
- Existing tests pass
|
|
||||||
- New tests added where appropriate
|
|
||||||
```
|
|
||||||
|
|
||||||
Route by executor:
|
|
||||||
- **codex**: `Bash("ccw cli -p \"<prompt>\" --tool codex --mode write --id issue-<issueId>", { run_in_background: false })`
|
|
||||||
- **gemini**: `Bash("ccw cli -p \"<prompt>\" --tool gemini --mode write --id issue-<issueId>", { run_in_background: false })`
|
|
||||||
- **qwen**: `Bash("ccw cli -p \"<prompt>\" --tool qwen --mode write --id issue-<issueId>", { run_in_background: false })`
|
|
||||||
|
|
||||||
On CLI failure, resume: `ccw cli -p "Continue" --resume issue-<issueId> --tool <tool> --mode write`
|
|
||||||
|
|
||||||
## Phase 4: Verify & Commit
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| Tests pass | Detect and run test command | No new failures |
|
|
||||||
| Code review | Optional, per task config | Review output logged |
|
|
||||||
|
|
||||||
- Tests pass -> optional code review -> `ccw issue update <issueId> --status resolved` -> report `impl_complete`
|
|
||||||
- Tests fail -> report `impl_failed` with truncated test output
|
|
||||||
|
|
||||||
Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace:
|
|
||||||
- Read existing -> merge `{ "implementer": { issue_id, executor, test_status, review_status } }` -> write back
|
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: MARSHAL
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: queue_ready
|
|
||||||
conflict: conflict_found
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Issue Integrator
|
|
||||||
|
|
||||||
Queue orchestration, conflict detection, and execution order optimization. Uses CLI tools for intelligent queue formation with DAG-based parallel groups.
|
|
||||||
|
|
||||||
## Phase 2: Collect Bound Solutions
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
|
|
||||||
| Bound solutions | `ccw issue solutions <id> --json` | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract issue IDs from task description via regex
|
|
||||||
2. Verify all issues have bound solutions:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash("ccw issue solutions <issueId> --json")
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Check for unbound issues:
|
|
||||||
|
|
||||||
| Condition | Action |
|
|
||||||
|-----------|--------|
|
|
||||||
| All issues bound | Proceed to Phase 3 |
|
|
||||||
| Any issue unbound | Report error to coordinator, STOP |
|
|
||||||
|
|
||||||
## Phase 3: Queue Formation via CLI
|
|
||||||
|
|
||||||
**CLI invocation**:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash("ccw cli -p \"
|
|
||||||
PURPOSE: Form execution queue for <count> issues with conflict detection and optimal ordering; success = DAG-based queue with parallel groups written to execution-queue.json
|
|
||||||
|
|
||||||
TASK: • Load all bound solutions from .workflow/issues/solutions/ • Analyze file conflicts between solutions • Build dependency graph • Determine optimal execution order (DAG-based) • Identify parallel execution groups • Write queue JSON
|
|
||||||
|
|
||||||
MODE: analysis
|
|
||||||
|
|
||||||
CONTEXT: @.workflow/issues/solutions/**/*.json | Memory: Issues to queue: <issueIds>
|
|
||||||
|
|
||||||
EXPECTED: Queue JSON with: ordered issue list, conflict analysis, parallel_groups (issues that can run concurrently), depends_on relationships
|
|
||||||
Write to: .workflow/issues/queue/execution-queue.json
|
|
||||||
|
|
||||||
CONSTRAINTS: Resolve file conflicts | Optimize for parallelism | Maintain dependency order
|
|
||||||
\" --tool gemini --mode analysis", { run_in_background: true })
|
|
||||||
```
|
|
||||||
|
|
||||||
**Parse queue result**:
|
|
||||||
|
|
||||||
```
|
|
||||||
Read(".workflow/issues/queue/execution-queue.json")
|
|
||||||
```
|
|
||||||
|
|
||||||
**Queue schema**:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"queue": [{ "issue_id": "", "solution_id": "", "order": 0, "depends_on": [], "estimated_files": [] }],
|
|
||||||
"conflicts": [{ "issues": [], "files": [], "resolution": "" }],
|
|
||||||
"parallel_groups": [{ "group": 0, "issues": [] }]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 4: Conflict Resolution & Reporting
|
|
||||||
|
|
||||||
**Queue validation**:
|
|
||||||
|
|
||||||
| Condition | Action |
|
|
||||||
|-----------|--------|
|
|
||||||
| Queue file exists, no unresolved conflicts | Report `queue_ready` |
|
|
||||||
| Queue file exists, has unresolved conflicts | Report `conflict_found` for user decision |
|
|
||||||
| Queue file not found | Report `error`, STOP |
|
|
||||||
|
|
||||||
**Queue metrics for report**: queue size, parallel group count, resolved conflict count, execution order list.
|
|
||||||
|
|
||||||
Update `<session>/wisdom/.msg/meta.json` under `integrator` namespace:
|
|
||||||
- Read existing -> merge `{ "integrator": { queue_size, parallel_groups, conflict_count } }` -> write back
|
|
||||||
@@ -1,83 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: SOLVE
|
|
||||||
inner_loop: false
|
|
||||||
additional_prefixes: [SOLVE-fix]
|
|
||||||
message_types:
|
|
||||||
success: solution_ready
|
|
||||||
multi: multi_solution
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Issue Planner
|
|
||||||
|
|
||||||
Design solutions and decompose into implementation tasks. Uses CLI tools for ACE exploration and solution generation. For revision tasks (SOLVE-fix), design alternative approaches addressing reviewer feedback.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
|
|
||||||
| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
|
|
||||||
| Review feedback | Task description (for SOLVE-fix tasks) | No |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract issue ID from task description via regex: `(?:GH-\d+|ISS-\d{8}-\d{6})`
|
|
||||||
2. If no issue ID found -> report error, STOP
|
|
||||||
3. Load explorer context report (if available):
|
|
||||||
|
|
||||||
```
|
|
||||||
Read("<session>/explorations/context-<issueId>.json")
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Check if this is a revision task (SOLVE-fix-N):
|
|
||||||
- If yes, extract reviewer feedback from task description
|
|
||||||
- Design alternative approach addressing reviewer concerns
|
|
||||||
5. Load wisdom files for accumulated codebase knowledge
|
|
||||||
|
|
||||||
## Phase 3: Solution Generation via CLI
|
|
||||||
|
|
||||||
**CLI invocation**:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash("ccw cli -p \"
|
|
||||||
PURPOSE: Design solution for issue <issueId> and decompose into implementation tasks; success = solution bound to issue with task breakdown
|
|
||||||
|
|
||||||
TASK: • Load issue details from ccw issue status • Analyze explorer context • Design solution approach • Break down into implementation tasks • Generate solution JSON • Bind solution to issue
|
|
||||||
|
|
||||||
MODE: analysis
|
|
||||||
|
|
||||||
CONTEXT: @**/* | Memory: Issue <issueId> - <issue.title> (Priority: <issue.priority>)
|
|
||||||
Explorer findings: <explorerContext.key_findings>
|
|
||||||
Relevant files: <explorerContext.relevant_files>
|
|
||||||
Complexity: <explorerContext.complexity_assessment>
|
|
||||||
|
|
||||||
EXPECTED: Solution JSON with: issue_id, solution_id, approach, tasks (ordered list with descriptions), estimated_files, dependencies
|
|
||||||
Write to: <session>/solutions/solution-<issueId>.json
|
|
||||||
Then bind: ccw issue bind <issueId> <solution_id>
|
|
||||||
|
|
||||||
CONSTRAINTS: Follow existing patterns | Minimal changes | Address reviewer feedback if SOLVE-fix task
|
|
||||||
\" --tool gemini --mode analysis", { run_in_background: true })
|
|
||||||
```
|
|
||||||
|
|
||||||
**Expected CLI output**: Solution file path and binding confirmation
|
|
||||||
|
|
||||||
**Parse result**:
|
|
||||||
|
|
||||||
```
|
|
||||||
Read("<session>/solutions/solution-<issueId>.json")
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 4: Solution Selection & Reporting
|
|
||||||
|
|
||||||
**Outcome routing**:
|
|
||||||
|
|
||||||
| Condition | Message Type | Action |
|
|
||||||
|-----------|-------------|--------|
|
|
||||||
| Single solution auto-bound | `solution_ready` | Report to coordinator |
|
|
||||||
| Multiple solutions pending | `multi_solution` | Report for user selection |
|
|
||||||
| No solution generated | `error` | Report failure to coordinator |
|
|
||||||
|
|
||||||
Write solution summary to `<session>/solutions/solution-<issueId>.json`.
|
|
||||||
|
|
||||||
Update `<session>/wisdom/.msg/meta.json` under `planner` namespace:
|
|
||||||
- Read existing -> merge `{ "planner": { issue_id, solution_id, task_count, is_revision } }` -> write back
|
|
||||||
@@ -1,89 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: AUDIT
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: approved
|
|
||||||
concerns: concerns
|
|
||||||
rejected: rejected
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Issue Reviewer
|
|
||||||
|
|
||||||
Review solution plans for technical feasibility, risk, and completeness. Quality gate role between plan and execute phases. Provides clear verdicts: approved, rejected, or concerns.
|
|
||||||
|
|
||||||
## Phase 2: Context & Solution Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
|
|
||||||
| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
|
|
||||||
| Bound solution | `ccw issue solutions <id> --json` | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract issue IDs from task description via regex
|
|
||||||
2. Load explorer context reports for each issue
|
|
||||||
3. Load bound solutions for each issue:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash("ccw issue solutions <issueId> --json")
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 3: Multi-Dimensional Review
|
|
||||||
|
|
||||||
Review each solution across three weighted dimensions:
|
|
||||||
|
|
||||||
**Technical Feasibility (40%)**:
|
|
||||||
|
|
||||||
| Criterion | Check |
|
|
||||||
|-----------|-------|
|
|
||||||
| File Coverage | Solution covers all affected files from explorer context |
|
|
||||||
| Dependency Awareness | Considers dependency cascade effects |
|
|
||||||
| API Compatibility | Maintains backward compatibility |
|
|
||||||
| Pattern Conformance | Follows existing code patterns (ACE semantic validation) |
|
|
||||||
|
|
||||||
**Risk Assessment (30%)**:
|
|
||||||
|
|
||||||
| Criterion | Check |
|
|
||||||
|-----------|-------|
|
|
||||||
| Scope Creep | Solution stays within issue boundary (task_count <= 10) |
|
|
||||||
| Breaking Changes | No destructive modifications |
|
|
||||||
| Side Effects | No unforeseen side effects |
|
|
||||||
| Rollback Path | Can rollback if issues occur |
|
|
||||||
|
|
||||||
**Completeness (30%)**:
|
|
||||||
|
|
||||||
| Criterion | Check |
|
|
||||||
|-----------|-------|
|
|
||||||
| All Tasks Defined | Task decomposition is complete (count > 0) |
|
|
||||||
| Test Coverage | Includes test plan |
|
|
||||||
| Edge Cases | Considers boundary conditions |
|
|
||||||
|
|
||||||
**Score calculation**:
|
|
||||||
|
|
||||||
```
|
|
||||||
total_score = round(
|
|
||||||
technical_feasibility.score * 0.4 +
|
|
||||||
risk_assessment.score * 0.3 +
|
|
||||||
completeness.score * 0.3
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Verdict rules**:
|
|
||||||
|
|
||||||
| Score | Verdict | Message Type |
|
|
||||||
|-------|---------|-------------|
|
|
||||||
| >= 80 | approved | `approved` |
|
|
||||||
| 60-79 | concerns | `concerns` |
|
|
||||||
| < 60 | rejected | `rejected` |
|
|
||||||
|
|
||||||
## Phase 4: Compile Audit Report
|
|
||||||
|
|
||||||
1. Write audit report to `<session>/audits/audit-report.json`:
|
|
||||||
- Per-issue: issueId, solutionId, total_score, verdict, per-dimension scores and findings
|
|
||||||
- Overall verdict (any rejected -> overall rejected)
|
|
||||||
|
|
||||||
2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
|
|
||||||
- Read existing -> merge `{ "reviewer": { overall_verdict, review_count, scores } }` -> write back
|
|
||||||
|
|
||||||
3. For rejected solutions, include specific rejection reasons and actionable feedback for SOLVE-fix task creation
|
|
||||||
@@ -1,64 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: DESIGN
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: design_ready
|
|
||||||
revision: design_revision
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Architect
|
|
||||||
|
|
||||||
Technical design, task decomposition, and architecture decision records for iterative development.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading + Codebase Exploration
|
|
||||||
|
|
||||||
| 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 |
|
|
||||||
| Wisdom files | <session>/wisdom/ | No |
|
|
||||||
|
|
||||||
1. Extract session path and requirement from task description
|
|
||||||
2. Read .msg/meta.json for shared context (architecture_decisions, implementation_context)
|
|
||||||
3. Read wisdom files if available (learnings.md, decisions.md, conventions.md)
|
|
||||||
4. Explore codebase for existing patterns, module structure, dependencies:
|
|
||||||
- Use mcp__ace-tool__search_context for semantic discovery
|
|
||||||
- Identify similar implementations and integration points
|
|
||||||
|
|
||||||
## Phase 3: Technical Design + Task Decomposition
|
|
||||||
|
|
||||||
**Design strategy selection**:
|
|
||||||
|
|
||||||
| Condition | Strategy |
|
|
||||||
|-----------|----------|
|
|
||||||
| Single module change | Direct inline design |
|
|
||||||
| Cross-module change | Multi-component design with integration points |
|
|
||||||
| Large refactoring | Phased approach with milestones |
|
|
||||||
|
|
||||||
**Outputs**:
|
|
||||||
|
|
||||||
1. **Design Document** (`<session>/design/design-<num>.md`):
|
|
||||||
- Architecture decision: approach, rationale, alternatives
|
|
||||||
- Component design: responsibility, dependencies, files, complexity
|
|
||||||
- Task breakdown: files, estimated complexity, dependencies, acceptance criteria
|
|
||||||
- Integration points and risks with mitigations
|
|
||||||
|
|
||||||
2. **Task Breakdown JSON** (`<session>/design/task-breakdown.json`):
|
|
||||||
- Array of tasks with id, title, files, complexity, dependencies, acceptance_criteria
|
|
||||||
- Execution order for developer to follow
|
|
||||||
|
|
||||||
## Phase 4: Design Validation
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| Components defined | Verify component list | At least 1 component |
|
|
||||||
| Task breakdown exists | Verify task list | At least 1 task |
|
|
||||||
| Dependencies mapped | All components have dependencies field | All present (can be empty) |
|
|
||||||
| Integration points | Verify integration section | Key integrations documented |
|
|
||||||
|
|
||||||
1. Run validation checks above
|
|
||||||
2. Write architecture_decisions entry to .msg/meta.json:
|
|
||||||
- design_id, approach, rationale, components, task_count
|
|
||||||
3. Write discoveries to wisdom/decisions.md and wisdom/conventions.md
|
|
||||||
@@ -1,73 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: DEV
|
|
||||||
inner_loop: true
|
|
||||||
message_types:
|
|
||||||
success: dev_complete
|
|
||||||
progress: dev_progress
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Developer
|
|
||||||
|
|
||||||
Code implementer. Implements code according to design, incremental delivery. Acts as Generator in Generator-Critic loop (paired with reviewer).
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
| Design document | <session>/design/design-001.md | For non-fix tasks |
|
|
||||||
| Task breakdown | <session>/design/task-breakdown.json | For non-fix tasks |
|
|
||||||
| Review feedback | <session>/review/*.md | For fix tasks |
|
|
||||||
| Wisdom files | <session>/wisdom/ | No |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for shared context
|
|
||||||
3. Detect task type:
|
|
||||||
|
|
||||||
| Task Type | Detection | Loading |
|
|
||||||
|-----------|-----------|---------|
|
|
||||||
| Fix task | Subject contains "fix" | Read latest review file for feedback |
|
|
||||||
| Normal task | No "fix" in subject | Read design document + task breakdown |
|
|
||||||
|
|
||||||
4. Load previous implementation_context from .msg/meta.json
|
|
||||||
5. Read wisdom files for conventions and known issues
|
|
||||||
|
|
||||||
## Phase 3: Code Implementation
|
|
||||||
|
|
||||||
**Implementation strategy selection**:
|
|
||||||
|
|
||||||
| Task Count | Complexity | Strategy |
|
|
||||||
|------------|------------|----------|
|
|
||||||
| <= 2 tasks | Low | Direct: inline Edit/Write |
|
|
||||||
| 3-5 tasks | Medium | Single agent: one code-developer for all |
|
|
||||||
| > 5 tasks | High | Batch agent: group by module, one agent per batch |
|
|
||||||
|
|
||||||
**Fix Task Mode** (GC Loop):
|
|
||||||
- Focus on review feedback items only
|
|
||||||
- Fix critical issues first, then high, then medium
|
|
||||||
- Do NOT change code that was not flagged
|
|
||||||
- Maintain existing code style and patterns
|
|
||||||
|
|
||||||
**Normal Task Mode**:
|
|
||||||
- Read target files, apply changes using Edit or Write
|
|
||||||
- Follow execution order from task breakdown
|
|
||||||
- Validate syntax after each major change
|
|
||||||
|
|
||||||
## Phase 4: Self-Validation
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| Syntax | tsc --noEmit or equivalent | No errors |
|
|
||||||
| File existence | Verify all planned files exist | All files present |
|
|
||||||
| Import resolution | Check no broken imports | All imports resolve |
|
|
||||||
|
|
||||||
1. Run syntax check: `tsc --noEmit` / `python -m py_compile` / equivalent
|
|
||||||
2. Auto-fix if validation fails (max 2 attempts)
|
|
||||||
3. Write dev log to `<session>/code/dev-log.md`:
|
|
||||||
- Changed files count, syntax status, fix task flag, file list
|
|
||||||
4. Update implementation_context in .msg/meta.json:
|
|
||||||
- task, changed_files, is_fix, syntax_clean
|
|
||||||
5. Write discoveries to wisdom/learnings.md
|
|
||||||
@@ -1,65 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: REVIEW
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: review_passed
|
|
||||||
revision: review_revision
|
|
||||||
critical: review_critical
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Reviewer
|
|
||||||
|
|
||||||
Code reviewer. Multi-dimensional review, quality scoring, improvement suggestions. Acts as Critic in Generator-Critic loop (paired with developer).
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
| Design document | <session>/design/design-001.md | For requirements alignment |
|
|
||||||
| Changed files | Git diff | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for shared context and previous review_feedback_trends
|
|
||||||
3. Read design document for requirements alignment
|
|
||||||
4. Get changed files via git diff, read file contents (limit 20 files)
|
|
||||||
|
|
||||||
## Phase 3: Multi-Dimensional Review
|
|
||||||
|
|
||||||
**Review dimensions**:
|
|
||||||
|
|
||||||
| Dimension | Weight | Focus Areas |
|
|
||||||
|-----------|--------|-------------|
|
|
||||||
| Correctness | 30% | Logic correctness, boundary handling |
|
|
||||||
| Completeness | 25% | Coverage of design requirements |
|
|
||||||
| Maintainability | 25% | Readability, code style, DRY |
|
|
||||||
| Security | 20% | Vulnerabilities, input validation |
|
|
||||||
|
|
||||||
Per-dimension: scan modified files, record findings with severity (CRITICAL/HIGH/MEDIUM/LOW), include file:line references and suggestions.
|
|
||||||
|
|
||||||
**Scoring**: Weighted average of dimension scores (1-10 each).
|
|
||||||
|
|
||||||
**Output review report** (`<session>/review/review-<num>.md`):
|
|
||||||
- Files reviewed count, quality score, issue counts by severity
|
|
||||||
- Per-finding: severity, file:line, dimension, description, suggestion
|
|
||||||
- Scoring breakdown by dimension
|
|
||||||
- Signal: CRITICAL / REVISION_NEEDED / APPROVED
|
|
||||||
- Design alignment notes
|
|
||||||
|
|
||||||
## Phase 4: Trend Analysis + Verdict
|
|
||||||
|
|
||||||
1. Compare with previous review_feedback_trends from .msg/meta.json
|
|
||||||
2. Identify recurring issues, improvement areas, new issues
|
|
||||||
|
|
||||||
| Verdict Condition | Message Type |
|
|
||||||
|-------------------|--------------|
|
|
||||||
| criticalCount > 0 | review_critical |
|
|
||||||
| score < 7 | review_revision |
|
|
||||||
| else | review_passed |
|
|
||||||
|
|
||||||
3. Update review_feedback_trends in .msg/meta.json:
|
|
||||||
- review_id, score, critical count, high count, dimensions, gc_round
|
|
||||||
4. Write discoveries to wisdom/learnings.md
|
|
||||||
@@ -1,87 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: VERIFY
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: verify_passed
|
|
||||||
failure: verify_failed
|
|
||||||
fix: fix_required
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Tester
|
|
||||||
|
|
||||||
Test validator. Test execution, fix cycles, and regression detection.
|
|
||||||
|
|
||||||
## Phase 2: 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 | Yes |
|
|
||||||
| Changed files | Git diff | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for shared context
|
|
||||||
3. Get changed files via git diff
|
|
||||||
4. Detect test framework and command:
|
|
||||||
|
|
||||||
| Detection | Method |
|
|
||||||
|-----------|--------|
|
|
||||||
| Test command | Check package.json scripts, pytest.ini, Makefile |
|
|
||||||
| Coverage tool | Check for nyc, coverage.py, jest --coverage config |
|
|
||||||
|
|
||||||
Common commands: npm test, pytest, go test ./..., cargo test
|
|
||||||
|
|
||||||
## Phase 3: Execution + Fix Cycle
|
|
||||||
|
|
||||||
**Iterative test-fix cycle** (max 5 iterations):
|
|
||||||
|
|
||||||
| Step | Action |
|
|
||||||
|------|--------|
|
|
||||||
| 1 | Run test command |
|
|
||||||
| 2 | Parse results, check pass rate |
|
|
||||||
| 3 | Pass rate >= 95% -> exit loop (success) |
|
|
||||||
| 4 | Extract failing test details |
|
|
||||||
| 5 | Apply fix using CLI tool |
|
|
||||||
| 6 | Increment iteration counter |
|
|
||||||
| 7 | iteration >= MAX (5) -> exit loop (report failures) |
|
|
||||||
| 8 | Go to Step 1 |
|
|
||||||
|
|
||||||
**Fix delegation**: Use CLI tool to fix failing tests:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ccw cli -p "PURPOSE: Fix failing tests; success = all listed tests pass
|
|
||||||
TASK: • Analyze test failure output • Identify root cause in changed files • Apply minimal fix
|
|
||||||
MODE: write
|
|
||||||
CONTEXT: @<changed-files> | Memory: Test output from current iteration
|
|
||||||
EXPECTED: Code fixes that make failing tests pass without breaking other tests
|
|
||||||
CONSTRAINTS: Only modify files in changed list | Minimal changes
|
|
||||||
Test output: <test-failure-details>
|
|
||||||
Changed files: <file-list>" --tool gemini --mode write --rule development-debug-runtime-issues
|
|
||||||
```
|
|
||||||
|
|
||||||
Wait for CLI completion before re-running tests.
|
|
||||||
|
|
||||||
## Phase 4: Regression Check + Report
|
|
||||||
|
|
||||||
1. Run full test suite for regression: `<test-command> --all`
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| Regression | Run full test suite | No FAIL in output |
|
|
||||||
| Coverage | Run coverage tool | >= 80% (if configured) |
|
|
||||||
|
|
||||||
2. Write verification results to `<session>/verify/verify-<num>.json`:
|
|
||||||
- verify_id, pass_rate, iterations, passed, timestamp, regression_passed
|
|
||||||
|
|
||||||
3. Determine message type:
|
|
||||||
|
|
||||||
| Condition | Message Type |
|
|
||||||
|-----------|--------------|
|
|
||||||
| passRate >= 0.95 | verify_passed |
|
|
||||||
| passRate < 0.95 && iterations >= MAX | fix_required |
|
|
||||||
| passRate < 0.95 | verify_failed |
|
|
||||||
|
|
||||||
4. Update .msg/meta.json with test_patterns entry
|
|
||||||
5. Write discoveries to wisdom/issues.md
|
|
||||||
@@ -1,110 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: BENCH
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: bench_complete
|
|
||||||
error: error
|
|
||||||
fix: fix_required
|
|
||||||
---
|
|
||||||
|
|
||||||
# Performance Benchmarker
|
|
||||||
|
|
||||||
Run benchmarks comparing before/after optimization metrics. Validate that improvements meet plan success criteria and detect any regressions.
|
|
||||||
|
|
||||||
## Phase 2: Environment & Baseline Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Baseline metrics | <session>/artifacts/baseline-metrics.json (shared) | Yes |
|
|
||||||
| Optimization plan / detail | Varies by mode (see below) | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. **Detect branch/pipeline context** from task description:
|
|
||||||
|
|
||||||
| Task Description Field | Value | Context |
|
|
||||||
|----------------------|-------|---------|
|
|
||||||
| `BranchId: B{NN}` | Present | Fan-out branch -- benchmark only this branch's metrics |
|
|
||||||
| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline |
|
|
||||||
| Neither present | - | Single mode -- full benchmark |
|
|
||||||
|
|
||||||
3. **Load baseline metrics**:
|
|
||||||
- Single / Fan-out: Read `<session>/artifacts/baseline-metrics.json` (shared baseline)
|
|
||||||
- Independent: Read `<session>/artifacts/pipelines/{P}/baseline-metrics.json`
|
|
||||||
|
|
||||||
4. **Load optimization context**:
|
|
||||||
- Single: Read `<session>/artifacts/optimization-plan.md` -- all success criteria
|
|
||||||
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md` -- only this branch's criteria
|
|
||||||
- Independent: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md`
|
|
||||||
|
|
||||||
5. Load .msg/meta.json for project type and optimization scope
|
|
||||||
6. Detect available benchmark tools from project:
|
|
||||||
|
|
||||||
| Signal | Benchmark Tool | Method |
|
|
||||||
|--------|---------------|--------|
|
|
||||||
| package.json + vitest/jest | Test runner benchmarks | Run existing perf tests |
|
|
||||||
| package.json + webpack/vite | Bundle analysis | Compare build output sizes |
|
|
||||||
| Cargo.toml + criterion | Rust benchmarks | cargo bench |
|
|
||||||
| go.mod | Go benchmarks | go test -bench |
|
|
||||||
| Makefile with bench target | Custom benchmarks | make bench |
|
|
||||||
| No tooling detected | Manual measurement | Timed execution via Bash |
|
|
||||||
|
|
||||||
7. Get changed files scope from shared-memory:
|
|
||||||
- Single: `optimizer` namespace
|
|
||||||
- Fan-out: `optimizer.B{NN}` namespace
|
|
||||||
- Independent: `optimizer.{P}` namespace
|
|
||||||
|
|
||||||
## Phase 3: Benchmark Execution
|
|
||||||
|
|
||||||
Run benchmarks matching detected project type:
|
|
||||||
|
|
||||||
**Frontend benchmarks**:
|
|
||||||
- Compare bundle size before/after (build output analysis)
|
|
||||||
- Measure render performance for affected components
|
|
||||||
- Check for dependency weight changes
|
|
||||||
|
|
||||||
**Backend benchmarks**:
|
|
||||||
- Measure endpoint response times for affected routes
|
|
||||||
- Profile memory usage under simulated load
|
|
||||||
- Verify database query performance improvements
|
|
||||||
|
|
||||||
**CLI / Library benchmarks**:
|
|
||||||
- Measure execution time for representative workloads
|
|
||||||
- Compare memory peak usage
|
|
||||||
- Test throughput under sustained load
|
|
||||||
|
|
||||||
**All project types**:
|
|
||||||
- Run existing test suite to verify no regressions
|
|
||||||
- Collect post-optimization metrics matching baseline format
|
|
||||||
- Calculate improvement percentages per metric
|
|
||||||
|
|
||||||
**Branch-scoped benchmarking** (fan-out mode):
|
|
||||||
- Only benchmark metrics relevant to this branch's optimization (from optimization-detail.md)
|
|
||||||
- Still check for regressions across all metrics (not just branch-specific ones)
|
|
||||||
|
|
||||||
## Phase 4: Result Analysis
|
|
||||||
|
|
||||||
Compare against baseline and plan criteria:
|
|
||||||
|
|
||||||
| Metric | Threshold | Verdict |
|
|
||||||
|--------|-----------|---------|
|
|
||||||
| Target improvement vs baseline | Meets plan success criteria | PASS |
|
|
||||||
| No regression in unrelated metrics | < 5% degradation allowed | PASS |
|
|
||||||
| All plan success criteria met | Every criterion satisfied | PASS |
|
|
||||||
| Improvement below target | > 50% of target achieved | WARN |
|
|
||||||
| Regression detected | Any unrelated metric degrades > 5% | FAIL -> fix_required |
|
|
||||||
| Plan criteria not met | Any criterion not satisfied | FAIL -> fix_required |
|
|
||||||
|
|
||||||
1. Write benchmark results to output path:
|
|
||||||
- Single: `<session>/artifacts/benchmark-results.json`
|
|
||||||
- Fan-out: `<session>/artifacts/branches/B{NN}/benchmark-results.json`
|
|
||||||
- Independent: `<session>/artifacts/pipelines/{P}/benchmark-results.json`
|
|
||||||
- Content: Per-metric: name, baseline value, current value, improvement %, verdict; Overall verdict: PASS / WARN / FAIL; Regression details (if any)
|
|
||||||
|
|
||||||
2. Update `<session>/.msg/meta.json` under scoped namespace:
|
|
||||||
- Single: merge `{ "benchmarker": { verdict, improvements, regressions } }`
|
|
||||||
- Fan-out: merge `{ "benchmarker.B{NN}": { verdict, improvements, regressions } }`
|
|
||||||
- Independent: merge `{ "benchmarker.{P}": { verdict, improvements, regressions } }`
|
|
||||||
|
|
||||||
3. If verdict is FAIL, include detailed feedback in message for FIX task creation:
|
|
||||||
- Which metrics failed, by how much, suggested investigation areas
|
|
||||||
@@ -1,102 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: IMPL
|
|
||||||
inner_loop: true
|
|
||||||
additional_prefixes: [FIX]
|
|
||||||
delegates_to: []
|
|
||||||
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 (no branch)**: Read `<session>/artifacts/optimization-plan.md` -- extract ALL priority-ordered changes
|
|
||||||
- **Fan-out branch**: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md` -- extract ONLY this branch's optimization (single OPT-ID)
|
|
||||||
- **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md` -- extract this pipeline's plan
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
**Shared-memory namespace**:
|
|
||||||
- Single: write to `optimizer` namespace
|
|
||||||
- Fan-out: write to `optimizer.B{NN}` namespace
|
|
||||||
- Independent: write to `optimizer.{P}` namespace
|
|
||||||
|
|
||||||
## 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 (from optimization-detail.md)
|
|
||||||
- **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}/`
|
|
||||||
@@ -1,73 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: PROFILE
|
|
||||||
inner_loop: false
|
|
||||||
delegates_to: []
|
|
||||||
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
|
|
||||||
@@ -1,91 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: REVIEW
|
|
||||||
inner_loop: false
|
|
||||||
additional_prefixes: [QUALITY]
|
|
||||||
discuss_rounds: [DISCUSS-REVIEW]
|
|
||||||
delegates_to: []
|
|
||||||
message_types:
|
|
||||||
success: review_complete
|
|
||||||
error: error
|
|
||||||
fix: fix_required
|
|
||||||
---
|
|
||||||
|
|
||||||
# Optimization Reviewer
|
|
||||||
|
|
||||||
Review optimization code changes for correctness, side effects, regression risks, and adherence to best practices. Provide structured verdicts with actionable feedback.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Optimization code changes | From IMPL task artifacts / git diff | Yes |
|
|
||||||
| Optimization plan / detail | Varies by mode (see below) | Yes |
|
|
||||||
| Benchmark results | Varies by mode (see below) | No |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. **Detect branch/pipeline context** from task description:
|
|
||||||
|
|
||||||
| Task Description Field | Value | Context |
|
|
||||||
|----------------------|-------|---------|
|
|
||||||
| `BranchId: B{NN}` | Present | Fan-out branch -- review only this branch's changes |
|
|
||||||
| `PipelineId: {P}` | Present | Independent pipeline -- review pipeline-scoped changes |
|
|
||||||
| Neither present | - | Single mode -- review all optimization changes |
|
|
||||||
|
|
||||||
3. **Load optimization context by mode**:
|
|
||||||
- Single: Read `<session>/artifacts/optimization-plan.md`
|
|
||||||
- Fan-out branch: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md`
|
|
||||||
- Independent: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md`
|
|
||||||
|
|
||||||
4. Load .msg/meta.json for scoped optimizer namespace:
|
|
||||||
- Single: `optimizer` namespace
|
|
||||||
- Fan-out: `optimizer.B{NN}` namespace
|
|
||||||
- Independent: `optimizer.{P}` namespace
|
|
||||||
|
|
||||||
5. Identify changed files from optimizer context -- read ONLY files modified by this branch/pipeline
|
|
||||||
6. If benchmark results available, read from scoped path:
|
|
||||||
- Single: `<session>/artifacts/benchmark-results.json`
|
|
||||||
- Fan-out: `<session>/artifacts/branches/B{NN}/benchmark-results.json`
|
|
||||||
- Independent: `<session>/artifacts/pipelines/{P}/benchmark-results.json`
|
|
||||||
|
|
||||||
## Phase 3: Multi-Dimension Review
|
|
||||||
|
|
||||||
Analyze optimization changes across five dimensions:
|
|
||||||
|
|
||||||
| Dimension | Focus | Severity |
|
|
||||||
|-----------|-------|----------|
|
|
||||||
| Correctness | Logic errors, off-by-one, race conditions, null safety | Critical |
|
|
||||||
| Side effects | Unintended behavior changes, API contract breaks, data loss | Critical |
|
|
||||||
| Maintainability | Code clarity, complexity increase, naming, documentation | High |
|
|
||||||
| Regression risk | Impact on unrelated code paths, implicit dependencies | High |
|
|
||||||
| Best practices | Idiomatic patterns, framework conventions, optimization anti-patterns | Medium |
|
|
||||||
|
|
||||||
Per-dimension review process:
|
|
||||||
- Scan modified files for patterns matching each dimension
|
|
||||||
- Record findings with severity (Critical / High / Medium / Low)
|
|
||||||
- Include specific file:line references and suggested fixes
|
|
||||||
|
|
||||||
If any Critical findings detected, use CLI tools for multi-perspective validation (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
|
|
||||||
|
|
||||||
## Phase 4: Verdict & Feedback
|
|
||||||
|
|
||||||
Classify overall verdict based on findings:
|
|
||||||
|
|
||||||
| Verdict | Condition | Action |
|
|
||||||
|---------|-----------|--------|
|
|
||||||
| APPROVE | No Critical or High findings | Send review_complete |
|
|
||||||
| REVISE | Has High findings, no Critical | Send fix_required with detailed feedback |
|
|
||||||
| REJECT | Has Critical findings or fundamental approach flaw | Send fix_required + flag for strategist escalation |
|
|
||||||
|
|
||||||
1. Write review report to scoped output path:
|
|
||||||
- Single: `<session>/artifacts/review-report.md`
|
|
||||||
- Fan-out: `<session>/artifacts/branches/B{NN}/review-report.md`
|
|
||||||
- Independent: `<session>/artifacts/pipelines/{P}/review-report.md`
|
|
||||||
- Content: Per-dimension findings with severity, file:line, description; Overall verdict with rationale; Specific fix instructions for REVISE/REJECT verdicts
|
|
||||||
|
|
||||||
2. Update `<session>/.msg/meta.json` under scoped namespace:
|
|
||||||
- Single: merge `{ "reviewer": { verdict, finding_count, critical_count, dimensions_reviewed } }`
|
|
||||||
- Fan-out: merge `{ "reviewer.B{NN}": { verdict, finding_count, critical_count, dimensions_reviewed } }`
|
|
||||||
- Independent: merge `{ "reviewer.{P}": { verdict, finding_count, critical_count, dimensions_reviewed } }`
|
|
||||||
|
|
||||||
3. If DISCUSS-REVIEW was triggered, record discussion summary in `<session>/discussions/DISCUSS-REVIEW.md` (or `DISCUSS-REVIEW-B{NN}.md` for branch-scoped discussions)
|
|
||||||
@@ -1,114 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: STRATEGY
|
|
||||||
inner_loop: false
|
|
||||||
discuss_rounds: [DISCUSS-OPT]
|
|
||||||
delegates_to: []
|
|
||||||
message_types:
|
|
||||||
success: strategy_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Optimization Strategist
|
|
||||||
|
|
||||||
Analyze bottleneck reports and baseline metrics to design a prioritized optimization plan with concrete strategies, expected improvements, and risk assessments.
|
|
||||||
|
|
||||||
## Phase 2: Analysis Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Bottleneck report | <session>/artifacts/bottleneck-report.md | Yes |
|
|
||||||
| Baseline metrics | <session>/artifacts/baseline-metrics.json | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
| Wisdom files | <session>/wisdom/patterns.md | No |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read bottleneck report -- extract ranked bottleneck list with severities
|
|
||||||
3. Read baseline metrics -- extract current performance numbers
|
|
||||||
4. Load .msg/meta.json for profiler findings (project_type, scope)
|
|
||||||
5. Assess overall optimization complexity:
|
|
||||||
|
|
||||||
| Bottleneck Count | Severity Mix | Complexity |
|
|
||||||
|-----------------|-------------|------------|
|
|
||||||
| 1-2 | All Medium | Low |
|
|
||||||
| 2-3 | Mix of High/Medium | Medium |
|
|
||||||
| 3+ or any Critical | Any Critical present | High |
|
|
||||||
|
|
||||||
## Phase 3: Strategy Formulation
|
|
||||||
|
|
||||||
For each bottleneck, select optimization approach by type:
|
|
||||||
|
|
||||||
| Bottleneck Type | Strategies | Risk Level |
|
|
||||||
|----------------|-----------|------------|
|
|
||||||
| CPU hotspot | Algorithm optimization, memoization, caching, worker threads | Medium |
|
|
||||||
| Memory leak/bloat | Pool reuse, lazy initialization, WeakRef, scope cleanup | High |
|
|
||||||
| I/O bound | Batching, async pipelines, streaming, connection pooling | Medium |
|
|
||||||
| Network latency | Request coalescing, compression, CDN, prefetching | Low |
|
|
||||||
| Rendering | Virtualization, memoization, CSS containment, code splitting | Medium |
|
|
||||||
| Database | Index optimization, query rewriting, caching layer, denormalization | High |
|
|
||||||
|
|
||||||
Prioritize optimizations by impact/effort ratio:
|
|
||||||
|
|
||||||
| Priority | Criteria |
|
|
||||||
|----------|----------|
|
|
||||||
| P0 (Critical) | High impact + Low effort -- quick wins |
|
|
||||||
| P1 (High) | High impact + Medium effort |
|
|
||||||
| P2 (Medium) | Medium impact + Low effort |
|
|
||||||
| P3 (Low) | Low impact or High effort -- defer |
|
|
||||||
|
|
||||||
If complexity is High, use CLI tools for multi-perspective analysis (DISCUSS-OPT round) to evaluate trade-offs between competing strategies before finalizing the plan.
|
|
||||||
|
|
||||||
Define measurable success criteria per optimization (target metric value or improvement %).
|
|
||||||
|
|
||||||
## Phase 4: Plan Output
|
|
||||||
|
|
||||||
1. Write optimization plan to `<session>/artifacts/optimization-plan.md`:
|
|
||||||
|
|
||||||
Each optimization MUST have a unique OPT-ID and self-contained detail block:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
### OPT-001: <title>
|
|
||||||
- Priority: P0
|
|
||||||
- Target bottleneck: <bottleneck from report>
|
|
||||||
- Target files: <file-list>
|
|
||||||
- Strategy: <selected approach>
|
|
||||||
- Expected improvement: <metric> by <X%>
|
|
||||||
- Risk level: <Low/Medium/High>
|
|
||||||
- Success criteria: <specific threshold to verify>
|
|
||||||
- Implementation guidance:
|
|
||||||
1. <step 1>
|
|
||||||
2. <step 2>
|
|
||||||
3. <step 3>
|
|
||||||
|
|
||||||
### OPT-002: <title>
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
Requirements:
|
|
||||||
- Each OPT-ID is sequentially numbered (OPT-001, OPT-002, ...)
|
|
||||||
- Each optimization must be **non-overlapping** in target files (no two OPT-IDs modify the same file unless explicitly noted with conflict resolution)
|
|
||||||
- Implementation guidance must be self-contained -- a branch optimizer should be able to work from a single OPT block without reading others
|
|
||||||
|
|
||||||
2. Update `<session>/.msg/meta.json` under `strategist` namespace:
|
|
||||||
- Read existing -> merge -> write back:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"strategist": {
|
|
||||||
"complexity": "<Low|Medium|High>",
|
|
||||||
"optimization_count": 4,
|
|
||||||
"priorities": ["P0", "P0", "P1", "P2"],
|
|
||||||
"discuss_used": false,
|
|
||||||
"optimizations": [
|
|
||||||
{
|
|
||||||
"id": "OPT-001",
|
|
||||||
"title": "<title>",
|
|
||||||
"priority": "P0",
|
|
||||||
"target_files": ["src/a.ts", "src/b.ts"],
|
|
||||||
"expected_improvement": "<metric> by <X%>",
|
|
||||||
"success_criteria": "<threshold>"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
3. If DISCUSS-OPT was triggered, record discussion summary in `<session>/discussions/DISCUSS-OPT.md`
|
|
||||||
@@ -73,7 +73,7 @@ Agent({
|
|||||||
run_in_background: true,
|
run_in_background: true,
|
||||||
prompt: `## Role Assignment
|
prompt: `## Role Assignment
|
||||||
role: <role>
|
role: <role>
|
||||||
role_spec: ~ or <project>/.claude/skills/team-perf-opt/role-specs/<role>.md
|
role_spec: ~ or <project>/.claude/skills/team-perf-opt/roles/<role>/role.md
|
||||||
session: <session-folder>
|
session: <session-folder>
|
||||||
session_id: <session-id>
|
session_id: <session-id>
|
||||||
team_name: perf-opt
|
team_name: perf-opt
|
||||||
|
|||||||
@@ -24,7 +24,7 @@
|
|||||||
"name": "profiler",
|
"name": "profiler",
|
||||||
"type": "orchestration",
|
"type": "orchestration",
|
||||||
"description": "Profiles application performance, identifies CPU/memory/IO/network/rendering bottlenecks",
|
"description": "Profiles application performance, identifies CPU/memory/IO/network/rendering bottlenecks",
|
||||||
"role_spec": "role-specs/profiler.md",
|
"role_spec": "roles/profiler/role.md",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "PROFILE",
|
"prefix": "PROFILE",
|
||||||
@@ -44,7 +44,7 @@
|
|||||||
"name": "strategist",
|
"name": "strategist",
|
||||||
"type": "orchestration",
|
"type": "orchestration",
|
||||||
"description": "Analyzes bottleneck reports, designs prioritized optimization plans with concrete strategies",
|
"description": "Analyzes bottleneck reports, designs prioritized optimization plans with concrete strategies",
|
||||||
"role_spec": "role-specs/strategist.md",
|
"role_spec": "roles/strategist/role.md",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "STRATEGY",
|
"prefix": "STRATEGY",
|
||||||
@@ -64,7 +64,7 @@
|
|||||||
"name": "optimizer",
|
"name": "optimizer",
|
||||||
"type": "code_generation",
|
"type": "code_generation",
|
||||||
"description": "Implements optimization changes following the strategy plan",
|
"description": "Implements optimization changes following the strategy plan",
|
||||||
"role_spec": "role-specs/optimizer.md",
|
"role_spec": "roles/optimizer/role.md",
|
||||||
"inner_loop": true,
|
"inner_loop": true,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "IMPL",
|
"prefix": "IMPL",
|
||||||
@@ -85,7 +85,7 @@
|
|||||||
"name": "benchmarker",
|
"name": "benchmarker",
|
||||||
"type": "validation",
|
"type": "validation",
|
||||||
"description": "Runs benchmarks, compares before/after metrics, validates performance improvements",
|
"description": "Runs benchmarks, compares before/after metrics, validates performance improvements",
|
||||||
"role_spec": "role-specs/benchmarker.md",
|
"role_spec": "roles/benchmarker/role.md",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "BENCH",
|
"prefix": "BENCH",
|
||||||
@@ -106,7 +106,7 @@
|
|||||||
"name": "reviewer",
|
"name": "reviewer",
|
||||||
"type": "read_only_analysis",
|
"type": "read_only_analysis",
|
||||||
"description": "Reviews optimization code for correctness, side effects, and regression risks",
|
"description": "Reviews optimization code for correctness, side effects, and regression risks",
|
||||||
"role_spec": "role-specs/reviewer.md",
|
"role_spec": "roles/reviewer/role.md",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"frontmatter": {
|
"frontmatter": {
|
||||||
"prefix": "REVIEW",
|
"prefix": "REVIEW",
|
||||||
|
|||||||
@@ -1,90 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: EXEC
|
|
||||||
inner_loop: true
|
|
||||||
message_types:
|
|
||||||
success: impl_complete
|
|
||||||
error: impl_failed
|
|
||||||
---
|
|
||||||
|
|
||||||
# Executor
|
|
||||||
|
|
||||||
Single-issue implementation agent. Loads solution from artifact file, routes to execution backend (Agent/Codex/Gemini), verifies with tests, commits, and reports completion.
|
|
||||||
|
|
||||||
## Phase 2: Task & Solution Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Issue ID | Task description `Issue ID:` field | Yes |
|
|
||||||
| Solution file | Task description `Solution file:` field | Yes |
|
|
||||||
| Session folder | Task description `Session:` field | Yes |
|
|
||||||
| Execution method | Task description `Execution method:` field | Yes |
|
|
||||||
| Wisdom | `<session>/wisdom/` | No |
|
|
||||||
|
|
||||||
1. Extract issue ID, solution file path, session folder, execution method
|
|
||||||
2. Load solution JSON from file (file-first)
|
|
||||||
3. If file not found -> fallback: `ccw issue solution <issueId> --json`
|
|
||||||
4. Load wisdom files for conventions and patterns
|
|
||||||
5. Verify solution has required fields: title, tasks
|
|
||||||
|
|
||||||
## Phase 3: Implementation
|
|
||||||
|
|
||||||
### Backend Selection
|
|
||||||
|
|
||||||
| Method | Backend | CLI Tool |
|
|
||||||
|--------|---------|----------|
|
|
||||||
| `codex` | `ccw cli --tool codex --mode write` | Background CLI |
|
|
||||||
| `gemini` | `ccw cli --tool gemini --mode write` | Background CLI |
|
|
||||||
|
|
||||||
### CLI Backend (Codex/Gemini)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ccw cli -p "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass
|
|
||||||
TASK: <solution.tasks as bullet points>
|
|
||||||
MODE: write
|
|
||||||
CONTEXT: @**/* | Memory: Session wisdom from <session>/wisdom/
|
|
||||||
EXPECTED: Working implementation with: code changes, test updates, no syntax errors
|
|
||||||
CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
|
|
||||||
Issue: <issueId>
|
|
||||||
Title: <solution.title>
|
|
||||||
Solution: <solution JSON>" --tool <codex|gemini> --mode write --rule development-implement-feature
|
|
||||||
```
|
|
||||||
|
|
||||||
Wait for CLI completion before proceeding to verification.
|
|
||||||
|
|
||||||
## Phase 4: Verification + Commit
|
|
||||||
|
|
||||||
### Test Verification
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| Tests | Detect and run project test command | All pass |
|
|
||||||
| Syntax | IDE diagnostics or `tsc --noEmit` | No errors |
|
|
||||||
|
|
||||||
If tests fail: retry implementation once, then report `impl_failed`.
|
|
||||||
|
|
||||||
### Commit
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add -A
|
|
||||||
git commit -m "feat(<issueId>): <solution.title>"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Update Issue Status
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ccw issue update <issueId> --status completed
|
|
||||||
```
|
|
||||||
|
|
||||||
### Report
|
|
||||||
|
|
||||||
Send `impl_complete` message to coordinator via team_msg + SendMessage.
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
| Allowed | Prohibited |
|
|
||||||
|---------|-----------|
|
|
||||||
| Load solution from file | Create or modify issues |
|
|
||||||
| Implement via CLI tools (Codex/Gemini) | Modify solution artifacts |
|
|
||||||
| Run tests | Spawn additional agents (use CLI tools instead) |
|
|
||||||
| git commit | Direct user interaction |
|
|
||||||
| Update issue status | Create tasks for other roles |
|
|
||||||
@@ -1,110 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: PLAN
|
|
||||||
inner_loop: true
|
|
||||||
message_types:
|
|
||||||
success: issue_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Planner
|
|
||||||
|
|
||||||
Requirement decomposition → issue creation → solution design → EXEC-* task creation. Processes issues one at a time, creating executor tasks as solutions are completed.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Input type + raw input | Task description | Yes |
|
|
||||||
| Session folder | Task description `Session:` field | Yes |
|
|
||||||
| Execution method | Task description `Execution method:` field | Yes |
|
|
||||||
| Wisdom | `<session>/wisdom/` | No |
|
|
||||||
|
|
||||||
1. Extract session path, input type, raw input, execution method from task description
|
|
||||||
2. Load wisdom files if available
|
|
||||||
3. Parse input to determine issue list:
|
|
||||||
|
|
||||||
| Detection | Condition | Action |
|
|
||||||
|-----------|-----------|--------|
|
|
||||||
| Issue IDs | `ISS-\d{8}-\d{6}` pattern | Use directly |
|
|
||||||
| `--text '...'` | Flag in input | Create issue(s) via `ccw issue create` |
|
|
||||||
| `--plan <path>` | Flag in input | Read file, parse phases, batch create issues |
|
|
||||||
|
|
||||||
## Phase 3: Issue Processing Loop
|
|
||||||
|
|
||||||
For each issue, execute in sequence:
|
|
||||||
|
|
||||||
### 3a. Generate Solution
|
|
||||||
|
|
||||||
Use CLI tool for issue planning:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ccw cli -p "PURPOSE: Generate implementation solution for issue <issueId>; success = actionable task breakdown with file paths
|
|
||||||
TASK: • Load issue details • Analyze requirements • Design solution approach • Break down into implementation tasks • Identify files to modify/create
|
|
||||||
MODE: analysis
|
|
||||||
CONTEXT: @**/* | Memory: Session context from <session>/wisdom/
|
|
||||||
EXPECTED: JSON solution with: title, description, tasks array (each with description, files_touched), estimated_complexity
|
|
||||||
CONSTRAINTS: Follow project patterns | Reference existing implementations
|
|
||||||
" --tool gemini --mode analysis --rule planning-breakdown-task-steps
|
|
||||||
```
|
|
||||||
|
|
||||||
Parse CLI output to extract solution JSON. If CLI fails, fallback to `ccw issue solution <issueId> --json`.
|
|
||||||
|
|
||||||
### 3b. Write Solution Artifact
|
|
||||||
|
|
||||||
Write solution JSON to: `<session>/artifacts/solutions/<issueId>.json`
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"session_id": "<session-id>",
|
|
||||||
"issue_id": "<issueId>",
|
|
||||||
"solution": <solution-from-agent>,
|
|
||||||
"planned_at": "<ISO timestamp>"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3c. Check Conflicts
|
|
||||||
|
|
||||||
Extract `files_touched` from solution. Compare against prior solutions in session.
|
|
||||||
Overlapping files -> log warning to `wisdom/issues.md`, continue.
|
|
||||||
|
|
||||||
### 3d. Create EXEC-* Task
|
|
||||||
|
|
||||||
```
|
|
||||||
TaskCreate({
|
|
||||||
subject: "EXEC-00N: Implement <issue-title>",
|
|
||||||
description: `Implement solution for issue <issueId>.
|
|
||||||
|
|
||||||
Issue ID: <issueId>
|
|
||||||
Solution file: <session>/artifacts/solutions/<issueId>.json
|
|
||||||
Session: <session>
|
|
||||||
Execution method: <method>
|
|
||||||
|
|
||||||
InnerLoop: true`,
|
|
||||||
activeForm: "Implementing <issue-title>"
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3e. Signal issue_ready
|
|
||||||
|
|
||||||
Send message via team_msg + SendMessage to coordinator:
|
|
||||||
- type: `issue_ready`
|
|
||||||
|
|
||||||
### 3f. Continue Loop
|
|
||||||
|
|
||||||
Process next issue. Do NOT wait for executor.
|
|
||||||
|
|
||||||
## Phase 4: Completion Signal
|
|
||||||
|
|
||||||
After all issues processed:
|
|
||||||
1. Send `all_planned` message to coordinator via team_msg + SendMessage
|
|
||||||
2. Summary: total issues planned, EXEC-* tasks created
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
| Allowed | Prohibited |
|
|
||||||
|---------|-----------|
|
|
||||||
| Parse input, create issues | Write/modify business code |
|
|
||||||
| Generate solutions (issue-plan-agent) | Run tests |
|
|
||||||
| Write solution artifacts | git commit |
|
|
||||||
| Create EXEC-* tasks | Call code-developer |
|
|
||||||
| Conflict checking | Direct user interaction |
|
|
||||||
@@ -1,79 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: QAANA
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: analysis_ready
|
|
||||||
report: quality_report
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Quality Analyst
|
|
||||||
|
|
||||||
Analyze defect patterns, coverage gaps, test effectiveness, and generate comprehensive quality reports. Maintain defect pattern database and provide quality scoring.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
| Discovered issues | meta.json -> discovered_issues | No |
|
|
||||||
| Test strategy | meta.json -> test_strategy | No |
|
|
||||||
| Generated tests | meta.json -> generated_tests | No |
|
|
||||||
| Execution results | meta.json -> execution_results | No |
|
|
||||||
| Historical patterns | meta.json -> defect_patterns | No |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for all accumulated QA data
|
|
||||||
3. Read coverage data from `coverage/coverage-summary.json` if available
|
|
||||||
4. Read layer execution results from `<session>/results/run-*.json`
|
|
||||||
5. Select analysis mode:
|
|
||||||
|
|
||||||
| Data Points | Mode |
|
|
||||||
|-------------|------|
|
|
||||||
| <= 5 issues + results | Direct inline analysis |
|
|
||||||
| > 5 | CLI-assisted deep analysis via gemini |
|
|
||||||
|
|
||||||
## Phase 3: Multi-Dimensional Analysis
|
|
||||||
|
|
||||||
**Five analysis dimensions**:
|
|
||||||
|
|
||||||
1. **Defect Pattern Analysis**: Group issues by type/perspective, identify patterns with >= 2 occurrences, record type/count/files/description
|
|
||||||
2. **Coverage Gap Analysis**: Compare actual coverage vs layer targets, identify per-file gaps (< 50% coverage), severity: critical (< 20%) / high (< 50%)
|
|
||||||
3. **Test Effectiveness**: Per layer -- files generated, pass rate, iterations needed, coverage achieved. Effective = pass_rate >= 95% AND iterations <= 2
|
|
||||||
4. **Quality Trend**: Compare against coverage_history. Trend: improving (delta > 5%), declining (delta < -5%), stable
|
|
||||||
5. **Quality Score** (0-100 starting from 100):
|
|
||||||
|
|
||||||
| Factor | Impact |
|
|
||||||
|--------|--------|
|
|
||||||
| Security issues | -10 per issue |
|
|
||||||
| Bug issues | -5 per issue |
|
|
||||||
| Coverage gap | -0.5 per gap percentage |
|
|
||||||
| Test failures | -(100 - pass_rate) * 0.3 per layer |
|
|
||||||
| Effective test layers | +5 per layer |
|
|
||||||
| Improving trend | +3 |
|
|
||||||
|
|
||||||
For CLI-assisted mode:
|
|
||||||
```
|
|
||||||
PURPOSE: Deep quality analysis on QA results to identify defect patterns and improvement opportunities
|
|
||||||
TASK: Classify defects by root cause, identify high-density files, analyze coverage gaps vs risk, generate recommendations
|
|
||||||
MODE: analysis
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 4: Report Generation & Output
|
|
||||||
|
|
||||||
1. Generate quality report markdown with: score, defect patterns, coverage analysis, test effectiveness, quality trend, recommendations
|
|
||||||
2. Write report to `<session>/analysis/quality-report.md`
|
|
||||||
3. Update `<session>/wisdom/.msg/meta.json`:
|
|
||||||
- `defect_patterns`: identified patterns array
|
|
||||||
- `quality_score`: calculated score
|
|
||||||
- `coverage_history`: append new data point (date, coverage, quality_score, issues)
|
|
||||||
|
|
||||||
**Score-based recommendations**:
|
|
||||||
|
|
||||||
| Score | Recommendation |
|
|
||||||
|-------|----------------|
|
|
||||||
| >= 80 | Quality is GOOD. Maintain current testing practices. |
|
|
||||||
| 60-79 | Quality needs IMPROVEMENT. Focus on coverage gaps and recurring patterns. |
|
|
||||||
| < 60 | Quality is CONCERNING. Recommend comprehensive review and testing effort. |
|
|
||||||
@@ -1,64 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: QARUN
|
|
||||||
inner_loop: true
|
|
||||||
additional_prefixes: [QARUN-gc]
|
|
||||||
message_types:
|
|
||||||
success: tests_passed
|
|
||||||
failure: tests_failed
|
|
||||||
coverage: coverage_report
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Test Executor
|
|
||||||
|
|
||||||
Run test suites, collect coverage data, and perform automatic fix cycles when tests fail. Implements the execution side of the Generator-Executor (GC) loop.
|
|
||||||
|
|
||||||
## Phase 2: Environment Detection
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
| Test strategy | meta.json -> test_strategy | Yes |
|
|
||||||
| Generated tests | meta.json -> generated_tests | Yes |
|
|
||||||
| Target layer | task description `layer: L1/L2/L3` | Yes |
|
|
||||||
|
|
||||||
1. Extract session path and target layer from task description
|
|
||||||
2. Read .msg/meta.json for strategy and generated test file list
|
|
||||||
3. Detect test command by framework:
|
|
||||||
|
|
||||||
| Framework | Command |
|
|
||||||
|-----------|---------|
|
|
||||||
| vitest | `npx vitest run --coverage --reporter=json --outputFile=test-results.json` |
|
|
||||||
| jest | `npx jest --coverage --json --outputFile=test-results.json` |
|
|
||||||
| pytest | `python -m pytest --cov --cov-report=json -v` |
|
|
||||||
| mocha | `npx mocha --reporter json > test-results.json` |
|
|
||||||
| unknown | `npm test -- --coverage` |
|
|
||||||
|
|
||||||
4. Get test files from `generated_tests[targetLayer].files`
|
|
||||||
|
|
||||||
## Phase 3: Iterative Test-Fix Cycle
|
|
||||||
|
|
||||||
**Max iterations**: 5. **Pass threshold**: 95% or all tests pass.
|
|
||||||
|
|
||||||
Per iteration:
|
|
||||||
1. Run test command, capture output
|
|
||||||
2. Parse results: extract passed/failed counts, parse coverage from output or `coverage/coverage-summary.json`
|
|
||||||
3. If all pass (0 failures) -> exit loop (success)
|
|
||||||
4. If pass rate >= 95% and iteration >= 2 -> exit loop (good enough)
|
|
||||||
5. If iteration >= MAX -> exit loop (report current state)
|
|
||||||
6. Extract failure details (error lines, assertion failures)
|
|
||||||
7. Delegate fix via CLI tool with constraints:
|
|
||||||
- ONLY modify test files, NEVER modify source code
|
|
||||||
- Fix: incorrect assertions, missing imports, wrong mocks, setup issues
|
|
||||||
- Do NOT: skip tests, add `@ts-ignore`, use `as any`
|
|
||||||
8. Increment iteration, repeat
|
|
||||||
|
|
||||||
## Phase 4: Result Analysis & Output
|
|
||||||
|
|
||||||
1. Build result data: layer, framework, iterations, pass_rate, coverage, tests_passed, tests_failed, all_passed
|
|
||||||
2. Save results to `<session>/results/run-<layer>.json`
|
|
||||||
3. Save last test output to `<session>/results/output-<layer>.txt`
|
|
||||||
4. Update `<session>/wisdom/.msg/meta.json` under `execution_results[layer]` and top-level `execution_results.pass_rate`, `execution_results.coverage`
|
|
||||||
5. Message type: `tests_passed` if all_passed, else `tests_failed`
|
|
||||||
@@ -1,67 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: QAGEN
|
|
||||||
inner_loop: false
|
|
||||||
additional_prefixes: [QAGEN-fix]
|
|
||||||
message_types:
|
|
||||||
success: tests_generated
|
|
||||||
revised: tests_revised
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Test Generator
|
|
||||||
|
|
||||||
Generate test code according to strategist's strategy and layers. Support L1 unit tests, L2 integration tests, L3 E2E tests. Follow project's existing test patterns and framework conventions.
|
|
||||||
|
|
||||||
## Phase 2: Strategy & Pattern Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
| Test strategy | meta.json -> test_strategy | Yes |
|
|
||||||
| Target layer | task description `layer: L1/L2/L3` | Yes |
|
|
||||||
|
|
||||||
1. Extract session path and target layer from task description
|
|
||||||
2. Read .msg/meta.json for test strategy (layers, coverage targets)
|
|
||||||
3. Determine if this is a GC fix task (subject contains "fix")
|
|
||||||
4. Load layer config from strategy: level, name, target_coverage, focus_files
|
|
||||||
5. Learn existing test patterns -- find 3 similar test files via Glob(`**/*.{test,spec}.{ts,tsx,js,jsx}`)
|
|
||||||
6. Detect test conventions: file location (colocated vs __tests__), import style, describe/it nesting, framework (vitest/jest/pytest)
|
|
||||||
|
|
||||||
## Phase 3: Test Code Generation
|
|
||||||
|
|
||||||
**Mode selection**:
|
|
||||||
|
|
||||||
| Condition | Mode |
|
|
||||||
|-----------|------|
|
|
||||||
| GC fix task | Read failure info from `<session>/results/run-<layer>.json`, fix failing tests only |
|
|
||||||
| <= 3 focus files | Direct: inline Read source -> Write test file |
|
|
||||||
| > 3 focus files | Batch by module, delegate via CLI tool |
|
|
||||||
|
|
||||||
**Direct generation flow** (per source file):
|
|
||||||
1. Read source file content, extract exports
|
|
||||||
2. Determine test file path following project conventions
|
|
||||||
3. If test exists -> analyze missing cases -> append new tests via Edit
|
|
||||||
4. If no test -> generate full test file via Write
|
|
||||||
5. Include: happy path, edge cases, error cases per export
|
|
||||||
|
|
||||||
**GC fix flow**:
|
|
||||||
1. Read execution results and failure output from results directory
|
|
||||||
2. Read each failing test file
|
|
||||||
3. Fix assertions, imports, mocks, or test setup
|
|
||||||
4. Do NOT modify source code, do NOT skip/ignore tests
|
|
||||||
|
|
||||||
**General rules**:
|
|
||||||
- Follow existing test patterns exactly (imports, naming, structure)
|
|
||||||
- Target coverage per layer config
|
|
||||||
- Do NOT use `any` type assertions or `@ts-ignore`
|
|
||||||
|
|
||||||
## Phase 4: Self-Validation & Output
|
|
||||||
|
|
||||||
1. Collect generated/modified test files
|
|
||||||
2. Run syntax check (TypeScript: `tsc --noEmit`, or framework-specific)
|
|
||||||
3. Auto-fix syntax errors (max 3 attempts)
|
|
||||||
4. Write test metadata to `<session>/wisdom/.msg/meta.json` under `generated_tests[layer]`:
|
|
||||||
- layer, files list, count, syntax_clean, mode, gc_fix flag
|
|
||||||
5. Message type: `tests_generated` for new, `tests_revised` for GC fix iterations
|
|
||||||
@@ -1,66 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: SCOUT
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: scan_ready
|
|
||||||
error: error
|
|
||||||
issues: issues_found
|
|
||||||
---
|
|
||||||
|
|
||||||
# Multi-Perspective Scout
|
|
||||||
|
|
||||||
Scan codebase from multiple perspectives (bug, security, test-coverage, code-quality, UX) to discover potential issues. Produce structured scan results with severity-ranked findings.
|
|
||||||
|
|
||||||
## Phase 2: Context & Scope Assessment
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path and target scope from task description
|
|
||||||
2. Determine scan scope: explicit scope from task or `**/*` default
|
|
||||||
3. Get recent changed files: `git diff --name-only HEAD~5 2>/dev/null || echo ""`
|
|
||||||
4. Read .msg/meta.json for historical defect patterns (`defect_patterns`)
|
|
||||||
5. Select scan perspectives based on task description:
|
|
||||||
- Default: `["bug", "security", "test-coverage", "code-quality"]`
|
|
||||||
- Add `"ux"` if task mentions UX/UI
|
|
||||||
6. Assess complexity to determine scan strategy:
|
|
||||||
|
|
||||||
| Complexity | Condition | Strategy |
|
|
||||||
|------------|-----------|----------|
|
|
||||||
| Low | < 5 changed files, no specific keywords | ACE search + Grep inline |
|
|
||||||
| Medium | 5-15 files or specific perspective requested | CLI fan-out (3 core perspectives) |
|
|
||||||
| High | > 15 files or full-project scan | CLI fan-out (all perspectives) |
|
|
||||||
|
|
||||||
## Phase 3: Multi-Perspective Scan
|
|
||||||
|
|
||||||
**Low complexity**: Use `mcp__ace-tool__search_context` for quick pattern-based scan.
|
|
||||||
|
|
||||||
**Medium/High complexity**: CLI fan-out -- one `ccw cli --mode analysis` per perspective:
|
|
||||||
|
|
||||||
For each active perspective, build prompt:
|
|
||||||
```
|
|
||||||
PURPOSE: Scan code from <perspective> perspective to discover potential issues
|
|
||||||
TASK: Analyze code patterns for <perspective> problems, identify anti-patterns, check for common issues
|
|
||||||
MODE: analysis
|
|
||||||
CONTEXT: @<scan-scope>
|
|
||||||
EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
|
|
||||||
CONSTRAINTS: Focus on actionable findings only
|
|
||||||
```
|
|
||||||
Execute via: `ccw cli -p "<prompt>" --tool gemini --mode analysis`
|
|
||||||
|
|
||||||
After all perspectives complete:
|
|
||||||
- Parse CLI outputs into structured findings
|
|
||||||
- Deduplicate by file:line (merge perspectives for same location)
|
|
||||||
- Compare against known defect patterns from .msg/meta.json
|
|
||||||
- Rank by severity: critical > high > medium > low
|
|
||||||
|
|
||||||
## Phase 4: Result Aggregation
|
|
||||||
|
|
||||||
1. Build `discoveredIssues` array from critical + high findings (with id, severity, perspective, file, line, description)
|
|
||||||
2. Write scan results to `<session>/scan/scan-results.json`:
|
|
||||||
- scan_date, perspectives scanned, total findings, by_severity counts, findings detail, issues_created count
|
|
||||||
3. Update `<session>/wisdom/.msg/meta.json`: merge `discovered_issues` field
|
|
||||||
4. Contribute to wisdom/issues.md if new patterns found
|
|
||||||
@@ -1,70 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: QASTRAT
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: strategy_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Test Strategist
|
|
||||||
|
|
||||||
Analyze change scope, determine test layers (L1-L3), define coverage targets, and generate test strategy document. Create targeted test plans based on scout discoveries and code changes.
|
|
||||||
|
|
||||||
## Phase 2: Context & Change Analysis
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
| Discovered issues | meta.json -> discovered_issues | No |
|
|
||||||
| Defect patterns | meta.json -> defect_patterns | No |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for scout discoveries and historical patterns
|
|
||||||
3. Analyze change scope: `git diff --name-only HEAD~5`
|
|
||||||
4. Categorize changed files:
|
|
||||||
|
|
||||||
| Category | Pattern |
|
|
||||||
|----------|---------|
|
|
||||||
| Source | `\.(ts|tsx|js|jsx|py|java|go|rs)$` |
|
|
||||||
| Test | `\.(test|spec)\.(ts|tsx|js|jsx)$` or `test_` |
|
|
||||||
| Config | `\.(json|yaml|yml|toml|env)$` |
|
|
||||||
|
|
||||||
5. Detect test framework from package.json / project files
|
|
||||||
6. Check existing coverage baseline from `coverage/coverage-summary.json`
|
|
||||||
7. Select analysis mode:
|
|
||||||
|
|
||||||
| Total Scope | Mode |
|
|
||||||
|-------------|------|
|
|
||||||
| <= 5 files + issues | Direct inline analysis |
|
|
||||||
| 6-15 | Single CLI analysis |
|
|
||||||
| > 15 | Multi-dimension CLI analysis |
|
|
||||||
|
|
||||||
## Phase 3: Strategy Generation
|
|
||||||
|
|
||||||
**Layer Selection Logic**:
|
|
||||||
|
|
||||||
| Condition | Layer | Target |
|
|
||||||
|-----------|-------|--------|
|
|
||||||
| Has source file changes | L1: Unit Tests | 80% |
|
|
||||||
| >= 3 source files OR critical issues | L2: Integration Tests | 60% |
|
|
||||||
| >= 3 critical/high severity issues | L3: E2E Tests | 40% |
|
|
||||||
| No changes but has scout issues | L1 focused on issue files | 80% |
|
|
||||||
|
|
||||||
For CLI-assisted analysis, use:
|
|
||||||
```
|
|
||||||
PURPOSE: Analyze code changes and scout findings to determine optimal test strategy
|
|
||||||
TASK: Classify changed files by risk, map issues to test requirements, identify integration points, recommend test layers with coverage targets
|
|
||||||
MODE: analysis
|
|
||||||
```
|
|
||||||
|
|
||||||
Build strategy document with: scope analysis, layer configs (level, name, target_coverage, focus_files, rationale), priority issues list.
|
|
||||||
|
|
||||||
**Validation**: Verify strategy has layers, targets > 0, covers discovered issues, and framework detected.
|
|
||||||
|
|
||||||
## Phase 4: Output & Persistence
|
|
||||||
|
|
||||||
1. Write strategy to `<session>/strategy/test-strategy.md`
|
|
||||||
2. Update `<session>/wisdom/.msg/meta.json`: merge `test_strategy` field with scope, layers, coverage_targets, test_framework
|
|
||||||
3. Contribute to wisdom/decisions.md with layer selection rationale
|
|
||||||
@@ -1,75 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: FIX
|
|
||||||
inner_loop: true
|
|
||||||
message_types:
|
|
||||||
success: fix_complete
|
|
||||||
error: fix_failed
|
|
||||||
---
|
|
||||||
|
|
||||||
# Code Fixer
|
|
||||||
|
|
||||||
Fix code based on reviewed findings. Load manifest, plan fix groups, apply with rollback-on-failure, verify. Code-generation role -- modifies source files.
|
|
||||||
|
|
||||||
## Phase 2: Context & Scope Resolution
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Fix manifest | <session>/fix/fix-manifest.json | Yes |
|
|
||||||
| Review report | <session>/review/review-report.json | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path, input path from task description
|
|
||||||
2. Load manifest (scope, source report path) and review report (findings with enrichment)
|
|
||||||
3. Filter fixable findings: severity in scope AND fix_strategy !== 'skip'
|
|
||||||
4. If 0 fixable -> report complete immediately
|
|
||||||
5. Detect quick path: findings <= 5 AND no cross-file dependencies
|
|
||||||
6. Detect verification tools: tsc (tsconfig.json), eslint (package.json), jest (package.json), pytest (pyproject.toml), semgrep (semgrep available)
|
|
||||||
7. Load wisdom files from `<session>/wisdom/`
|
|
||||||
|
|
||||||
## Phase 3: Plan + Execute
|
|
||||||
|
|
||||||
### 3A: Plan Fixes (deterministic, no CLI)
|
|
||||||
1. Group findings by primary file
|
|
||||||
2. Merge groups with cross-file dependencies (union-find)
|
|
||||||
3. Topological sort within each group (respect fix_dependencies, append cycles at end)
|
|
||||||
4. Sort groups by max severity (critical first)
|
|
||||||
5. Determine execution path: quick_path (<=5 findings, <=1 group) or standard
|
|
||||||
6. Write `<session>/fix/fix-plan.json`: `{plan_id, quick_path, groups[{id, files[], findings[], max_severity}], execution_order[], total_findings, total_groups}`
|
|
||||||
|
|
||||||
### 3B: Execute Fixes
|
|
||||||
**Quick path**: Single code-developer agent for all findings.
|
|
||||||
**Standard path**: One code-developer agent per group, in execution_order.
|
|
||||||
|
|
||||||
Agent prompt includes: finding list (dependency-sorted), file contents (truncated 8K), critical rules:
|
|
||||||
1. Apply each fix using Edit tool in order
|
|
||||||
2. After each fix, run related tests
|
|
||||||
3. Tests PASS -> finding is "fixed"
|
|
||||||
4. Tests FAIL -> `git checkout -- {file}` -> mark "failed" -> continue
|
|
||||||
5. No retry on failure. Rollback and move on
|
|
||||||
6. If finding depends on previously failed finding -> mark "skipped"
|
|
||||||
|
|
||||||
Agent returns JSON: `{results:[{id, status: fixed|failed|skipped, file, error?}]}`
|
|
||||||
Fallback: check git diff per file if no structured output.
|
|
||||||
|
|
||||||
Write `<session>/fix/execution-results.json`: `{fixed[], failed[], skipped[]}`
|
|
||||||
|
|
||||||
## Phase 4: Post-Fix Verification
|
|
||||||
|
|
||||||
1. Run available verification tools on modified files:
|
|
||||||
|
|
||||||
| Tool | Command | Pass Criteria |
|
|
||||||
|------|---------|---------------|
|
|
||||||
| tsc | `npx tsc --noEmit` | 0 errors |
|
|
||||||
| eslint | `npx eslint <files>` | 0 errors |
|
|
||||||
| jest | `npx jest --passWithNoTests` | Tests pass |
|
|
||||||
| pytest | `pytest --tb=short` | Tests pass |
|
|
||||||
| semgrep | `semgrep --config auto <files> --json` | 0 results |
|
|
||||||
|
|
||||||
2. If verification fails critically -> rollback last batch
|
|
||||||
3. Write `<session>/fix/verify-results.json`
|
|
||||||
4. Generate `<session>/fix/fix-summary.json`: `{fix_id, fix_date, scope, total, fixed, failed, skipped, fix_rate, verification}`
|
|
||||||
5. Generate `<session>/fix/fix-summary.md` (human-readable)
|
|
||||||
6. Update `<session>/.msg/meta.json` with fix results
|
|
||||||
7. Contribute discoveries to `<session>/wisdom/` files
|
|
||||||
@@ -1,66 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: REV
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: review_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Finding Reviewer
|
|
||||||
|
|
||||||
Deep analysis on scan findings: triage, root cause / impact / optimization enrichment via CLI fan-out, cross-correlation, and structured review report generation. Read-only -- never modifies source code.
|
|
||||||
|
|
||||||
## Phase 2: Context & Triage
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Scan results | <session>/scan/scan-results.json | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path, input path, dimensions from task description
|
|
||||||
2. Load scan results. If missing or empty -> report clean, complete immediately
|
|
||||||
3. Load wisdom files from `<session>/wisdom/`
|
|
||||||
4. Triage findings into two buckets:
|
|
||||||
|
|
||||||
| Bucket | Criteria | Action |
|
|
||||||
|--------|----------|--------|
|
|
||||||
| deep_analysis | severity in [critical, high, medium], max 15, sorted critical-first | Enrich with root cause, impact, optimization |
|
|
||||||
| pass_through | remaining (low, info, or overflow) | Include in report without enrichment |
|
|
||||||
|
|
||||||
If deep_analysis empty -> skip Phase 3, go to Phase 4.
|
|
||||||
|
|
||||||
## Phase 3: Deep Analysis (CLI Fan-out)
|
|
||||||
|
|
||||||
Split deep_analysis into two domain groups, run parallel CLI agents:
|
|
||||||
|
|
||||||
| Group | Dimensions | Focus |
|
|
||||||
|-------|-----------|-------|
|
|
||||||
| A | Security + Correctness | Root cause tracing, fix dependencies, blast radius |
|
|
||||||
| B | Performance + Maintainability | Optimization approaches, refactor tradeoffs |
|
|
||||||
|
|
||||||
If either group empty -> skip that agent.
|
|
||||||
|
|
||||||
Build prompt per group requesting 6 enrichment fields per finding:
|
|
||||||
- `root_cause`: `{description, related_findings[], is_symptom}`
|
|
||||||
- `impact`: `{scope: low/medium/high, affected_files[], blast_radius}`
|
|
||||||
- `optimization`: `{approach, alternative, tradeoff}`
|
|
||||||
- `fix_strategy`: minimal / refactor / skip
|
|
||||||
- `fix_complexity`: low / medium / high
|
|
||||||
- `fix_dependencies`: finding IDs that must be fixed first
|
|
||||||
|
|
||||||
Execute via `ccw cli --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause` (fallback: qwen -> codex). Parse JSON array responses, merge with originals (CLI-enriched replace originals, unenriched get defaults). Write `<session>/review/enriched-findings.json`.
|
|
||||||
|
|
||||||
## Phase 4: Report Generation
|
|
||||||
|
|
||||||
1. Combine enriched + pass_through findings
|
|
||||||
2. Cross-correlate:
|
|
||||||
- **Critical files**: file appears in >=2 dimensions -> list with finding_count, severities
|
|
||||||
- **Root cause groups**: cluster findings sharing related_findings -> identify primary
|
|
||||||
- **Optimization suggestions**: from root cause groups + standalone enriched findings
|
|
||||||
3. Compute metrics: by_dimension, by_severity, dimension_severity_matrix, fixable_count, auto_fixable_count
|
|
||||||
4. Write `<session>/review/review-report.json`: `{review_id, review_date, findings[], critical_files[], optimization_suggestions[], root_cause_groups[], summary}`
|
|
||||||
5. Write `<session>/review/review-report.md`: Executive summary, metrics matrix (dimension x severity), critical/high findings table, critical files list, optimization suggestions, recommended fix scope
|
|
||||||
6. Update `<session>/.msg/meta.json` with review summary
|
|
||||||
7. Contribute discoveries to `<session>/wisdom/` files
|
|
||||||
@@ -1,70 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: SCAN
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: scan_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Code Scanner
|
|
||||||
|
|
||||||
Toolchain + LLM semantic scan producing structured findings. Static analysis tools in parallel, then LLM for issues tools miss. Read-only -- never modifies source code. 4-dimension system: security (SEC), correctness (COR), performance (PRF), maintainability (MNT).
|
|
||||||
|
|
||||||
## Phase 2: Context & Toolchain 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, target, dimensions, quick flag from task description
|
|
||||||
2. Resolve target files (glob pattern or directory -> `**/*.{ts,tsx,js,jsx,py,go,java,rs}`)
|
|
||||||
3. If no source files found -> report empty, complete task cleanly
|
|
||||||
4. Detect toolchain availability:
|
|
||||||
|
|
||||||
| Tool | Detection | Dimension |
|
|
||||||
|------|-----------|-----------|
|
|
||||||
| tsc | `tsconfig.json` exists | COR |
|
|
||||||
| eslint | `.eslintrc*` or `eslint` in package.json | COR/MNT |
|
|
||||||
| semgrep | `.semgrep.yml` exists | SEC |
|
|
||||||
| ruff | `pyproject.toml` + ruff available | SEC/COR/MNT |
|
|
||||||
| mypy | mypy available + `pyproject.toml` | COR |
|
|
||||||
| npmAudit | `package-lock.json` exists | SEC |
|
|
||||||
|
|
||||||
5. Load wisdom files from `<session>/wisdom/` if they exist
|
|
||||||
|
|
||||||
## Phase 3: Scan Execution
|
|
||||||
|
|
||||||
**Quick mode**: Single CLI call with analysis mode, max 20 findings, skip toolchain.
|
|
||||||
|
|
||||||
**Standard mode** (sequential):
|
|
||||||
|
|
||||||
### 3A: Toolchain Scan
|
|
||||||
Run detected tools in parallel via Bash backgrounding. Each tool writes to `<session>/scan/tmp/<tool>.{json|txt}`. After `wait`, parse each output into normalized findings:
|
|
||||||
- tsc: `file(line,col): error TSxxxx: msg` -> dimension=correctness, source=tool:tsc
|
|
||||||
- eslint: JSON array -> severity 2=correctness/high, else=maintainability/medium
|
|
||||||
- semgrep: `{results[]}` -> dimension=security, severity from extra.severity
|
|
||||||
- ruff: `[{code,message,filename}]` -> S*=security, F*/B*=correctness, else=maintainability
|
|
||||||
- mypy: `file:line: error: msg [code]` -> dimension=correctness
|
|
||||||
- npm audit: `{vulnerabilities:{}}` -> dimension=security, category=dependency
|
|
||||||
|
|
||||||
Write `<session>/scan/toolchain-findings.json`.
|
|
||||||
|
|
||||||
### 3B: Semantic Scan (LLM via CLI)
|
|
||||||
Build prompt with target file patterns, toolchain dedup summary, and per-dimension focus areas:
|
|
||||||
- SEC: Business logic vulnerabilities, privilege escalation, sensitive data flow, auth bypass
|
|
||||||
- COR: Logic errors, unhandled exception paths, state management bugs, race conditions
|
|
||||||
- PRF: Algorithm complexity, N+1 queries, unnecessary sync, memory leaks, missing caching
|
|
||||||
- MNT: Architectural coupling, abstraction leaks, convention violations, dead code
|
|
||||||
|
|
||||||
Execute via `ccw cli --tool gemini --mode analysis --rule analysis-review-code-quality` (fallback: qwen -> codex). Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`.
|
|
||||||
|
|
||||||
## Phase 4: Aggregate & Output
|
|
||||||
|
|
||||||
1. Merge toolchain + semantic findings, deduplicate (same file + line + dimension = duplicate)
|
|
||||||
2. Assign dimension-prefixed IDs: SEC-001, COR-001, PRF-001, MNT-001
|
|
||||||
3. Write `<session>/scan/scan-results.json` with schema: `{scan_date, target, dimensions, quick_mode, total_findings, by_severity, by_dimension, findings[]}`
|
|
||||||
4. Each finding: `{id, dimension, category, severity, title, description, location:{file,line}, source, suggested_fix, effort, confidence}`
|
|
||||||
5. Update `<session>/.msg/meta.json` with scan summary (findings_count, by_severity, by_dimension)
|
|
||||||
6. Contribute discoveries to `<session>/wisdom/` files
|
|
||||||
@@ -1,71 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: EXEC
|
|
||||||
inner_loop: true
|
|
||||||
cli_tools:
|
|
||||||
- gemini --mode write
|
|
||||||
message_types:
|
|
||||||
success: exec_complete
|
|
||||||
progress: exec_progress
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Executor
|
|
||||||
|
|
||||||
Wave-based code implementation per phase. Reads IMPL-*.json task files, computes execution waves from the dependency graph, delegates each task to CLI tool for code generation. Produces summary-{IMPL-ID}.md per task.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes |
|
|
||||||
| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No |
|
|
||||||
| Wisdom | <session>/wisdom/ | No |
|
|
||||||
|
|
||||||
1. Glob `<session>/phase-{N}/.task/IMPL-*.json`, error if none found
|
|
||||||
2. Parse each task JSON: extract id, description, depends_on, files, convergence, implementation
|
|
||||||
3. Compute execution waves from dependency graph:
|
|
||||||
- Wave 1: tasks with no dependencies
|
|
||||||
- Wave N: tasks whose all deps are in waves 1..N-1
|
|
||||||
- Force-assign if circular (break at lowest-numbered task)
|
|
||||||
4. Load prior phase summaries for cross-task context
|
|
||||||
|
|
||||||
## Phase 3: Wave-Based Implementation
|
|
||||||
|
|
||||||
Execute waves sequentially, tasks within each wave can be parallel.
|
|
||||||
|
|
||||||
**Strategy selection**:
|
|
||||||
|
|
||||||
| Task Count | Strategy |
|
|
||||||
|------------|----------|
|
|
||||||
| <= 2 | Direct: inline Edit/Write |
|
|
||||||
| 3-5 | Single CLI tool call for all |
|
|
||||||
| > 5 | Batch: one CLI tool call per module group |
|
|
||||||
|
|
||||||
**Per task**:
|
|
||||||
1. Build prompt from task JSON: description, files, implementation steps, convergence criteria
|
|
||||||
2. Include prior summaries and wisdom as context
|
|
||||||
3. Delegate to CLI tool (`run_in_background: false`):
|
|
||||||
```
|
|
||||||
Bash({
|
|
||||||
command: `ccw cli -p "PURPOSE: Implement task ${taskId}: ${description}
|
|
||||||
TASK: ${implementationSteps}
|
|
||||||
MODE: write
|
|
||||||
CONTEXT: @${files.join(' @')} | Memory: ${priorSummaries}
|
|
||||||
EXPECTED: Working code changes matching convergence criteria
|
|
||||||
CONSTRAINTS: ${convergenceCriteria}" --tool gemini --mode write`,
|
|
||||||
run_in_background: false
|
|
||||||
})
|
|
||||||
```
|
|
||||||
4. Write `<session>/phase-{N}/summary-{IMPL-ID}.md` with: task ID, affected files, changes made, status
|
|
||||||
|
|
||||||
**Between waves**: report wave progress via team_msg (type: exec_progress)
|
|
||||||
|
|
||||||
## Phase 4: Self-Validation
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| Affected files exist | `test -f <path>` for each file in summary | All present |
|
|
||||||
| TypeScript syntax | `npx tsc --noEmit` (if tsconfig.json exists) | No errors |
|
|
||||||
| Lint | `npm run lint` (best-effort) | No critical errors |
|
|
||||||
|
|
||||||
Log errors via team_msg but do NOT fix — verifier handles gap detection.
|
|
||||||
@@ -1,77 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: PLAN
|
|
||||||
inner_loop: true
|
|
||||||
cli_tools:
|
|
||||||
- gemini --mode analysis
|
|
||||||
message_types:
|
|
||||||
success: plan_ready
|
|
||||||
progress: plan_progress
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Planner
|
|
||||||
|
|
||||||
Research and plan creation per roadmap phase. Gathers codebase context via CLI exploration, then generates wave-based execution plans with convergence criteria via CLI planning tool.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading + Research
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| roadmap.md | <session>/roadmap.md | Yes |
|
|
||||||
| config.json | <session>/config.json | Yes |
|
|
||||||
| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No |
|
|
||||||
| Wisdom | <session>/wisdom/ | No |
|
|
||||||
|
|
||||||
1. Read roadmap.md, extract phase goal, requirements (REQ-IDs), success criteria
|
|
||||||
2. Read config.json for depth setting (quick/standard/comprehensive)
|
|
||||||
3. Load prior phase summaries for dependency context
|
|
||||||
4. Detect gap closure mode (task description contains "Gap closure")
|
|
||||||
5. Launch CLI exploration with phase requirements as exploration query:
|
|
||||||
```
|
|
||||||
Bash({
|
|
||||||
command: `ccw cli -p "PURPOSE: Explore codebase for phase requirements
|
|
||||||
TASK: • Identify files needing modification • Map patterns and dependencies • Assess test infrastructure • Identify risks
|
|
||||||
MODE: analysis
|
|
||||||
CONTEXT: @**/* | Memory: Phase goal: ${phaseGoal}
|
|
||||||
EXPECTED: Structured exploration results with file lists, patterns, risks
|
|
||||||
CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis`,
|
|
||||||
run_in_background: false
|
|
||||||
})
|
|
||||||
```
|
|
||||||
- Target: files needing modification, patterns, dependencies, test infrastructure, risks
|
|
||||||
6. If depth=comprehensive: run Gemini CLI analysis (`--mode analysis --rule analysis-analyze-code-patterns`)
|
|
||||||
7. Write `<session>/phase-{N}/context.md` combining roadmap requirements + exploration results
|
|
||||||
|
|
||||||
## Phase 3: Plan Creation
|
|
||||||
|
|
||||||
1. Load context.md from Phase 2
|
|
||||||
2. Create output directory: `<session>/phase-{N}/.task/`
|
|
||||||
3. Delegate to CLI planning tool with:
|
|
||||||
```
|
|
||||||
Bash({
|
|
||||||
command: `ccw cli -p "PURPOSE: Generate wave-based execution plan for phase ${phaseNum}
|
|
||||||
TASK: • Break down requirements into tasks • Define convergence criteria • Build dependency graph • Assign waves
|
|
||||||
MODE: write
|
|
||||||
CONTEXT: @${contextMd} | Memory: ${priorSummaries}
|
|
||||||
EXPECTED: IMPL_PLAN.md + IMPL-*.json files + TODO_LIST.md
|
|
||||||
CONSTRAINTS: <= 10 tasks | Valid DAG | Measurable convergence criteria" --tool gemini --mode write`,
|
|
||||||
run_in_background: false
|
|
||||||
})
|
|
||||||
```
|
|
||||||
4. CLI tool produces: `IMPL_PLAN.md`, `.task/IMPL-*.json`, `TODO_LIST.md`
|
|
||||||
5. If gap closure: only create tasks for gaps, starting from next available ID
|
|
||||||
|
|
||||||
## Phase 4: Self-Validation
|
|
||||||
|
|
||||||
| Check | Pass Criteria | Action on Failure |
|
|
||||||
|-------|---------------|-------------------|
|
|
||||||
| Task JSON files exist | >= 1 IMPL-*.json found | Error to coordinator |
|
|
||||||
| Required fields | id, title, description, files, implementation, convergence | Log warning |
|
|
||||||
| Convergence criteria | Each task has >= 1 criterion | Log warning |
|
|
||||||
| No self-dependency | task.id not in task.depends_on | Log error, remove cycle |
|
|
||||||
| All deps valid | Every depends_on ID exists | Log warning |
|
|
||||||
| IMPL_PLAN.md exists | File present | Generate minimal version from task JSONs |
|
|
||||||
|
|
||||||
After validation, compute wave structure from dependency graph for reporting:
|
|
||||||
- Wave count = topological layers of DAG
|
|
||||||
- Report: task count, wave count, file list
|
|
||||||
@@ -1,73 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: VERIFY
|
|
||||||
inner_loop: true
|
|
||||||
cli_tools:
|
|
||||||
- gemini --mode analysis
|
|
||||||
message_types:
|
|
||||||
success: verify_passed
|
|
||||||
failure: gaps_found
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Verifier
|
|
||||||
|
|
||||||
Goal-backward verification per phase. Reads convergence criteria from IMPL-*.json task files and checks against actual codebase state. Read-only — never modifies code. Produces verification.md with pass/fail and structured gap lists.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes |
|
|
||||||
| Summaries | <session>/phase-{N}/summary-*.md | Yes |
|
|
||||||
| Wisdom | <session>/wisdom/ | No |
|
|
||||||
|
|
||||||
1. Glob IMPL-*.json files, extract convergence criteria from each task
|
|
||||||
2. Glob summary-*.md files, parse frontmatter (task, affects, provides)
|
|
||||||
3. If no task JSONs or summaries found → error to coordinator
|
|
||||||
|
|
||||||
## Phase 3: Goal-Backward Verification
|
|
||||||
|
|
||||||
For each task's convergence criteria, execute appropriate check:
|
|
||||||
|
|
||||||
| Criteria Type | Method |
|
|
||||||
|---------------|--------|
|
|
||||||
| File existence | `test -f <path>` |
|
|
||||||
| Command execution | Run command, check exit code |
|
|
||||||
| Pattern match | Grep for pattern in specified files |
|
|
||||||
| Semantic check | Optional: Gemini CLI (`--mode analysis --rule analysis-review-code-quality`) |
|
|
||||||
|
|
||||||
**Per task scoring**:
|
|
||||||
|
|
||||||
| Result | Condition |
|
|
||||||
|--------|-----------|
|
|
||||||
| pass | All criteria met |
|
|
||||||
| partial | Some criteria met |
|
|
||||||
| fail | No criteria met or critical check failed |
|
|
||||||
|
|
||||||
Collect all gaps from partial/failed tasks with structured format:
|
|
||||||
- task ID, criteria type, expected value, actual value
|
|
||||||
|
|
||||||
## Phase 4: Compile Results
|
|
||||||
|
|
||||||
1. Aggregate per-task results: count passed, partial, failed
|
|
||||||
2. Determine overall status:
|
|
||||||
- `passed` if gaps.length === 0
|
|
||||||
- `gaps_found` otherwise
|
|
||||||
3. Write `<session>/phase-{N}/verification.md`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
phase: <N>
|
|
||||||
status: passed | gaps_found
|
|
||||||
tasks_checked: <count>
|
|
||||||
tasks_passed: <count>
|
|
||||||
gaps:
|
|
||||||
- task: "<task-id>"
|
|
||||||
type: "<criteria-type>"
|
|
||||||
item: "<description>"
|
|
||||||
expected: "<expected>"
|
|
||||||
actual: "<actual>"
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Update .msg/meta.json with verification summary
|
|
||||||
@@ -1,70 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TDEVAL
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: assessment_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Tech Debt Assessor
|
|
||||||
|
|
||||||
Quantitative evaluator for tech debt items. Score each debt item on business impact (1-5) and fix cost (1-5), classify into priority quadrants, produce priority-matrix.json.
|
|
||||||
|
|
||||||
## Phase 2: Load Debt Inventory
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Session path | task description (regex: `session:\s*(.+)`) | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
| Debt inventory | meta.json:debt_inventory OR <session>/scan/debt-inventory.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for team context
|
|
||||||
3. Load debt_inventory from shared memory or fallback to debt-inventory.json file
|
|
||||||
4. If debt_inventory is empty -> report empty assessment and exit
|
|
||||||
|
|
||||||
## Phase 3: Evaluate Each Item
|
|
||||||
|
|
||||||
**Strategy selection**:
|
|
||||||
|
|
||||||
| Item Count | Strategy |
|
|
||||||
|------------|----------|
|
|
||||||
| <= 10 | Heuristic: severity-based impact + effort-based cost |
|
|
||||||
| 11-50 | CLI batch: single gemini analysis call |
|
|
||||||
| > 50 | CLI chunked: batches of 25 items |
|
|
||||||
|
|
||||||
**Impact Score Mapping** (heuristic):
|
|
||||||
|
|
||||||
| Severity | Impact Score |
|
|
||||||
|----------|-------------|
|
|
||||||
| critical | 5 |
|
|
||||||
| high | 4 |
|
|
||||||
| medium | 3 |
|
|
||||||
| low | 1 |
|
|
||||||
|
|
||||||
**Cost Score Mapping** (heuristic):
|
|
||||||
|
|
||||||
| Estimated Effort | Cost Score |
|
|
||||||
|------------------|------------|
|
|
||||||
| small | 1 |
|
|
||||||
| medium | 3 |
|
|
||||||
| large | 5 |
|
|
||||||
| unknown | 3 |
|
|
||||||
|
|
||||||
**Priority Quadrant Classification**:
|
|
||||||
|
|
||||||
| Impact | Cost | Quadrant |
|
|
||||||
|--------|------|----------|
|
|
||||||
| >= 4 | <= 2 | quick-win |
|
|
||||||
| >= 4 | >= 3 | strategic |
|
|
||||||
| <= 3 | <= 2 | backlog |
|
|
||||||
| <= 3 | >= 3 | defer |
|
|
||||||
|
|
||||||
For CLI mode, prompt gemini with full debt summary requesting JSON array of `{id, impact_score, cost_score, risk_if_unfixed, priority_quadrant}`. Unevaluated items fall back to heuristic scoring.
|
|
||||||
|
|
||||||
## Phase 4: Generate Priority Matrix
|
|
||||||
|
|
||||||
1. Build matrix structure: evaluation_date, total_items, by_quadrant (grouped), summary (counts per quadrant)
|
|
||||||
2. Sort within each quadrant by impact_score descending
|
|
||||||
3. Write `<session>/assessment/priority-matrix.json`
|
|
||||||
4. Update .msg/meta.json with `priority_matrix` summary and evaluated `debt_inventory`
|
|
||||||
@@ -1,80 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TDFIX
|
|
||||||
inner_loop: true
|
|
||||||
cli_tools:
|
|
||||||
- gemini --mode write
|
|
||||||
message_types:
|
|
||||||
success: fix_complete
|
|
||||||
progress: fix_progress
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Tech Debt Executor
|
|
||||||
|
|
||||||
Debt cleanup executor. Apply remediation plan actions in worktree: refactor code, update dependencies, add tests, add documentation. Batch-delegate to CLI tools, self-validate after each batch.
|
|
||||||
|
|
||||||
## Phase 2: Load Remediation Plan
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Session path | task description (regex: `session:\s*(.+)`) | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
| Remediation plan | <session>/plan/remediation-plan.json | Yes |
|
|
||||||
| Worktree info | meta.json:worktree.path, worktree.branch | Yes |
|
|
||||||
| Context accumulator | From prior TDFIX tasks (inner loop) | Yes (inner loop) |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for worktree path and branch
|
|
||||||
3. Read remediation-plan.json, extract all actions from plan phases
|
|
||||||
4. Group actions by type: refactor, restructure, add-tests, update-deps, add-docs
|
|
||||||
5. Split large groups (> 10 items) into sub-batches of 10
|
|
||||||
6. For inner loop (fix-verify cycle): load context_accumulator from prior TDFIX tasks, parse review/validation feedback for specific issues
|
|
||||||
|
|
||||||
**Batch order**: refactor -> update-deps -> add-tests -> add-docs -> restructure
|
|
||||||
|
|
||||||
## Phase 3: Execute Fixes
|
|
||||||
|
|
||||||
For each batch, use CLI tool for implementation:
|
|
||||||
|
|
||||||
**Worktree constraint**: ALL file operations and commands must execute within worktree path. Use `cd "<worktree-path>" && ...` prefix for all Bash commands.
|
|
||||||
|
|
||||||
**Per-batch delegation**:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ccw cli -p "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
|
|
||||||
TASK: <batch-type-specific-tasks>
|
|
||||||
MODE: write
|
|
||||||
CONTEXT: @<worktree-path>/**/* | Memory: Remediation plan context
|
|
||||||
EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests
|
|
||||||
CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying
|
|
||||||
Batch type: <refactor|update-deps|add-tests|add-docs|restructure>
|
|
||||||
Items: <list-of-items-with-file-paths-and-descriptions>" --tool gemini --mode write --cd "<worktree-path>"
|
|
||||||
```
|
|
||||||
|
|
||||||
Wait for CLI completion before proceeding to next batch.
|
|
||||||
|
|
||||||
**Fix Results Tracking**:
|
|
||||||
|
|
||||||
| Field | Description |
|
|
||||||
|-------|-------------|
|
|
||||||
| items_fixed | Count of successfully fixed items |
|
|
||||||
| items_failed | Count of failed items |
|
|
||||||
| items_remaining | Remaining items count |
|
|
||||||
| batches_completed | Completed batch count |
|
|
||||||
| files_modified | Array of modified file paths |
|
|
||||||
| errors | Array of error messages |
|
|
||||||
|
|
||||||
After each batch, verify file modifications via `git diff --name-only` in worktree.
|
|
||||||
|
|
||||||
## Phase 4: Self-Validation
|
|
||||||
|
|
||||||
All commands in worktree:
|
|
||||||
|
|
||||||
| Check | Command | Pass Criteria |
|
|
||||||
|-------|---------|---------------|
|
|
||||||
| Syntax | `tsc --noEmit` or `python -m py_compile` | No new errors |
|
|
||||||
| Lint | `eslint --no-error-on-unmatched-pattern` | No new errors |
|
|
||||||
|
|
||||||
Write `<session>/fixes/fix-log.json` with fix results. Update .msg/meta.json with `fix_results`.
|
|
||||||
|
|
||||||
Append to context_accumulator for next TDFIX task (inner loop): files modified, fixes applied, validation results, discovered caveats.
|
|
||||||
@@ -1,71 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TDPLAN
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: plan_ready
|
|
||||||
revision: plan_revision
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Tech Debt Planner
|
|
||||||
|
|
||||||
Remediation plan designer. Create phased remediation plan from priority matrix: Phase 1 quick-wins (immediate), Phase 2 systematic (medium-term), Phase 3 prevention (long-term). Produce remediation-plan.md.
|
|
||||||
|
|
||||||
## Phase 2: Load Assessment Data
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Session path | task description (regex: `session:\s*(.+)`) | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
| Priority matrix | <session>/assessment/priority-matrix.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for debt_inventory
|
|
||||||
3. Read priority-matrix.json for quadrant groupings
|
|
||||||
4. Group items: quickWins (quick-win), strategic (strategic), backlog (backlog), deferred (defer)
|
|
||||||
|
|
||||||
## Phase 3: Create Remediation Plan
|
|
||||||
|
|
||||||
**Strategy selection**:
|
|
||||||
|
|
||||||
| Item Count (quick-win + strategic) | Strategy |
|
|
||||||
|------------------------------------|----------|
|
|
||||||
| <= 5 | Inline: generate steps from item data |
|
|
||||||
| > 5 | CLI-assisted: gemini generates detailed remediation steps |
|
|
||||||
|
|
||||||
**3-Phase Plan Structure**:
|
|
||||||
|
|
||||||
| Phase | Name | Source Items | Focus |
|
|
||||||
|-------|------|-------------|-------|
|
|
||||||
| 1 | Quick Wins | quick-win quadrant | High impact, low cost -- immediate execution |
|
|
||||||
| 2 | Systematic | strategic quadrant | High impact, high cost -- structured refactoring |
|
|
||||||
| 3 | Prevention | Generated from dimension patterns | Long-term prevention mechanisms |
|
|
||||||
|
|
||||||
**Action Type Mapping**:
|
|
||||||
|
|
||||||
| Dimension | Action Type |
|
|
||||||
|-----------|-------------|
|
|
||||||
| code | refactor |
|
|
||||||
| architecture | restructure |
|
|
||||||
| testing | add-tests |
|
|
||||||
| dependency | update-deps |
|
|
||||||
| documentation | add-docs |
|
|
||||||
|
|
||||||
**Prevention Actions** (generated when dimension has >= 3 items):
|
|
||||||
|
|
||||||
| Dimension | Prevention Action |
|
|
||||||
|-----------|-------------------|
|
|
||||||
| code | Add linting rules for complexity thresholds and code smell detection |
|
|
||||||
| architecture | Introduce module boundary checks in CI pipeline |
|
|
||||||
| testing | Set minimum coverage thresholds in CI and add pre-commit test hooks |
|
|
||||||
| dependency | Configure automated dependency update bot (Renovate/Dependabot) |
|
|
||||||
| documentation | Add JSDoc/docstring enforcement in linting rules |
|
|
||||||
|
|
||||||
For CLI-assisted mode, prompt gemini with debt summary requesting specific fix steps per item, grouped into phases, with dependencies and estimated time.
|
|
||||||
|
|
||||||
## Phase 4: Validate & Save
|
|
||||||
|
|
||||||
1. Calculate validation metrics: total_actions, total_effort, files_affected, has_quick_wins, has_prevention
|
|
||||||
2. Write `<session>/plan/remediation-plan.md` (markdown with per-item checklists)
|
|
||||||
3. Write `<session>/plan/remediation-plan.json` (machine-readable)
|
|
||||||
4. Update .msg/meta.json with `remediation_plan` summary
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TDSCAN
|
|
||||||
inner_loop: false
|
|
||||||
cli_tools:
|
|
||||||
- gemini --mode analysis
|
|
||||||
message_types:
|
|
||||||
success: scan_complete
|
|
||||||
error: error
|
|
||||||
info: debt_items_found
|
|
||||||
---
|
|
||||||
|
|
||||||
# Tech Debt Scanner
|
|
||||||
|
|
||||||
Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, architecture, testing, dependency, documentation), produce structured debt inventory with severity rankings.
|
|
||||||
|
|
||||||
## Phase 2: Context & Environment Detection
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Scan scope | task description (regex: `scope:\s*(.+)`) | No (default: `**/*`) |
|
|
||||||
| Session path | task description (regex: `session:\s*(.+)`) | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path and scan scope from task description
|
|
||||||
2. Read .msg/meta.json for team context
|
|
||||||
3. Detect project type and framework:
|
|
||||||
|
|
||||||
| Signal File | Project Type |
|
|
||||||
|-------------|-------------|
|
|
||||||
| package.json + React/Vue/Angular | Frontend Node |
|
|
||||||
| package.json + Express/Fastify/NestJS | Backend Node |
|
|
||||||
| pyproject.toml / requirements.txt | Python |
|
|
||||||
| go.mod | Go |
|
|
||||||
| No detection | Generic |
|
|
||||||
|
|
||||||
4. Determine scan dimensions (default: code, architecture, testing, dependency, documentation)
|
|
||||||
5. Detect perspectives from task description:
|
|
||||||
|
|
||||||
| Condition | Perspective |
|
|
||||||
|-----------|-------------|
|
|
||||||
| `security\|auth\|inject\|xss` | security |
|
|
||||||
| `performance\|speed\|optimize` | performance |
|
|
||||||
| `quality\|clean\|maintain\|debt` | code-quality |
|
|
||||||
| `architect\|pattern\|structure` | architecture |
|
|
||||||
| Default | code-quality + architecture |
|
|
||||||
|
|
||||||
6. Assess complexity:
|
|
||||||
|
|
||||||
| Score | Complexity | Strategy |
|
|
||||||
|-------|------------|----------|
|
|
||||||
| >= 4 | High | Triple Fan-out: CLI explore + CLI 5 dimensions + multi-perspective Gemini |
|
|
||||||
| 2-3 | Medium | Dual Fan-out: CLI explore + CLI 3 dimensions |
|
|
||||||
| 0-1 | Low | Inline: ACE search + Grep |
|
|
||||||
|
|
||||||
## Phase 3: Multi-Dimension Scan
|
|
||||||
|
|
||||||
**Low Complexity** (inline):
|
|
||||||
- Use `mcp__ace-tool__search_context` for code smells, TODO/FIXME, deprecated APIs, complex functions, dead code, missing tests
|
|
||||||
- Classify findings into dimensions
|
|
||||||
|
|
||||||
**Medium/High Complexity** (Fan-out):
|
|
||||||
- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `ccw cli --tool gemini --mode analysis`
|
|
||||||
- Fan-out B: CLI dimension analysis (parallel gemini per dimension -- code, architecture, testing, dependency, documentation)
|
|
||||||
- Fan-out C (High only): Multi-perspective Gemini analysis (security, performance, code-quality, architecture)
|
|
||||||
- Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings
|
|
||||||
|
|
||||||
**Standardize each finding**:
|
|
||||||
|
|
||||||
| Field | Description |
|
|
||||||
|-------|-------------|
|
|
||||||
| `id` | `TD-NNN` (sequential) |
|
|
||||||
| `dimension` | code, architecture, testing, dependency, documentation |
|
|
||||||
| `severity` | critical, high, medium, low |
|
|
||||||
| `file` | File path |
|
|
||||||
| `line` | Line number |
|
|
||||||
| `description` | Issue description |
|
|
||||||
| `suggestion` | Fix suggestion |
|
|
||||||
| `estimated_effort` | small, medium, large, unknown |
|
|
||||||
|
|
||||||
## Phase 4: Aggregate & Save
|
|
||||||
|
|
||||||
1. Deduplicate findings across Fan-out layers (file:line key), merge cross-references
|
|
||||||
2. Sort by severity (cross-referenced items boosted)
|
|
||||||
3. Write `<session>/scan/debt-inventory.json` with scan_date, dimensions, total_items, by_dimension, by_severity, items
|
|
||||||
4. Update .msg/meta.json with `debt_inventory` array and `debt_score_before` count
|
|
||||||
@@ -1,83 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TDVAL
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: validation_complete
|
|
||||||
error: error
|
|
||||||
fix: regression_found
|
|
||||||
---
|
|
||||||
|
|
||||||
# Tech Debt Validator
|
|
||||||
|
|
||||||
Cleanup result validator. Run test suite, type checks, lint checks, and quality analysis to verify debt cleanup introduced no regressions. Compare before/after debt scores, produce validation-report.json.
|
|
||||||
|
|
||||||
## Phase 2: Load Context
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Session path | task description (regex: `session:\s*(.+)`) | Yes |
|
|
||||||
| .msg/meta.json | <session>/.msg/meta.json | Yes |
|
|
||||||
| Fix log | <session>/fixes/fix-log.json | No |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for: worktree.path, debt_inventory, fix_results, debt_score_before
|
|
||||||
3. Determine command prefix: `cd "<worktree-path>" && ` if worktree exists
|
|
||||||
4. Read fix-log.json for modified files list
|
|
||||||
5. Detect available validation tools in worktree:
|
|
||||||
|
|
||||||
| Signal | Tool | Method |
|
|
||||||
|--------|------|--------|
|
|
||||||
| package.json + npm | npm test | Test suite |
|
|
||||||
| pytest available | python -m pytest | Test suite |
|
|
||||||
| npx tsc available | npx tsc --noEmit | Type check |
|
|
||||||
| npx eslint available | npx eslint | Lint check |
|
|
||||||
|
|
||||||
## Phase 3: Run Validation Checks
|
|
||||||
|
|
||||||
Execute 4-layer validation (all commands in worktree):
|
|
||||||
|
|
||||||
**1. Test Suite**:
|
|
||||||
- Run `npm test` or `python -m pytest` in worktree
|
|
||||||
- PASS if no FAIL/error/failed keywords; FAIL with regression count otherwise
|
|
||||||
- Skip with "no-tests" if no test runner available
|
|
||||||
|
|
||||||
**2. Type Check**:
|
|
||||||
- Run `npx tsc --noEmit` in worktree
|
|
||||||
- Count `error TS` occurrences for error count
|
|
||||||
|
|
||||||
**3. Lint Check**:
|
|
||||||
- Run `npx eslint --no-error-on-unmatched-pattern <modified-files>` in worktree
|
|
||||||
- Count error occurrences
|
|
||||||
|
|
||||||
**4. Quality Analysis** (optional, when > 5 modified files):
|
|
||||||
- Use gemini CLI to compare code quality before/after
|
|
||||||
- Assess complexity, duplication, naming quality improvements
|
|
||||||
|
|
||||||
**Debt Score Calculation**:
|
|
||||||
- debt_score_after = debt items NOT in modified files (remaining unfixed items)
|
|
||||||
- improvement_percentage = ((before - after) / before) * 100
|
|
||||||
|
|
||||||
**Auto-fix attempt** (when total_regressions <= 3):
|
|
||||||
- Use CLI tool to fix regressions in worktree:
|
|
||||||
```
|
|
||||||
Bash({
|
|
||||||
command: `cd "${worktreePath}" && ccw cli -p "PURPOSE: Fix regressions found in validation
|
|
||||||
TASK: ${regressionDetails}
|
|
||||||
MODE: write
|
|
||||||
CONTEXT: @${modifiedFiles.join(' @')}
|
|
||||||
EXPECTED: Fixed regressions
|
|
||||||
CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --tool gemini --mode write`,
|
|
||||||
run_in_background: false
|
|
||||||
})
|
|
||||||
```
|
|
||||||
- Re-run validation checks after fix attempt
|
|
||||||
})
|
|
||||||
```
|
|
||||||
- Re-run checks after fix attempt
|
|
||||||
|
|
||||||
## Phase 4: Compare & Report
|
|
||||||
|
|
||||||
1. Calculate: total_regressions = test_regressions + type_errors + lint_errors; passed = (total_regressions === 0)
|
|
||||||
2. Write `<session>/validation/validation-report.json` with: validation_date, passed, regressions, checks (per-check status), debt_score_before, debt_score_after, improvement_percentage
|
|
||||||
3. Update .msg/meta.json with `validation_results` and `debt_score_after`
|
|
||||||
4. Select message type: `validation_complete` if passed, `regression_found` if not
|
|
||||||
@@ -1,94 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TESTANA
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: analysis_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Test Quality Analyst
|
|
||||||
|
|
||||||
Analyze defect patterns, identify coverage gaps, assess GC loop effectiveness, and generate a quality report with actionable recommendations.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Execution results | <session>/results/run-*.json | Yes |
|
|
||||||
| Test strategy | <session>/strategy/test-strategy.md | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read .msg/meta.json for execution context (executor, generator namespaces)
|
|
||||||
3. Read all execution results:
|
|
||||||
|
|
||||||
```
|
|
||||||
Glob("<session>/results/run-*.json")
|
|
||||||
Read("<session>/results/run-001.json")
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Read test strategy:
|
|
||||||
|
|
||||||
```
|
|
||||||
Read("<session>/strategy/test-strategy.md")
|
|
||||||
```
|
|
||||||
|
|
||||||
5. Read test files for pattern analysis:
|
|
||||||
|
|
||||||
```
|
|
||||||
Glob("<session>/tests/**/*")
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 3: Quality Analysis
|
|
||||||
|
|
||||||
**Analysis dimensions**:
|
|
||||||
|
|
||||||
1. **Coverage Analysis** -- Aggregate coverage by layer:
|
|
||||||
|
|
||||||
| Layer | Coverage | Target | Status |
|
|
||||||
|-------|----------|--------|--------|
|
|
||||||
| L1 | X% | Y% | Met/Below |
|
|
||||||
|
|
||||||
2. **Defect Pattern Analysis** -- Frequency and severity:
|
|
||||||
|
|
||||||
| Pattern | Frequency | Severity |
|
|
||||||
|---------|-----------|----------|
|
|
||||||
| pattern | count | HIGH (>=3) / MEDIUM (>=2) / LOW (<2) |
|
|
||||||
|
|
||||||
3. **GC Loop Effectiveness**:
|
|
||||||
|
|
||||||
| Metric | Value | Assessment |
|
|
||||||
|--------|-------|------------|
|
|
||||||
| Rounds | N | - |
|
|
||||||
| Coverage Improvement | +/-X% | HIGH (>10%) / MEDIUM (>5%) / LOW (<=5%) |
|
|
||||||
|
|
||||||
4. **Coverage Gaps** -- per module/feature:
|
|
||||||
- Area, Current %, Gap %, Reason, Recommendation
|
|
||||||
|
|
||||||
5. **Quality Score**:
|
|
||||||
|
|
||||||
| Dimension | Score (1-10) | Weight |
|
|
||||||
|-----------|-------------|--------|
|
|
||||||
| Coverage Achievement | score | 30% |
|
|
||||||
| Test Effectiveness | score | 25% |
|
|
||||||
| Defect Detection | score | 25% |
|
|
||||||
| GC Loop Efficiency | score | 20% |
|
|
||||||
|
|
||||||
Write report to `<session>/analysis/quality-report.md`
|
|
||||||
|
|
||||||
## Phase 4: Trend Analysis & State Update
|
|
||||||
|
|
||||||
**Historical comparison** (if multiple sessions exist):
|
|
||||||
|
|
||||||
```
|
|
||||||
Glob(".workflow/.team/TST-*/.msg/meta.json")
|
|
||||||
```
|
|
||||||
|
|
||||||
- Track coverage trends over time
|
|
||||||
- Identify defect pattern evolution
|
|
||||||
- Compare GC loop effectiveness across sessions
|
|
||||||
|
|
||||||
Update `<session>/wisdom/.msg/meta.json` under `analyst` namespace:
|
|
||||||
- Merge `{ "analyst": { quality_score, coverage_gaps, top_defect_patterns, gc_effectiveness, recommendations } }`
|
|
||||||
@@ -1,97 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TESTRUN
|
|
||||||
inner_loop: true
|
|
||||||
message_types:
|
|
||||||
success: tests_passed
|
|
||||||
failure: tests_failed
|
|
||||||
coverage: coverage_report
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Test Executor
|
|
||||||
|
|
||||||
Execute tests, collect coverage, attempt auto-fix for failures. Acts as the Critic in the Generator-Critic loop. Reports pass rate and coverage for coordinator GC decisions.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Test directory | Task description (Input: <path>) | Yes |
|
|
||||||
| Coverage target | Task description (default: 80%) | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path and test directory from task description
|
|
||||||
2. Extract coverage target (default: 80%)
|
|
||||||
3. Read .msg/meta.json for framework info (from strategist namespace)
|
|
||||||
4. Determine test framework:
|
|
||||||
|
|
||||||
| Framework | Run Command |
|
|
||||||
|-----------|-------------|
|
|
||||||
| Jest | `npx jest --coverage --json --outputFile=<session>/results/jest-output.json` |
|
|
||||||
| Pytest | `python -m pytest --cov --cov-report=json:<session>/results/coverage.json -v` |
|
|
||||||
| Vitest | `npx vitest run --coverage --reporter=json` |
|
|
||||||
|
|
||||||
5. Find test files to execute:
|
|
||||||
|
|
||||||
```
|
|
||||||
Glob("<session>/<test-dir>/**/*")
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 3: Test Execution + Fix Cycle
|
|
||||||
|
|
||||||
**Iterative test-fix cycle** (max 3 iterations):
|
|
||||||
|
|
||||||
| Step | Action |
|
|
||||||
|------|--------|
|
|
||||||
| 1 | Run test command |
|
|
||||||
| 2 | Parse results: pass rate + coverage |
|
|
||||||
| 3 | pass_rate >= 0.95 AND coverage >= target -> success, exit |
|
|
||||||
| 4 | Extract failing test details |
|
|
||||||
| 5 | Delegate fix to CLI tool (gemini write mode) |
|
|
||||||
| 6 | Increment iteration; >= 3 -> exit with failures |
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash("<test-command> 2>&1 || true")
|
|
||||||
```
|
|
||||||
|
|
||||||
**Auto-fix delegation** (on failure):
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash({
|
|
||||||
command: `ccw cli -p "PURPOSE: Fix test failures to achieve pass rate >= 0.95; success = all tests pass
|
|
||||||
TASK: • Analyze test failure output • Identify root causes • Fix test code only (not source) • Preserve test intent
|
|
||||||
MODE: write
|
|
||||||
CONTEXT: @<session>/<test-dir>/**/* | Memory: Test framework: <framework>, iteration <N>/3
|
|
||||||
EXPECTED: Fixed test files with: corrected assertions, proper async handling, fixed imports, maintained coverage
|
|
||||||
CONSTRAINTS: Only modify test files | Preserve test structure | No source code changes
|
|
||||||
Test failures:
|
|
||||||
<test-output>" --tool gemini --mode write --cd <session>`,
|
|
||||||
run_in_background: false
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
**Save results**: `<session>/results/run-<N>.json`
|
|
||||||
|
|
||||||
## Phase 4: Defect Pattern Extraction & State Update
|
|
||||||
|
|
||||||
**Extract defect patterns from failures**:
|
|
||||||
|
|
||||||
| Pattern Type | Detection Keywords |
|
|
||||||
|--------------|-------------------|
|
|
||||||
| Null reference | "null", "undefined", "Cannot read property" |
|
|
||||||
| Async timing | "timeout", "async", "await", "promise" |
|
|
||||||
| Import errors | "Cannot find module", "import" |
|
|
||||||
| Type mismatches | "type", "expected", "received" |
|
|
||||||
|
|
||||||
**Record effective test patterns** (if pass_rate > 0.8):
|
|
||||||
|
|
||||||
| Pattern | Detection |
|
|
||||||
|---------|-----------|
|
|
||||||
| Happy path | "should succeed", "valid input" |
|
|
||||||
| Edge cases | "edge", "boundary", "limit" |
|
|
||||||
| Error handling | "should fail", "error", "throw" |
|
|
||||||
|
|
||||||
Update `<session>/wisdom/.msg/meta.json` under `executor` namespace:
|
|
||||||
- Merge `{ "executor": { pass_rate, coverage, defect_patterns, effective_patterns, coverage_history_entry } }`
|
|
||||||
@@ -1,96 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TESTGEN
|
|
||||||
inner_loop: true
|
|
||||||
message_types:
|
|
||||||
success: tests_generated
|
|
||||||
revision: tests_revised
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Test Generator
|
|
||||||
|
|
||||||
Generate test code by layer (L1 unit / L2 integration / L3 E2E). Acts as the Generator in the Generator-Critic loop. Supports revision mode for GC loop iterations.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Task description | From task subject/description | Yes |
|
|
||||||
| Session path | Extracted from task description | Yes |
|
|
||||||
| Test strategy | <session>/strategy/test-strategy.md | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path and layer from task description
|
|
||||||
2. Read test strategy:
|
|
||||||
|
|
||||||
```
|
|
||||||
Read("<session>/strategy/test-strategy.md")
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Read source files to test (from strategy priority_files, limit 20)
|
|
||||||
4. Read .msg/meta.json for framework and scope context
|
|
||||||
|
|
||||||
5. Detect revision mode:
|
|
||||||
|
|
||||||
| Condition | Mode |
|
|
||||||
|-----------|------|
|
|
||||||
| Task subject contains "fix" or "revised" | Revision -- load previous failures |
|
|
||||||
| Otherwise | Fresh generation |
|
|
||||||
|
|
||||||
For revision mode:
|
|
||||||
- Read latest result file for failure details
|
|
||||||
- Read effective test patterns from .msg/meta.json
|
|
||||||
|
|
||||||
6. Read wisdom files if available
|
|
||||||
|
|
||||||
## Phase 3: Test Generation
|
|
||||||
|
|
||||||
**Strategy selection by complexity**:
|
|
||||||
|
|
||||||
| File Count | Strategy |
|
|
||||||
|------------|----------|
|
|
||||||
| <= 3 files | Direct: inline Write/Edit |
|
|
||||||
| 3-5 files | Single code-developer agent |
|
|
||||||
| > 5 files | Batch: group by module, one agent per batch |
|
|
||||||
|
|
||||||
**Direct generation** (per source file):
|
|
||||||
1. Generate test path: `<session>/tests/<layer>/<test-file>`
|
|
||||||
2. Generate test code: happy path, edge cases, error handling
|
|
||||||
3. Write test file
|
|
||||||
|
|
||||||
**CLI delegation** (medium/high complexity):
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash({
|
|
||||||
command: `ccw cli -p "PURPOSE: Generate <layer> tests using <framework> to achieve coverage target; success = all priority files covered with quality tests
|
|
||||||
TASK: • Analyze source files • Generate test cases (happy path, edge cases, errors) • Write test files with proper structure • Ensure import resolution
|
|
||||||
MODE: write
|
|
||||||
CONTEXT: @<source-files> @<session>/strategy/test-strategy.md | Memory: Framework: <framework>, Layer: <layer>, Round: <round>
|
|
||||||
<if-revision: Previous failures: <failure-details>
|
|
||||||
Effective patterns: <patterns-from-meta>>
|
|
||||||
EXPECTED: Test files in <session>/tests/<layer>/ with: proper test structure, comprehensive coverage, correct imports, framework conventions
|
|
||||||
CONSTRAINTS: Follow test strategy priorities | Use framework best practices | <layer>-appropriate assertions
|
|
||||||
Source files to test:
|
|
||||||
<file-list-with-content>" --tool gemini --mode write --cd <session>`,
|
|
||||||
run_in_background: false
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
**Output verification**:
|
|
||||||
|
|
||||||
```
|
|
||||||
Glob("<session>/tests/<layer>/**/*")
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 4: Self-Validation & State Update
|
|
||||||
|
|
||||||
**Validation checks**:
|
|
||||||
|
|
||||||
| Check | Method | Action on Fail |
|
|
||||||
|-------|--------|----------------|
|
|
||||||
| Syntax | `tsc --noEmit` or equivalent | Auto-fix imports/types |
|
|
||||||
| File count | Count generated files | Report issue |
|
|
||||||
| Import resolution | Check broken imports | Fix import paths |
|
|
||||||
|
|
||||||
Update `<session>/wisdom/.msg/meta.json` under `generator` namespace:
|
|
||||||
- Merge `{ "generator": { test_files, layer, round, is_revision } }`
|
|
||||||
@@ -1,82 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: STRATEGY
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: strategy_ready
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Test Strategist
|
|
||||||
|
|
||||||
Analyze git diff, determine test layers, define coverage targets, and formulate test strategy with prioritized execution order.
|
|
||||||
|
|
||||||
## 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>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path and scope from task description
|
|
||||||
2. Get git diff for change analysis:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash("git diff HEAD~1 --name-only 2>/dev/null || git diff --cached --name-only")
|
|
||||||
Bash("git diff HEAD~1 -- <changed-files> 2>/dev/null || git diff --cached -- <changed-files>")
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Detect test framework from project files:
|
|
||||||
|
|
||||||
| Signal File | Framework | Test Pattern |
|
|
||||||
|-------------|-----------|-------------|
|
|
||||||
| jest.config.js/ts | Jest | `**/*.test.{ts,tsx,js}` |
|
|
||||||
| vitest.config.ts/js | Vitest | `**/*.test.{ts,tsx}` |
|
|
||||||
| pytest.ini / pyproject.toml | Pytest | `**/test_*.py` |
|
|
||||||
| No detection | Default | Jest patterns |
|
|
||||||
|
|
||||||
4. Scan existing test patterns:
|
|
||||||
|
|
||||||
```
|
|
||||||
Glob("**/*.test.*")
|
|
||||||
Glob("**/*.spec.*")
|
|
||||||
```
|
|
||||||
|
|
||||||
5. Read .msg/meta.json if exists for session context
|
|
||||||
|
|
||||||
## Phase 3: Strategy Formulation
|
|
||||||
|
|
||||||
**Change analysis dimensions**:
|
|
||||||
|
|
||||||
| Change Type | Analysis | Priority |
|
|
||||||
|-------------|----------|----------|
|
|
||||||
| New files | Need new tests | High |
|
|
||||||
| Modified functions | Need updated tests | Medium |
|
|
||||||
| Deleted files | Need test cleanup | Low |
|
|
||||||
| Config changes | May need integration tests | Variable |
|
|
||||||
|
|
||||||
**Strategy output structure**:
|
|
||||||
|
|
||||||
1. **Change Analysis Table**: File, Change Type, Impact, Priority
|
|
||||||
2. **Test Layer Recommendations**:
|
|
||||||
- L1 Unit: Scope, Coverage Target, Priority Files, Patterns
|
|
||||||
- L2 Integration: Scope, Coverage Target, Integration Points
|
|
||||||
- L3 E2E: Scope, Coverage Target, User Scenarios
|
|
||||||
3. **Risk Assessment**: Risk, Probability, Impact, Mitigation
|
|
||||||
4. **Test Execution Order**: Prioritized sequence
|
|
||||||
|
|
||||||
Write strategy to `<session>/strategy/test-strategy.md`
|
|
||||||
|
|
||||||
**Self-validation**:
|
|
||||||
|
|
||||||
| Check | Criteria | Fallback |
|
|
||||||
|-------|----------|----------|
|
|
||||||
| Has L1 scope | L1 scope not empty | Default to all changed files |
|
|
||||||
| Has coverage targets | L1 target > 0 | Use defaults (80/60/40) |
|
|
||||||
| Has priority files | List not empty | Use all changed files |
|
|
||||||
|
|
||||||
## Phase 4: Wisdom & State Update
|
|
||||||
|
|
||||||
1. Write discoveries to `<session>/wisdom/conventions.md` (detected framework, patterns)
|
|
||||||
2. Update `<session>/wisdom/.msg/meta.json` under `strategist` namespace:
|
|
||||||
- Read existing -> merge `{ "strategist": { framework, layers, coverage_targets, priority_files, risks } }` -> write back
|
|
||||||
@@ -1,72 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: DESIGN
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: design_ready
|
|
||||||
revision: design_revision
|
|
||||||
progress: design_progress
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Design Token & Component Spec Author
|
|
||||||
|
|
||||||
Define visual language through design tokens (W3C Design Tokens Format) and component specifications. Consume design intelligence from researcher. Act as Generator in the designer<->reviewer Generator-Critic loop.
|
|
||||||
|
|
||||||
## Phase 2: Context & Artifact Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Research artifacts | <session>/research/*.json | Yes |
|
|
||||||
| Design intelligence | <session>/research/design-intelligence.json | Yes |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
| Audit feedback | <session>/audit/audit-*.md | Only for GC fix tasks |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read research findings: design-system-analysis.json, component-inventory.json, accessibility-audit.json
|
|
||||||
3. Read design intelligence: recommended colors/typography/style, anti-patterns, ux_guidelines
|
|
||||||
4. Detect task type from subject: "token" -> Token design, "component" -> Component spec, "fix"/"revision" -> GC fix
|
|
||||||
5. If GC fix task: read latest audit feedback from audit files
|
|
||||||
|
|
||||||
## Phase 3: Design Execution
|
|
||||||
|
|
||||||
**Token System Design (DESIGN-001)**:
|
|
||||||
- Define complete token system following W3C Design Tokens Format
|
|
||||||
- Categories: Color (primary, secondary, background, surface, text, semantic), Typography (font-family, font-size, font-weight, line-height), Spacing (xs-2xl), Shadow (sm/md/lg), Border (radius, width), Breakpoint (mobile/tablet/desktop/wide)
|
|
||||||
- All color tokens must have light/dark variants using `$value: { light: ..., dark: ... }`
|
|
||||||
- Integrate design intelligence: recommended.colors -> color tokens, recommended.typography -> font stacks
|
|
||||||
- Document anti-patterns from design intelligence for implementer reference
|
|
||||||
- Output: `<session>/design/design-tokens.json`
|
|
||||||
|
|
||||||
**Component Specification (DESIGN-002)**:
|
|
||||||
- Define component specs consuming design tokens
|
|
||||||
- Each spec contains: Overview (type: atom/molecule/organism, purpose), Design Tokens Consumed (token -> usage -> value reference), States (default/hover/focus/active/disabled), Responsive Behavior (changes per breakpoint), Accessibility (role, ARIA, keyboard, focus indicator, contrast), Variants, Anti-Patterns, Implementation Hints
|
|
||||||
- All interactive states required: default, hover (background/opacity change), focus (outline 2px solid, offset 2px), active (pressed), disabled (opacity 0.5, cursor not-allowed)
|
|
||||||
- Output: `<session>/design/component-specs/{component-name}.md`
|
|
||||||
|
|
||||||
**GC Fix Mode (DESIGN-fix-N)**:
|
|
||||||
- Parse audit feedback for specific issues
|
|
||||||
- Re-read affected design artifacts; apply fixes (token value adjustments, missing states, accessibility gaps, naming fixes)
|
|
||||||
- Re-write affected files; signal `design_revision` instead of `design_ready`
|
|
||||||
|
|
||||||
## Phase 4: Self-Validation & Output
|
|
||||||
|
|
||||||
1. Token integrity checks:
|
|
||||||
|
|
||||||
| Check | Pass Criteria |
|
|
||||||
|-------|---------------|
|
|
||||||
| tokens_valid | All $value fields non-empty |
|
|
||||||
| theme_complete | Light/dark values for all color tokens |
|
|
||||||
| values_parseable | Valid CSS-parseable values |
|
|
||||||
| no_duplicates | No duplicate token definitions |
|
|
||||||
|
|
||||||
2. Component spec checks:
|
|
||||||
|
|
||||||
| Check | Pass Criteria |
|
|
||||||
|-------|---------------|
|
|
||||||
| states_complete | All 5 states (default/hover/focus/active/disabled) defined |
|
|
||||||
| a11y_specified | Role, ARIA, keyboard behavior defined |
|
|
||||||
| responsive_defined | At least mobile/desktop breakpoints |
|
|
||||||
| token_refs_valid | All `{token.path}` references resolve to defined tokens |
|
|
||||||
|
|
||||||
3. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
|
|
||||||
- Read existing -> merge `{ "designer": { task_type, token_categories, component_count, style_decisions } }` -> write back
|
|
||||||
@@ -1,74 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: BUILD
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: build_complete
|
|
||||||
progress: build_progress
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Component Code Builder
|
|
||||||
|
|
||||||
Translate design tokens and component specifications into production code. Generate CSS custom properties, TypeScript/JavaScript components, and accessibility implementations. Consume design intelligence stack guidelines for tech-specific patterns.
|
|
||||||
|
|
||||||
## Phase 2: Context & Artifact Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Design tokens | <session>/design/design-tokens.json | Yes (token build) |
|
|
||||||
| Component specs | <session>/design/component-specs/*.md | Yes (component build) |
|
|
||||||
| Design intelligence | <session>/research/design-intelligence.json | Yes |
|
|
||||||
| Latest audit report | <session>/audit/audit-*.md | No |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Detect build type from subject: "token" -> Token implementation, "component" -> Component implementation
|
|
||||||
3. Read design artifacts: design-tokens.json (token build), component-specs/*.md (component build)
|
|
||||||
4. Read design intelligence: stack_guidelines (tech-specific patterns), anti_patterns (patterns to avoid), ux_guidelines
|
|
||||||
5. Read latest audit report for approved changes and feedback
|
|
||||||
6. Detect project tech stack from package.json
|
|
||||||
|
|
||||||
## Phase 3: Implementation Execution
|
|
||||||
|
|
||||||
**Token Implementation (BUILD-001)**:
|
|
||||||
- Convert design tokens to production code
|
|
||||||
- Output files in `<session>/build/token-files/`:
|
|
||||||
- `tokens.css`: CSS custom properties with `:root` (light) and `[data-theme="dark"]` selectors, plus `@media (prefers-color-scheme: dark)` fallback
|
|
||||||
- `tokens.ts`: TypeScript constants and types for programmatic access with autocomplete support
|
|
||||||
- `README.md`: Token usage guide
|
|
||||||
- All color tokens must have both light and dark values
|
|
||||||
- Semantic token names must match design token definitions
|
|
||||||
|
|
||||||
**Component Implementation (BUILD-002)**:
|
|
||||||
- Implement component code from design specifications
|
|
||||||
- Per-component output in `<session>/build/component-files/`:
|
|
||||||
- `{ComponentName}.tsx`: React/Vue/Svelte component (match detected stack)
|
|
||||||
- `{ComponentName}.css`: Styles consuming tokens via `var(--token-name)` only
|
|
||||||
- `{ComponentName}.test.tsx`: Basic render + state tests
|
|
||||||
- `index.ts`: Re-export
|
|
||||||
- Requirements: no hardcoded colors/spacing (use design tokens), implement all 5 states, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
|
|
||||||
- Accessibility: keyboard navigation, screen reader support, visible focus indicators, WCAG AA contrast
|
|
||||||
- Check implementation against design intelligence anti_patterns
|
|
||||||
|
|
||||||
## Phase 4: Validation & Output
|
|
||||||
|
|
||||||
1. Token build validation:
|
|
||||||
|
|
||||||
| Check | Pass Criteria |
|
|
||||||
|-------|---------------|
|
|
||||||
| File existence | tokens.css and tokens.ts exist |
|
|
||||||
| Token coverage | All defined tokens present in CSS |
|
|
||||||
| Theme support | Light/dark variants exist |
|
|
||||||
|
|
||||||
2. Component build validation:
|
|
||||||
|
|
||||||
| Check | Pass Criteria |
|
|
||||||
|-------|---------------|
|
|
||||||
| File existence | At least 3 files per component (component, style, index) |
|
|
||||||
| No hardcoded values | No `#xxx` or `rgb()` in component CSS (only in tokens.css) |
|
|
||||||
| Focus styles | `:focus` or `:focus-visible` defined |
|
|
||||||
| Responsive | `@media` queries present |
|
|
||||||
| Anti-pattern clean | No violations of design intelligence anti_patterns |
|
|
||||||
|
|
||||||
3. Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace:
|
|
||||||
- Read existing -> merge `{ "implementer": { build_type, file_count, output_dir, components_built } }` -> write back
|
|
||||||
@@ -1,84 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: RESEARCH
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: research_ready
|
|
||||||
progress: research_progress
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Design System Researcher
|
|
||||||
|
|
||||||
Analyze existing design system, build component inventory, assess accessibility baseline, and retrieve industry-specific design intelligence via ui-ux-pro-max. Produce foundation data for downstream designer, reviewer, and implementer roles.
|
|
||||||
|
|
||||||
## 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>/wisdom/.msg/meta.json | No |
|
|
||||||
|
|
||||||
1. Extract session path and target scope from task description
|
|
||||||
2. Detect project type and tech stack from package.json or equivalent:
|
|
||||||
|
|
||||||
| Package | Detected Stack |
|
|
||||||
|---------|---------------|
|
|
||||||
| next | nextjs |
|
|
||||||
| react | react |
|
|
||||||
| vue | vue |
|
|
||||||
| svelte | svelte |
|
|
||||||
| @shadcn/ui | shadcn |
|
|
||||||
| (default) | html-tailwind |
|
|
||||||
|
|
||||||
3. Use CLI tools (e.g., `ccw cli -p "..." --tool gemini --mode analysis`) or direct tools (Glob, Grep, mcp__ace-tool__search_context) to scan for existing design tokens, component files, styling patterns
|
|
||||||
4. Read industry context from session config (industry, strictness, must-have features)
|
|
||||||
|
|
||||||
## Phase 3: Research Execution
|
|
||||||
|
|
||||||
Execute 4 analysis streams:
|
|
||||||
|
|
||||||
**Stream 1 -- Design System Analysis**:
|
|
||||||
- Search for existing design tokens (CSS variables, theme configs, token files)
|
|
||||||
- Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS)
|
|
||||||
- Map color palette, typography scale, spacing system
|
|
||||||
- Find component library usage (MUI, Ant Design, shadcn, custom)
|
|
||||||
- Output: `<session>/research/design-system-analysis.json`
|
|
||||||
|
|
||||||
**Stream 2 -- Component Inventory**:
|
|
||||||
- Find all UI component files; identify props/API surface
|
|
||||||
- Identify states supported (hover, focus, disabled, etc.)
|
|
||||||
- Check accessibility attributes (ARIA labels, roles)
|
|
||||||
- Map inter-component dependencies and usage counts
|
|
||||||
- Output: `<session>/research/component-inventory.json`
|
|
||||||
|
|
||||||
**Stream 3 -- Accessibility Baseline**:
|
|
||||||
- Check ARIA attribute usage patterns, keyboard navigation support
|
|
||||||
- Assess color contrast ratios (if design tokens found)
|
|
||||||
- Find focus management and semantic HTML patterns
|
|
||||||
- Output: `<session>/research/accessibility-audit.json`
|
|
||||||
|
|
||||||
**Stream 4 -- Design Intelligence (ui-ux-pro-max)**:
|
|
||||||
- Call `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` for design system recommendations
|
|
||||||
- Call `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` for UX guidelines
|
|
||||||
- Call `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` for stack guidelines
|
|
||||||
- Degradation: when unavailable, use LLM general knowledge, mark `_source: "llm-general-knowledge"`
|
|
||||||
- Output: `<session>/research/design-intelligence.json`
|
|
||||||
|
|
||||||
Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count.
|
|
||||||
|
|
||||||
## Phase 4: Validation & Output
|
|
||||||
|
|
||||||
1. Verify all 4 output files exist and contain valid JSON with required fields:
|
|
||||||
|
|
||||||
| File | Required Fields |
|
|
||||||
|------|----------------|
|
|
||||||
| design-system-analysis.json | existing_tokens, styling_approach |
|
|
||||||
| component-inventory.json | components array |
|
|
||||||
| accessibility-audit.json | wcag_level |
|
|
||||||
| design-intelligence.json | _source, design_system |
|
|
||||||
|
|
||||||
2. If any file missing or invalid, re-run corresponding stream
|
|
||||||
|
|
||||||
3. Update `<session>/wisdom/.msg/meta.json` under `researcher` namespace:
|
|
||||||
- Read existing -> merge `{ "researcher": { detected_stack, component_count, wcag_level, di_source, scope } }` -> write back
|
|
||||||
@@ -1,70 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: AUDIT
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: audit_passed
|
|
||||||
result: audit_result
|
|
||||||
fix: fix_required
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Design Auditor
|
|
||||||
|
|
||||||
Audit design tokens and component specs for consistency, accessibility compliance, completeness, quality, and industry best-practice adherence. Act as Critic in the designer<->reviewer Generator-Critic loop. Serve as sync point gatekeeper in dual-track pipelines.
|
|
||||||
|
|
||||||
## Phase 2: Context & Artifact Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Design artifacts | <session>/design/*.json, <session>/design/component-specs/*.md | Yes |
|
|
||||||
| Design intelligence | <session>/research/design-intelligence.json | Yes |
|
|
||||||
| Audit history | .msg/meta.json -> reviewer namespace | No |
|
|
||||||
| Build artifacts | <session>/build/**/* | Only for final audit |
|
|
||||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Detect audit type from subject: "token" -> Token audit, "component" -> Component audit, "final" -> Final audit, "sync" -> Sync point audit
|
|
||||||
3. Read design intelligence for anti-patterns and ux_guidelines
|
|
||||||
4. Read design artifacts: design-tokens.json (token/component audit), component-specs/*.md (component/final audit), build/**/* (final audit only)
|
|
||||||
5. Load audit_history from meta.json for trend analysis
|
|
||||||
|
|
||||||
## Phase 3: Audit Execution
|
|
||||||
|
|
||||||
Score 5 dimensions on 1-10 scale:
|
|
||||||
|
|
||||||
| Dimension | Weight | Focus |
|
|
||||||
|-----------|--------|-------|
|
|
||||||
| Consistency | 20% | Token usage, naming conventions, visual uniformity |
|
|
||||||
| Accessibility | 25% | WCAG AA compliance, ARIA attributes, keyboard nav, contrast |
|
|
||||||
| Completeness | 20% | All states defined, responsive specs, edge cases |
|
|
||||||
| Quality | 15% | Token reference integrity, documentation clarity, maintainability |
|
|
||||||
| Industry Compliance | 20% | Anti-pattern avoidance, UX best practices, design intelligence adherence |
|
|
||||||
|
|
||||||
**Token Audit**: Naming convention (kebab-case, semantic names), value patterns (consistent units), theme completeness (light+dark for all colors), contrast ratios (text on background >= 4.5:1), minimum font sizes (>= 12px), all categories present, W3C $type metadata, no duplicates.
|
|
||||||
|
|
||||||
**Component Audit**: Token references resolve, naming matches convention, ARIA roles defined, keyboard behavior specified, focus indicator defined, all 5 states present, responsive breakpoints specified, variants documented, clear descriptions.
|
|
||||||
|
|
||||||
**Final Audit (cross-cutting)**: Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns).
|
|
||||||
|
|
||||||
**Score calculation**: `overallScore = round(consistency*0.20 + accessibility*0.25 + completeness*0.20 + quality*0.15 + industryCompliance*0.20)`
|
|
||||||
|
|
||||||
**Signal determination**:
|
|
||||||
|
|
||||||
| Condition | Signal |
|
|
||||||
|-----------|--------|
|
|
||||||
| Score >= 8 AND critical_count === 0 | `audit_passed` (GC CONVERGED) |
|
|
||||||
| Score >= 6 AND critical_count === 0 | `audit_result` (GC REVISION NEEDED) |
|
|
||||||
| Score < 6 OR critical_count > 0 | `fix_required` (CRITICAL FIX NEEDED) |
|
|
||||||
|
|
||||||
## Phase 4: Report & Output
|
|
||||||
|
|
||||||
1. Write audit report to `<session>/audit/audit-{NNN}.md`:
|
|
||||||
- Summary: overall score, signal, critical/high/medium counts
|
|
||||||
- Sync Point Status (if applicable): PASSED/BLOCKED
|
|
||||||
- Dimension Scores table (score/weight/weighted per dimension)
|
|
||||||
- Critical/High/Medium issues with descriptions, locations, fix suggestions
|
|
||||||
- GC Loop Status: signal, action required
|
|
||||||
- Trend analysis (if audit_history exists): improving/stable/declining
|
|
||||||
|
|
||||||
2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
|
|
||||||
- Read existing -> merge `{ "reviewer": { audit_id, score, critical_count, signal, is_sync_point, audit_type, timestamp } }` -> write back
|
|
||||||
@@ -1,191 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: DESIGN
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: design_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# UX Designer
|
|
||||||
|
|
||||||
Design feedback mechanisms (loading/error/success states) and state management patterns (React/Vue reactive updates).
|
|
||||||
|
|
||||||
## Phase 2: Context & Pattern Loading
|
|
||||||
|
|
||||||
1. Load diagnosis report from `<session>/artifacts/diagnosis.md`
|
|
||||||
2. Load diagnoser state via `team_msg(operation="get_state", session_id=<session-id>, role="diagnoser")`
|
|
||||||
3. Detect framework from project structure
|
|
||||||
4. Load framework-specific patterns:
|
|
||||||
|
|
||||||
| Framework | State Pattern | Event Pattern |
|
|
||||||
|-----------|---------------|---------------|
|
|
||||||
| React | useState, useRef | onClick, onChange |
|
|
||||||
| Vue | ref, reactive | @click, @change |
|
|
||||||
|
|
||||||
### Wisdom Input
|
|
||||||
|
|
||||||
1. Read `<session>/wisdom/patterns/ui-feedback.md` for established feedback design patterns
|
|
||||||
2. Read `<session>/wisdom/patterns/state-management.md` for state handling patterns
|
|
||||||
3. Read `<session>/wisdom/principles/general-ux.md` for UX design principles
|
|
||||||
4. Apply patterns when designing solutions for identified issues
|
|
||||||
|
|
||||||
### Complex Design (use CLI)
|
|
||||||
|
|
||||||
For complex multi-component solutions:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash(`ccw cli -p "PURPOSE: Design comprehensive feedback mechanism for multi-step form
|
|
||||||
CONTEXT: @<component-files>
|
|
||||||
EXPECTED: Complete design with state flow diagram and code patterns
|
|
||||||
CONSTRAINTS: Must support React hooks" --tool gemini --mode analysis`)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 3: Solution Design
|
|
||||||
|
|
||||||
For each diagnosed issue, design solution:
|
|
||||||
|
|
||||||
### Feedback Mechanism Design
|
|
||||||
|
|
||||||
| Issue Type | Solution Design |
|
|
||||||
|------------|-----------------|
|
|
||||||
| Missing loading | Add loading state + UI indicator (spinner, disabled button) |
|
|
||||||
| Missing error | Add error state + error message display |
|
|
||||||
| Missing success | Add success state + confirmation toast/message |
|
|
||||||
| No empty state | Add conditional rendering for empty data |
|
|
||||||
|
|
||||||
### State Management Design
|
|
||||||
|
|
||||||
**React Pattern**:
|
|
||||||
```typescript
|
|
||||||
// Add state variables
|
|
||||||
const [isLoading, setIsLoading] = useState(false);
|
|
||||||
const [error, setError] = useState<string | null>(null);
|
|
||||||
|
|
||||||
// Wrap async operation
|
|
||||||
const handleSubmit = async (event: React.FormEvent) => {
|
|
||||||
event.preventDefault();
|
|
||||||
setIsLoading(true);
|
|
||||||
setError(null);
|
|
||||||
|
|
||||||
try {
|
|
||||||
const response = await fetch('/api/upload', { method: 'POST', body: formData });
|
|
||||||
if (!response.ok) throw new Error('Upload failed');
|
|
||||||
// Success handling
|
|
||||||
} catch (err: any) {
|
|
||||||
setError(err.message || 'An error occurred');
|
|
||||||
} finally {
|
|
||||||
setIsLoading(false);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
// UI binding
|
|
||||||
<button type="submit" disabled={isLoading}>
|
|
||||||
{isLoading ? 'Uploading...' : 'Upload File'}
|
|
||||||
</button>
|
|
||||||
{error && <p style={{ color: 'red' }}>{error}</p>}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Vue Pattern**:
|
|
||||||
```typescript
|
|
||||||
// Add reactive state
|
|
||||||
const isLoading = ref(false);
|
|
||||||
const error = ref<string | null>(null);
|
|
||||||
|
|
||||||
// Wrap async operation
|
|
||||||
const handleSubmit = async () => {
|
|
||||||
isLoading.value = true;
|
|
||||||
error.value = null;
|
|
||||||
|
|
||||||
try {
|
|
||||||
const response = await fetch('/api/upload', { method: 'POST', body: formData });
|
|
||||||
if (!response.ok) throw new Error('Upload failed');
|
|
||||||
// Success handling
|
|
||||||
} catch (err: any) {
|
|
||||||
error.value = err.message || 'An error occurred';
|
|
||||||
} finally {
|
|
||||||
isLoading.value = false;
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
// UI binding
|
|
||||||
<button @click="handleSubmit" :disabled="isLoading">
|
|
||||||
{{ isLoading ? 'Uploading...' : 'Upload File' }}
|
|
||||||
</button>
|
|
||||||
<p v-if="error" style="color: red">{{ error }}</p>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Input Control Design
|
|
||||||
|
|
||||||
| Issue | Solution |
|
|
||||||
|-------|----------|
|
|
||||||
| Text input for file path | Add file picker: `<input type="file" />` |
|
|
||||||
| Text input for folder path | Add directory picker: `<input type="file" webkitdirectory />` |
|
|
||||||
| No validation | Add validation rules and error messages |
|
|
||||||
|
|
||||||
## Phase 4: Design Document Generation
|
|
||||||
|
|
||||||
1. Generate implementation guide for each issue:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Design Guide
|
|
||||||
|
|
||||||
## Issue #1: Upload form no loading state
|
|
||||||
|
|
||||||
### Solution Design
|
|
||||||
Add loading state with UI feedback and error handling.
|
|
||||||
|
|
||||||
### State Variables (React)
|
|
||||||
```typescript
|
|
||||||
const [isLoading, setIsLoading] = useState(false);
|
|
||||||
const [error, setError] = useState<string | null>(null);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Event Handler
|
|
||||||
```typescript
|
|
||||||
const handleUpload = async (event: React.FormEvent) => {
|
|
||||||
event.preventDefault();
|
|
||||||
setIsLoading(true);
|
|
||||||
setError(null);
|
|
||||||
|
|
||||||
try {
|
|
||||||
// API call
|
|
||||||
} catch (err: any) {
|
|
||||||
setError(err.message);
|
|
||||||
} finally {
|
|
||||||
setIsLoading(false);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### UI Binding
|
|
||||||
```tsx
|
|
||||||
<button type="submit" disabled={isLoading}>
|
|
||||||
{isLoading ? 'Uploading...' : 'Upload File'}
|
|
||||||
</button>
|
|
||||||
{error && <p className="error">{error}</p>}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Acceptance Criteria
|
|
||||||
- Loading state shows during upload
|
|
||||||
- Button disabled during upload
|
|
||||||
- Error message displays on failure
|
|
||||||
- Success confirmation on completion
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Write guide to `<session>/artifacts/design-guide.md`
|
|
||||||
|
|
||||||
### Wisdom Contribution
|
|
||||||
|
|
||||||
If novel design patterns created:
|
|
||||||
1. Write new patterns to `<session>/wisdom/contributions/designer-pattern-<timestamp>.md`
|
|
||||||
2. Format: Problem context, solution design, implementation hints, trade-offs
|
|
||||||
|
|
||||||
3. Share state via team_msg:
|
|
||||||
```
|
|
||||||
team_msg(operation="log", session_id=<session-id>, from="designer",
|
|
||||||
type="state_update", data={
|
|
||||||
designed_solutions: <count>,
|
|
||||||
framework: <framework>,
|
|
||||||
patterns_used: [<pattern-list>]
|
|
||||||
})
|
|
||||||
```
|
|
||||||
@@ -1,110 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: DIAG
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: diag_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# State Diagnoser
|
|
||||||
|
|
||||||
Diagnose root causes of UI issues: state management problems, event binding failures, async handling errors.
|
|
||||||
|
|
||||||
## Phase 2: Context & Complexity Assessment
|
|
||||||
|
|
||||||
1. Load scan report from `<session>/artifacts/scan-report.md`
|
|
||||||
2. Load scanner state via `team_msg(operation="get_state", session_id=<session-id>, role="scanner")`
|
|
||||||
|
|
||||||
### Wisdom Input
|
|
||||||
|
|
||||||
1. Read `<session>/wisdom/patterns/ui-feedback.md` and `<session>/wisdom/patterns/state-management.md` if available
|
|
||||||
2. Use patterns to identify root causes of UI interaction issues
|
|
||||||
3. Reference `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common causes
|
|
||||||
|
|
||||||
3. Assess issue complexity:
|
|
||||||
|
|
||||||
| Complexity | Criteria | Strategy |
|
|
||||||
|------------|----------|----------|
|
|
||||||
| High | 5+ issues, cross-component state | CLI delegation |
|
|
||||||
| Medium | 2-4 issues, single component | CLI for analysis |
|
|
||||||
| Low | 1 issue, simple pattern | Inline analysis |
|
|
||||||
|
|
||||||
### Complex Analysis (use CLI)
|
|
||||||
|
|
||||||
For complex multi-file state management issues:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash(`ccw cli -p "PURPOSE: Analyze state management patterns and identify root causes
|
|
||||||
CONTEXT: @<issue-files>
|
|
||||||
EXPECTED: Root cause analysis with fix recommendations
|
|
||||||
CONSTRAINTS: Focus on reactive update patterns" --tool gemini --mode analysis`)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 3: Root Cause Analysis
|
|
||||||
|
|
||||||
For each issue from scan report:
|
|
||||||
|
|
||||||
### State Management Diagnosis
|
|
||||||
|
|
||||||
| Pattern | Root Cause | Fix Strategy |
|
|
||||||
|---------|------------|--------------|
|
|
||||||
| Array.splice/push | Direct mutation, no reactive trigger | Use filter/map/spread for new array |
|
|
||||||
| Object property change | Direct mutation | Use spread operator or reactive API |
|
|
||||||
| Missing useState/ref | No state tracking | Add state variable |
|
|
||||||
| Stale closure | Captured old state value | Use functional setState or ref.current |
|
|
||||||
|
|
||||||
### Event Binding Diagnosis
|
|
||||||
|
|
||||||
| Pattern | Root Cause | Fix Strategy |
|
|
||||||
|---------|------------|--------------|
|
|
||||||
| onClick without handler | Missing event binding | Add event handler function |
|
|
||||||
| Async without await | Unhandled promise | Add async/await or .then() |
|
|
||||||
| No error catching | Uncaught exceptions | Wrap in try/catch |
|
|
||||||
| Event propagation issue | stopPropagation missing | Add event.stopPropagation() |
|
|
||||||
|
|
||||||
### Async Handling Diagnosis
|
|
||||||
|
|
||||||
| Pattern | Root Cause | Fix Strategy |
|
|
||||||
|---------|------------|--------------|
|
|
||||||
| No loading state | Missing async state tracking | Add isLoading state |
|
|
||||||
| No error handling | Missing catch block | Add try/catch with error state |
|
|
||||||
| Race condition | Multiple concurrent requests | Add request cancellation or debounce |
|
|
||||||
|
|
||||||
## Phase 4: Diagnosis Report
|
|
||||||
|
|
||||||
1. Generate root cause analysis for each issue:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Diagnosis Report
|
|
||||||
|
|
||||||
## Issue #1: Upload form no loading state
|
|
||||||
- **File**: src/components/Upload.tsx:45
|
|
||||||
- **Root Cause**: Form submit handler is async but no loading state variable exists
|
|
||||||
- **Pattern Type**: Missing async state tracking
|
|
||||||
- **Fix Recommendation**:
|
|
||||||
- Add `const [isLoading, setIsLoading] = useState(false)` (React)
|
|
||||||
- Add `const isLoading = ref(false)` (Vue)
|
|
||||||
- Wrap async call in try/finally with setIsLoading(true/false)
|
|
||||||
- Disable button when isLoading is true
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Write report to `<session>/artifacts/diagnosis.md`
|
|
||||||
|
|
||||||
### Wisdom Contribution
|
|
||||||
|
|
||||||
If new root cause patterns discovered:
|
|
||||||
1. Write diagnosis patterns to `<session>/wisdom/contributions/diagnoser-patterns-<timestamp>.md`
|
|
||||||
2. Format: Symptom, root cause, detection method, fix approach
|
|
||||||
|
|
||||||
3. Share state via team_msg:
|
|
||||||
```
|
|
||||||
team_msg(operation="log", session_id=<session-id>, from="diagnoser",
|
|
||||||
type="state_update", data={
|
|
||||||
diagnosed_issues: <count>,
|
|
||||||
pattern_types: {
|
|
||||||
state_management: <count>,
|
|
||||||
event_binding: <count>,
|
|
||||||
async_handling: <count>
|
|
||||||
}
|
|
||||||
})
|
|
||||||
```
|
|
||||||
@@ -1,109 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: EXPLORE
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: explore_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Codebase Explorer
|
|
||||||
|
|
||||||
Explore codebase for UI component patterns, state management conventions, and framework-specific patterns. Callable by coordinator only.
|
|
||||||
|
|
||||||
## Phase 2: Exploration Scope
|
|
||||||
|
|
||||||
1. Parse exploration request from task description
|
|
||||||
2. Determine file patterns based on framework:
|
|
||||||
|
|
||||||
### Wisdom Input
|
|
||||||
|
|
||||||
1. Read `<session>/wisdom/patterns/ui-feedback.md` and `<session>/wisdom/patterns/state-management.md` if available
|
|
||||||
2. Use known patterns as reference when exploring codebase for component structures
|
|
||||||
3. Check `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` to identify problematic patterns during exploration
|
|
||||||
|
|
||||||
| Framework | Patterns |
|
|
||||||
|-----------|----------|
|
|
||||||
| React | `**/*.tsx`, `**/*.jsx`, `**/use*.ts`, `**/store*.ts` |
|
|
||||||
| Vue | `**/*.vue`, `**/composables/*.ts`, `**/stores/*.ts` |
|
|
||||||
|
|
||||||
3. Check exploration cache: `<session>/explorations/cache-index.json`
|
|
||||||
- If cache hit and fresh -> return cached results
|
|
||||||
- If cache miss or stale -> proceed to Phase 3
|
|
||||||
|
|
||||||
## Phase 3: Codebase Exploration
|
|
||||||
|
|
||||||
Use ACE search for semantic queries:
|
|
||||||
|
|
||||||
```
|
|
||||||
mcp__ace-tool__search_context(
|
|
||||||
project_root_path="<project-path>",
|
|
||||||
query="<exploration-query>"
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
Exploration dimensions:
|
|
||||||
|
|
||||||
| Dimension | Query | Purpose |
|
|
||||||
|-----------|-------|---------|
|
|
||||||
| Component patterns | "UI components with user interactions" | Find interactive components |
|
|
||||||
| State management | "State management patterns useState ref reactive" | Identify state conventions |
|
|
||||||
| Event handling | "Event handlers onClick onChange onSubmit" | Map event patterns |
|
|
||||||
| Error handling | "Error handling try catch error state" | Find error patterns |
|
|
||||||
| Feedback mechanisms | "Loading state spinner progress indicator" | Find existing feedback |
|
|
||||||
|
|
||||||
For each dimension, collect:
|
|
||||||
- File paths
|
|
||||||
- Pattern examples
|
|
||||||
- Convention notes
|
|
||||||
|
|
||||||
## Phase 4: Exploration Summary
|
|
||||||
|
|
||||||
1. Generate pattern summary:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Exploration Summary
|
|
||||||
|
|
||||||
## Framework: React/Vue
|
|
||||||
|
|
||||||
## Component Patterns
|
|
||||||
- Button components use <pattern>
|
|
||||||
- Form components use <pattern>
|
|
||||||
|
|
||||||
## State Management Conventions
|
|
||||||
- Global state: Zustand/Pinia
|
|
||||||
- Local state: useState/ref
|
|
||||||
- Async state: custom hooks/composables
|
|
||||||
|
|
||||||
## Event Handling Patterns
|
|
||||||
- Form submit: <pattern>
|
|
||||||
- Button click: <pattern>
|
|
||||||
|
|
||||||
## Existing Feedback Mechanisms
|
|
||||||
- Loading: <pattern>
|
|
||||||
- Error: <pattern>
|
|
||||||
- Success: <pattern>
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Cache results to `<session>/explorations/cache-index.json`
|
|
||||||
3. Write summary to `<session>/explorations/exploration-summary.md`
|
|
||||||
|
|
||||||
### Wisdom Contribution
|
|
||||||
|
|
||||||
If new component patterns or framework conventions discovered:
|
|
||||||
1. Write pattern summaries to `<session>/wisdom/contributions/explorer-patterns-<timestamp>.md`
|
|
||||||
2. Format:
|
|
||||||
- Pattern Name: Descriptive name
|
|
||||||
- Framework: React/Vue/etc.
|
|
||||||
- Use Case: When to apply this pattern
|
|
||||||
- Code Example: Representative snippet
|
|
||||||
- Adoption: How widely used in codebase
|
|
||||||
|
|
||||||
4. Share state via team_msg:
|
|
||||||
```
|
|
||||||
team_msg(operation="log", session_id=<session-id>, from="explorer",
|
|
||||||
type="state_update", data={
|
|
||||||
framework: <framework>,
|
|
||||||
components_found: <count>,
|
|
||||||
patterns_identified: [<pattern-list>]
|
|
||||||
})
|
|
||||||
```
|
|
||||||
@@ -1,164 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: IMPL
|
|
||||||
inner_loop: true
|
|
||||||
message_types:
|
|
||||||
success: impl_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# Code Implementer
|
|
||||||
|
|
||||||
Generate executable fix code with proper state management, event handling, and UI feedback bindings.
|
|
||||||
|
|
||||||
## Phase 2: Task & Design Loading
|
|
||||||
|
|
||||||
1. Extract session path from task description
|
|
||||||
2. Read design guide: `<session>/artifacts/design-guide.md`
|
|
||||||
3. Extract implementation tasks from design guide
|
|
||||||
4. **Wisdom Input**:
|
|
||||||
- Read `<session>/wisdom/patterns/state-management.md` for state handling patterns
|
|
||||||
- Read `<session>/wisdom/patterns/ui-feedback.md` for UI feedback implementation patterns
|
|
||||||
- Read `<session>/wisdom/principles/general-ux.md` for implementation principles
|
|
||||||
- Load framework-specific conventions if available
|
|
||||||
- Apply these patterns and principles when generating code to ensure consistency and quality
|
|
||||||
5. **For inner loop**: Load context_accumulator from prior IMPL tasks
|
|
||||||
|
|
||||||
### Context Accumulator (Inner Loop)
|
|
||||||
|
|
||||||
```
|
|
||||||
context_accumulator = {
|
|
||||||
completed_fixes: [<fix-1>, <fix-2>],
|
|
||||||
modified_files: [<file-1>, <file-2>],
|
|
||||||
patterns_applied: [<pattern-1>]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 3: Code Implementation
|
|
||||||
|
|
||||||
Implementation backend selection:
|
|
||||||
|
|
||||||
| Backend | Condition | Method |
|
|
||||||
|---------|-----------|--------|
|
|
||||||
| CLI | Complex multi-file changes | `ccw cli --tool gemini --mode write` |
|
|
||||||
| Direct | Simple single-file changes | Inline Edit/Write |
|
|
||||||
|
|
||||||
### CLI Implementation (Complex)
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash(`ccw cli -p "PURPOSE: Implement loading state and error handling for upload form
|
|
||||||
TASK:
|
|
||||||
- Add useState for isLoading and error
|
|
||||||
- Wrap async call in try/catch/finally
|
|
||||||
- Update UI bindings for button and error display
|
|
||||||
CONTEXT: @src/components/Upload.tsx
|
|
||||||
EXPECTED: Modified Upload.tsx with complete implementation
|
|
||||||
CONSTRAINTS: Maintain existing code style" --tool gemini --mode write`)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Direct Implementation (Simple)
|
|
||||||
|
|
||||||
For simple state variable additions or UI binding changes:
|
|
||||||
|
|
||||||
```
|
|
||||||
Edit({
|
|
||||||
file_path: "src/components/Upload.tsx",
|
|
||||||
old_string: "const handleUpload = async () => {",
|
|
||||||
new_string: "const [isLoading, setIsLoading] = useState(false);\nconst [error, setError] = useState<string | null>(null);\n\nconst handleUpload = async () => {\n setIsLoading(true);\n setError(null);\n try {"
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### Implementation Steps
|
|
||||||
|
|
||||||
For each fix in design guide:
|
|
||||||
1. Read target file
|
|
||||||
2. Determine complexity (simple vs complex)
|
|
||||||
3. Apply fix using appropriate backend
|
|
||||||
4. Verify syntax (no compilation errors)
|
|
||||||
5. Append to context_accumulator
|
|
||||||
|
|
||||||
## Phase 4: Self-Validation
|
|
||||||
|
|
||||||
| Check | Method | Pass Criteria |
|
|
||||||
|-------|--------|---------------|
|
|
||||||
| Syntax | IDE diagnostics or tsc --noEmit | No errors |
|
|
||||||
| File existence | Verify planned files exist | All present |
|
|
||||||
| Acceptance criteria | Match against design guide | All met |
|
|
||||||
|
|
||||||
Validation steps:
|
|
||||||
1. Run syntax check on modified files
|
|
||||||
2. Verify all files from design guide exist
|
|
||||||
3. Check acceptance criteria from design guide
|
|
||||||
4. If validation fails -> attempt auto-fix (max 2 attempts)
|
|
||||||
|
|
||||||
### Context Accumulator Update
|
|
||||||
|
|
||||||
Append to context_accumulator:
|
|
||||||
```
|
|
||||||
{
|
|
||||||
completed_fixes: [...prev, <current-fix>],
|
|
||||||
modified_files: [...prev, <current-files>],
|
|
||||||
patterns_applied: [...prev, <current-patterns>]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Write summary to `<session>/artifacts/fixes/README.md`:
|
|
||||||
```markdown
|
|
||||||
# Implementation Summary
|
|
||||||
|
|
||||||
## Completed Fixes
|
|
||||||
- Issue #1: Upload form loading state - DONE
|
|
||||||
- Issue #2: Error handling - DONE
|
|
||||||
|
|
||||||
## Modified Files
|
|
||||||
- src/components/Upload.tsx
|
|
||||||
- src/components/Form.tsx
|
|
||||||
|
|
||||||
## Patterns Applied
|
|
||||||
- React useState for loading/error states
|
|
||||||
- try/catch/finally for async handling
|
|
||||||
- Conditional rendering for error messages
|
|
||||||
```
|
|
||||||
|
|
||||||
Share state via team_msg:
|
|
||||||
```
|
|
||||||
team_msg(operation="log", session_id=<session-id>, from="implementer",
|
|
||||||
type="state_update", data={
|
|
||||||
completed_fixes: <count>,
|
|
||||||
modified_files: [<file-list>],
|
|
||||||
validation_passed: true
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### Wisdom Contribution
|
|
||||||
|
|
||||||
If reusable code patterns or snippets created:
|
|
||||||
1. Write code snippets to `<session>/wisdom/contributions/implementer-snippets-<timestamp>.md`
|
|
||||||
2. Format: Use case, code snippet with comments, framework compatibility notes
|
|
||||||
|
|
||||||
Example contribution format:
|
|
||||||
```markdown
|
|
||||||
# Implementer Snippets - <timestamp>
|
|
||||||
|
|
||||||
## Loading State Pattern (React)
|
|
||||||
|
|
||||||
### Use Case
|
|
||||||
Async operations requiring loading indicator
|
|
||||||
|
|
||||||
### Code Snippet
|
|
||||||
```tsx
|
|
||||||
const [isLoading, setIsLoading] = useState(false);
|
|
||||||
|
|
||||||
const handleAsyncAction = async () => {
|
|
||||||
setIsLoading(true);
|
|
||||||
try {
|
|
||||||
await performAction();
|
|
||||||
} finally {
|
|
||||||
setIsLoading(false);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### Framework Compatibility
|
|
||||||
- React 16.8+ (hooks)
|
|
||||||
- Next.js compatible
|
|
||||||
```
|
|
||||||
@@ -1,117 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: SCAN
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: scan_complete
|
|
||||||
error: error
|
|
||||||
---
|
|
||||||
|
|
||||||
# UI Scanner
|
|
||||||
|
|
||||||
Scan UI components to identify interaction issues: unresponsive buttons, missing feedback mechanisms, state not refreshing.
|
|
||||||
|
|
||||||
## Phase 2: Context Loading
|
|
||||||
|
|
||||||
| Input | Source | Required |
|
|
||||||
|-------|--------|----------|
|
|
||||||
| Project path | Task description CONTEXT | Yes |
|
|
||||||
| Framework | Task description CONTEXT | Yes |
|
|
||||||
| Scan scope | Task description CONSTRAINTS | Yes |
|
|
||||||
|
|
||||||
1. Extract session path and project path from task description
|
|
||||||
2. Detect framework from project structure:
|
|
||||||
|
|
||||||
| Signal | Framework |
|
|
||||||
|--------|-----------|
|
|
||||||
| package.json has "react" | React |
|
|
||||||
| package.json has "vue" | Vue |
|
|
||||||
| *.tsx files present | React |
|
|
||||||
| *.vue files present | Vue |
|
|
||||||
|
|
||||||
3. Build file pattern list for scanning:
|
|
||||||
- React: `**/*.tsx`, `**/*.jsx`, `**/use*.ts`
|
|
||||||
- Vue: `**/*.vue`, `**/composables/*.ts`
|
|
||||||
|
|
||||||
### Wisdom Input
|
|
||||||
|
|
||||||
1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` if available
|
|
||||||
2. Use anti-patterns to identify known UX issues during scanning
|
|
||||||
3. Check `<session>/wisdom/patterns/ui-feedback.md` for expected feedback patterns
|
|
||||||
|
|
||||||
### Complex Analysis (use CLI)
|
|
||||||
|
|
||||||
For large projects with many components:
|
|
||||||
|
|
||||||
```
|
|
||||||
Bash(`ccw cli -p "PURPOSE: Discover all UI components with user interactions
|
|
||||||
CONTEXT: @<project-path>/**/*.tsx @<project-path>/**/*.vue
|
|
||||||
EXPECTED: Component list with interaction types (click, submit, input, select)
|
|
||||||
CONSTRAINTS: Focus on interactive components only" --tool gemini --mode analysis`)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Phase 3: Component Scanning
|
|
||||||
|
|
||||||
Scan strategy:
|
|
||||||
|
|
||||||
| Category | Detection Pattern | Severity |
|
|
||||||
|----------|-------------------|----------|
|
|
||||||
| Unresponsive actions | onClick/\@click without async handling or error catching | High |
|
|
||||||
| Missing loading state | Form submit without isLoading/loading ref | High |
|
|
||||||
| State not refreshing | Array.splice/push without reactive reassignment | High |
|
|
||||||
| Missing error feedback | try/catch without error state or user notification | Medium |
|
|
||||||
| Missing success feedback | API call without success confirmation | Medium |
|
|
||||||
| No empty state | Data list without empty state placeholder | Low |
|
|
||||||
| Input without validation | Form input without validation rules | Low |
|
|
||||||
| Missing file selector | Text input for file/folder path without picker | Medium |
|
|
||||||
|
|
||||||
For each component file:
|
|
||||||
1. Read file content
|
|
||||||
2. Scan for interaction patterns using Grep
|
|
||||||
3. Check for feedback mechanisms (loading, error, success states)
|
|
||||||
4. Check state update patterns (mutation vs reactive)
|
|
||||||
5. Record issues with file:line references
|
|
||||||
|
|
||||||
## Phase 4: Issue Report Generation
|
|
||||||
|
|
||||||
1. Classify issues by severity (High/Medium/Low)
|
|
||||||
2. Group by category (unresponsive, missing feedback, state issues, input UX)
|
|
||||||
3. Generate structured report:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# UI Scan Report
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
- Total issues: <count>
|
|
||||||
- High: <count> | Medium: <count> | Low: <count>
|
|
||||||
|
|
||||||
## Issues
|
|
||||||
|
|
||||||
### High Severity
|
|
||||||
| # | File:Line | Component | Issue | Category |
|
|
||||||
|---|-----------|-----------|-------|----------|
|
|
||||||
| 1 | src/components/Upload.tsx:45 | UploadForm | No loading state on submit | Missing feedback |
|
|
||||||
|
|
||||||
### Medium Severity
|
|
||||||
...
|
|
||||||
|
|
||||||
### Low Severity
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Write report to `<session>/artifacts/scan-report.md`
|
|
||||||
5. Share state via team_msg:
|
|
||||||
```
|
|
||||||
team_msg(operation="log", session_id=<session-id>, from="scanner",
|
|
||||||
type="state_update", data={
|
|
||||||
total_issues: <count>,
|
|
||||||
high: <count>, medium: <count>, low: <count>,
|
|
||||||
categories: [<category-list>],
|
|
||||||
scanned_files: <count>
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### Wisdom Contribution
|
|
||||||
|
|
||||||
If novel UX issues discovered that aren't in anti-patterns:
|
|
||||||
1. Write findings to `<session>/wisdom/contributions/scanner-issues-<timestamp>.md`
|
|
||||||
2. Format: Issue description, detection criteria, affected components
|
|
||||||
@@ -1,163 +0,0 @@
|
|||||||
---
|
|
||||||
prefix: TEST
|
|
||||||
inner_loop: false
|
|
||||||
message_types:
|
|
||||||
success: test_complete
|
|
||||||
error: error
|
|
||||||
fix: fix_required
|
|
||||||
---
|
|
||||||
|
|
||||||
# Test Engineer
|
|
||||||
|
|
||||||
Generate and run tests to verify fixes (loading states, error handling, state updates).
|
|
||||||
|
|
||||||
## Phase 2: Environment Detection
|
|
||||||
|
|
||||||
1. Detect test framework from project files:
|
|
||||||
|
|
||||||
| Signal | Framework |
|
|
||||||
|--------|-----------|
|
|
||||||
| package.json has "jest" | Jest |
|
|
||||||
| package.json has "vitest" | Vitest |
|
|
||||||
| package.json has "@testing-library/react" | React Testing Library |
|
|
||||||
| package.json has "@vue/test-utils" | Vue Test Utils |
|
|
||||||
|
|
||||||
2. Get changed files from implementer state:
|
|
||||||
```
|
|
||||||
team_msg(operation="get_state", session_id=<session-id>, role="implementer")
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Load test strategy from design guide
|
|
||||||
|
|
||||||
### Wisdom Input
|
|
||||||
|
|
||||||
1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common issues to test
|
|
||||||
2. Read `<session>/wisdom/patterns/ui-feedback.md` for expected feedback behaviors to verify
|
|
||||||
3. Use wisdom to design comprehensive test cases covering known edge cases
|
|
||||||
|
|
||||||
## Phase 3: Test Generation & Execution
|
|
||||||
|
|
||||||
### Test Generation
|
|
||||||
|
|
||||||
For each modified file, generate test cases:
|
|
||||||
|
|
||||||
**React Example**:
|
|
||||||
```typescript
|
|
||||||
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
|
|
||||||
import Upload from '../Upload';
|
|
||||||
|
|
||||||
describe('Upload Component', () => {
|
|
||||||
it('shows loading state during upload', async () => {
|
|
||||||
global.fetch = vi.fn(() => Promise.resolve({ ok: true }));
|
|
||||||
|
|
||||||
render(<Upload />);
|
|
||||||
const uploadButton = screen.getByRole('button', { name: /upload/i });
|
|
||||||
|
|
||||||
fireEvent.click(uploadButton);
|
|
||||||
|
|
||||||
// Check loading state
|
|
||||||
await waitFor(() => {
|
|
||||||
expect(screen.getByText(/uploading.../i)).toBeInTheDocument();
|
|
||||||
expect(uploadButton).toBeDisabled();
|
|
||||||
});
|
|
||||||
|
|
||||||
// Check normal state restored
|
|
||||||
await waitFor(() => {
|
|
||||||
expect(uploadButton).not.toBeDisabled();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
it('displays error message on failure', async () => {
|
|
||||||
global.fetch = vi.fn(() => Promise.reject(new Error('Upload failed')));
|
|
||||||
|
|
||||||
render(<Upload />);
|
|
||||||
fireEvent.click(screen.getByRole('button', { name: /upload/i }));
|
|
||||||
|
|
||||||
await waitFor(() => {
|
|
||||||
expect(screen.getByText(/upload failed/i)).toBeInTheDocument();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Test Execution
|
|
||||||
|
|
||||||
Iterative test-fix cycle (max 5 iterations):
|
|
||||||
|
|
||||||
1. Run tests: `npm test` or `npm run test:unit`
|
|
||||||
2. Parse results -> calculate pass rate
|
|
||||||
3. If pass rate >= 95% -> exit (success)
|
|
||||||
4. If pass rate < 95% and iterations < 5:
|
|
||||||
- Analyze failures
|
|
||||||
- Use CLI to generate fixes:
|
|
||||||
```
|
|
||||||
Bash(`ccw cli -p "PURPOSE: Fix test failures
|
|
||||||
CONTEXT: @<test-file> @<source-file>
|
|
||||||
EXPECTED: Fixed code that passes tests
|
|
||||||
CONSTRAINTS: Maintain existing functionality" --tool gemini --mode write`)
|
|
||||||
```
|
|
||||||
- Increment iteration counter
|
|
||||||
- Loop to step 1
|
|
||||||
5. If iterations >= 5 -> send fix_required message
|
|
||||||
|
|
||||||
## Phase 4: Test Report
|
|
||||||
|
|
||||||
### Wisdom Contribution
|
|
||||||
|
|
||||||
If new edge cases or test patterns discovered:
|
|
||||||
1. Write test findings to `<session>/wisdom/contributions/tester-edge-cases-<timestamp>.md`
|
|
||||||
2. Format: Edge case description, test scenario, expected behavior, actual behavior
|
|
||||||
|
|
||||||
Generate test report:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Test Report
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
- Total tests: <count>
|
|
||||||
- Passed: <count>
|
|
||||||
- Failed: <count>
|
|
||||||
- Pass rate: <percentage>%
|
|
||||||
- Fix iterations: <count>
|
|
||||||
|
|
||||||
## Test Results
|
|
||||||
|
|
||||||
### Passed Tests
|
|
||||||
- ✅ Upload Component > shows loading state during upload
|
|
||||||
- ✅ Upload Component > displays error message on failure
|
|
||||||
|
|
||||||
### Failed Tests
|
|
||||||
- ❌ Form Component > validates input before submit
|
|
||||||
- Error: Expected validation message not found
|
|
||||||
|
|
||||||
## Coverage
|
|
||||||
- Statements: 85%
|
|
||||||
- Branches: 78%
|
|
||||||
- Functions: 90%
|
|
||||||
- Lines: 84%
|
|
||||||
|
|
||||||
## Remaining Issues
|
|
||||||
- Form validation test failing (needs manual review)
|
|
||||||
```
|
|
||||||
|
|
||||||
Write report to `<session>/artifacts/test-report.md`
|
|
||||||
|
|
||||||
Share state via team_msg:
|
|
||||||
```
|
|
||||||
team_msg(operation="log", session_id=<session-id>, from="tester",
|
|
||||||
type="state_update", data={
|
|
||||||
total_tests: <count>,
|
|
||||||
passed: <count>,
|
|
||||||
failed: <count>,
|
|
||||||
pass_rate: <percentage>,
|
|
||||||
fix_iterations: <count>
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
If pass rate < 95%, send fix_required message:
|
|
||||||
```
|
|
||||||
SendMessage({
|
|
||||||
to: "coordinator",
|
|
||||||
message: "[tester] Test validation incomplete. Pass rate: <percentage>%. Manual review needed."
|
|
||||||
})
|
|
||||||
```
|
|
||||||
@@ -27,7 +27,7 @@
|
|||||||
"display_name": "UI Scanner",
|
"display_name": "UI Scanner",
|
||||||
"type": "worker",
|
"type": "worker",
|
||||||
"responsibility_type": "read_only_analysis",
|
"responsibility_type": "read_only_analysis",
|
||||||
"role_spec": "role-specs/scanner.md",
|
"role_spec": "roles/scanner/role.md",
|
||||||
"task_prefix": "SCAN",
|
"task_prefix": "SCAN",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
"allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||||
@@ -46,7 +46,7 @@
|
|||||||
"display_name": "State Diagnoser",
|
"display_name": "State Diagnoser",
|
||||||
"type": "worker",
|
"type": "worker",
|
||||||
"responsibility_type": "orchestration",
|
"responsibility_type": "orchestration",
|
||||||
"role_spec": "role-specs/diagnoser.md",
|
"role_spec": "roles/diagnoser/role.md",
|
||||||
"task_prefix": "DIAG",
|
"task_prefix": "DIAG",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"allowed_tools": ["Read", "Grep", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
"allowed_tools": ["Read", "Grep", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||||
@@ -65,7 +65,7 @@
|
|||||||
"display_name": "UX Designer",
|
"display_name": "UX Designer",
|
||||||
"type": "worker",
|
"type": "worker",
|
||||||
"responsibility_type": "orchestration",
|
"responsibility_type": "orchestration",
|
||||||
"role_spec": "role-specs/designer.md",
|
"role_spec": "roles/designer/role.md",
|
||||||
"task_prefix": "DESIGN",
|
"task_prefix": "DESIGN",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"allowed_tools": ["Read", "Write", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
"allowed_tools": ["Read", "Write", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||||
@@ -84,7 +84,7 @@
|
|||||||
"display_name": "Code Implementer",
|
"display_name": "Code Implementer",
|
||||||
"type": "worker",
|
"type": "worker",
|
||||||
"responsibility_type": "code_generation",
|
"responsibility_type": "code_generation",
|
||||||
"role_spec": "role-specs/implementer.md",
|
"role_spec": "roles/implementer/role.md",
|
||||||
"task_prefix": "IMPL",
|
"task_prefix": "IMPL",
|
||||||
"inner_loop": true,
|
"inner_loop": true,
|
||||||
"allowed_tools": ["Read", "Write", "Edit", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__edit_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
"allowed_tools": ["Read", "Write", "Edit", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__edit_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||||
@@ -103,7 +103,7 @@
|
|||||||
"display_name": "Test Engineer",
|
"display_name": "Test Engineer",
|
||||||
"type": "worker",
|
"type": "worker",
|
||||||
"responsibility_type": "validation",
|
"responsibility_type": "validation",
|
||||||
"role_spec": "role-specs/tester.md",
|
"role_spec": "roles/tester/role.md",
|
||||||
"task_prefix": "TEST",
|
"task_prefix": "TEST",
|
||||||
"inner_loop": false,
|
"inner_loop": false,
|
||||||
"allowed_tools": ["Read", "Write", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
"allowed_tools": ["Read", "Write", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||||
@@ -123,7 +123,7 @@
|
|||||||
{
|
{
|
||||||
"name": "explorer",
|
"name": "explorer",
|
||||||
"display_name": "Codebase Explorer",
|
"display_name": "Codebase Explorer",
|
||||||
"role_spec": "role-specs/explorer.md",
|
"role_spec": "roles/explorer/role.md",
|
||||||
"callable_by": "coordinator",
|
"callable_by": "coordinator",
|
||||||
"purpose": "Explore codebase for UI component patterns, state management conventions, and framework-specific patterns",
|
"purpose": "Explore codebase for UI component patterns, state management conventions, and framework-specific patterns",
|
||||||
"allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg"],
|
"allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg"],
|
||||||
|
|||||||
186
.codex/skills/team-designer/agents/validation-reporter.md
Normal file
186
.codex/skills/team-designer/agents/validation-reporter.md
Normal file
@@ -0,0 +1,186 @@
|
|||||||
|
# Validation Reporter Agent
|
||||||
|
|
||||||
|
Validate generated skill package structure and content, reporting results with PASS/WARN/FAIL verdict.
|
||||||
|
|
||||||
|
## Identity
|
||||||
|
|
||||||
|
- **Type**: `interactive`
|
||||||
|
- **Role File**: `agents/validation-reporter.md`
|
||||||
|
- **Responsibility**: Validate generated skill package structure and content, report results
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
### MUST
|
||||||
|
|
||||||
|
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||||
|
- Load the generated skill package from session artifacts
|
||||||
|
- Validate all structural integrity checks
|
||||||
|
- Produce structured output with clear PASS/WARN/FAIL verdict
|
||||||
|
- Include specific file references in findings
|
||||||
|
|
||||||
|
### MUST NOT
|
||||||
|
|
||||||
|
- Skip the MANDATORY FIRST STEPS role loading
|
||||||
|
- Modify generated skill files
|
||||||
|
- Produce unstructured output
|
||||||
|
- Report PASS without actually validating all checks
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toolbox
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
| Tool | Type | Purpose |
|
||||||
|
|------|------|---------|
|
||||||
|
| `Read` | builtin | Load generated skill files and verify content |
|
||||||
|
| `Glob` | builtin | Find files by pattern in skill package |
|
||||||
|
| `Grep` | builtin | Search for cross-references and patterns |
|
||||||
|
| `Bash` | builtin | Run validation commands, check JSON syntax |
|
||||||
|
|
||||||
|
### Tool Usage Patterns
|
||||||
|
|
||||||
|
**Read Pattern**: Load skill package files for validation
|
||||||
|
```
|
||||||
|
Read("{session_folder}/artifacts/<skill-name>/SKILL.md")
|
||||||
|
Read("{session_folder}/artifacts/<skill-name>/team-config.json")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Glob Pattern**: Discover actual role files
|
||||||
|
```
|
||||||
|
Glob("{session_folder}/artifacts/<skill-name>/roles/*.md")
|
||||||
|
Glob("{session_folder}/artifacts/<skill-name>/commands/*.md")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Grep Pattern**: Check cross-references
|
||||||
|
```
|
||||||
|
Grep("role:", "{session_folder}/artifacts/<skill-name>/SKILL.md")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
### Phase 1: Package Loading
|
||||||
|
|
||||||
|
**Objective**: Load the generated skill package from session artifacts.
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
|
||||||
|
| Source | Required | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| Skill package path | Yes | Path to generated skill directory in artifacts/ |
|
||||||
|
| teamConfig.json | Yes | Original configuration used for generation |
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Read SKILL.md from the generated package
|
||||||
|
2. Read team-config.json from the generated package
|
||||||
|
3. Enumerate all files in the package using Glob
|
||||||
|
4. Read teamConfig.json from session folder for comparison
|
||||||
|
|
||||||
|
**Output**: Loaded skill package contents and file inventory
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Structural Validation
|
||||||
|
|
||||||
|
**Objective**: Validate structural integrity of the generated skill package.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. **SKILL.md validation**:
|
||||||
|
- Verify file exists
|
||||||
|
- Verify valid frontmatter (name, description, allowed-tools)
|
||||||
|
- Verify Role Registry table is present
|
||||||
|
|
||||||
|
2. **Role Registry consistency**:
|
||||||
|
- Extract roles listed in SKILL.md Role Registry table
|
||||||
|
- Glob actual files in roles/ directory
|
||||||
|
- Compare: every registry entry has a matching file, every file has a registry entry
|
||||||
|
|
||||||
|
3. **Role file validation**:
|
||||||
|
- Read each role.md in roles/ directory
|
||||||
|
- Verify valid frontmatter (prefix, inner_loop, message_types)
|
||||||
|
- Check frontmatter values are non-empty
|
||||||
|
|
||||||
|
4. **Pipeline validation**:
|
||||||
|
- Extract pipeline stages from SKILL.md or specs/pipelines.md
|
||||||
|
- Verify each stage references an existing role
|
||||||
|
|
||||||
|
5. **team-config.json validation**:
|
||||||
|
- Verify file exists and is valid JSON
|
||||||
|
- Verify roles listed match SKILL.md Role Registry
|
||||||
|
|
||||||
|
6. **Cross-reference validation**:
|
||||||
|
- Check coordinator commands/ files exist if referenced in SKILL.md
|
||||||
|
- Verify no broken file paths in cross-references
|
||||||
|
|
||||||
|
7. **Issue classification**:
|
||||||
|
|
||||||
|
| Finding Severity | Condition | Impact |
|
||||||
|
|------------------|-----------|--------|
|
||||||
|
| FAIL | Missing required file or broken structure | Package unusable |
|
||||||
|
| WARN | Inconsistency between files or missing optional content | Package may have issues |
|
||||||
|
| INFO | Style or formatting suggestions | Non-blocking |
|
||||||
|
|
||||||
|
**Output**: Validation findings with severity classifications
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Verdict Report
|
||||||
|
|
||||||
|
**Objective**: Report validation results with overall verdict.
|
||||||
|
|
||||||
|
| Verdict | Condition | Action |
|
||||||
|
|---------|-----------|--------|
|
||||||
|
| PASS | No FAIL findings, zero or few WARN | Package is ready for use |
|
||||||
|
| WARN | No FAIL findings, but multiple WARN issues | Package usable with noted issues |
|
||||||
|
| FAIL | One or more FAIL findings | Package requires regeneration or manual fix |
|
||||||
|
|
||||||
|
**Output**: Verdict with detailed findings
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Summary
|
||||||
|
- Verdict: PASS | WARN | FAIL
|
||||||
|
- Skill: <skill-name>
|
||||||
|
- Files checked: <count>
|
||||||
|
|
||||||
|
## Findings
|
||||||
|
- [FAIL] description with file reference (if any)
|
||||||
|
- [WARN] description with file reference (if any)
|
||||||
|
- [INFO] description with file reference (if any)
|
||||||
|
|
||||||
|
## Validation Details
|
||||||
|
- SKILL.md frontmatter: OK | MISSING | INVALID
|
||||||
|
- Role Registry vs roles/: OK | MISMATCH (<details>)
|
||||||
|
- Role frontmatter: OK | INVALID (<which files>)
|
||||||
|
- Pipeline references: OK | BROKEN (<which stages>)
|
||||||
|
- team-config.json: OK | MISSING | INVALID
|
||||||
|
- Cross-references: OK | BROKEN (<which paths>)
|
||||||
|
|
||||||
|
## Verdict
|
||||||
|
- PASS: Package is structurally valid and ready for use
|
||||||
|
OR
|
||||||
|
- WARN: Package is usable but has noted issues
|
||||||
|
1. Issue description
|
||||||
|
OR
|
||||||
|
- FAIL: Package requires fixes before use
|
||||||
|
1. Issue description + suggested resolution
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Scenario | Resolution |
|
||||||
|
|----------|------------|
|
||||||
|
| Skill package directory not found | Report as FAIL, request correct path |
|
||||||
|
| SKILL.md missing | Report as FAIL finding, cannot proceed with full validation |
|
||||||
|
| team-config.json invalid JSON | Report as FAIL, include parse error |
|
||||||
|
| Role file unreadable | Report as WARN, note which file |
|
||||||
|
| Timeout approaching | Output current findings with "PARTIAL" status |
|
||||||
193
.codex/skills/team-iterdev/agents/gc-controller.md
Normal file
193
.codex/skills/team-iterdev/agents/gc-controller.md
Normal file
@@ -0,0 +1,193 @@
|
|||||||
|
# GC Controller Agent
|
||||||
|
|
||||||
|
Evaluate review severity after REVIEW wave and decide whether to trigger a DEV-fix iteration or converge the pipeline.
|
||||||
|
|
||||||
|
## Identity
|
||||||
|
|
||||||
|
- **Type**: `interactive`
|
||||||
|
- **Role File**: `agents/gc-controller.md`
|
||||||
|
- **Responsibility**: Evaluate review severity, decide DEV-fix vs convergence
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
### MUST
|
||||||
|
|
||||||
|
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||||
|
- Load review results from completed REVIEW tasks
|
||||||
|
- Evaluate gc_signal and review_score to determine decision
|
||||||
|
- Respect max iteration count to prevent infinite loops
|
||||||
|
- Produce structured output with clear CONVERGE/FIX/ESCALATE decision
|
||||||
|
|
||||||
|
### MUST NOT
|
||||||
|
|
||||||
|
- Skip the MANDATORY FIRST STEPS role loading
|
||||||
|
- Modify source code directly
|
||||||
|
- Produce unstructured output
|
||||||
|
- Exceed max iteration count without escalating
|
||||||
|
- Ignore Critical findings in review results
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toolbox
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
| Tool | Type | Purpose |
|
||||||
|
|------|------|---------|
|
||||||
|
| `Read` | builtin | Load review results and session state |
|
||||||
|
| `Write` | builtin | Create FIX task definitions for next wave |
|
||||||
|
| `Bash` | builtin | Query session state, count iterations |
|
||||||
|
|
||||||
|
### Tool Usage Patterns
|
||||||
|
|
||||||
|
**Read Pattern**: Load review results
|
||||||
|
```
|
||||||
|
Read("{session_folder}/artifacts/review-results.json")
|
||||||
|
Read("{session_folder}/session-state.json")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Write Pattern**: Create FIX tasks for next iteration
|
||||||
|
```
|
||||||
|
Write("{session_folder}/tasks/FIX-<iteration>-<N>.json", <task>)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
### Phase 1: Review Loading
|
||||||
|
|
||||||
|
**Objective**: Load review results from completed REVIEW tasks.
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
|
||||||
|
| Source | Required | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| Review results | Yes | review_score, gc_signal, findings from REVIEW tasks |
|
||||||
|
| Session state | Yes | Current iteration count, max iterations |
|
||||||
|
| Task analysis | No | Original task-analysis.json for context |
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Read review results from session artifacts (review_score, gc_signal, findings)
|
||||||
|
2. Read session state to determine current iteration number
|
||||||
|
3. Read max_iterations from task-analysis.json or default to 3
|
||||||
|
|
||||||
|
**Output**: Loaded review context with iteration state
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Severity Evaluation
|
||||||
|
|
||||||
|
**Objective**: Evaluate review severity and determine pipeline decision.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. **Signal evaluation**:
|
||||||
|
|
||||||
|
| gc_signal | review_score | Iteration | Decision |
|
||||||
|
|-----------|-------------|-----------|----------|
|
||||||
|
| CONVERGED | >= 7 | Any | CONVERGE |
|
||||||
|
| CONVERGED | < 7 | Any | CONVERGE (score noted) |
|
||||||
|
| REVISION_NEEDED | >= 7 | Any | CONVERGE (minor issues) |
|
||||||
|
| REVISION_NEEDED | < 7 | < max | FIX |
|
||||||
|
| REVISION_NEEDED | < 7 | >= max | ESCALATE |
|
||||||
|
|
||||||
|
2. **Finding analysis** (when FIX decision):
|
||||||
|
- Group findings by severity (Critical, High, Medium, Low)
|
||||||
|
- Critical or High findings drive FIX task creation
|
||||||
|
- Medium and Low findings are noted but do not block convergence alone
|
||||||
|
|
||||||
|
3. **Iteration guard**:
|
||||||
|
- Track current iteration count
|
||||||
|
- If iteration >= max_iterations (default 3): force ESCALATE regardless of score
|
||||||
|
- Include iteration history in decision reasoning
|
||||||
|
|
||||||
|
**Output**: GC decision with reasoning
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Decision Execution
|
||||||
|
|
||||||
|
**Objective**: Execute the GC decision.
|
||||||
|
|
||||||
|
| Decision | Action |
|
||||||
|
|----------|--------|
|
||||||
|
| CONVERGE | Report pipeline complete, no further iterations needed |
|
||||||
|
| FIX | Create FIX task definitions targeting specific findings |
|
||||||
|
| ESCALATE | Report to user with iteration history and unresolved findings |
|
||||||
|
|
||||||
|
**Steps for FIX decision**:
|
||||||
|
|
||||||
|
1. Extract actionable findings (Critical and High severity)
|
||||||
|
2. Group findings by target file or module
|
||||||
|
3. Create FIX task JSON for each group:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"task_id": "FIX-<iteration>-<N>",
|
||||||
|
"type": "fix",
|
||||||
|
"iteration": <current + 1>,
|
||||||
|
"target_files": ["<file-list>"],
|
||||||
|
"findings": ["<finding-descriptions>"],
|
||||||
|
"acceptance": "<what-constitutes-fixed>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Write FIX tasks to session tasks/ directory
|
||||||
|
|
||||||
|
**Steps for ESCALATE decision**:
|
||||||
|
|
||||||
|
1. Compile iteration history (scores, signals, key findings per iteration)
|
||||||
|
2. List unresolved Critical/High findings
|
||||||
|
3. Report to user with recommendation
|
||||||
|
|
||||||
|
**Output**: Decision report with created tasks or escalation details
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Summary
|
||||||
|
- Decision: CONVERGE | FIX | ESCALATE
|
||||||
|
- Review score: <score>/10
|
||||||
|
- GC signal: <signal>
|
||||||
|
- Iteration: <current>/<max>
|
||||||
|
|
||||||
|
## Review Analysis
|
||||||
|
- Critical findings: <count>
|
||||||
|
- High findings: <count>
|
||||||
|
- Medium findings: <count>
|
||||||
|
- Low findings: <count>
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
- CONVERGE: Pipeline complete, code meets quality threshold
|
||||||
|
OR
|
||||||
|
- FIX: Creating <N> fix tasks for iteration <next>
|
||||||
|
1. FIX-<id>: <description> targeting <files>
|
||||||
|
2. FIX-<id>: <description> targeting <files>
|
||||||
|
OR
|
||||||
|
- ESCALATE: Max iterations reached, unresolved issues require user input
|
||||||
|
1. Unresolved: <finding-description>
|
||||||
|
2. Unresolved: <finding-description>
|
||||||
|
|
||||||
|
## Iteration History
|
||||||
|
- Iteration 1: score=<N>, signal=<signal>, findings=<count>
|
||||||
|
- Iteration 2: score=<N>, signal=<signal>, findings=<count>
|
||||||
|
|
||||||
|
## Reasoning
|
||||||
|
- <Why this decision was made>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Scenario | Resolution |
|
||||||
|
|----------|------------|
|
||||||
|
| Review results not found | Report as error, cannot make GC decision |
|
||||||
|
| Missing gc_signal field | Infer from review_score: >= 7 treat as CONVERGED, < 7 as REVISION_NEEDED |
|
||||||
|
| Missing review_score field | Infer from gc_signal and findings count |
|
||||||
|
| Session state corrupted | Default to iteration 1, note uncertainty |
|
||||||
|
| Timeout approaching | Output current decision with "PARTIAL" status |
|
||||||
206
.codex/skills/team-iterdev/agents/task-analyzer.md
Normal file
206
.codex/skills/team-iterdev/agents/task-analyzer.md
Normal file
@@ -0,0 +1,206 @@
|
|||||||
|
# Task Analyzer Agent
|
||||||
|
|
||||||
|
Analyze task complexity, detect required capabilities, and select the appropriate pipeline mode for iterative development.
|
||||||
|
|
||||||
|
## Identity
|
||||||
|
|
||||||
|
- **Type**: `interactive`
|
||||||
|
- **Role File**: `agents/task-analyzer.md`
|
||||||
|
- **Responsibility**: Analyze task complexity, detect required capabilities, select pipeline mode
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
### MUST
|
||||||
|
|
||||||
|
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||||
|
- Parse user requirement to detect project type
|
||||||
|
- Analyze complexity by file count and dependency depth
|
||||||
|
- Select appropriate pipeline mode based on analysis
|
||||||
|
- Produce structured output with task-analysis JSON
|
||||||
|
|
||||||
|
### MUST NOT
|
||||||
|
|
||||||
|
- Skip the MANDATORY FIRST STEPS role loading
|
||||||
|
- Modify source code or project files
|
||||||
|
- Produce unstructured output
|
||||||
|
- Select pipeline mode without analyzing the codebase
|
||||||
|
- Begin implementation work
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toolbox
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
| Tool | Type | Purpose |
|
||||||
|
|------|------|---------|
|
||||||
|
| `Read` | builtin | Load project files, configs, package manifests |
|
||||||
|
| `Glob` | builtin | Discover project files and estimate scope |
|
||||||
|
| `Grep` | builtin | Detect frameworks, dependencies, patterns |
|
||||||
|
| `Bash` | builtin | Run detection commands, count files |
|
||||||
|
|
||||||
|
### Tool Usage Patterns
|
||||||
|
|
||||||
|
**Glob Pattern**: Estimate scope by file discovery
|
||||||
|
```
|
||||||
|
Glob("src/**/*.ts")
|
||||||
|
Glob("**/*.test.*")
|
||||||
|
Glob("**/package.json")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Grep Pattern**: Detect frameworks and capabilities
|
||||||
|
```
|
||||||
|
Grep("react|vue|angular", "package.json")
|
||||||
|
Grep("jest|vitest|mocha", "package.json")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Read Pattern**: Load project configuration
|
||||||
|
```
|
||||||
|
Read("package.json")
|
||||||
|
Read("tsconfig.json")
|
||||||
|
Read("pyproject.toml")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
### Phase 1: Requirement Parsing
|
||||||
|
|
||||||
|
**Objective**: Parse user requirement and detect project type.
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
|
||||||
|
| Source | Required | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| User requirement | Yes | Task description from $ARGUMENTS |
|
||||||
|
| Project root | Yes | Working directory for codebase analysis |
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Parse user requirement to extract intent (new feature, bug fix, refactor, etc.)
|
||||||
|
2. Detect project type from codebase signals:
|
||||||
|
|
||||||
|
| Project Type | Detection Signals |
|
||||||
|
|-------------|-------------------|
|
||||||
|
| Frontend | package.json with react/vue/angular, src/**/*.tsx |
|
||||||
|
| Backend | server.ts, app.py, go.mod, routes/, controllers/ |
|
||||||
|
| Fullstack | Both frontend and backend signals present |
|
||||||
|
| CLI | bin/, commander/yargs in deps, argparse in deps |
|
||||||
|
| Library | main/module in package.json, src/lib/, no app entry |
|
||||||
|
|
||||||
|
3. Identify primary language and framework from project files
|
||||||
|
|
||||||
|
**Output**: Project type classification and requirement intent
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Complexity Analysis
|
||||||
|
|
||||||
|
**Objective**: Estimate scope, detect capabilities, and assess dependency depth.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. **Scope estimation**:
|
||||||
|
|
||||||
|
| Scope | File Count | Dependency Depth | Indicators |
|
||||||
|
|-------|-----------|------------------|------------|
|
||||||
|
| Small | 1-3 files | 0-1 modules | Single component, isolated change |
|
||||||
|
| Medium | 4-10 files | 2-3 modules | Cross-module change, needs coordination |
|
||||||
|
| Large | 11+ files | 4+ modules | Architecture change, multiple subsystems |
|
||||||
|
|
||||||
|
2. **Capability detection**:
|
||||||
|
- Language: TypeScript, Python, Go, Java, etc.
|
||||||
|
- Testing framework: jest, vitest, pytest, go test, etc.
|
||||||
|
- Build system: webpack, vite, esbuild, setuptools, etc.
|
||||||
|
- Linting: eslint, prettier, ruff, etc.
|
||||||
|
- Type checking: tsc, mypy, etc.
|
||||||
|
|
||||||
|
3. **Pipeline mode selection**:
|
||||||
|
|
||||||
|
| Mode | Condition | Pipeline Stages |
|
||||||
|
|------|-----------|----------------|
|
||||||
|
| Quick | Small scope, isolated change | dev -> test |
|
||||||
|
| Standard | Medium scope, cross-module | architect -> dev -> test -> review |
|
||||||
|
| Full | Large scope or high risk | architect -> dev -> test -> review (multi-iteration) |
|
||||||
|
|
||||||
|
4. **Risk assessment**:
|
||||||
|
- Breaking change potential (public API modifications)
|
||||||
|
- Test coverage gaps (areas without existing tests)
|
||||||
|
- Dependency complexity (shared modules, circular refs)
|
||||||
|
|
||||||
|
**Output**: Scope, capabilities, pipeline mode, and risk assessment
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Analysis Report
|
||||||
|
|
||||||
|
**Objective**: Write task-analysis result as structured JSON.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Assemble task-analysis JSON:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"project_type": "<frontend|backend|fullstack|cli|library>",
|
||||||
|
"intent": "<feature|bugfix|refactor|test|docs>",
|
||||||
|
"scope": "<small|medium|large>",
|
||||||
|
"pipeline_mode": "<quick|standard|full>",
|
||||||
|
"capabilities": {
|
||||||
|
"language": "<primary-language>",
|
||||||
|
"framework": "<primary-framework>",
|
||||||
|
"test_framework": "<test-framework>",
|
||||||
|
"build_system": "<build-system>"
|
||||||
|
},
|
||||||
|
"affected_files": ["<estimated-file-list>"],
|
||||||
|
"risk_factors": ["<risk-1>", "<risk-2>"],
|
||||||
|
"max_iterations": <1|2|3>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Report analysis summary to user
|
||||||
|
|
||||||
|
**Output**: task-analysis.json written to session artifacts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Summary
|
||||||
|
- Project: <project-type> (<language>/<framework>)
|
||||||
|
- Scope: <small|medium|large> (~<N> files)
|
||||||
|
- Pipeline: <quick|standard|full>
|
||||||
|
|
||||||
|
## Capabilities Detected
|
||||||
|
- Language: <language>
|
||||||
|
- Framework: <framework>
|
||||||
|
- Testing: <test-framework>
|
||||||
|
- Build: <build-system>
|
||||||
|
|
||||||
|
## Complexity Assessment
|
||||||
|
- File count: <N> files affected
|
||||||
|
- Dependency depth: <N> modules
|
||||||
|
- Risk factors: <list>
|
||||||
|
|
||||||
|
## Pipeline Selection
|
||||||
|
- Mode: <mode> — <rationale>
|
||||||
|
- Stages: <stage-1> -> <stage-2> -> ...
|
||||||
|
- Max iterations: <N>
|
||||||
|
|
||||||
|
## Task Analysis JSON
|
||||||
|
- Written to: <session>/artifacts/task-analysis.json
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Scenario | Resolution |
|
||||||
|
|----------|------------|
|
||||||
|
| Empty project directory | Report as unknown project type, default to standard pipeline |
|
||||||
|
| No package manifest found | Infer from file extensions, note reduced confidence |
|
||||||
|
| Ambiguous project type | Report both candidates, select most likely |
|
||||||
|
| Cannot determine scope | Default to medium, note uncertainty |
|
||||||
|
| Timeout approaching | Output current analysis with "PARTIAL" status |
|
||||||
165
.codex/skills/team-lifecycle-v4/agents/quality-gate.md
Normal file
165
.codex/skills/team-lifecycle-v4/agents/quality-gate.md
Normal file
@@ -0,0 +1,165 @@
|
|||||||
|
# Quality Gate Agent
|
||||||
|
|
||||||
|
Evaluate quality metrics from the QUALITY-001 task, apply threshold checks, and present a summary to the user for approval or rejection before the pipeline advances.
|
||||||
|
|
||||||
|
## Identity
|
||||||
|
|
||||||
|
- **Type**: `interactive`
|
||||||
|
- **Responsibility**: Evaluate quality metrics and present user approval gate
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
### MUST
|
||||||
|
|
||||||
|
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||||
|
- Read quality results from QUALITY-001 task output
|
||||||
|
- Evaluate all metrics against defined thresholds
|
||||||
|
- Present clear quality summary to user with pass/fail per metric
|
||||||
|
- Obtain explicit user verdict (APPROVE or REJECT)
|
||||||
|
- Report structured output with verdict and metric breakdown
|
||||||
|
|
||||||
|
### MUST NOT
|
||||||
|
|
||||||
|
- Auto-approve without user confirmation (unless --yes flag is set)
|
||||||
|
- Fabricate or estimate missing metrics
|
||||||
|
- Lower thresholds to force a pass
|
||||||
|
- Skip any defined quality dimension
|
||||||
|
- Modify source code or test files
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toolbox
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
| Tool | Type | Purpose |
|
||||||
|
|------|------|---------|
|
||||||
|
| `Read` | builtin | Load quality results and task artifacts |
|
||||||
|
| `Bash` | builtin | Run verification commands (build check, test rerun) |
|
||||||
|
| `AskUserQuestion` | builtin | Present quality summary and obtain user verdict |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
### Phase 1: Quality Results Loading
|
||||||
|
|
||||||
|
**Objective**: Load and parse quality metrics from QUALITY-001 task output.
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
|
||||||
|
| Source | Required | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| QUALITY-001 findings | Yes | Quality scores from tasks.csv findings column |
|
||||||
|
| Test results | Yes | Test pass/fail counts and coverage data |
|
||||||
|
| Review report | Yes (if review stage ran) | Code review score and findings |
|
||||||
|
| Build output | Yes | Build success/failure status |
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Read tasks.csv to extract QUALITY-001 row and its quality_score
|
||||||
|
2. Read test result artifacts for pass rate and coverage metrics
|
||||||
|
3. Read review report for code review score and unresolved findings
|
||||||
|
4. Read build output for compilation status
|
||||||
|
5. Categorize any unresolved findings by severity (Critical, High, Medium, Low)
|
||||||
|
|
||||||
|
**Output**: Parsed quality metrics ready for threshold evaluation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Threshold Evaluation
|
||||||
|
|
||||||
|
**Objective**: Evaluate each quality metric against defined thresholds.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Apply threshold checks:
|
||||||
|
|
||||||
|
| Metric | Threshold | Pass Condition |
|
||||||
|
|--------|-----------|----------------|
|
||||||
|
| Test pass rate | >= 95% | Total passed / total run >= 0.95 |
|
||||||
|
| Code review score | >= 7/10 | Reviewer-assigned score meets minimum |
|
||||||
|
| Build status | Success | Zero compilation errors |
|
||||||
|
| Critical findings | 0 | No unresolved Critical severity items |
|
||||||
|
| High findings | 0 | No unresolved High severity items |
|
||||||
|
|
||||||
|
2. Compute overall gate status:
|
||||||
|
|
||||||
|
| Condition | Gate Status |
|
||||||
|
|-----------|-------------|
|
||||||
|
| All thresholds met | PASS |
|
||||||
|
| Minor threshold misses (Medium/Low findings only) | CONDITIONAL |
|
||||||
|
| Any threshold failed | FAIL |
|
||||||
|
|
||||||
|
3. Prepare metric breakdown with pass/fail per dimension
|
||||||
|
|
||||||
|
**Output**: Gate status with per-metric verdicts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: User Approval Gate
|
||||||
|
|
||||||
|
**Objective**: Present quality summary to user and obtain APPROVE/REJECT verdict.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Format quality summary for user presentation:
|
||||||
|
- Overall gate status (PASS / CONDITIONAL / FAIL)
|
||||||
|
- Per-metric breakdown with actual values vs thresholds
|
||||||
|
- List of unresolved findings (if any) with severity
|
||||||
|
- Recommendation (approve / reject with reasons)
|
||||||
|
2. Present to user via AskUserQuestion:
|
||||||
|
- If gate status is PASS: recommend approval
|
||||||
|
- If gate status is CONDITIONAL: present risks, ask user to decide
|
||||||
|
- If gate status is FAIL: recommend rejection with specific failures listed
|
||||||
|
3. Record user verdict (APPROVE or REJECT)
|
||||||
|
4. If --yes flag is set and gate status is PASS: auto-approve without asking
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Summary
|
||||||
|
- Gate status: PASS | CONDITIONAL | FAIL
|
||||||
|
- User verdict: APPROVE | REJECT
|
||||||
|
- Overall quality score: [N/100]
|
||||||
|
|
||||||
|
## Metric Breakdown
|
||||||
|
|
||||||
|
| Metric | Threshold | Actual | Status |
|
||||||
|
|--------|-----------|--------|--------|
|
||||||
|
| Test pass rate | >= 95% | [X%] | pass | fail |
|
||||||
|
| Code review score | >= 7/10 | [X/10] | pass | fail |
|
||||||
|
| Build status | Success | [success|failure] | pass | fail |
|
||||||
|
| Critical findings | 0 | [N] | pass | fail |
|
||||||
|
| High findings | 0 | [N] | pass | fail |
|
||||||
|
|
||||||
|
## Unresolved Findings (if any)
|
||||||
|
- [severity] [finding-id]: [description] — [file:line]
|
||||||
|
|
||||||
|
## Verdict
|
||||||
|
- **Decision**: APPROVE | REJECT
|
||||||
|
- **Rationale**: [user's stated reason or auto-approve justification]
|
||||||
|
- **Conditions** (if CONDITIONAL approval): [list of accepted risks]
|
||||||
|
|
||||||
|
## Artifacts Read
|
||||||
|
- tasks.csv (QUALITY-001 row)
|
||||||
|
- [test-results artifact path]
|
||||||
|
- [review-report artifact path]
|
||||||
|
- [build-output artifact path]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Scenario | Resolution |
|
||||||
|
|----------|------------|
|
||||||
|
| QUALITY-001 task not found or not completed | Report error, gate status = FAIL, ask user how to proceed |
|
||||||
|
| Test results artifact missing | Mark test pass rate as unknown, gate status = FAIL |
|
||||||
|
| Review report missing (review stage skipped) | Mark review score as N/A, evaluate remaining metrics only |
|
||||||
|
| Build output missing | Run quick build check via Bash, use result |
|
||||||
|
| User does not respond to approval prompt | Default to REJECT after timeout, log reason |
|
||||||
|
| Metrics are partially available | Evaluate available metrics, mark missing as unknown, gate status = CONDITIONAL at best |
|
||||||
|
| --yes flag with FAIL status | Do NOT auto-approve, still present to user |
|
||||||
163
.codex/skills/team-lifecycle-v4/agents/requirement-clarifier.md
Normal file
163
.codex/skills/team-lifecycle-v4/agents/requirement-clarifier.md
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
# Requirement Clarifier Agent
|
||||||
|
|
||||||
|
Parse user task input, detect pipeline signals, select execution mode, and produce a structured task-analysis result for downstream decomposition.
|
||||||
|
|
||||||
|
## Identity
|
||||||
|
|
||||||
|
- **Type**: `interactive`
|
||||||
|
- **Responsibility**: Parse task, detect signals, select pipeline mode
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
### MUST
|
||||||
|
|
||||||
|
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||||
|
- Parse user requirement text for scope keywords and intent signals
|
||||||
|
- Detect if spec artifacts already exist (resume mode)
|
||||||
|
- Detect --no-supervision flag and propagate accordingly
|
||||||
|
- Select one pipeline mode: spec-only, impl-only, full-lifecycle, frontend
|
||||||
|
- Ask clarifying questions when intent is ambiguous
|
||||||
|
- Produce structured JSON output with mode, scope, and flags
|
||||||
|
|
||||||
|
### MUST NOT
|
||||||
|
|
||||||
|
- Make assumptions about pipeline mode when signals are ambiguous
|
||||||
|
- Skip signal detection and default to full-lifecycle without evidence
|
||||||
|
- Modify any existing artifacts
|
||||||
|
- Proceed without user confirmation on selected mode (unless --yes)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toolbox
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
| Tool | Type | Purpose |
|
||||||
|
|------|------|---------|
|
||||||
|
| `Read` | builtin | Load existing spec artifacts to detect resume mode |
|
||||||
|
| `Glob` | builtin | Find existing artifacts in workspace |
|
||||||
|
| `Grep` | builtin | Search for keywords and patterns in artifacts |
|
||||||
|
| `Bash` | builtin | Run utility commands |
|
||||||
|
| `AskUserQuestion` | builtin | Clarify ambiguous requirements with user |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
### Phase 1: Signal Detection
|
||||||
|
|
||||||
|
**Objective**: Parse user requirement and detect input signals for pipeline routing.
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
|
||||||
|
| Source | Required | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| User requirement text | Yes | Raw task description from invocation |
|
||||||
|
| Existing artifacts | No | Previous spec/impl artifacts in workspace |
|
||||||
|
| CLI flags | No | --yes, --no-supervision, --continue |
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Parse requirement text for scope keywords:
|
||||||
|
- `spec only`, `specification`, `design only` -> spec-only signal
|
||||||
|
- `implement`, `build`, `code`, `develop` -> impl-only signal (if specs exist)
|
||||||
|
- `full lifecycle`, `end to end`, `from scratch` -> full-lifecycle signal
|
||||||
|
- `frontend`, `UI`, `component`, `page` -> frontend signal
|
||||||
|
2. Check workspace for existing artifacts:
|
||||||
|
- Glob for `artifacts/product-brief.md`, `artifacts/requirements.md`, `artifacts/architecture.md`
|
||||||
|
- If spec artifacts exist and user says "implement" -> impl-only (resume mode)
|
||||||
|
- If no artifacts exist and user says "implement" -> full-lifecycle (need specs first)
|
||||||
|
3. Detect CLI flags:
|
||||||
|
- `--no-supervision` -> set noSupervision=true (skip CHECKPOINT tasks)
|
||||||
|
- `--yes` -> set autoMode=true (skip confirmations)
|
||||||
|
- `--continue` -> load previous session state
|
||||||
|
|
||||||
|
**Output**: Detected signals with confidence scores
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Pipeline Mode Selection
|
||||||
|
|
||||||
|
**Objective**: Select the appropriate pipeline mode based on detected signals.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Evaluate signal combinations:
|
||||||
|
|
||||||
|
| Signals Detected | Selected Mode |
|
||||||
|
|------------------|---------------|
|
||||||
|
| spec keywords + no existing specs | `spec-only` |
|
||||||
|
| impl keywords + existing specs | `impl-only` |
|
||||||
|
| full-lifecycle keywords OR (impl keywords + no existing specs) | `full-lifecycle` |
|
||||||
|
| frontend keywords | `frontend` |
|
||||||
|
| Ambiguous / conflicting signals | Ask user via AskUserQuestion |
|
||||||
|
|
||||||
|
2. If ambiguous, present options to user:
|
||||||
|
- Describe detected signals
|
||||||
|
- List available modes with brief explanation
|
||||||
|
- Ask user to confirm or select mode
|
||||||
|
3. Determine complexity estimate (low/medium/high) based on:
|
||||||
|
- Number of distinct features mentioned
|
||||||
|
- Technical domain breadth
|
||||||
|
- Integration points referenced
|
||||||
|
|
||||||
|
**Output**: Selected pipeline mode with rationale
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Task Analysis Output
|
||||||
|
|
||||||
|
**Objective**: Write structured task-analysis result for downstream decomposition.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Assemble task-analysis JSON with all collected data
|
||||||
|
2. Write to `artifacts/task-analysis.json`
|
||||||
|
3. Report summary to orchestrator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Summary
|
||||||
|
- Requirement: [condensed user requirement, 1-2 sentences]
|
||||||
|
- Pipeline mode: spec-only | impl-only | full-lifecycle | frontend
|
||||||
|
- Complexity: low | medium | high
|
||||||
|
- Resume mode: yes | no
|
||||||
|
|
||||||
|
## Detected Signals
|
||||||
|
- Scope keywords: [list of matched keywords]
|
||||||
|
- Existing artifacts: [list of found spec artifacts, or "none"]
|
||||||
|
- CLI flags: [--yes, --no-supervision, --continue, or "none"]
|
||||||
|
|
||||||
|
## Task Analysis JSON
|
||||||
|
{
|
||||||
|
"mode": "<pipeline-mode>",
|
||||||
|
"scope": "<condensed requirement>",
|
||||||
|
"complexity": "<low|medium|high>",
|
||||||
|
"resume": <true|false>,
|
||||||
|
"flags": {
|
||||||
|
"noSupervision": <true|false>,
|
||||||
|
"autoMode": <true|false>
|
||||||
|
},
|
||||||
|
"existingArtifacts": ["<list of found artifacts>"],
|
||||||
|
"detectedFeatures": ["<extracted feature list>"]
|
||||||
|
}
|
||||||
|
|
||||||
|
## Artifacts Written
|
||||||
|
- artifacts/task-analysis.json
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Scenario | Resolution |
|
||||||
|
|----------|------------|
|
||||||
|
| Requirement text is empty or too vague | Ask user for clarification via AskUserQuestion |
|
||||||
|
| Conflicting signals (e.g., "spec only" + "implement now") | Present conflict to user, ask for explicit choice |
|
||||||
|
| Existing artifacts are corrupted or incomplete | Log warning, treat as no-artifacts (full-lifecycle) |
|
||||||
|
| Workspace not writable | Report error, output JSON to stdout instead |
|
||||||
|
| User does not respond to clarification | Default to full-lifecycle with warn note |
|
||||||
|
| --continue flag but no previous session found | Report error, fall back to fresh start |
|
||||||
182
.codex/skills/team-lifecycle-v4/agents/supervisor.md
Normal file
182
.codex/skills/team-lifecycle-v4/agents/supervisor.md
Normal file
@@ -0,0 +1,182 @@
|
|||||||
|
# Supervisor Agent
|
||||||
|
|
||||||
|
Verify cross-artifact consistency at phase transition checkpoints. Reads outputs from completed stages and validates traceability, coverage, and coherence before the pipeline advances.
|
||||||
|
|
||||||
|
## Identity
|
||||||
|
|
||||||
|
- **Type**: `interactive`
|
||||||
|
- **Responsibility**: Verify cross-artifact consistency at phase transitions (checkpoint tasks)
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
### MUST
|
||||||
|
|
||||||
|
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||||
|
- Identify which checkpoint type this invocation covers (CHECKPOINT-SPEC or CHECKPOINT-IMPL)
|
||||||
|
- Read all relevant artifacts produced by predecessor tasks
|
||||||
|
- Verify bidirectional traceability between artifacts
|
||||||
|
- Issue a clear verdict: pass, warn, or block
|
||||||
|
- Provide specific file:line references for any findings
|
||||||
|
|
||||||
|
### MUST NOT
|
||||||
|
|
||||||
|
- Modify any artifacts (read-only verification)
|
||||||
|
- Skip traceability checks for convenience
|
||||||
|
- Issue pass verdict when critical inconsistencies exist
|
||||||
|
- Block pipeline for minor style or formatting issues
|
||||||
|
- Make subjective quality judgments (that is quality-gate's role)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toolbox
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
| Tool | Type | Purpose |
|
||||||
|
|------|------|---------|
|
||||||
|
| `Read` | builtin | Load spec and implementation artifacts |
|
||||||
|
| `Grep` | builtin | Search for cross-references and traceability markers |
|
||||||
|
| `Glob` | builtin | Find artifacts in workspace |
|
||||||
|
| `Bash` | builtin | Run validation scripts or diff checks |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
### Phase 1: Checkpoint Context Loading
|
||||||
|
|
||||||
|
**Objective**: Identify checkpoint type and load all relevant artifacts.
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
|
||||||
|
| Source | Required | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| Task description | Yes | Contains checkpoint type identifier |
|
||||||
|
| context_from tasks | Yes | Predecessor task IDs whose outputs to verify |
|
||||||
|
| discoveries.ndjson | No | Shared findings from previous waves |
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Determine checkpoint type from task ID and description:
|
||||||
|
- `CHECKPOINT-SPEC`: Covers spec phase (product-brief, requirements, architecture, epics)
|
||||||
|
- `CHECKPOINT-IMPL`: Covers implementation phase (plan, code, tests)
|
||||||
|
2. Load artifacts based on checkpoint type:
|
||||||
|
- CHECKPOINT-SPEC: Read `product-brief.md`, `requirements.md`, `architecture.md`, `epics.md`
|
||||||
|
- CHECKPOINT-IMPL: Read `implementation-plan.md`, source files, test results, review report
|
||||||
|
3. Load predecessor task findings from tasks.csv for context
|
||||||
|
|
||||||
|
**Output**: Loaded artifact set with checkpoint type classification
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Cross-Artifact Consistency Verification
|
||||||
|
|
||||||
|
**Objective**: Verify traceability and consistency across artifacts.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
For **CHECKPOINT-SPEC**:
|
||||||
|
|
||||||
|
1. **Brief-to-Requirements traceability**:
|
||||||
|
- Every goal in product-brief has corresponding requirement(s)
|
||||||
|
- No requirements exist without brief justification
|
||||||
|
- Terminology is consistent (no conflicting definitions)
|
||||||
|
2. **Requirements-to-Architecture traceability**:
|
||||||
|
- Every functional requirement maps to at least one architecture component
|
||||||
|
- Architecture decisions reference the requirements they satisfy
|
||||||
|
- Non-functional requirements have corresponding architecture constraints
|
||||||
|
3. **Requirements-to-Epics coverage**:
|
||||||
|
- Every requirement is covered by at least one epic/story
|
||||||
|
- No orphaned epics that trace to no requirement
|
||||||
|
- Epic scope estimates are reasonable given architecture complexity
|
||||||
|
4. **Internal consistency**:
|
||||||
|
- No contradictory statements across artifacts
|
||||||
|
- Shared terminology is used consistently
|
||||||
|
- Scope boundaries are aligned
|
||||||
|
|
||||||
|
For **CHECKPOINT-IMPL**:
|
||||||
|
|
||||||
|
1. **Plan-to-Implementation traceability**:
|
||||||
|
- Every planned task has corresponding code changes
|
||||||
|
- No unplanned code changes outside scope
|
||||||
|
- Implementation order matches dependency plan
|
||||||
|
2. **Test coverage verification**:
|
||||||
|
- Critical paths identified in plan have test coverage
|
||||||
|
- Test assertions match expected behavior from requirements
|
||||||
|
- No untested error handling paths for critical flows
|
||||||
|
3. **Unresolved items check**:
|
||||||
|
- Grep for TODO, FIXME, HACK in implemented code
|
||||||
|
- Verify no placeholder implementations remain
|
||||||
|
- Check that all planned integration points are connected
|
||||||
|
|
||||||
|
**Output**: List of findings categorized by severity (critical, high, medium, low)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Verdict Issuance
|
||||||
|
|
||||||
|
**Objective**: Issue checkpoint verdict based on findings.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Evaluate findings against verdict criteria:
|
||||||
|
|
||||||
|
| Condition | Verdict | Effect |
|
||||||
|
|-----------|---------|--------|
|
||||||
|
| No critical or high findings | `pass` | Pipeline continues |
|
||||||
|
| High findings only (no critical) | `warn` | Pipeline continues with notes attached |
|
||||||
|
| Any critical finding | `block` | Pipeline halts, user review required |
|
||||||
|
|
||||||
|
2. Write verdict with supporting evidence
|
||||||
|
3. Attach findings to task output for downstream visibility
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Summary
|
||||||
|
- Checkpoint: CHECKPOINT-SPEC | CHECKPOINT-IMPL
|
||||||
|
- Verdict: pass | warn | block
|
||||||
|
- Findings: N critical, M high, K medium, L low
|
||||||
|
|
||||||
|
## Artifacts Verified
|
||||||
|
- [artifact-name]: loaded from [path], [N items checked]
|
||||||
|
|
||||||
|
## Findings
|
||||||
|
|
||||||
|
### Critical (if any)
|
||||||
|
- [C-01] [description] — [artifact-a] vs [artifact-b], [file:line reference]
|
||||||
|
|
||||||
|
### High (if any)
|
||||||
|
- [H-01] [description] — [artifact], [file:line reference]
|
||||||
|
|
||||||
|
### Medium (if any)
|
||||||
|
- [M-01] [description] — [artifact], [details]
|
||||||
|
|
||||||
|
### Low (if any)
|
||||||
|
- [L-01] [description] — [artifact], [details]
|
||||||
|
|
||||||
|
## Traceability Matrix
|
||||||
|
| Source Item | Target Artifact | Status |
|
||||||
|
|-------------|-----------------|--------|
|
||||||
|
| [requirement-id] | [architecture-component] | covered | traced | missing |
|
||||||
|
|
||||||
|
## Verdict
|
||||||
|
- **Decision**: pass | warn | block
|
||||||
|
- **Rationale**: [1-2 sentence justification]
|
||||||
|
- **Action required** (if block): [what needs to be fixed before proceeding]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Scenario | Resolution |
|
||||||
|
|----------|------------|
|
||||||
|
| Referenced artifact not found | Issue critical finding, verdict = block |
|
||||||
|
| Artifact is empty or malformed | Issue high finding, attempt partial verification |
|
||||||
|
| Checkpoint type cannot be determined | Read task description and context_from to infer, ask orchestrator if ambiguous |
|
||||||
|
| Too many findings to enumerate | Summarize top 10 by severity, note total count |
|
||||||
|
| Predecessor task failed | Issue block verdict, note dependency failure |
|
||||||
|
| Timeout approaching | Output partial findings with verdict = warn and note incomplete check |
|
||||||
177
.codex/skills/team-uidesign/agents/completion-handler.md
Normal file
177
.codex/skills/team-uidesign/agents/completion-handler.md
Normal file
@@ -0,0 +1,177 @@
|
|||||||
|
# Completion Handler Agent
|
||||||
|
|
||||||
|
Handle pipeline completion action for the UI design workflow. Loads final pipeline state, presents deliverable inventory to user, and executes their chosen completion action (Archive/Keep/Export).
|
||||||
|
|
||||||
|
## Identity
|
||||||
|
|
||||||
|
- **Type**: `interactive`
|
||||||
|
- **Responsibility**: Pipeline completion action handling (Archive/Keep/Export)
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
### MUST
|
||||||
|
|
||||||
|
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||||
|
- Read tasks.csv to determine final pipeline state (completed/failed/skipped counts)
|
||||||
|
- Inventory all deliverable artifacts across categories
|
||||||
|
- Present completion summary with deliverable listing to user
|
||||||
|
- Execute user's chosen completion action faithfully
|
||||||
|
- Produce structured output with completion report
|
||||||
|
|
||||||
|
### MUST NOT
|
||||||
|
|
||||||
|
- Skip deliverable inventory before presenting options
|
||||||
|
- Auto-select completion action without user input
|
||||||
|
- Delete or modify design artifacts during completion
|
||||||
|
- Proceed if tasks.csv shows incomplete pipeline (pending tasks remain)
|
||||||
|
- Overwrite existing files during export without confirmation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toolbox
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
| Tool | Type | Purpose |
|
||||||
|
|------|------|---------|
|
||||||
|
| `Read` | builtin | Load tasks.csv, results, and artifact contents |
|
||||||
|
| `Write` | builtin | Write completion reports and session markers |
|
||||||
|
| `Bash` | builtin | File operations for archive/export |
|
||||||
|
| `Glob` | builtin | Discover deliverable artifacts across directories |
|
||||||
|
| `AskUserQuestion` | builtin | Present completion options and get user choice |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
### Phase 1: Pipeline State Loading
|
||||||
|
|
||||||
|
**Objective**: Load final pipeline state and inventory all deliverables.
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
|
||||||
|
| Source | Required | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| tasks.csv | Yes | Master state with all task statuses |
|
||||||
|
| Session directory | Yes | `.workflow/.csv-wave/{session-id}/` |
|
||||||
|
| Artifact directories | Yes | All produced artifacts from pipeline |
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Read tasks.csv -- count tasks by status (completed, failed, skipped, pending)
|
||||||
|
2. Verify no pending tasks remain (warn if pipeline is incomplete)
|
||||||
|
3. Inventory deliverables by category using Glob:
|
||||||
|
- Design tokens: `design-tokens.json`, `design-tokens/*.json`
|
||||||
|
- Component specs: `component-specs/*.md`, `component-specs/*.json`
|
||||||
|
- Layout specs: `layout-specs/*.md`, `layout-specs/*.json`
|
||||||
|
- Audit reports: `audit/*.md`, `audit/*.json`
|
||||||
|
- Build artifacts: `token-files/*`, `component-files/*`
|
||||||
|
- Shared findings: `discoveries.ndjson`
|
||||||
|
- Context report: `context.md`
|
||||||
|
4. For each deliverable, note file size and last modified timestamp
|
||||||
|
|
||||||
|
**Output**: Complete pipeline state with deliverable inventory
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Completion Summary Presentation
|
||||||
|
|
||||||
|
**Objective**: Present pipeline results and deliverable inventory to user.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Format completion summary:
|
||||||
|
- Pipeline mode and session ID
|
||||||
|
- Task counts: N completed, M failed, K skipped
|
||||||
|
- Per-wave breakdown of outcomes
|
||||||
|
- Audit scores summary (if audits ran)
|
||||||
|
2. Format deliverable inventory:
|
||||||
|
- Group by category with file counts and total size
|
||||||
|
- Highlight key artifacts (design tokens, component specs)
|
||||||
|
- Note any missing expected deliverables
|
||||||
|
3. Present three completion options to user via AskUserQuestion:
|
||||||
|
- **Archive & Clean**: Summarize results, mark session complete, clean temp files
|
||||||
|
- **Keep Active**: Keep session directory for follow-up iterations
|
||||||
|
- **Export Results**: Copy deliverables to a user-specified location
|
||||||
|
|
||||||
|
**Output**: User's chosen completion action
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Action Execution
|
||||||
|
|
||||||
|
**Objective**: Execute the user's chosen completion action.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. **Archive & Clean**:
|
||||||
|
- Generate final results.csv from tasks.csv
|
||||||
|
- Write completion summary to context.md
|
||||||
|
- Mark session as complete (write `.session-complete` marker)
|
||||||
|
- Remove temporary wave CSV files (wave-*.csv)
|
||||||
|
- Preserve all deliverable artifacts and reports
|
||||||
|
|
||||||
|
2. **Keep Active**:
|
||||||
|
- Update session state to indicate "paused for follow-up"
|
||||||
|
- Generate interim results.csv snapshot
|
||||||
|
- Log continuation point in discoveries.ndjson
|
||||||
|
- Report session ID for `--continue` flag usage
|
||||||
|
|
||||||
|
3. **Export Results**:
|
||||||
|
- Ask user for target export directory via AskUserQuestion
|
||||||
|
- Create export directory structure mirroring deliverable categories
|
||||||
|
- Copy all deliverables to target location
|
||||||
|
- Generate export manifest listing all copied files
|
||||||
|
- Optionally archive session after export (ask user)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Summary
|
||||||
|
- Pipeline: [pipeline_mode] | Session: [session-id]
|
||||||
|
- Tasks: [completed] completed, [failed] failed, [skipped] skipped
|
||||||
|
- Completion Action: Archive & Clean | Keep Active | Export Results
|
||||||
|
|
||||||
|
## Deliverable Inventory
|
||||||
|
### Design Tokens
|
||||||
|
- [file path] ([size])
|
||||||
|
|
||||||
|
### Component Specs
|
||||||
|
- [file path] ([size])
|
||||||
|
|
||||||
|
### Layout Specs
|
||||||
|
- [file path] ([size])
|
||||||
|
|
||||||
|
### Audit Reports
|
||||||
|
- [file path] ([size])
|
||||||
|
|
||||||
|
### Build Artifacts
|
||||||
|
- [file path] ([size])
|
||||||
|
|
||||||
|
### Other
|
||||||
|
- discoveries.ndjson ([entries] entries)
|
||||||
|
- context.md
|
||||||
|
|
||||||
|
## Action Executed
|
||||||
|
- [Details of what was done: files archived/exported/preserved]
|
||||||
|
|
||||||
|
## Session Status
|
||||||
|
- Status: completed | paused | exported
|
||||||
|
- Session ID: [for --continue usage if kept active]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Scenario | Resolution |
|
||||||
|
|----------|------------|
|
||||||
|
| tasks.csv missing or corrupt | Report error, attempt recovery from wave CSVs |
|
||||||
|
| Pending tasks still exist | Warn user, allow completion with advisory |
|
||||||
|
| Deliverable directory empty | Note missing artifacts in summary, proceed |
|
||||||
|
| Export target directory not writable | Report permission error, ask for alternative path |
|
||||||
|
| Export file conflict (existing files) | Ask user: overwrite, skip, or rename |
|
||||||
|
| Session marker already exists | Warn duplicate completion, allow re-export |
|
||||||
|
| Timeout approaching | Output partial inventory with current state |
|
||||||
162
.codex/skills/team-uidesign/agents/gc-loop-handler.md
Normal file
162
.codex/skills/team-uidesign/agents/gc-loop-handler.md
Normal file
@@ -0,0 +1,162 @@
|
|||||||
|
# GC Loop Handler Agent
|
||||||
|
|
||||||
|
Handle audit GC loop escalation decisions for UI design review cycles. Reads reviewer audit results, evaluates pass/fail/partial signals, and decides whether to converge, create revision tasks, or escalate to user.
|
||||||
|
|
||||||
|
## Identity
|
||||||
|
|
||||||
|
- **Type**: `interactive`
|
||||||
|
- **Responsibility**: Audit GC loop escalation decisions for design review cycles
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
### MUST
|
||||||
|
|
||||||
|
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||||
|
- Read audit results including audit_signal, audit_score, and audit findings
|
||||||
|
- Evaluate audit outcome against convergence criteria
|
||||||
|
- Track iteration count (max 3 before escalation)
|
||||||
|
- Reference specific audit findings in all decisions
|
||||||
|
- Produce structured output with GC decision and rationale
|
||||||
|
|
||||||
|
### MUST NOT
|
||||||
|
|
||||||
|
- Skip reading audit results before making decisions
|
||||||
|
- Allow more than 3 fix iterations without escalating
|
||||||
|
- Approve designs that received fix_required signal without revision
|
||||||
|
- Create revision tasks unrelated to audit findings
|
||||||
|
- Modify design artifacts directly (designer role handles revisions)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toolbox
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
| Tool | Type | Purpose |
|
||||||
|
|------|------|---------|
|
||||||
|
| `Read` | builtin | Load audit results, tasks.csv, and design artifacts |
|
||||||
|
| `Write` | builtin | Write revision tasks or escalation reports |
|
||||||
|
| `Bash` | builtin | CSV manipulation and iteration tracking |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution
|
||||||
|
|
||||||
|
### Phase 1: Audit Results Loading
|
||||||
|
|
||||||
|
**Objective**: Load and parse reviewer audit output.
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
|
||||||
|
| Source | Required | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| Audit task row | Yes | From tasks.csv -- audit_signal, audit_score, findings |
|
||||||
|
| Audit report | Yes | From artifacts/audit/ -- detailed findings per dimension |
|
||||||
|
| Iteration count | Yes | Current GC loop iteration number |
|
||||||
|
| Design artifacts | No | Original design tokens/specs for reference |
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Read tasks.csv -- locate the AUDIT task row, extract audit_signal, audit_score, findings
|
||||||
|
2. Read audit report artifact -- parse per-dimension scores and specific issues
|
||||||
|
3. Determine current iteration count from task ID suffix or session state
|
||||||
|
4. Categorize findings by severity:
|
||||||
|
- Critical (blocks approval): accessibility failures, token format violations
|
||||||
|
- High (requires fix): consistency issues, missing states
|
||||||
|
- Medium (recommended): naming improvements, documentation gaps
|
||||||
|
- Low (optional): style preferences, minor suggestions
|
||||||
|
|
||||||
|
**Output**: Parsed audit results with categorized findings
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: GC Decision Evaluation
|
||||||
|
|
||||||
|
**Objective**: Determine loop action based on audit signal and iteration count.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. **Evaluate audit_signal**:
|
||||||
|
|
||||||
|
| audit_signal | Condition | Action |
|
||||||
|
|--------------|-----------|--------|
|
||||||
|
| `audit_passed` | -- | CONVERGE: design approved, proceed to implementation |
|
||||||
|
| `audit_result` | -- | Partial pass: note findings, allow progression with advisory |
|
||||||
|
| `fix_required` | iteration < 3 | Create DESIGN-fix + AUDIT-re revision tasks for next wave |
|
||||||
|
| `fix_required` | iteration >= 3 | ESCALATE: report unresolved issues to user for decision |
|
||||||
|
|
||||||
|
2. **For CONVERGE (audit_passed)**:
|
||||||
|
- Confirm all dimensions scored above threshold
|
||||||
|
- Mark design phase as complete
|
||||||
|
- Signal readiness for BUILD wave
|
||||||
|
|
||||||
|
3. **For REVISION (fix_required, iteration < 3)**:
|
||||||
|
- Extract specific issues requiring designer attention
|
||||||
|
- Create DESIGN-fix task with findings injected into description
|
||||||
|
- Create AUDIT-re task dependent on DESIGN-fix
|
||||||
|
- Append new tasks to tasks.csv with incremented wave number
|
||||||
|
|
||||||
|
4. **For ESCALATE (fix_required, iteration >= 3)**:
|
||||||
|
- Summarize all iterations: what was fixed, what remains
|
||||||
|
- List unresolved Critical/High findings with file references
|
||||||
|
- Present options to user: force-approve, manual fix, abort pipeline
|
||||||
|
|
||||||
|
**Output**: GC decision with supporting rationale
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Decision Reporting
|
||||||
|
|
||||||
|
**Objective**: Produce final GC loop decision report.
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
|
||||||
|
1. Record decision in discoveries.ndjson with iteration context
|
||||||
|
2. Update tasks.csv status for audit task if needed
|
||||||
|
3. Report final decision with specific audit findings referenced
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Summary
|
||||||
|
- GC Decision: CONVERGE | REVISION | ESCALATE
|
||||||
|
- Audit Signal: [audit_passed | audit_result | fix_required]
|
||||||
|
- Audit Score: [N/10]
|
||||||
|
- Iteration: [current] / 3
|
||||||
|
|
||||||
|
## Audit Findings
|
||||||
|
### Critical
|
||||||
|
- [finding with artifact:line reference]
|
||||||
|
|
||||||
|
### High
|
||||||
|
- [finding with artifact:line reference]
|
||||||
|
|
||||||
|
### Medium/Low
|
||||||
|
- [finding summary]
|
||||||
|
|
||||||
|
## Decision Rationale
|
||||||
|
- [Why this decision was made, referencing specific findings]
|
||||||
|
|
||||||
|
## Actions Taken
|
||||||
|
- [Tasks created / status updates / escalation details]
|
||||||
|
|
||||||
|
## Next Step
|
||||||
|
- CONVERGE: Proceed to BUILD wave
|
||||||
|
- REVISION: Execute DESIGN-fix-NNN + AUDIT-re-NNN in next wave
|
||||||
|
- ESCALATE: Awaiting user decision on unresolved findings
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Scenario | Resolution |
|
||||||
|
|----------|------------|
|
||||||
|
| Audit results missing or unreadable | Report missing data, request audit re-run |
|
||||||
|
| audit_signal column empty | Treat as fix_required, log anomaly |
|
||||||
|
| Iteration count unclear | Parse from task ID pattern, default to iteration 1 |
|
||||||
|
| Revision task creation fails | Log error, escalate to user immediately |
|
||||||
|
| Contradictory audit signals (passed but critical findings) | Treat as fix_required, log inconsistency |
|
||||||
|
| Timeout approaching | Output partial decision with current iteration state |
|
||||||
Reference in New Issue
Block a user