mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-07 16:41:06 +08:00
Refactor and optimize templates and code structure
- Deleted outdated templates for epics, product brief, and requirements PRD. - Introduced lazy loading for locale messages in i18n module to enhance performance. - Updated main application bootstrap to parallelize CSRF token fetching and locale loading. - Implemented code splitting for router configuration to optimize bundle size and loading times. - Added WebSocket connection limits and rate limiting to improve server performance and prevent abuse. - Enhanced input validation with compiled regex patterns for better performance and maintainability.
This commit is contained in:
catlog22
@@ -1,113 +0,0 @@
|
||||
# Role: analyst
|
||||
|
||||
Seed analysis, codebase exploration, and multi-dimensional context gathering. Maps to spec-generator Phase 1 (Discovery).
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `analyst` | **Prefix**: `RESEARCH-*` | **Tag**: `[analyst]`
|
||||
- **Responsibility**: Seed Analysis → Codebase Exploration → Context Packaging → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process RESEARCH-* tasks
|
||||
- Communicate only with coordinator
|
||||
- Generate discovery-context.json and spec-config.json
|
||||
- Support file reference input (@ prefix or .md/.txt extension)
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks for other roles
|
||||
- Directly contact other workers
|
||||
- Modify spec documents (only create discovery artifacts)
|
||||
- Skip seed analysis step
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| research_ready | → coordinator | Research complete |
|
||||
| research_progress | → coordinator | Long research progress update |
|
||||
| error | → coordinator | Unrecoverable error |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| ccw cli --tool gemini --mode analysis | Seed analysis |
|
||||
| mcp__ace-tool__search_context | Codebase semantic search |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Seed Analysis
|
||||
|
||||
**Objective**: Extract structured seed information from the topic/idea.
|
||||
|
||||
**Workflow**:
|
||||
1. Extract session folder from task description (`Session: <path>`)
|
||||
2. Parse topic from task description (first non-metadata line)
|
||||
3. If topic starts with `@` or ends with `.md`/`.txt` → Read the referenced file as topic content
|
||||
4. Run Gemini CLI seed analysis:
|
||||
|
||||
```
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Analyze topic and extract structured seed information.
|
||||
TASK: • Extract problem statement • Identify target users • Determine domain context
|
||||
• List constraints and assumptions • Identify 3-5 exploration dimensions • Assess complexity
|
||||
TOPIC: <topic-content>
|
||||
MODE: analysis
|
||||
EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
5. Wait for CLI result, parse seed analysis JSON
|
||||
|
||||
**Success**: Seed analysis parsed with problem statement, dimensions, complexity.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Codebase Exploration (conditional)
|
||||
|
||||
**Objective**: Gather codebase context if an existing project is detected.
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore codebase |
|
||||
| No project files | Skip → codebase context = null |
|
||||
|
||||
**When project detected**:
|
||||
1. Report progress: "种子分析完成, 开始代码库探索"
|
||||
2. ACE semantic search for architecture patterns related to topic
|
||||
3. Detect tech stack from package files
|
||||
4. Build codebase context: tech_stack, architecture_patterns, conventions, integration_points
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Context Packaging
|
||||
|
||||
**Objective**: Generate spec-config.json and discovery-context.json.
|
||||
|
||||
**spec-config.json** → `<session-folder>/spec/spec-config.json`:
|
||||
- session_id, topic, status="research_complete", complexity, depth, focus_areas, mode="interactive"
|
||||
|
||||
**discovery-context.json** → `<session-folder>/spec/discovery-context.json`:
|
||||
- session_id, phase=1, seed_analysis (all fields), codebase_context (or null), recommendations
|
||||
|
||||
**design-intelligence.json** → `<session-folder>/analysis/design-intelligence.json` (UI mode only):
|
||||
- Produced when frontend keywords detected (component, page, UI, React, Vue, CSS, 前端) in seed_analysis
|
||||
- Fields: industry, style_direction, ux_patterns, color_strategy, typography, component_patterns
|
||||
- Consumed by architect (for design-tokens.json) and fe-developer
|
||||
|
||||
**Report**: complexity, codebase presence, problem statement, exploration dimensions, output paths.
|
||||
|
||||
**Success**: Both JSON files created; design-intelligence.json created if UI mode.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Gemini CLI failure | Fallback to direct Claude analysis |
|
||||
| Codebase detection failed | Continue as new project |
|
||||
| Topic too vague | Report with clarification questions |
|
||||
@@ -1,193 +0,0 @@
|
||||
# Command: assess
|
||||
|
||||
## Purpose
|
||||
|
||||
Multi-mode architecture assessment. Auto-detects consultation mode from task subject prefix, runs mode-specific analysis, and produces a verdict with concerns and recommendations.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
### Common Context (all modes)
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Wisdom | `<session_folder>/wisdom/` (all files) | No |
|
||||
| Project tech | `.workflow/project-tech.json` | No |
|
||||
| Explorations | `<session_folder>/explorations/` | No |
|
||||
|
||||
### Mode-Specific Context
|
||||
|
||||
| Mode | Task Pattern | Additional Context |
|
||||
|------|-------------|-------------------|
|
||||
| spec-review | ARCH-SPEC-* | `spec/architecture/_index.md`, `spec/architecture/ADR-*.md` |
|
||||
| plan-review | ARCH-PLAN-* | `plan/plan.json`, `plan/.task/TASK-*.json` |
|
||||
| code-review | ARCH-CODE-* | `git diff --name-only`, changed file contents |
|
||||
| consult | ARCH-CONSULT-* | Question extracted from task description |
|
||||
| feasibility | ARCH-FEASIBILITY-* | Proposal from task description, codebase search results |
|
||||
|
||||
## Phase 3: Mode-Specific Assessment
|
||||
|
||||
### Mode: spec-review
|
||||
|
||||
Review architecture documents for technical soundness across 4 dimensions.
|
||||
|
||||
**Assessment dimensions**:
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Consistency | 25% | ADR decisions align with each other and with architecture index |
|
||||
| Scalability | 25% | Design supports growth, no single-point bottlenecks |
|
||||
| Security | 25% | Auth model, data protection, API security addressed |
|
||||
| Tech fitness | 25% | Technology choices match project-tech.json and problem domain |
|
||||
|
||||
**Checks**:
|
||||
- Read architecture index and all ADR files
|
||||
- Cross-reference ADR decisions for contradictions
|
||||
- Verify tech choices align with project-tech.json
|
||||
- Score each dimension 0-100
|
||||
|
||||
---
|
||||
|
||||
### Mode: plan-review
|
||||
|
||||
Review implementation plan for architectural soundness.
|
||||
|
||||
**Checks**:
|
||||
|
||||
| Check | What | Severity if Failed |
|
||||
|-------|------|-------------------|
|
||||
| Dependency cycles | Build task graph, detect cycles via DFS | High |
|
||||
| Task granularity | Flag tasks touching >8 files | Medium |
|
||||
| Convention compliance | Verify plan follows wisdom/conventions.md | Medium |
|
||||
| Architecture alignment | Verify plan doesn't contradict wisdom/decisions.md | High |
|
||||
|
||||
**Dependency cycle detection flow**:
|
||||
1. Parse all TASK-*.json files -> extract id and depends_on
|
||||
2. Build directed graph
|
||||
3. DFS traversal -> flag any node visited twice in same stack
|
||||
4. Report cycle path if found
|
||||
|
||||
---
|
||||
|
||||
### Mode: code-review
|
||||
|
||||
Assess architectural impact of code changes.
|
||||
|
||||
**Checks**:
|
||||
|
||||
| Check | Method | Severity if Found |
|
||||
|-------|--------|-------------------|
|
||||
| Layer violations | Detect upward imports (deeper layer importing shallower) | High |
|
||||
| New dependencies | Parse package.json diff for added deps | Medium |
|
||||
| Module boundary changes | Flag index.ts/index.js modifications | Medium |
|
||||
| Architectural impact | Score based on file count and boundary changes | Info |
|
||||
|
||||
**Impact scoring**:
|
||||
|
||||
| Condition | Impact Level |
|
||||
|-----------|-------------|
|
||||
| Changed files > 10 | High |
|
||||
| index.ts/index.js or package.json modified | Medium |
|
||||
| All other cases | Low |
|
||||
|
||||
**Detection example** (find changed files):
|
||||
|
||||
```bash
|
||||
Bash(command="git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Mode: consult
|
||||
|
||||
Answer architecture decision questions. Route by question complexity.
|
||||
|
||||
**Complexity detection**:
|
||||
|
||||
| Condition | Classification |
|
||||
|-----------|---------------|
|
||||
| Question > 200 chars OR matches: architect, design, pattern, refactor, migrate, scalab | Complex |
|
||||
| All other questions | Simple |
|
||||
|
||||
**Complex questions** -> delegate to CLI exploration:
|
||||
|
||||
```bash
|
||||
Bash(command="ccw cli -p \"PURPOSE: Architecture consultation for: <question_summary>
|
||||
TASK: Search codebase for relevant patterns, analyze architectural implications, provide options with trade-offs
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED: Options with trade-offs, file references, architectural implications
|
||||
CONSTRAINTS: Advisory only, provide options not decisions\" --tool gemini --mode analysis --rule analysis-review-architecture", timeout=300000)
|
||||
```
|
||||
|
||||
**Simple questions** -> direct analysis using available context (wisdom, project-tech, codebase search).
|
||||
|
||||
---
|
||||
|
||||
### Mode: feasibility
|
||||
|
||||
Evaluate technical feasibility of a proposal.
|
||||
|
||||
**Assessment areas**:
|
||||
|
||||
| Area | Method | Output |
|
||||
|------|--------|--------|
|
||||
| Tech stack compatibility | Compare proposal needs against project-tech.json | Compatible / Requires additions |
|
||||
| Codebase readiness | Search for integration points using Grep/Glob | Touch-point count |
|
||||
| Effort estimation | Based on touch-point count (see table below) | Low / Medium / High |
|
||||
| Risk assessment | Based on effort + tech compatibility | Risks + mitigations |
|
||||
|
||||
**Effort estimation**:
|
||||
|
||||
| Touch Points | Effort | Implication |
|
||||
|-------------|--------|-------------|
|
||||
| <= 5 | Low | Straightforward implementation |
|
||||
| 6 - 20 | Medium | Moderate refactoring needed |
|
||||
| > 20 | High | Significant refactoring, consider phasing |
|
||||
|
||||
**Verdict for feasibility**:
|
||||
|
||||
| Condition | Verdict |
|
||||
|-----------|---------|
|
||||
| Low/medium effort, compatible stack | FEASIBLE |
|
||||
| High touch-points OR new tech required | RISKY |
|
||||
| Fundamental incompatibility or unreasonable effort | INFEASIBLE |
|
||||
|
||||
---
|
||||
|
||||
### Verdict Routing (all modes except feasibility)
|
||||
|
||||
| Verdict | Criteria |
|
||||
|---------|----------|
|
||||
| BLOCK | >= 2 high-severity concerns |
|
||||
| CONCERN | >= 1 high-severity OR >= 3 medium-severity concerns |
|
||||
| APPROVE | All other cases |
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Output Format
|
||||
|
||||
Write assessment to `<session_folder>/architecture/arch-<slug>.json`.
|
||||
|
||||
**Report content sent to coordinator**:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| mode | Consultation mode used |
|
||||
| verdict | APPROVE / CONCERN / BLOCK (or FEASIBLE / RISKY / INFEASIBLE) |
|
||||
| concern_count | Number of concerns by severity |
|
||||
| recommendations | Actionable suggestions with trade-offs |
|
||||
| output_path | Path to full assessment file |
|
||||
|
||||
**Wisdom contribution**: Append significant decisions to `<session_folder>/wisdom/decisions.md`.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Architecture docs not found | Assess from available context, note limitation in report |
|
||||
| Plan file missing | Report to coordinator via arch_concern |
|
||||
| Git diff fails (no commits) | Use staged changes or skip code-review mode |
|
||||
| CLI exploration timeout | Provide partial assessment, flag as incomplete |
|
||||
| Exploration results unparseable | Fall back to direct analysis without exploration |
|
||||
| Insufficient context | Request explorer assistance via coordinator |
|
||||
@@ -1,103 +0,0 @@
|
||||
# Role: architect
|
||||
|
||||
Architecture consultant. Advice on decisions, feasibility, design patterns.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `architect` | **Prefix**: `ARCH-*` | **Tag**: `[architect]`
|
||||
- **Type**: Consulting (on-demand, advisory only)
|
||||
- **Responsibility**: Context loading → Mode detection → Analysis → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process ARCH-* tasks
|
||||
- Auto-detect mode from task subject prefix
|
||||
- Provide options with trade-offs (not final decisions)
|
||||
|
||||
### MUST NOT
|
||||
- Modify source code
|
||||
- Make final decisions (advisory only)
|
||||
- Execute implementation or testing
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| arch_ready | → coordinator | Assessment complete |
|
||||
| arch_concern | → coordinator | Significant risk found |
|
||||
| error | → coordinator | Analysis failure |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/assess.md | Multi-mode assessment |
|
||||
| cli-explore-agent | Deep architecture exploration |
|
||||
| ccw cli --tool gemini --mode analysis | Architecture analysis |
|
||||
|
||||
---
|
||||
|
||||
## Consultation Modes
|
||||
|
||||
| Task Pattern | Mode | Focus |
|
||||
|-------------|------|-------|
|
||||
| ARCH-SPEC-* | spec-review | Review architecture docs |
|
||||
| ARCH-PLAN-* | plan-review | Review plan soundness |
|
||||
| ARCH-CODE-* | code-review | Assess code change impact |
|
||||
| ARCH-CONSULT-* | consult | Answer architecture questions |
|
||||
| ARCH-FEASIBILITY-* | feasibility | Technical feasibility |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
**Common**: session folder, wisdom, project-tech.json, explorations
|
||||
|
||||
**Mode-specific**:
|
||||
|
||||
| Mode | Additional Context |
|
||||
|------|-------------------|
|
||||
| spec-review | architecture/_index.md, ADR-*.md |
|
||||
| plan-review | plan/plan.json |
|
||||
| code-review | git diff, changed files |
|
||||
| consult | Question from task description |
|
||||
| feasibility | Requirements + codebase |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Assessment
|
||||
|
||||
Delegate to `commands/assess.md`. Output: mode, verdict (APPROVE/CONCERN/BLOCK), dimensions[], concerns[], recommendations[].
|
||||
|
||||
For complex questions → Gemini CLI with architecture review rule.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Report
|
||||
|
||||
Output to `<session-folder>/architecture/arch-<slug>.json`. Contribute decisions to wisdom/decisions.md.
|
||||
|
||||
**Frontend project outputs** (when frontend tech stack detected in shared-memory or discovery-context):
|
||||
- `<session-folder>/architecture/design-tokens.json` — color, spacing, typography, shadow tokens
|
||||
- `<session-folder>/architecture/component-specs/*.md` — per-component design spec
|
||||
|
||||
**Report**: mode, verdict, concern count, recommendations, output path(s).
|
||||
|
||||
---
|
||||
|
||||
## Coordinator Integration
|
||||
|
||||
| Timing | Task |
|
||||
|--------|------|
|
||||
| After DRAFT-003 | ARCH-SPEC-001: 架构文档评审 |
|
||||
| After PLAN-001 | ARCH-PLAN-001: 计划架构审查 |
|
||||
| On-demand | ARCH-CONSULT-001: 架构咨询 |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Docs not found | Assess from available context |
|
||||
| CLI timeout | Partial assessment |
|
||||
| Insufficient context | Request explorer via coordinator |
|
||||
@@ -1,142 +0,0 @@
|
||||
# Command: dispatch
|
||||
|
||||
## Purpose
|
||||
|
||||
Create task chains based on execution mode. Each mode maps to a predefined pipeline from SKILL.md Task Metadata Registry. Tasks are created with proper dependency chains, owner assignments, and session references.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Mode | Phase 1 requirements (spec-only, impl-only, etc.) | Yes |
|
||||
| Session folder | `<session-folder>` from Phase 2 | Yes |
|
||||
| Scope | User requirements description | Yes |
|
||||
| Spec file | User-provided path (impl-only mode only) | Conditional |
|
||||
|
||||
## Phase 3: Task Chain Creation
|
||||
|
||||
### Mode-to-Pipeline Routing
|
||||
|
||||
| Mode | Tasks | Pipeline | First Task |
|
||||
|------|-------|----------|------------|
|
||||
| spec-only | 12 | Spec pipeline | RESEARCH-001 |
|
||||
| impl-only | 4 | Impl pipeline | PLAN-001 |
|
||||
| fe-only | 3 | FE pipeline | PLAN-001 |
|
||||
| fullstack | 6 | Fullstack pipeline | PLAN-001 |
|
||||
| full-lifecycle | 16 | Spec + Impl | RESEARCH-001 |
|
||||
| full-lifecycle-fe | 18 | Spec + Fullstack | RESEARCH-001 |
|
||||
|
||||
---
|
||||
|
||||
### Spec Pipeline (12 tasks)
|
||||
|
||||
Used by: spec-only, full-lifecycle, full-lifecycle-fe
|
||||
|
||||
| # | Subject | Owner | BlockedBy | Description |
|
||||
|---|---------|-------|-----------|-------------|
|
||||
| 1 | RESEARCH-001 | analyst | (none) | Seed analysis and context gathering |
|
||||
| 2 | DISCUSS-001 | discussant | RESEARCH-001 | Critique research findings |
|
||||
| 3 | DRAFT-001 | writer | DISCUSS-001 | Generate Product Brief |
|
||||
| 4 | DISCUSS-002 | discussant | DRAFT-001 | Critique Product Brief |
|
||||
| 5 | DRAFT-002 | writer | DISCUSS-002 | Generate Requirements/PRD |
|
||||
| 6 | DISCUSS-003 | discussant | DRAFT-002 | Critique Requirements/PRD |
|
||||
| 7 | DRAFT-003 | writer | DISCUSS-003 | Generate Architecture Document |
|
||||
| 8 | DISCUSS-004 | discussant | DRAFT-003 | Critique Architecture Document |
|
||||
| 9 | DRAFT-004 | writer | DISCUSS-004 | Generate Epics |
|
||||
| 10 | DISCUSS-005 | discussant | DRAFT-004 | Critique Epics |
|
||||
| 11 | QUALITY-001 | reviewer | DISCUSS-005 | 5-dimension spec quality validation |
|
||||
| 12 | DISCUSS-006 | discussant | QUALITY-001 | Final review discussion and sign-off |
|
||||
|
||||
### Impl Pipeline (4 tasks)
|
||||
|
||||
Used by: impl-only, full-lifecycle (PLAN-001 blockedBy DISCUSS-006)
|
||||
|
||||
| # | Subject | Owner | BlockedBy | Description |
|
||||
|---|---------|-------|-----------|-------------|
|
||||
| 1 | PLAN-001 | planner | (none) | Multi-angle exploration and planning |
|
||||
| 2 | IMPL-001 | executor | PLAN-001 | Code implementation |
|
||||
| 3 | TEST-001 | tester | IMPL-001 | Test-fix cycles |
|
||||
| 4 | REVIEW-001 | reviewer | IMPL-001 | 4-dimension code review |
|
||||
|
||||
### FE Pipeline (3 tasks)
|
||||
|
||||
Used by: fe-only
|
||||
|
||||
| # | Subject | Owner | BlockedBy | Description |
|
||||
|---|---------|-------|-----------|-------------|
|
||||
| 1 | PLAN-001 | planner | (none) | Planning (frontend focus) |
|
||||
| 2 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation |
|
||||
| 3 | QA-FE-001 | fe-qa | DEV-FE-001 | 5-dimension frontend QA |
|
||||
|
||||
GC loop (max 2 rounds): QA-FE verdict=NEEDS_FIX → create DEV-FE-002 + QA-FE-002 dynamically.
|
||||
|
||||
### Fullstack Pipeline (6 tasks)
|
||||
|
||||
Used by: fullstack, full-lifecycle-fe (PLAN-001 blockedBy DISCUSS-006)
|
||||
|
||||
| # | Subject | Owner | BlockedBy | Description |
|
||||
|---|---------|-------|-----------|-------------|
|
||||
| 1 | PLAN-001 | planner | (none) | Fullstack planning |
|
||||
| 2 | IMPL-001 | executor | PLAN-001 | Backend implementation |
|
||||
| 3 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation |
|
||||
| 4 | TEST-001 | tester | IMPL-001 | Backend test-fix cycles |
|
||||
| 5 | QA-FE-001 | fe-qa | DEV-FE-001 | Frontend QA |
|
||||
| 6 | REVIEW-001 | reviewer | TEST-001, QA-FE-001 | Full code review |
|
||||
|
||||
### Composite Modes
|
||||
|
||||
| Mode | Construction | PLAN-001 BlockedBy |
|
||||
|------|-------------|-------------------|
|
||||
| full-lifecycle | Spec (12) + Impl (4) | DISCUSS-006 |
|
||||
| full-lifecycle-fe | Spec (12) + Fullstack (6) | DISCUSS-006 |
|
||||
|
||||
---
|
||||
|
||||
### Impl-Only Pre-check
|
||||
|
||||
Before creating impl-only tasks, verify specification exists:
|
||||
|
||||
```
|
||||
Spec exists?
|
||||
├─ YES → read spec path → proceed with task creation
|
||||
└─ NO → error: "impl-only requires existing spec, use spec-only or full-lifecycle"
|
||||
```
|
||||
|
||||
### Task Description Template
|
||||
|
||||
Every task description includes session and scope context:
|
||||
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "<TASK-ID>",
|
||||
owner: "<role>",
|
||||
description: "<task description from pipeline table>\nSession: <session-folder>\nScope: <scope>",
|
||||
blockedBy: [<dependency-list>],
|
||||
status: "pending"
|
||||
})
|
||||
```
|
||||
|
||||
### Execution Method
|
||||
|
||||
| Method | Behavior |
|
||||
|--------|----------|
|
||||
| sequential | One task active at a time; next activated after predecessor completes |
|
||||
| parallel | Tasks with all deps met run concurrently (e.g., TEST-001 + REVIEW-001) |
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
| Check | Criteria |
|
||||
|-------|----------|
|
||||
| Task count | Matches mode total from routing table |
|
||||
| Dependencies | Every blockedBy references an existing task subject |
|
||||
| Owner assignment | Each task owner matches SKILL.md Role Registry prefix |
|
||||
| Session reference | Every task description contains `Session: <session-folder>` |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Unknown mode | Reject with supported mode list |
|
||||
| Missing spec for impl-only | Error, suggest spec-only or full-lifecycle |
|
||||
| TaskCreate fails | Log error, report to user |
|
||||
| Duplicate task subject | Skip creation, log warning |
|
||||
@@ -1,180 +0,0 @@
|
||||
# Command: monitor
|
||||
|
||||
## Purpose
|
||||
|
||||
Event-driven pipeline coordination with Spawn-and-Stop pattern. Three wake-up sources drive pipeline advancement: worker callbacks (auto-advance), user `check` (status report), user `resume` (manual advance).
|
||||
|
||||
## Constants
|
||||
|
||||
| Constant | Value | Description |
|
||||
|----------|-------|-------------|
|
||||
| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` |
|
||||
| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS |
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session file | `<session-folder>/team-session.json` | Yes |
|
||||
| Task list | `TaskList()` | Yes |
|
||||
| Active workers | session.active_workers[] | Yes |
|
||||
| Pipeline mode | session.mode | Yes |
|
||||
|
||||
## Phase 3: Handler Routing
|
||||
|
||||
### Wake-up Source Detection
|
||||
|
||||
Parse `$ARGUMENTS` to determine handler:
|
||||
|
||||
| Priority | Condition | Handler |
|
||||
|----------|-----------|---------|
|
||||
| 1 | Message contains `[<role-name>]` from known worker role | handleCallback |
|
||||
| 2 | Contains "check" or "status" | handleCheck |
|
||||
| 3 | Contains "resume", "continue", or "next" | handleResume |
|
||||
| 4 | None of the above (initial spawn after dispatch) | handleSpawnNext |
|
||||
|
||||
Known worker roles: analyst, writer, discussant, planner, executor, tester, reviewer, explorer, architect, fe-developer, fe-qa.
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleCallback
|
||||
|
||||
Worker completed a task. Verify completion, update state, auto-advance.
|
||||
|
||||
```
|
||||
Receive callback from [<role>]
|
||||
├─ Find matching active worker by role
|
||||
├─ Task status = completed?
|
||||
│ ├─ YES → remove from active_workers → update session
|
||||
│ │ ├─ Handle checkpoints (see below)
|
||||
│ │ └─ → handleSpawnNext
|
||||
│ └─ NO → progress message, do not advance → STOP
|
||||
└─ No matching worker found
|
||||
├─ Scan all active workers for completed tasks
|
||||
├─ Found completed → process each → handleSpawnNext
|
||||
└─ None completed → STOP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleCheck
|
||||
|
||||
Read-only status report. No pipeline advancement.
|
||||
|
||||
**Output format**:
|
||||
|
||||
```
|
||||
[coordinator] Pipeline Status
|
||||
[coordinator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)
|
||||
|
||||
[coordinator] Execution Graph:
|
||||
Spec Phase: (if applicable)
|
||||
[<icon> RESEARCH-001] → [<icon> DISCUSS-001] → ...
|
||||
Impl Phase: (if applicable)
|
||||
[<icon> PLAN-001]
|
||||
├─ BE: [<icon> IMPL-001] → [<icon> TEST-001] → [<icon> REVIEW-001]
|
||||
└─ FE: [<icon> DEV-FE-001] → [<icon> QA-FE-001]
|
||||
|
||||
done=completed >>>=running o=pending .=not created
|
||||
|
||||
[coordinator] Active Workers:
|
||||
> <subject> (<role>) - running <elapsed>
|
||||
|
||||
[coordinator] Ready to spawn: <subjects>
|
||||
[coordinator] Commands: 'resume' to advance | 'check' to refresh
|
||||
```
|
||||
|
||||
**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=.
|
||||
|
||||
Then STOP.
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleResume
|
||||
|
||||
Check active worker completion, process results, advance pipeline.
|
||||
|
||||
```
|
||||
Load active_workers from session
|
||||
├─ No active workers → handleSpawnNext
|
||||
└─ Has active workers → check each:
|
||||
├─ status = completed → mark done, log
|
||||
├─ status = in_progress → still running, log
|
||||
└─ other status → worker failure → reset to pending
|
||||
After processing:
|
||||
├─ Some completed → handleSpawnNext
|
||||
├─ All still running → report status → STOP
|
||||
└─ All failed → handleSpawnNext (retry)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleSpawnNext
|
||||
|
||||
Find all ready tasks, spawn workers in background, update session, STOP.
|
||||
|
||||
```
|
||||
Collect task states from TaskList()
|
||||
├─ completedSubjects: status = completed
|
||||
├─ inProgressSubjects: status = in_progress
|
||||
└─ readySubjects: pending + all blockedBy in completedSubjects
|
||||
|
||||
Ready tasks found?
|
||||
├─ NONE + work in progress → report waiting → STOP
|
||||
├─ NONE + nothing in progress → PIPELINE_COMPLETE → Phase 5
|
||||
└─ HAS ready tasks → for each:
|
||||
├─ TaskUpdate → in_progress
|
||||
├─ team_msg log → task_unblocked
|
||||
├─ Spawn worker (see tool call below)
|
||||
└─ Add to session.active_workers
|
||||
Update session file → output summary → STOP
|
||||
```
|
||||
|
||||
**Spawn worker tool call** (one per ready task):
|
||||
|
||||
```bash
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
description: "Spawn <role> worker for <subject>",
|
||||
team_name: <team-name>,
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: "<worker prompt from SKILL.md Coordinator Spawn Template>"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Checkpoints
|
||||
|
||||
| Completed Task | Mode Condition | Action |
|
||||
|---------------|----------------|--------|
|
||||
| DISCUSS-006 | full-lifecycle or full-lifecycle-fe | Output "SPEC PHASE COMPLETE" checkpoint, pause for user review before impl |
|
||||
|
||||
---
|
||||
|
||||
### Worker Failure Handling
|
||||
|
||||
When a worker has unexpected status (not completed, not in_progress):
|
||||
|
||||
1. Reset task → pending via TaskUpdate
|
||||
2. Log via team_msg (type: error)
|
||||
3. Report to user: task reset, will retry on next resume
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
| Check | Criteria |
|
||||
|-------|----------|
|
||||
| Session state consistent | active_workers matches TaskList in_progress tasks |
|
||||
| No orphaned tasks | Every in_progress task has an active_worker entry |
|
||||
| Pipeline completeness | All expected tasks exist per mode |
|
||||
| Completion detection | readySubjects=0 + inProgressSubjects=0 → PIPELINE_COMPLETE |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Session file not found | Error, suggest re-initialization |
|
||||
| Worker callback from unknown role | Log info, scan for other completions |
|
||||
| All workers still running on resume | Report status, suggest check later |
|
||||
| Pipeline stall (no ready, no running) | Check for missing tasks, report to user |
|
||||
@@ -1,209 +0,0 @@
|
||||
# Coordinator Role
|
||||
|
||||
Orchestrate the team-lifecycle workflow: team creation, task dispatching, progress monitoring, session state.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `coordinator` | **Tag**: `[coordinator]`
|
||||
- **Responsibility**: Parse requirements → Create team → Dispatch tasks → Monitor progress → Report results
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Parse user requirements and clarify ambiguous inputs via AskUserQuestion
|
||||
- Create team and spawn worker subagents in background
|
||||
- Dispatch tasks with proper dependency chains (see SKILL.md Task Metadata Registry)
|
||||
- Monitor progress via worker callbacks and route messages
|
||||
- Maintain session state persistence (team-session.json)
|
||||
|
||||
### MUST NOT
|
||||
- Execute spec/impl/research work directly (delegate to workers)
|
||||
- Modify task outputs (workers own their deliverables)
|
||||
- Call implementation subagents (code-developer, etc.) directly
|
||||
- Skip dependency validation when creating task chains
|
||||
|
||||
---
|
||||
|
||||
## Command Execution Protocol
|
||||
|
||||
When coordinator needs to execute a command (dispatch, monitor):
|
||||
|
||||
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
|
||||
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
|
||||
3. **Commands are inline execution guides** - NOT separate agents or subprocesses
|
||||
4. **Execute synchronously** - complete the command workflow before proceeding
|
||||
|
||||
Example:
|
||||
```
|
||||
Phase 3 needs task dispatch
|
||||
-> Read roles/coordinator/commands/dispatch.md
|
||||
-> Execute Phase 2 (Context Loading)
|
||||
-> Execute Phase 3 (Task Chain Creation)
|
||||
-> Execute Phase 4 (Validation)
|
||||
-> Continue to Phase 4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entry Router
|
||||
|
||||
When coordinator is invoked, first detect the invocation type:
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains `[role-name]` tag from a known worker role | → handleCallback: auto-advance pipeline |
|
||||
| Status check | Arguments contain "check" or "status" | → handleCheck: output execution graph, no advancement |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | → handleResume: check worker states, advance pipeline |
|
||||
| Interrupted session | Active/paused session exists in `.workflow/.team/TLS-*` | → Phase 0 (Session Resume Check) |
|
||||
| New session | None of the above | → Phase 1 (Requirement Clarification) |
|
||||
|
||||
For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP.
|
||||
|
||||
### Router Implementation
|
||||
|
||||
1. **Load session context** (if exists):
|
||||
- Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions
|
||||
- If found, extract known worker roles from session or SKILL.md Role Registry
|
||||
|
||||
2. **Parse $ARGUMENTS** for detection keywords
|
||||
|
||||
3. **Route to handler**:
|
||||
- For monitor handlers: Read `commands/monitor.md`, execute matched handler section, STOP
|
||||
- For Phase 0: Execute Session Resume Check below
|
||||
- For Phase 1: Execute Requirement Clarification below
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
**Objective**: Detect and resume interrupted sessions before creating new ones.
|
||||
|
||||
**Workflow**:
|
||||
1. Scan `.workflow/.team/TLS-*/team-session.json` for sessions with status "active" or "paused"
|
||||
2. No sessions found → proceed to Phase 1
|
||||
3. Single session found → resume it (→ Session Reconciliation)
|
||||
4. Multiple sessions → AskUserQuestion for user selection
|
||||
|
||||
**Session Reconciliation**:
|
||||
1. Audit TaskList → get real status of all tasks
|
||||
2. Reconcile: session.completed_tasks ↔ TaskList status (bidirectional sync)
|
||||
3. Reset any in_progress tasks → pending (they were interrupted)
|
||||
4. Determine remaining pipeline from reconciled state
|
||||
5. Rebuild team if disbanded (TeamCreate + spawn needed workers only)
|
||||
6. Create missing tasks with correct blockedBy dependencies
|
||||
7. Verify dependency chain integrity
|
||||
8. Update session file with reconciled state
|
||||
9. Kick first executable task's worker → Phase 4
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Requirement Clarification
|
||||
|
||||
**Objective**: Parse user input and gather execution parameters.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. **Parse arguments** for explicit settings: mode, scope, focus areas, depth
|
||||
|
||||
2. **Ask for missing parameters** via AskUserQuestion:
|
||||
- Mode: spec-only / impl-only / full-lifecycle / fe-only / fullstack / full-lifecycle-fe
|
||||
- Scope: project description
|
||||
- Execution method: sequential / parallel
|
||||
|
||||
3. **Frontend auto-detection** (for impl-only and full-lifecycle modes):
|
||||
|
||||
| Signal | Detection | Pipeline Upgrade |
|
||||
|--------|----------|-----------------|
|
||||
| FE keywords (component, page, UI, React, Vue, CSS...) | Keyword match in description | impl-only → fe-only or fullstack |
|
||||
| BE keywords also present (API, database, server...) | Both FE + BE keywords | impl-only → fullstack |
|
||||
| FE framework in package.json | grep react/vue/svelte/next | full-lifecycle → full-lifecycle-fe |
|
||||
|
||||
4. **Store requirements**: mode, scope, focus, depth, executionMethod
|
||||
|
||||
**Success**: All parameters captured, mode finalized.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Create Team + Initialize Session
|
||||
|
||||
**Objective**: Initialize team, session file, and wisdom directory.
|
||||
|
||||
**Workflow**:
|
||||
1. Generate session ID: `TLS-<slug>-<date>`
|
||||
2. Create session folder: `.workflow/.team/<session-id>/`
|
||||
3. Call TeamCreate with team name
|
||||
4. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
|
||||
5. Write team-session.json with: session_id, mode, scope, status="active", tasks_total, tasks_completed=0
|
||||
|
||||
**Task counts by mode**:
|
||||
|
||||
| Mode | Tasks |
|
||||
|------|-------|
|
||||
| spec-only | 12 |
|
||||
| impl-only | 4 |
|
||||
| fe-only | 3 |
|
||||
| fullstack | 6 |
|
||||
| full-lifecycle | 16 |
|
||||
| full-lifecycle-fe | 18 |
|
||||
|
||||
**Success**: Team created, session file written, wisdom initialized.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Create Task Chain
|
||||
|
||||
**Objective**: Dispatch tasks based on mode with proper dependencies.
|
||||
|
||||
Delegate to `commands/dispatch.md` which creates the full task chain:
|
||||
1. Reads SKILL.md Task Metadata Registry for task definitions
|
||||
2. Creates tasks via TaskCreate with correct blockedBy
|
||||
3. Assigns owner based on role mapping
|
||||
4. Includes `Session: <session-folder>` in every task description
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Spawn-and-Stop
|
||||
|
||||
**Objective**: Spawn first batch of ready workers in background, then STOP.
|
||||
|
||||
**Design**: Spawn-and-Stop + Callback pattern.
|
||||
- Spawn workers with `Task(run_in_background: true)` → immediately return
|
||||
- Worker completes → SendMessage callback → auto-advance
|
||||
- User can use "check" / "resume" to manually advance
|
||||
- Coordinator does one operation per invocation, then STOPS
|
||||
|
||||
**Workflow**:
|
||||
1. Load `commands/monitor.md`
|
||||
2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
|
||||
3. For each ready task → spawn worker (see SKILL.md Spawn Template)
|
||||
4. Output status summary
|
||||
5. STOP
|
||||
|
||||
**Pipeline advancement** driven by three wake sources:
|
||||
- Worker callback (automatic) → Entry Router → handleCallback
|
||||
- User "check" → handleCheck (status only)
|
||||
- User "resume" → handleResume (advance)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Report + Next Steps
|
||||
|
||||
**Objective**: Completion report and follow-up options.
|
||||
|
||||
**Workflow**:
|
||||
1. Load session state → count completed tasks, duration
|
||||
2. List deliverables with output paths
|
||||
3. Update session status → "completed"
|
||||
4. Offer next steps: 退出 / 查看产物 / 扩展任务 / 生成 lite-plan / 创建 Issue
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Task timeout | Log, mark failed, ask user to retry or skip |
|
||||
| Worker crash | Respawn worker, reassign task |
|
||||
| Dependency cycle | Detect, report to user, halt |
|
||||
| Invalid mode | Reject with error, ask to clarify |
|
||||
| Session corruption | Attempt recovery, fallback to manual reconciliation |
|
||||
@@ -1,136 +0,0 @@
|
||||
# Command: critique
|
||||
|
||||
## Purpose
|
||||
|
||||
Multi-perspective CLI critique: launch parallel analyses from assigned perspectives, collect structured ratings, detect divergences, and synthesize consensus.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Round config | DISCUSS-NNN → look up round in role.md table | Yes |
|
||||
| Artifact | `<session-folder>/<artifact-path>` from round config | Yes |
|
||||
| Perspectives | Round config perspectives column | Yes |
|
||||
| Discovery context | `<session-folder>/spec/discovery-context.json` | For coverage perspective |
|
||||
| Prior discussions | `<session-folder>/discussions/` | No |
|
||||
|
||||
## Phase 3: Multi-Perspective Critique
|
||||
|
||||
### Perspective Routing
|
||||
|
||||
| Perspective | CLI Tool | Role | Focus Areas |
|
||||
|-------------|----------|------|-------------|
|
||||
| Product | gemini | Product Manager | Market fit, user value, business viability, competitive differentiation |
|
||||
| Technical | codex | Tech Lead | Feasibility, tech debt, performance, security, maintainability |
|
||||
| Quality | claude | QA Lead | Completeness, testability, consistency, standards compliance |
|
||||
| Risk | gemini | Risk Analyst | Risk identification, dependencies, failure modes, mitigation |
|
||||
| Coverage | gemini | Requirements Analyst | Requirement completeness vs discovery-context, gap detection, scope creep |
|
||||
|
||||
### Execution Flow
|
||||
|
||||
```
|
||||
For each perspective in round config:
|
||||
├─ Build prompt with perspective focus + artifact content
|
||||
├─ Launch CLI analysis (background)
|
||||
│ Bash(command="ccw cli -p '<prompt>' --tool <cli-tool> --mode analysis", run_in_background=true)
|
||||
└─ Collect result via hook callback
|
||||
```
|
||||
|
||||
### CLI Call Template
|
||||
|
||||
```bash
|
||||
Bash(command="ccw cli -p 'PURPOSE: Analyze from <role> perspective for <round-id>
|
||||
TASK: <focus-areas-from-table>
|
||||
MODE: analysis
|
||||
CONTEXT: Artifact content below
|
||||
EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5)
|
||||
CONSTRAINTS: Output valid JSON only
|
||||
|
||||
Artifact:
|
||||
<artifact-content>' --tool <cli-tool> --mode analysis", run_in_background=true)
|
||||
```
|
||||
|
||||
### Extra Fields by Perspective
|
||||
|
||||
| Perspective | Additional Output Fields |
|
||||
|-------------|------------------------|
|
||||
| Risk | `risk_level`: low / medium / high / critical |
|
||||
| Coverage | `covered_requirements[]`, `partial_requirements[]`, `missing_requirements[]`, `scope_creep[]` |
|
||||
|
||||
---
|
||||
|
||||
### Divergence Detection
|
||||
|
||||
After all perspectives return, scan results for critical signals:
|
||||
|
||||
| Signal | Condition | Severity |
|
||||
|--------|-----------|----------|
|
||||
| Coverage gap | `missing_requirements` non-empty | High |
|
||||
| High risk | `risk_level` is high or critical | High |
|
||||
| Low rating | Any perspective rating <= 2 | Medium |
|
||||
| Rating spread | Max rating - min rating >= 3 | Medium |
|
||||
|
||||
### Consensus Determination
|
||||
|
||||
| Condition | Verdict |
|
||||
|-----------|---------|
|
||||
| No high-severity divergences AND average rating >= 3.0 | consensus_reached |
|
||||
| Any high-severity divergence OR average rating < 3.0 | consensus_blocked |
|
||||
|
||||
### Synthesis Process
|
||||
|
||||
```
|
||||
Collect all perspective results
|
||||
├─ Extract convergent themes (agreed by 2+ perspectives)
|
||||
├─ Extract divergent views (conflicting assessments)
|
||||
├─ Check coverage gaps from coverage result
|
||||
├─ Compile action items from all suggestions
|
||||
└─ Determine consensus per table above
|
||||
```
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Discussion Record
|
||||
|
||||
Write to `<session-folder>/discussions/<round-id>-discussion.md`:
|
||||
|
||||
```
|
||||
# Discussion Record: <round-id>
|
||||
|
||||
**Artifact**: <artifact-path>
|
||||
**Perspectives**: <list>
|
||||
**Consensus**: reached / blocked
|
||||
|
||||
## Convergent Themes
|
||||
- <theme>
|
||||
|
||||
## Divergent Views
|
||||
- **<topic>** (<severity>): <description>
|
||||
|
||||
## Action Items
|
||||
1. <item>
|
||||
|
||||
## Ratings
|
||||
| Perspective | Rating |
|
||||
|-------------|--------|
|
||||
| <name> | <n>/5 |
|
||||
|
||||
**Average**: <avg>/5
|
||||
```
|
||||
|
||||
### Result Routing
|
||||
|
||||
| Outcome | Message Type | Content |
|
||||
|---------|-------------|---------|
|
||||
| Consensus reached | discussion_ready | Action items, record path, average rating |
|
||||
| Consensus blocked | discussion_blocked | Divergence points, severity, record path |
|
||||
| Artifact not found | error | Missing artifact path |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Artifact not found | Report error to coordinator |
|
||||
| Single CLI perspective fails | Fallback to direct Claude analysis for that perspective |
|
||||
| All CLI analyses fail | Generate basic discussion from direct artifact reading |
|
||||
| All perspectives diverge | Report as discussion_blocked with all divergence points |
|
||||
@@ -1,128 +0,0 @@
|
||||
# Role: discussant
|
||||
|
||||
Multi-perspective critique, consensus building, and conflict escalation. Ensures quality feedback between each phase transition.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `discussant` | **Prefix**: `DISCUSS-*` | **Tag**: `[discussant]`
|
||||
- **Responsibility**: Load Artifact → Multi-Perspective Critique → Synthesize Consensus → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process DISCUSS-* tasks
|
||||
- Execute multi-perspective critique via CLI tools
|
||||
- Detect coverage gaps from coverage perspective
|
||||
- Synthesize consensus with convergent/divergent analysis
|
||||
- Write discussion records to `discussions/` folder
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks
|
||||
- Contact other workers directly
|
||||
- Modify spec documents directly
|
||||
- Skip perspectives defined in round config
|
||||
- Ignore critical divergences
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| discussion_ready | → coordinator | Consensus reached |
|
||||
| discussion_blocked | → coordinator | Cannot reach consensus |
|
||||
| error | → coordinator | Input artifact missing |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/critique.md | Multi-perspective CLI critique |
|
||||
| gemini CLI | Product, Risk, Coverage perspectives |
|
||||
| codex CLI | Technical perspective |
|
||||
| claude CLI | Quality perspective |
|
||||
|
||||
---
|
||||
|
||||
## Perspective Model
|
||||
|
||||
| Perspective | Focus | CLI Tool |
|
||||
|-------------|-------|----------|
|
||||
| Product | Market fit, user value, business viability | gemini |
|
||||
| Technical | Feasibility, tech debt, performance, security | codex |
|
||||
| Quality | Completeness, testability, consistency | claude |
|
||||
| Risk | Risk identification, dependency analysis, failure modes | gemini |
|
||||
| Coverage | Requirement completeness vs original intent, gap detection | gemini |
|
||||
|
||||
## Round Configuration
|
||||
|
||||
| Round | Artifact | Perspectives | Focus |
|
||||
|-------|----------|-------------|-------|
|
||||
| DISCUSS-001 | spec/discovery-context.json | product, risk, coverage | Scope confirmation |
|
||||
| DISCUSS-002 | spec/product-brief.md | product, technical, quality, coverage | Positioning, feasibility |
|
||||
| DISCUSS-003 | spec/requirements/_index.md | quality, product, coverage | Completeness, priority |
|
||||
| DISCUSS-004 | spec/architecture/_index.md | technical, risk | Tech choices, security |
|
||||
| DISCUSS-005 | spec/epics/_index.md | product, technical, quality, coverage | MVP scope, estimation |
|
||||
| DISCUSS-006 | spec/readiness-report.md | all 5 | Final sign-off |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Artifact Loading
|
||||
|
||||
**Objective**: Load target artifact and determine discussion parameters.
|
||||
|
||||
**Workflow**:
|
||||
1. Extract session folder and round number from task subject (`DISCUSS-<NNN>`)
|
||||
2. Look up round config from table above
|
||||
3. Load target artifact from `<session-folder>/<artifact-path>`
|
||||
4. Create `<session-folder>/discussions/` directory
|
||||
5. Load prior discussion records for continuity
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Multi-Perspective Critique
|
||||
|
||||
**Objective**: Run parallel CLI analyses from each required perspective.
|
||||
|
||||
Delegate to `commands/critique.md` -- launches parallel CLI calls per perspective with focused prompts and designated tools.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Consensus Synthesis
|
||||
|
||||
**Objective**: Synthesize into consensus with actionable outcomes.
|
||||
|
||||
**Synthesis process**:
|
||||
1. Extract convergent themes (agreed by 2+ perspectives)
|
||||
2. Extract divergent views (conflicting perspectives, with severity)
|
||||
3. Check coverage gaps from coverage perspective
|
||||
4. Compile action items and open questions
|
||||
|
||||
**Consensus routing**:
|
||||
|
||||
| Condition | Status | Report |
|
||||
|-----------|--------|--------|
|
||||
| No high-severity divergences | consensus_reached | Action items, open questions, record path |
|
||||
| Any high-severity divergences | consensus_blocked | Escalate divergence points to coordinator |
|
||||
|
||||
Write discussion record to `<session-folder>/discussions/<output-file>`.
|
||||
|
||||
**Output file naming convention**:
|
||||
|
||||
| Round | Output File |
|
||||
|-------|------------|
|
||||
| DISCUSS-001 | discuss-001-scope.md |
|
||||
| DISCUSS-002 | discuss-002-brief.md |
|
||||
| DISCUSS-003 | discuss-003-requirements.md |
|
||||
| DISCUSS-004 | discuss-004-architecture.md |
|
||||
| DISCUSS-005 | discuss-005-epics.md |
|
||||
| DISCUSS-006 | discuss-006-signoff.md |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Target artifact not found | Notify coordinator |
|
||||
| CLI perspective failure | Fallback to direct Claude analysis |
|
||||
| All CLI analyses fail | Generate basic discussion from direct reading |
|
||||
| All perspectives diverge | Escalate as discussion_blocked |
|
||||
@@ -1,166 +0,0 @@
|
||||
# Command: implement
|
||||
|
||||
## Purpose
|
||||
|
||||
Multi-backend code implementation: route tasks to appropriate execution backend (direct edit, subagent, or CLI), build focused prompts, execute with retry and fallback.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Plan | `<session-folder>/plan/plan.json` | Yes |
|
||||
| Task files | `<session-folder>/plan/.task/TASK-*.json` | Yes |
|
||||
| Backend | Task metadata / plan default / auto-select | Yes |
|
||||
| Working directory | task.metadata.working_dir or project root | No |
|
||||
| Wisdom | `<session-folder>/wisdom/` | No |
|
||||
|
||||
## Phase 3: Implementation
|
||||
|
||||
### Backend Selection
|
||||
|
||||
Priority order (first match wins):
|
||||
|
||||
| Priority | Source | Method |
|
||||
|----------|--------|--------|
|
||||
| 1 | Task metadata | `task.metadata.executor` field |
|
||||
| 2 | Plan default | "Execution Backend:" line in plan.json |
|
||||
| 3 | Auto-select | See auto-select table below |
|
||||
|
||||
**Auto-select routing**:
|
||||
|
||||
| Condition | Backend |
|
||||
|-----------|---------|
|
||||
| Description < 200 chars AND no refactor/architecture keywords AND single target file | agent (direct edit) |
|
||||
| Description < 200 chars AND simple scope | agent (subagent) |
|
||||
| Complex scope OR architecture keywords | codex |
|
||||
| Analysis-heavy OR multi-module integration | gemini |
|
||||
|
||||
### Execution Paths
|
||||
|
||||
```
|
||||
Backend selected
|
||||
├─ agent (direct edit)
|
||||
│ └─ Read target file → Edit directly → no subagent overhead
|
||||
├─ agent (subagent)
|
||||
│ └─ Task({ subagent_type: "code-developer", run_in_background: false })
|
||||
├─ codex (CLI)
|
||||
│ └─ Bash(command="ccw cli ... --tool codex --mode write", run_in_background=true)
|
||||
└─ gemini (CLI)
|
||||
└─ Bash(command="ccw cli ... --tool gemini --mode write", run_in_background=true)
|
||||
```
|
||||
|
||||
### Path 1: Direct Edit (agent, simple task)
|
||||
|
||||
```bash
|
||||
Read(file_path="<target-file>")
|
||||
Edit(file_path="<target-file>", old_string="<old>", new_string="<new>")
|
||||
```
|
||||
|
||||
### Path 2: Subagent (agent, moderate task)
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
run_in_background: false,
|
||||
description: "Implement <task-id>",
|
||||
prompt: "<execution-prompt>"
|
||||
})
|
||||
```
|
||||
|
||||
### Path 3: CLI Backend (codex or gemini)
|
||||
|
||||
```bash
|
||||
Bash(command="ccw cli -p '<execution-prompt>' --tool <codex|gemini> --mode write --cd <working-dir>", run_in_background=true)
|
||||
```
|
||||
|
||||
### Execution Prompt Template
|
||||
|
||||
All backends receive the same structured prompt:
|
||||
|
||||
```
|
||||
# Implementation Task: <task-id>
|
||||
|
||||
## Task Description
|
||||
<task-description>
|
||||
|
||||
## Acceptance Criteria
|
||||
1. <criterion>
|
||||
|
||||
## Context from Plan
|
||||
<architecture-section>
|
||||
<technical-stack-section>
|
||||
<task-context-section>
|
||||
|
||||
## Files to Modify
|
||||
<target-files or "Auto-detect based on task">
|
||||
|
||||
## Constraints
|
||||
- Follow existing code style and patterns
|
||||
- Preserve backward compatibility
|
||||
- Add appropriate error handling
|
||||
- Include inline comments for complex logic
|
||||
```
|
||||
|
||||
### Batch Execution
|
||||
|
||||
When multiple IMPL tasks exist, execute in dependency order:
|
||||
|
||||
```
|
||||
Topological sort by task.depends_on
|
||||
├─ Batch 1: Tasks with no dependencies → execute
|
||||
├─ Batch 2: Tasks depending on batch 1 → execute
|
||||
└─ Batch N: Continue until all tasks complete
|
||||
|
||||
Progress update per batch (when > 1 batch):
|
||||
→ team_msg: "Processing batch <N>/<total>: <task-id>"
|
||||
```
|
||||
|
||||
### Retry and Fallback
|
||||
|
||||
**Retry** (max 3 attempts per task):
|
||||
|
||||
```
|
||||
Attempt 1 → failure
|
||||
├─ team_msg: "Retry 1/3 after error: <message>"
|
||||
└─ Attempt 2 → failure
|
||||
├─ team_msg: "Retry 2/3 after error: <message>"
|
||||
└─ Attempt 3 → failure → fallback
|
||||
|
||||
```
|
||||
|
||||
**Fallback** (when primary backend fails after retries):
|
||||
|
||||
| Primary Backend | Fallback |
|
||||
|----------------|----------|
|
||||
| codex | agent (subagent) |
|
||||
| gemini | agent (subagent) |
|
||||
| agent (subagent) | Report failure to coordinator |
|
||||
| agent (direct edit) | agent (subagent) |
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Self-Validation Steps
|
||||
|
||||
| Step | Method | Pass Criteria |
|
||||
|------|--------|--------------|
|
||||
| Syntax check | `Bash(command="tsc --noEmit", timeout=30000)` | Exit code 0 |
|
||||
| Acceptance match | Check criteria keywords vs modified files | All criteria addressed |
|
||||
| Test detection | Search for .test.ts/.spec.ts matching modified files | Tests identified |
|
||||
| File changes | `Bash(command="git diff --name-only HEAD")` | At least 1 file modified |
|
||||
|
||||
### Result Routing
|
||||
|
||||
| Outcome | Message Type | Content |
|
||||
|---------|-------------|---------|
|
||||
| All tasks pass validation | impl_complete | Task ID, files modified, backend used |
|
||||
| Batch progress | impl_progress | Batch index, total batches, current task |
|
||||
| Validation failure after retries | error | Task ID, error details, retry count |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Syntax errors after implementation | Retry with error context (max 3) |
|
||||
| Backend unavailable | Fallback to agent |
|
||||
| Missing dependencies | Request from coordinator |
|
||||
| All retries + fallback exhausted | Report failure with full error log |
|
||||
@@ -1,103 +0,0 @@
|
||||
# Role: executor
|
||||
|
||||
Code implementation following approved plans. Multi-backend execution with self-validation.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `executor` | **Prefix**: `IMPL-*` | **Tag**: `[executor]`
|
||||
- **Responsibility**: Load plan → Route to backend → Implement → Self-validate → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process IMPL-* tasks
|
||||
- Follow approved plan exactly
|
||||
- Use declared execution backends
|
||||
- Self-validate all implementations
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks
|
||||
- Contact other workers directly
|
||||
- Modify plan files
|
||||
- Skip self-validation
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| impl_complete | → coordinator | Implementation success |
|
||||
| impl_progress | → coordinator | Batch progress |
|
||||
| error | → coordinator | Implementation failure |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/implement.md | Multi-backend implementation |
|
||||
| code-developer agent | Simple tasks (synchronous) |
|
||||
| ccw cli --tool codex --mode write | Complex tasks |
|
||||
| ccw cli --tool gemini --mode write | Alternative backend |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Task & Plan Loading
|
||||
|
||||
**Objective**: Load plan and determine execution strategy.
|
||||
|
||||
1. Load plan.json and .task/TASK-*.json from `<session-folder>/plan/`
|
||||
|
||||
**Backend selection** (priority order):
|
||||
|
||||
| Priority | Source | Method |
|
||||
|----------|--------|--------|
|
||||
| 1 | Task metadata | task.metadata.executor field |
|
||||
| 2 | Plan default | "Execution Backend:" in plan |
|
||||
| 3 | Auto-select | Simple (< 200 chars, no refactor) → agent; Complex → codex |
|
||||
|
||||
**Code review selection**:
|
||||
|
||||
| Priority | Source | Method |
|
||||
|----------|--------|--------|
|
||||
| 1 | Task metadata | task.metadata.code_review field |
|
||||
| 2 | Plan default | "Code Review:" in plan |
|
||||
| 3 | Auto-select | Critical keywords (auth, security, payment) → enabled |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Code Implementation
|
||||
|
||||
**Objective**: Execute implementation across batches.
|
||||
|
||||
**Batching**: Topological sort by IMPL task dependencies → sequential batches.
|
||||
|
||||
Delegate to `commands/implement.md` for prompt building and backend routing:
|
||||
|
||||
| Backend | Invocation | Use Case |
|
||||
|---------|-----------|----------|
|
||||
| agent | Task({ subagent_type: "code-developer", run_in_background: false }) | Simple, direct edits |
|
||||
| codex | ccw cli --tool codex --mode write (background) | Complex, architecture |
|
||||
| gemini | ccw cli --tool gemini --mode write (background) | Analysis-heavy |
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Self-Validation
|
||||
|
||||
| Step | Method | Pass Criteria |
|
||||
|------|--------|--------------|
|
||||
| Syntax check | `tsc --noEmit` (30s) | Exit code 0 |
|
||||
| Acceptance criteria | Match criteria keywords vs implementation | All addressed |
|
||||
| Test detection | Find .test.ts/.spec.ts for modified files | Tests identified |
|
||||
| Code review (optional) | gemini analysis or codex review | No blocking issues |
|
||||
|
||||
**Report**: task ID, status, files modified, validation results, backend used.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Syntax errors | Retry with error context (max 3) |
|
||||
| Missing dependencies | Request from coordinator |
|
||||
| Backend unavailable | Fallback to agent |
|
||||
| Circular dependencies | Abort, report graph |
|
||||
@@ -1,91 +0,0 @@
|
||||
# Role: explorer
|
||||
|
||||
Code search, pattern discovery, dependency tracing. Service role, on-demand.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `explorer` | **Prefix**: `EXPLORE-*` | **Tag**: `[explorer]`
|
||||
- **Type**: Service (on-demand, not on main pipeline)
|
||||
- **Responsibility**: Parse request → Multi-strategy search → Package results
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process EXPLORE-* tasks
|
||||
- Output structured JSON
|
||||
- Cache results in `<session>/explorations/`
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks or modify source code
|
||||
- Execute analysis, planning, or implementation
|
||||
- Make architectural decisions (only discover patterns)
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| explore_ready | → coordinator | Search complete |
|
||||
| task_failed | → coordinator | Search failure |
|
||||
|
||||
## Search Tools (priority order)
|
||||
|
||||
| Tool | Priority | Use Case |
|
||||
|------|----------|----------|
|
||||
| mcp__ace-tool__search_context | P0 | Semantic search |
|
||||
| Grep / Glob | P1 | Pattern matching |
|
||||
| cli-explore-agent | Deep | Multi-angle exploration |
|
||||
| WebSearch | P3 | External docs |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Request Parsing
|
||||
|
||||
Parse from task description:
|
||||
|
||||
| Field | Pattern | Default |
|
||||
|-------|---------|---------|
|
||||
| Session | `Session: <path>` | .workflow/.tmp |
|
||||
| Mode | `Mode: codebase\|external\|hybrid` | codebase |
|
||||
| Angles | `Angles: <list>` | general |
|
||||
| Keywords | `Keywords: <list>` | from subject |
|
||||
| Requester | `Requester: <role>` | coordinator |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Multi-Strategy Search
|
||||
|
||||
Execute strategies in priority order, accumulating findings:
|
||||
|
||||
1. **ACE (P0)**: Per keyword → semantic search → relevant_files
|
||||
2. **Grep (P1)**: Per keyword → class/function/export definitions → relevant_files
|
||||
3. **Dependency trace**: Top 10 files → Read imports → dependencies
|
||||
4. **Deep exploration** (multi-angle): Per angle → cli-explore-agent → merge
|
||||
5. **External (P3)** (external/hybrid mode): Top 3 keywords → WebSearch
|
||||
|
||||
Deduplicate by path.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Package Results
|
||||
|
||||
Write JSON to `<output-dir>/explore-<slug>.json`:
|
||||
- relevant_files[], patterns[], dependencies[], external_refs[], _metadata
|
||||
|
||||
**Report**: file count, pattern count, top files, output path.
|
||||
|
||||
---
|
||||
|
||||
## Coordinator Integration
|
||||
|
||||
| Trigger | Example Task |
|
||||
|---------|-------------|
|
||||
| RESEARCH needs context | EXPLORE-001: 代码库搜索 |
|
||||
| PLAN needs exploration | EXPLORE-002: 实现代码探索 |
|
||||
| DISCUSS needs practices | EXPLORE-003: 外部文档 |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| ACE unavailable | Fallback to Grep |
|
||||
| No results | Report empty, suggest broader keywords |
|
||||
@@ -1,111 +0,0 @@
|
||||
# Role: fe-developer
|
||||
|
||||
Frontend development. Consumes plan/architecture output, implements components, pages, styles.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `fe-developer` | **Prefix**: `DEV-FE-*` | **Tag**: `[fe-developer]`
|
||||
- **Type**: Frontend pipeline worker
|
||||
- **Responsibility**: Context loading → Design token consumption → Component implementation → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process DEV-FE-* tasks
|
||||
- Follow existing design tokens and component specs (if available)
|
||||
- Generate accessible frontend code (semantic HTML, ARIA, keyboard nav)
|
||||
- Follow project's frontend tech stack
|
||||
|
||||
### MUST NOT
|
||||
- Modify backend code or API interfaces
|
||||
- Contact other workers directly
|
||||
- Introduce new frontend dependencies without architecture review
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| dev_fe_complete | → coordinator | Implementation done |
|
||||
| dev_fe_progress | → coordinator | Long task progress |
|
||||
| error | → coordinator | Implementation failure |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| code-developer agent | Component implementation |
|
||||
| ccw cli --tool gemini --mode write | Complex frontend generation |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
**Inputs to load**:
|
||||
- Plan: `<session-folder>/plan/plan.json`
|
||||
- Design tokens: `<session-folder>/architecture/design-tokens.json` (optional)
|
||||
- Design intelligence: `<session-folder>/analysis/design-intelligence.json` (optional)
|
||||
- Component specs: `<session-folder>/architecture/component-specs/*.md` (optional)
|
||||
- Shared memory, wisdom
|
||||
|
||||
**Tech stack detection**:
|
||||
|
||||
| Signal | Framework | Styling |
|
||||
|--------|-----------|---------|
|
||||
| react/react-dom in deps | react | - |
|
||||
| vue in deps | vue | - |
|
||||
| next in deps | nextjs | - |
|
||||
| tailwindcss in deps | - | tailwind |
|
||||
| @shadcn/ui in deps | - | shadcn |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Frontend Implementation
|
||||
|
||||
**Step 1**: Generate design token CSS (if tokens available)
|
||||
- Convert design-tokens.json → CSS custom properties (`:root { --color-*, --space-*, --text-* }`)
|
||||
- Include dark mode overrides via `@media (prefers-color-scheme: dark)`
|
||||
- Write to `src/styles/tokens.css`
|
||||
|
||||
**Step 2**: Implement components
|
||||
|
||||
| Task Size | Strategy |
|
||||
|-----------|----------|
|
||||
| Simple (≤ 3 files, single component) | code-developer agent (synchronous) |
|
||||
| Complex (system, multi-component) | ccw cli --tool gemini --mode write (background) |
|
||||
|
||||
**Coding standards** (include in agent/CLI prompt):
|
||||
- Use design token CSS variables, never hardcode colors/spacing
|
||||
- Interactive elements: cursor: pointer
|
||||
- Transitions: 150-300ms
|
||||
- Text contrast: minimum 4.5:1
|
||||
- Include focus-visible styles
|
||||
- Support prefers-reduced-motion
|
||||
- Responsive: mobile-first
|
||||
- No emoji as functional icons
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Self-Validation
|
||||
|
||||
| Check | What |
|
||||
|-------|------|
|
||||
| hardcoded-color | No #hex outside tokens.css |
|
||||
| cursor-pointer | Interactive elements have cursor: pointer |
|
||||
| focus-styles | Interactive elements have focus styles |
|
||||
| responsive | Has responsive breakpoints |
|
||||
| reduced-motion | Animations respect prefers-reduced-motion |
|
||||
| emoji-icon | No emoji as functional icons |
|
||||
|
||||
Contribute to wisdom/conventions.md. Update shared-memory.json with component inventory.
|
||||
|
||||
**Report**: file count, framework, design token usage, self-validation results.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Design tokens not found | Use project defaults |
|
||||
| Tech stack undetected | Default HTML + CSS |
|
||||
| Subagent failure | Fallback to CLI write mode |
|
||||
@@ -1,152 +0,0 @@
|
||||
# Command: pre-delivery-checklist
|
||||
|
||||
## Purpose
|
||||
|
||||
CSS-level pre-delivery checks for frontend files. Validates accessibility, interaction, design compliance, and layout patterns before final delivery.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Changed frontend files | git diff --name-only (filtered to .tsx, .jsx, .css, .scss) | Yes |
|
||||
| File contents | Read each changed file | Yes |
|
||||
| Design tokens path | `src/styles/tokens.css` or equivalent | No |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
|
||||
## Phase 3: Checklist Execution
|
||||
|
||||
### Category 1: Accessibility (6 items)
|
||||
|
||||
| # | Check | Pattern to Detect | Severity |
|
||||
|---|-------|--------------------|----------|
|
||||
| 1 | Images have alt text | `<img` without `alt=` | CRITICAL |
|
||||
| 2 | Form inputs have labels | `<input` without `<label` or `aria-label` | HIGH |
|
||||
| 3 | Focus states visible | Interactive elements without `:focus` styles | HIGH |
|
||||
| 4 | Color contrast 4.5:1 | Light text on light background patterns | HIGH |
|
||||
| 5 | prefers-reduced-motion | Animations without `@media (prefers-reduced-motion)` | MEDIUM |
|
||||
| 6 | Heading hierarchy | Skipped heading levels (h1 followed by h3) | MEDIUM |
|
||||
|
||||
**Do / Don't**:
|
||||
|
||||
| # | Do | Don't |
|
||||
|---|-----|-------|
|
||||
| 1 | Always provide descriptive alt text | Leave alt empty without `role="presentation"` |
|
||||
| 2 | Associate every input with a label | Use placeholder as sole label |
|
||||
| 3 | Add `focus-visible` outline | Remove default focus ring without replacement |
|
||||
| 4 | Ensure 4.5:1 minimum contrast ratio | Use low-contrast decorative text for content |
|
||||
| 5 | Wrap in `@media (prefers-reduced-motion: no-preference)` | Force animations on all users |
|
||||
| 6 | Use sequential heading levels | Skip levels for visual sizing |
|
||||
|
||||
---
|
||||
|
||||
### Category 2: Interaction (4 items)
|
||||
|
||||
| # | Check | Pattern to Detect | Severity |
|
||||
|---|-------|--------------------|----------|
|
||||
| 7 | cursor-pointer on clickable | Buttons/links without `cursor: pointer` | MEDIUM |
|
||||
| 8 | Transitions 150-300ms | Duration outside 150-300ms range | LOW |
|
||||
| 9 | Loading states | Async operations without loading indicator | MEDIUM |
|
||||
| 10 | Error states | Async operations without error handling UI | HIGH |
|
||||
|
||||
**Do / Don't**:
|
||||
|
||||
| # | Do | Don't |
|
||||
|---|-----|-------|
|
||||
| 7 | Add `cursor: pointer` to all clickable elements | Leave default cursor on buttons |
|
||||
| 8 | Use 150-300ms for micro-interactions | Use >500ms or <100ms transitions |
|
||||
| 9 | Show skeleton/spinner during fetch | Leave blank screen while loading |
|
||||
| 10 | Show user-friendly error message | Silently fail or show raw error |
|
||||
|
||||
---
|
||||
|
||||
### Category 3: Design Compliance (4 items)
|
||||
|
||||
| # | Check | Pattern to Detect | Severity |
|
||||
|---|-------|--------------------|----------|
|
||||
| 11 | No hardcoded colors | Hex values (`#XXXXXX`) outside tokens file | HIGH |
|
||||
| 12 | No hardcoded spacing | Raw `px` values for margin/padding | MEDIUM |
|
||||
| 13 | No emoji as icons | Unicode emoji (U+1F300-1F9FF) in UI code | HIGH |
|
||||
| 14 | Dark mode support | No `prefers-color-scheme` or `.dark` class | MEDIUM |
|
||||
|
||||
**Do / Don't**:
|
||||
|
||||
| # | Do | Don't |
|
||||
|---|-----|-------|
|
||||
| 11 | Use `var(--color-*)` design tokens | Hardcode `#hex` values |
|
||||
| 12 | Use `var(--space-*)` spacing tokens | Hardcode pixel values |
|
||||
| 13 | Use proper SVG/icon library | Use emoji for functional icons |
|
||||
| 14 | Support light/dark themes | Design for light mode only |
|
||||
|
||||
---
|
||||
|
||||
### Category 4: Layout (2 items)
|
||||
|
||||
| # | Check | Pattern to Detect | Severity |
|
||||
|---|-------|--------------------|----------|
|
||||
| 15 | Responsive breakpoints | No `md:`/`lg:`/`@media` queries | MEDIUM |
|
||||
| 16 | No horizontal scroll | Fixed widths greater than viewport | HIGH |
|
||||
|
||||
**Do / Don't**:
|
||||
|
||||
| # | Do | Don't |
|
||||
|---|-----|-------|
|
||||
| 15 | Mobile-first responsive design | Desktop-only layout |
|
||||
| 16 | Use relative/fluid widths | Set fixed pixel widths on containers |
|
||||
|
||||
---
|
||||
|
||||
### Check Execution Strategy
|
||||
|
||||
| Check Scope | Applies To | Method |
|
||||
|-------------|-----------|--------|
|
||||
| Per-file checks | Items 1-4, 7-8, 10-13, 16 | Run against each changed file individually |
|
||||
| Global checks | Items 5-6, 9, 14-15 | Run against concatenated content of all files |
|
||||
|
||||
**Detection example** (check for hardcoded colors):
|
||||
|
||||
```bash
|
||||
Grep(pattern="#[0-9a-fA-F]{6}", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
**Detection example** (check for missing alt text):
|
||||
|
||||
```bash
|
||||
Grep(pattern="<img\\s(?![^>]*alt=)", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Pass/Fail Criteria
|
||||
|
||||
| Condition | Result |
|
||||
|-----------|--------|
|
||||
| Zero CRITICAL + zero HIGH failures | PASS |
|
||||
| Zero CRITICAL, some HIGH | CONDITIONAL (list fixes needed) |
|
||||
| Any CRITICAL failure | FAIL |
|
||||
|
||||
### Output Format
|
||||
|
||||
```
|
||||
## Pre-Delivery Checklist Results
|
||||
|
||||
- Total checks: <n>
|
||||
- Passed: <n> / <total>
|
||||
- Failed: <n>
|
||||
|
||||
### Failed Items
|
||||
- [CRITICAL] #1 Images have alt text -- <file_path>
|
||||
- [HIGH] #11 No hardcoded colors -- <file_path>:<line>
|
||||
- [MEDIUM] #7 cursor-pointer on clickable -- <file_path>
|
||||
|
||||
### Recommendations
|
||||
(Do/Don't guidance for each failed item)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No frontend files to check | Report empty checklist, all checks N/A |
|
||||
| File read error | Skip file, note in report |
|
||||
| Regex match error | Skip check, note in report |
|
||||
| Design tokens file not found | Skip items 11-12, adjust total |
|
||||
@@ -1,113 +0,0 @@
|
||||
# Role: fe-qa
|
||||
|
||||
Frontend quality assurance. 5-dimension review + Generator-Critic loop.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `fe-qa` | **Prefix**: `QA-FE-*` | **Tag**: `[fe-qa]`
|
||||
- **Type**: Frontend pipeline worker
|
||||
- **Responsibility**: Context loading → 5-dimension review → GC feedback → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process QA-FE-* tasks
|
||||
- Execute 5-dimension review
|
||||
- Support Generator-Critic loop (max 2 rounds)
|
||||
- Provide actionable fix suggestions (Do/Don't format)
|
||||
|
||||
### MUST NOT
|
||||
- Modify source code directly (review only)
|
||||
- Contact other workers directly
|
||||
- Mark pass when score below threshold
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| qa_fe_passed | → coordinator | All dimensions pass |
|
||||
| qa_fe_result | → coordinator | Review complete (may have issues) |
|
||||
| fix_required | → coordinator | Critical issues found |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/pre-delivery-checklist.md | CSS-level delivery checks |
|
||||
| ccw cli --tool gemini --mode analysis | Frontend code review |
|
||||
| ccw cli --tool codex --mode review | Git-aware code review |
|
||||
|
||||
---
|
||||
|
||||
## Review Dimensions
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Code Quality | 25% | TypeScript types, component structure, error handling |
|
||||
| Accessibility | 25% | Semantic HTML, ARIA, keyboard nav, contrast, focus-visible |
|
||||
| Design Compliance | 20% | Token usage, no hardcoded colors, no emoji icons |
|
||||
| UX Best Practices | 15% | Loading/error/empty states, cursor-pointer, responsive |
|
||||
| Pre-Delivery | 15% | No console.log, dark mode, i18n readiness |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
**Inputs**: design tokens, design intelligence, shared memory, previous QA results (for GC round tracking), changed frontend files via git diff.
|
||||
|
||||
Determine GC round from previous QA results count. Max 2 rounds.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: 5-Dimension Review
|
||||
|
||||
For each changed frontend file, check against all 5 dimensions. Score each dimension 0-10, deducting for issues found.
|
||||
|
||||
**Scoring deductions**:
|
||||
|
||||
| Severity | Deduction |
|
||||
|----------|-----------|
|
||||
| High | -2 to -3 |
|
||||
| Medium | -1 to -1.5 |
|
||||
| Low | -0.5 |
|
||||
|
||||
**Overall score** = weighted sum of dimension scores.
|
||||
|
||||
**Verdict routing**:
|
||||
|
||||
| Condition | Verdict |
|
||||
|-----------|---------|
|
||||
| Score ≥ 8 AND no critical issues | PASS |
|
||||
| GC round ≥ max AND score ≥ 6 | PASS_WITH_WARNINGS |
|
||||
| GC round ≥ max AND score < 6 | FAIL |
|
||||
| Otherwise | NEEDS_FIX |
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Report
|
||||
|
||||
Write audit to `<session-folder>/qa/audit-fe-<task>-r<round>.json`. Update wisdom and shared memory.
|
||||
|
||||
**Report**: round, verdict, overall score, dimension scores, critical issues with Do/Don't format, action required (if NEEDS_FIX).
|
||||
|
||||
---
|
||||
|
||||
## Generator-Critic Loop
|
||||
|
||||
Orchestrated by coordinator:
|
||||
```
|
||||
Round 1: DEV-FE-001 → QA-FE-001
|
||||
if NEEDS_FIX → coordinator creates DEV-FE-002 + QA-FE-002
|
||||
Round 2: DEV-FE-002 → QA-FE-002
|
||||
if still NEEDS_FIX → PASS_WITH_WARNINGS or FAIL (max 2)
|
||||
```
|
||||
|
||||
**Convergence**: score ≥ 8 AND critical_count = 0
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No changed files | Report empty, score N/A |
|
||||
| Design tokens not found | Skip design compliance, adjust weights |
|
||||
| Max GC rounds exceeded | Force verdict |
|
||||
@@ -1,154 +0,0 @@
|
||||
# Command: explore
|
||||
|
||||
## Purpose
|
||||
|
||||
Complexity-driven codebase exploration: assess task complexity, select exploration angles by category, execute parallel exploration agents, and produce structured exploration results for plan generation.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | PLAN-* task subject/description | Yes |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Spec context | `<session-folder>/spec/` (if exists) | No |
|
||||
| Plan directory | `<session-folder>/plan/` | Yes (create if missing) |
|
||||
| Project tech | `.workflow/project-tech.json` | No |
|
||||
|
||||
## Phase 3: Exploration
|
||||
|
||||
### Complexity Assessment
|
||||
|
||||
Score the task description against keyword indicators:
|
||||
|
||||
| Indicator | Keywords | Score |
|
||||
|-----------|----------|-------|
|
||||
| Structural change | refactor, architect, restructure, modular | +2 |
|
||||
| Multi-scope | multiple, across, cross-cutting | +2 |
|
||||
| Integration | integrate, api, database | +1 |
|
||||
| Non-functional | security, performance, auth | +1 |
|
||||
|
||||
**Complexity routing**:
|
||||
|
||||
| Score | Level | Strategy | Angle Count |
|
||||
|-------|-------|----------|-------------|
|
||||
| 0-1 | Low | ACE semantic search only | 1 |
|
||||
| 2-3 | Medium | cli-explore-agent per angle | 2-3 |
|
||||
| 4+ | High | cli-explore-agent per angle | 3-5 |
|
||||
|
||||
### Angle Presets
|
||||
|
||||
Select preset by dominant keyword match, then take first N angles per complexity:
|
||||
|
||||
| Preset | Trigger Keywords | Angles (priority order) |
|
||||
|--------|-----------------|------------------------|
|
||||
| architecture | refactor, architect, restructure, modular | architecture, dependencies, modularity, integration-points |
|
||||
| security | security, auth, permission, access | security, auth-patterns, dataflow, validation |
|
||||
| performance | performance, slow, optimize, cache | performance, bottlenecks, caching, data-access |
|
||||
| bugfix | fix, bug, error, issue, broken | error-handling, dataflow, state-management, edge-cases |
|
||||
| feature | (default) | patterns, integration-points, testing, dependencies |
|
||||
|
||||
### Low Complexity: Direct Search
|
||||
|
||||
```bash
|
||||
mcp__ace-tool__search_context(project_root_path="<project-root>", query="<task-description>")
|
||||
```
|
||||
|
||||
Transform results into exploration JSON and write to `<plan-dir>/exploration-<angle>.json`.
|
||||
|
||||
**ACE failure fallback**:
|
||||
|
||||
```bash
|
||||
Bash(command="rg -l '<keywords>' --type ts", timeout=30000)
|
||||
```
|
||||
|
||||
### Medium/High Complexity: Parallel Exploration
|
||||
|
||||
For each selected angle, launch an exploration agent:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: "Explore: <angle>",
|
||||
prompt: "## Task Objective
|
||||
Execute <angle> exploration for task planning context.
|
||||
|
||||
## Output Location
|
||||
Output File: <plan-dir>/exploration-<angle>.json
|
||||
|
||||
## Assigned Context
|
||||
- Exploration Angle: <angle>
|
||||
- Task Description: <task-description>
|
||||
- Spec Context: <available|not available>
|
||||
|
||||
## Mandatory First Steps
|
||||
1. rg -l '<relevant-keyword>' --type ts
|
||||
2. cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json
|
||||
3. Read .workflow/project-tech.json (if exists)
|
||||
|
||||
## Exploration Focus
|
||||
<angle-focus-from-table-below>
|
||||
|
||||
## Output
|
||||
Write JSON to: <plan-dir>/exploration-<angle>.json
|
||||
Each file in relevant_files MUST have: rationale (>10 chars), role, discovery_source, key_symbols"
|
||||
})
|
||||
```
|
||||
|
||||
### Angle Focus Guide
|
||||
|
||||
| Angle | Focus Points |
|
||||
|-------|-------------|
|
||||
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs |
|
||||
| dependencies | Import chains, external libraries, circular dependencies, shared utilities |
|
||||
| modularity | Module interfaces, separation of concerns, extraction opportunities |
|
||||
| integration-points | API endpoints, data flow between modules, event systems, service integrations |
|
||||
| security | Auth/authz logic, input validation, sensitive data handling, middleware |
|
||||
| auth-patterns | Auth flows (login/refresh), session management, token validation, permissions |
|
||||
| dataflow | Data transformations, state propagation, validation points, mutation paths |
|
||||
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity |
|
||||
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging |
|
||||
| patterns | Code conventions, design patterns, naming conventions, best practices |
|
||||
| testing | Test files, coverage gaps, test patterns (unit/integration/e2e), mocking |
|
||||
|
||||
### Explorations Manifest
|
||||
|
||||
After all explorations complete, write manifest to `<plan-dir>/explorations-manifest.json`:
|
||||
|
||||
```
|
||||
{
|
||||
"task_description": "<description>",
|
||||
"complexity": "<Low|Medium|High>",
|
||||
"exploration_count": <N>,
|
||||
"explorations": [
|
||||
{ "angle": "<angle>", "file": "exploration-<angle>.json" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Output Files
|
||||
|
||||
```
|
||||
<session-folder>/plan/
|
||||
├─ exploration-<angle>.json (per angle)
|
||||
└─ explorations-manifest.json (summary)
|
||||
```
|
||||
|
||||
### Success Criteria
|
||||
|
||||
| Check | Criteria | Required |
|
||||
|-------|----------|----------|
|
||||
| At least 1 exploration | Non-empty exploration file exists | Yes |
|
||||
| Manifest written | explorations-manifest.json exists | Yes |
|
||||
| File roles assigned | Every relevant_file has role + rationale | Yes |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Single exploration agent fails | Skip angle, remove from manifest, continue |
|
||||
| All explorations fail | Proceed to plan generation with task description only |
|
||||
| ACE search fails (Low) | Fallback to ripgrep keyword search |
|
||||
| Schema file not found | Use inline schema from Output section |
|
||||
@@ -1,120 +0,0 @@
|
||||
# Role: planner
|
||||
|
||||
Multi-angle code exploration and structured implementation planning. Submits plans to coordinator for approval.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `planner` | **Prefix**: `PLAN-*` | **Tag**: `[planner]`
|
||||
- **Responsibility**: Complexity assessment → Code exploration → Plan generation → Approval
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process PLAN-* tasks
|
||||
- Assess complexity before planning
|
||||
- Execute multi-angle exploration for Medium/High complexity
|
||||
- Generate plan.json + .task/TASK-*.json
|
||||
- Load spec context in full-lifecycle mode
|
||||
- Submit plan for coordinator approval
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks for other roles
|
||||
- Implement code
|
||||
- Modify spec documents
|
||||
- Skip complexity assessment
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| plan_ready | → coordinator | Plan complete |
|
||||
| plan_revision | → coordinator | Plan revised per feedback |
|
||||
| error | → coordinator | Exploration or planning failure |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/explore.md | Multi-angle codebase exploration |
|
||||
| cli-explore-agent | Per-angle exploration |
|
||||
| cli-lite-planning-agent | Plan generation |
|
||||
|
||||
---
|
||||
|
||||
## Phase 1.5: Load Spec Context (Full-Lifecycle)
|
||||
|
||||
If `<session-folder>/spec/` exists → load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise → impl-only mode.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Multi-Angle Exploration
|
||||
|
||||
**Objective**: Explore codebase to inform planning.
|
||||
|
||||
**Complexity routing**:
|
||||
|
||||
| Complexity | Criteria | Strategy |
|
||||
|------------|----------|----------|
|
||||
| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only |
|
||||
| Medium | 200-500 chars or moderate scope | 2-3 angle cli-explore-agent |
|
||||
| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle cli-explore-agent |
|
||||
|
||||
Delegate to `commands/explore.md` for angle selection and parallel execution.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Plan Generation
|
||||
|
||||
**Objective**: Generate structured implementation plan.
|
||||
|
||||
| Complexity | Strategy |
|
||||
|------------|----------|
|
||||
| Low | Direct planning → single TASK-001 with plan.json |
|
||||
| Medium/High | cli-lite-planning-agent with exploration results |
|
||||
|
||||
**Agent call** (Medium/High):
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "cli-lite-planning-agent",
|
||||
run_in_background: false,
|
||||
description: "Generate implementation plan",
|
||||
prompt: "Generate plan.
|
||||
Output: <plan-dir>/plan.json + <plan-dir>/.task/TASK-*.json
|
||||
Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
|
||||
Task: <task-description>
|
||||
Explorations: <explorations-manifest>
|
||||
Complexity: <complexity>
|
||||
Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, depends_on"
|
||||
})
|
||||
```
|
||||
|
||||
**Spec context** (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Submit for Approval
|
||||
|
||||
1. Read plan.json and TASK-*.json
|
||||
2. Report to coordinator: complexity, task count, task list, approach, plan location
|
||||
3. Wait for response: approved → complete; revision → update and resubmit
|
||||
|
||||
**Session files**:
|
||||
```
|
||||
<session-folder>/plan/
|
||||
├── exploration-<angle>.json
|
||||
├── explorations-manifest.json
|
||||
├── plan.json
|
||||
└── .task/TASK-*.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Exploration agent failure | Plan from description only |
|
||||
| Planning agent failure | Fallback to direct planning |
|
||||
| Plan rejected 3+ times | Notify coordinator, suggest alternative |
|
||||
| Schema not found | Use basic structure |
|
||||
@@ -1,163 +0,0 @@
|
||||
# Command: code-review
|
||||
|
||||
## Purpose
|
||||
|
||||
4-dimension code review analyzing quality, security, architecture, and requirements compliance. Produces a verdict (BLOCK/CONDITIONAL/APPROVE) with categorized findings.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Plan file | `<session_folder>/plan/plan.json` | Yes |
|
||||
| Git diff | `git diff HEAD~1` or `git diff --cached` | Yes |
|
||||
| Modified files | From git diff --name-only | Yes |
|
||||
| Test results | Tester output (if available) | No |
|
||||
| Wisdom | `<session_folder>/wisdom/` | No |
|
||||
|
||||
## Phase 3: 4-Dimension Review
|
||||
|
||||
### Dimension Overview
|
||||
|
||||
| Dimension | Focus | Weight |
|
||||
|-----------|-------|--------|
|
||||
| Quality | Code correctness, type safety, clean code | Equal |
|
||||
| Security | Vulnerability patterns, secret exposure | Equal |
|
||||
| Architecture | Module structure, coupling, file size | Equal |
|
||||
| Requirements | Acceptance criteria coverage, completeness | Equal |
|
||||
|
||||
---
|
||||
|
||||
### Dimension 1: Quality
|
||||
|
||||
Scan each modified file for quality anti-patterns.
|
||||
|
||||
| Severity | Pattern | What to Detect |
|
||||
|----------|---------|----------------|
|
||||
| Critical | Empty catch blocks | `catch(e) {}` with no handling |
|
||||
| High | @ts-ignore without justification | Suppression comment < 10 chars explanation |
|
||||
| High | `any` type in public APIs | `any` outside comments and generic definitions |
|
||||
| High | console.log in production | `console.(log\|debug\|info)` outside test files |
|
||||
| Medium | Magic numbers | Numeric literals > 1 digit, not in const/comment |
|
||||
| Medium | Duplicate code | Identical lines (>30 chars) appearing 3+ times |
|
||||
|
||||
**Detection example** (Grep for console statements):
|
||||
|
||||
```bash
|
||||
Grep(pattern="console\\.(log|debug|info)", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Dimension 2: Security
|
||||
|
||||
Scan for vulnerability patterns across all modified files.
|
||||
|
||||
| Severity | Pattern | What to Detect |
|
||||
|----------|---------|----------------|
|
||||
| Critical | Hardcoded secrets | `api_key=`, `password=`, `secret=`, `token=` with string values (20+ chars) |
|
||||
| Critical | SQL injection | String concatenation in `query()`/`execute()` calls |
|
||||
| High | eval/exec usage | `eval()`, `new Function()`, `setTimeout(string)` |
|
||||
| High | XSS vectors | `innerHTML`, `dangerouslySetInnerHTML` |
|
||||
| Medium | Insecure random | `Math.random()` in security context (token/key/password/session) |
|
||||
| Low | Missing input validation | Functions with parameters but no validation in first 5 lines |
|
||||
|
||||
---
|
||||
|
||||
### Dimension 3: Architecture
|
||||
|
||||
Assess structural health of modified files.
|
||||
|
||||
| Severity | Pattern | What to Detect |
|
||||
|----------|---------|----------------|
|
||||
| Critical | Circular dependencies | File A imports B, B imports A |
|
||||
| High | Excessive parent imports | Import traverses >2 parent directories (`../../../`) |
|
||||
| Medium | Large files | Files exceeding 500 lines |
|
||||
| Medium | Tight coupling | >5 imports from same base module |
|
||||
| Medium | Long functions | Functions exceeding 50 lines |
|
||||
| Medium | Module boundary changes | Modifications to index.ts/index.js files |
|
||||
|
||||
**Detection example** (check for deep parent imports):
|
||||
|
||||
```bash
|
||||
Grep(pattern="from\\s+['\"](\\.\\./){3,}", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Dimension 4: Requirements
|
||||
|
||||
Verify implementation against plan acceptance criteria.
|
||||
|
||||
| Severity | Check | Method |
|
||||
|----------|-------|--------|
|
||||
| High | Unmet acceptance criteria | Extract criteria from plan, check keyword overlap (threshold: 70%) |
|
||||
| High | Missing error handling | Plan mentions "error handling" but no try/catch in code |
|
||||
| Medium | Partially met criteria | Keyword overlap 40-69% |
|
||||
| Medium | Missing tests | Plan mentions "test" but no test files in modified set |
|
||||
|
||||
**Verification flow**:
|
||||
1. Read plan file → extract acceptance criteria section
|
||||
2. For each criterion → extract keywords (4+ char meaningful words)
|
||||
3. Search modified files for keyword matches
|
||||
4. Score: >= 70% match = met, 40-69% = partial, < 40% = unmet
|
||||
|
||||
---
|
||||
|
||||
### Verdict Routing
|
||||
|
||||
| Verdict | Criteria | Action |
|
||||
|---------|----------|--------|
|
||||
| BLOCK | Any critical-severity issues found | Must fix before merge |
|
||||
| CONDITIONAL | High or medium issues, no critical | Should address, can merge with tracking |
|
||||
| APPROVE | Only low issues or none | Ready to merge |
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Report Format
|
||||
|
||||
The review report follows this structure:
|
||||
|
||||
```
|
||||
# Code Review Report
|
||||
|
||||
**Verdict**: <BLOCK|CONDITIONAL|APPROVE>
|
||||
|
||||
## Blocking Issues (if BLOCK)
|
||||
- **<type>** (<file>:<line>): <message>
|
||||
|
||||
## Review Dimensions
|
||||
|
||||
### Quality Issues
|
||||
**CRITICAL** (<count>)
|
||||
- <message> (<file>:<line>)
|
||||
|
||||
### Security Issues
|
||||
(same format per severity)
|
||||
|
||||
### Architecture Issues
|
||||
(same format per severity)
|
||||
|
||||
### Requirements Issues
|
||||
(same format per severity)
|
||||
|
||||
## Recommendations
|
||||
1. <actionable recommendation>
|
||||
```
|
||||
|
||||
### Summary Counts
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Total issues | Sum across all dimensions and severities |
|
||||
| Critical count | Must be 0 for APPROVE |
|
||||
| Blocking issues | Listed explicitly in report header |
|
||||
| Dimensions covered | Must be 4/4 |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Plan file not found | Skip requirements dimension, note in report |
|
||||
| Git diff empty | Report no changes to review |
|
||||
| File read fails | Skip file, note in report |
|
||||
| No modified files | Report empty review |
|
||||
@@ -1,202 +0,0 @@
|
||||
# Command: spec-quality
|
||||
|
||||
## Purpose
|
||||
|
||||
5-dimension spec quality check with weighted scoring, quality gate determination, and readiness report generation.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Spec documents | `<session_folder>/spec/` (all .md files) | Yes |
|
||||
| Original requirements | Product brief objectives section | Yes |
|
||||
| Quality gate config | specs/quality-gates.md | No |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
|
||||
**Spec document phases** (matched by filename/directory):
|
||||
|
||||
| Phase | Expected Path | Required |
|
||||
|-------|--------------|---------|
|
||||
| product-brief | spec/product-brief.md | Yes |
|
||||
| prd | spec/requirements/*.md | Yes |
|
||||
| architecture | spec/architecture/_index.md + ADR-*.md | Yes |
|
||||
| user-stories | spec/epics/*.md | Yes |
|
||||
| implementation-plan | plan/plan.json | No (impl-only/full-lifecycle) |
|
||||
| test-strategy | spec/test-strategy.md | No (optional, not generated by pipeline) |
|
||||
|
||||
## Phase 3: 5-Dimension Scoring
|
||||
|
||||
### Dimension Weights
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Completeness | 25% | All required sections present with substance |
|
||||
| Consistency | 20% | Terminology, format, references, naming |
|
||||
| Traceability | 25% | Goals -> Reqs -> Components -> Stories chain |
|
||||
| Depth | 20% | AC testable, ADRs justified, stories estimable |
|
||||
| Coverage | 10% | Original requirements mapped to spec |
|
||||
|
||||
---
|
||||
|
||||
### Dimension 1: Completeness (25%)
|
||||
|
||||
Check each spec document for required sections.
|
||||
|
||||
**Required sections by phase**:
|
||||
|
||||
| Phase | Required Sections |
|
||||
|-------|------------------|
|
||||
| product-brief | Vision Statement, Problem Statement, Target Audience, Success Metrics, Constraints |
|
||||
| prd | Goals, Requirements, User Stories, Acceptance Criteria, Non-Functional Requirements |
|
||||
| architecture | System Overview, Component Design, Data Models, API Specifications, Technology Stack |
|
||||
| user-stories | Story List, Acceptance Criteria, Priority, Estimation |
|
||||
| implementation-plan | Task Breakdown, Dependencies, Timeline, Resource Allocation |
|
||||
|
||||
> **Note**: `test-strategy` is optional — skip scoring if `spec/test-strategy.md` is absent. Do not penalize completeness score for missing optional phases.
|
||||
|
||||
**Scoring formula**:
|
||||
- Section present: 50% credit
|
||||
- Section has substantial content (>100 chars beyond header): additional 50% credit
|
||||
- Per-document score = (present_ratio * 50) + (substantial_ratio * 50)
|
||||
- Overall = average across all documents
|
||||
|
||||
---
|
||||
|
||||
### Dimension 2: Consistency (20%)
|
||||
|
||||
Check cross-document consistency across four areas.
|
||||
|
||||
| Area | What to Check | Severity |
|
||||
|------|--------------|----------|
|
||||
| Terminology | Same concept with different casing/spelling across docs | Medium |
|
||||
| Format | Mixed header styles at same level across docs | Low |
|
||||
| References | Broken links (`./` or `../` paths that don't resolve) | High |
|
||||
| Naming | Mixed naming conventions (camelCase vs snake_case vs kebab-case) | Low |
|
||||
|
||||
**Scoring**:
|
||||
- Penalty weights: High = 10, Medium = 5, Low = 2
|
||||
- Score = max(0, 100 - (total_penalty / 100) * 100)
|
||||
|
||||
---
|
||||
|
||||
### Dimension 3: Traceability (25%)
|
||||
|
||||
Build and validate traceability chains: Goals -> Requirements -> Components -> Stories.
|
||||
|
||||
**Chain building flow**:
|
||||
1. Extract goals from product-brief (pattern: `- Goal: <text>`)
|
||||
2. Extract requirements from PRD (pattern: `- REQ-NNN: <text>`)
|
||||
3. Extract components from architecture (pattern: `- Component: <text>`)
|
||||
4. Extract stories from user-stories (pattern: `- US-NNN: <text>`)
|
||||
5. Link by keyword overlap (threshold: 30% keyword match)
|
||||
|
||||
**Chain completeness**: A chain is complete when a goal links to at least one requirement, one component, and one story.
|
||||
|
||||
**Scoring**: (complete chains / total chains) * 100
|
||||
|
||||
**Weak link identification**: For each incomplete chain, report which link is missing (no requirements, no components, or no stories).
|
||||
|
||||
---
|
||||
|
||||
### Dimension 4: Depth (20%)
|
||||
|
||||
Assess the analytical depth of spec content across four sub-dimensions.
|
||||
|
||||
| Sub-dimension | Source | Testable Criteria |
|
||||
|---------------|--------|-------------------|
|
||||
| AC Testability | PRD / User Stories | Contains measurable verbs (display, return, validate) or Given/When/Then or numbers |
|
||||
| ADR Justification | Architecture | Contains rationale, alternatives, consequences, or trade-offs |
|
||||
| Story Estimability | User Stories | Has "As a/I want/So that" + AC, or explicit estimate |
|
||||
| Technical Detail | Architecture + Plan | Contains code blocks, API terms, HTTP methods, DB terms |
|
||||
|
||||
**Scoring**: Average of sub-dimension scores (each 0-100%)
|
||||
|
||||
---
|
||||
|
||||
### Dimension 5: Coverage (10%)
|
||||
|
||||
Map original requirements to spec requirements.
|
||||
|
||||
**Flow**:
|
||||
1. Extract original requirements from product-brief objectives section
|
||||
2. Extract spec requirements from all documents (pattern: `- REQ-NNN:` or `- Requirement:` or `- Feature:`)
|
||||
3. For each original requirement, check keyword overlap with any spec requirement (threshold: 40%)
|
||||
4. Score = (covered_count / total_original) * 100
|
||||
|
||||
---
|
||||
|
||||
### Quality Gate Decision Table
|
||||
|
||||
| Gate | Criteria | Message |
|
||||
|------|----------|---------|
|
||||
| PASS | Overall score >= 80% AND coverage >= 70% | Ready for implementation |
|
||||
| FAIL | Overall score < 60% OR coverage < 50% | Major revisions required |
|
||||
| REVIEW | All other cases | Improvements needed, may proceed with caution |
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Readiness Report Format
|
||||
|
||||
Write to `<session_folder>/spec/readiness-report.md`:
|
||||
|
||||
```
|
||||
# Specification Readiness Report
|
||||
|
||||
**Generated**: <timestamp>
|
||||
**Overall Score**: <score>%
|
||||
**Quality Gate**: <PASS|REVIEW|FAIL> - <message>
|
||||
**Recommended Action**: <action>
|
||||
|
||||
## Dimension Scores
|
||||
|
||||
| Dimension | Score | Weight | Weighted Score |
|
||||
|-----------|-------|--------|----------------|
|
||||
| Completeness | <n>% | 25% | <n>% |
|
||||
| Consistency | <n>% | 20% | <n>% |
|
||||
| Traceability | <n>% | 25% | <n>% |
|
||||
| Depth | <n>% | 20% | <n>% |
|
||||
| Coverage | <n>% | 10% | <n>% |
|
||||
|
||||
## Completeness Analysis
|
||||
(per-phase breakdown: sections present/expected, missing sections)
|
||||
|
||||
## Consistency Analysis
|
||||
(issues by area: terminology, format, references, naming)
|
||||
|
||||
## Traceability Analysis
|
||||
(complete chains / total, weak links)
|
||||
|
||||
## Depth Analysis
|
||||
(per sub-dimension scores)
|
||||
|
||||
## Requirement Coverage
|
||||
(covered / total, uncovered requirements list)
|
||||
```
|
||||
|
||||
### Spec Summary Format
|
||||
|
||||
Write to `<session_folder>/spec/spec-summary.md`:
|
||||
|
||||
```
|
||||
# Specification Summary
|
||||
|
||||
**Overall Quality Score**: <score>%
|
||||
**Quality Gate**: <gate>
|
||||
|
||||
## Documents Reviewed
|
||||
(per document: phase, path, size, section list)
|
||||
|
||||
## Key Findings
|
||||
### Strengths (dimensions scoring >= 80%)
|
||||
### Areas for Improvement (dimensions scoring < 70%)
|
||||
### Recommendations
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Spec folder empty | FAIL gate, report no documents found |
|
||||
| Missing phase document | Score 0 for that phase in completeness, note in report |
|
||||
| No original requirements found | Score coverage at 100% (nothing to cover) |
|
||||
| Broken references | Flag in consistency, do not fail entire review |
|
||||
@@ -1,104 +0,0 @@
|
||||
# Role: reviewer
|
||||
|
||||
Dual-mode review: code review (REVIEW-*) and spec quality validation (QUALITY-*). Auto-switches by task prefix.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `reviewer` | **Prefix**: `REVIEW-*` + `QUALITY-*` | **Tag**: `[reviewer]`
|
||||
- **Responsibility**: Branch by Prefix → Review/Score → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Process REVIEW-* and QUALITY-* tasks
|
||||
- Generate readiness-report.md for QUALITY tasks
|
||||
- Cover all required dimensions per mode
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks
|
||||
- Modify source code
|
||||
- Skip quality dimensions
|
||||
- Approve without verification
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| review_result | → coordinator | Code review complete |
|
||||
| quality_result | → coordinator | Spec quality complete |
|
||||
| fix_required | → coordinator | Critical issues found |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/code-review.md | 4-dimension code review |
|
||||
| commands/spec-quality.md | 5-dimension spec quality |
|
||||
|
||||
---
|
||||
|
||||
## Mode Detection
|
||||
|
||||
| Task Prefix | Mode | Dimensions |
|
||||
|-------------|------|-----------|
|
||||
| REVIEW-* | Code Review | quality, security, architecture, requirements |
|
||||
| QUALITY-* | Spec Quality | completeness, consistency, traceability, depth, coverage |
|
||||
|
||||
---
|
||||
|
||||
## Code Review (REVIEW-*)
|
||||
|
||||
**Inputs**: Plan file, git diff, modified files, test results (if available)
|
||||
|
||||
**4 dimensions** (delegate to commands/code-review.md):
|
||||
|
||||
| Dimension | Critical Issues |
|
||||
|-----------|----------------|
|
||||
| Quality | Empty catch, any in public APIs, @ts-ignore, console.log |
|
||||
| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML |
|
||||
| Architecture | Circular deps, parent imports >2 levels, files >500 lines |
|
||||
| Requirements | Missing core functionality, incomplete acceptance criteria |
|
||||
|
||||
**Verdict**:
|
||||
|
||||
| Verdict | Criteria |
|
||||
|---------|----------|
|
||||
| BLOCK | Critical issues present |
|
||||
| CONDITIONAL | High/medium only |
|
||||
| APPROVE | Low or none |
|
||||
|
||||
---
|
||||
|
||||
## Spec Quality (QUALITY-*)
|
||||
|
||||
**Inputs**: All spec docs in session folder, quality gate config
|
||||
|
||||
**5 dimensions** (delegate to commands/spec-quality.md):
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Completeness | 25% | All sections present with substance |
|
||||
| Consistency | 20% | Terminology, format, references |
|
||||
| Traceability | 25% | Goals → Reqs → Arch → Stories chain |
|
||||
| Depth | 20% | AC testable, ADRs justified, stories estimable |
|
||||
| Coverage | 10% | Original requirements mapped |
|
||||
|
||||
**Quality gate**:
|
||||
|
||||
| Gate | Criteria |
|
||||
|------|----------|
|
||||
| PASS | Score ≥ 80% AND coverage ≥ 70% |
|
||||
| REVIEW | Score 60-79% OR coverage 50-69% |
|
||||
| FAIL | Score < 60% OR coverage < 50% |
|
||||
|
||||
**Artifacts**: readiness-report.md + spec-summary.md
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Missing context | Request from coordinator |
|
||||
| Invalid mode | Abort with error |
|
||||
| Analysis failure | Retry, then fallback template |
|
||||
@@ -1,152 +0,0 @@
|
||||
# Command: validate
|
||||
|
||||
## Purpose
|
||||
|
||||
Test-fix cycle with strategy engine: detect framework, run tests, classify failures, select fix strategy, iterate until pass rate target is met or max iterations exhausted.
|
||||
|
||||
## Constants
|
||||
|
||||
| Constant | Value | Description |
|
||||
|----------|-------|-------------|
|
||||
| MAX_ITERATIONS | 10 | Maximum test-fix cycle attempts |
|
||||
| PASS_RATE_TARGET | 95% | Minimum pass rate to succeed |
|
||||
| AFFECTED_TESTS_FIRST | true | Run affected tests before full suite |
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
Load from task description and executor output:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Framework | Auto-detected (see below) | Yes |
|
||||
| Modified files | Executor task output / git diff | Yes |
|
||||
| Affected tests | Derived from modified files | No |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Wisdom | `<session_folder>/wisdom/` | No |
|
||||
|
||||
**Framework detection** (priority order):
|
||||
|
||||
| Priority | Method | Check |
|
||||
|----------|--------|-------|
|
||||
| 1 | package.json devDependencies | vitest, jest, mocha, pytest |
|
||||
| 2 | package.json scripts.test | Command contains framework name |
|
||||
| 3 | Config file existence | vitest.config.*, jest.config.*, pytest.ini |
|
||||
|
||||
**Affected test discovery** from modified files:
|
||||
- For each modified file `<name>.<ext>`, search:
|
||||
`<name>.test.ts`, `<name>.spec.ts`, `tests/<name>.test.ts`, `__tests__/<name>.test.ts`
|
||||
|
||||
## Phase 3: Test-Fix Cycle
|
||||
|
||||
### Test Command Table
|
||||
|
||||
| Framework | Affected Tests | Full Suite |
|
||||
|-----------|---------------|------------|
|
||||
| vitest | `vitest run <files> --reporter=verbose` | `vitest run --reporter=verbose` |
|
||||
| jest | `jest <files> --no-coverage --verbose` | `jest --no-coverage --verbose` |
|
||||
| mocha | `mocha <files> --reporter spec` | `mocha --reporter spec` |
|
||||
| pytest | `pytest <files> -v --tb=short` | `pytest -v --tb=short` |
|
||||
|
||||
### Iteration Flow
|
||||
|
||||
```
|
||||
Iteration 1
|
||||
├─ Run affected tests (or full suite if none)
|
||||
├─ Parse results → pass rate
|
||||
├─ Pass rate >= 95%?
|
||||
│ ├─ YES + affected-only → run full suite to confirm
|
||||
│ │ ├─ Full suite passes → SUCCESS
|
||||
│ │ └─ Full suite fails → continue with full results
|
||||
│ └─ YES + full suite → SUCCESS
|
||||
└─ NO → classify failures → select strategy → apply fixes
|
||||
|
||||
Iteration 2..10
|
||||
├─ Re-run tests
|
||||
├─ Track best pass rate across iterations
|
||||
├─ Pass rate >= 95% → SUCCESS
|
||||
├─ No failures to fix → STOP (anomaly)
|
||||
└─ Failures remain → classify → select strategy → apply fixes
|
||||
|
||||
After iteration 10
|
||||
└─ FAIL: max iterations reached, report best pass rate
|
||||
```
|
||||
|
||||
**Progress update**: When iteration > 5, send progress to coordinator with current pass rate and iteration count.
|
||||
|
||||
### Strategy Selection Matrix
|
||||
|
||||
| Condition | Strategy | Behavior |
|
||||
|-----------|----------|----------|
|
||||
| Iteration <= 3 OR pass rate >= 80% | Conservative | Fix one failure at a time, highest severity first |
|
||||
| Critical failures exist AND count < 5 | Surgical | Identify common error pattern, fix all matching occurrences |
|
||||
| Pass rate < 50% OR iteration > 7 | Aggressive | Fix all critical + high failures in batch |
|
||||
| Default (no other match) | Conservative | Safe fallback |
|
||||
|
||||
### Failure Classification Table
|
||||
|
||||
| Severity | Error Patterns |
|
||||
|----------|---------------|
|
||||
| Critical | SyntaxError, cannot find module, is not defined |
|
||||
| High | Assertion mismatch (expected/received), toBe/toEqual failures |
|
||||
| Medium | Timeout, async errors |
|
||||
| Low | Warnings, deprecation notices |
|
||||
|
||||
### Fix Approach by Error Type
|
||||
|
||||
| Error Type | Pattern | Fix Approach |
|
||||
|------------|---------|-------------|
|
||||
| missing_import | "Cannot find module '<module>'" | Add import statement, resolve relative path from modified files |
|
||||
| undefined_variable | "<name> is not defined" | Check source for renamed/moved exports, update reference |
|
||||
| assertion_mismatch | "Expected: X, Received: Y" | Read test file at failure line, update expected value if behavior change is intentional |
|
||||
| timeout | "Timeout" | Increase timeout or add async/await |
|
||||
| syntax_error | "SyntaxError" | Read source at error line, fix syntax |
|
||||
|
||||
### Tool Call Example
|
||||
|
||||
Run tests with framework-appropriate command:
|
||||
|
||||
```bash
|
||||
Bash(command="vitest run src/utils/__tests__/parser.test.ts --reporter=verbose", timeout=120000)
|
||||
```
|
||||
|
||||
Read test file to analyze failure:
|
||||
|
||||
```bash
|
||||
Read(file_path="<test_file_path>")
|
||||
```
|
||||
|
||||
Apply fix via Edit:
|
||||
|
||||
```bash
|
||||
Edit(file_path="<file>", old_string="<old>", new_string="<new>")
|
||||
```
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Success Criteria
|
||||
|
||||
| Check | Criteria | Required |
|
||||
|-------|----------|----------|
|
||||
| Pass rate | >= 95% | Yes |
|
||||
| Full suite run | At least one full suite pass | Yes |
|
||||
| No critical failures | Zero critical-severity failures remaining | Yes |
|
||||
| Best pass rate tracked | Reported in final result | Yes |
|
||||
|
||||
### Result Routing
|
||||
|
||||
| Outcome | Message Type | Content |
|
||||
|---------|-------------|---------|
|
||||
| Pass rate >= target | test_result | Success, iterations count, full suite confirmed |
|
||||
| Max iterations, pass rate < target | fix_required | Best pass rate, remaining failures, iteration count |
|
||||
| No tests found | error | Framework detected but no test files |
|
||||
| Framework not detected | error | Detection methods exhausted |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Framework not detected | Report error to coordinator, list detection attempts |
|
||||
| No test files found | Report to coordinator, suggest manual test path |
|
||||
| Test command fails (exit code != 0/1) | Check stderr for environment issues, retry once |
|
||||
| Fix application fails | Skip fix, try next iteration with different strategy |
|
||||
| Infinite loop (same failures repeat) | Abort after 3 identical result sets |
|
||||
@@ -1,108 +0,0 @@
|
||||
# Role: tester
|
||||
|
||||
Adaptive test execution with fix cycles and quality gates.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `tester` | **Prefix**: `TEST-*` | **Tag**: `[tester]`
|
||||
- **Responsibility**: Detect Framework → Run Tests → Fix Cycle → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process TEST-* tasks
|
||||
- Detect test framework before running
|
||||
- Run affected tests before full suite
|
||||
- Use strategy engine for fix cycles
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks
|
||||
- Contact other workers directly
|
||||
- Modify production code beyond test fixes
|
||||
- Skip framework detection
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| test_result | → coordinator | Tests pass or final result |
|
||||
| fix_required | → coordinator | Failures after max iterations |
|
||||
| error | → coordinator | Framework not detected |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/validate.md | Test-fix cycle with strategy engine |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Framework Detection & Test Discovery
|
||||
|
||||
**Framework detection** (priority order):
|
||||
|
||||
| Priority | Method | Frameworks |
|
||||
|----------|--------|-----------|
|
||||
| 1 | package.json devDependencies | vitest, jest, mocha, pytest |
|
||||
| 2 | package.json scripts.test | vitest, jest, mocha, pytest |
|
||||
| 3 | Config files | vitest.config.*, jest.config.*, pytest.ini |
|
||||
|
||||
**Affected test discovery** from executor's modified files:
|
||||
- Search variants: `<name>.test.ts`, `<name>.spec.ts`, `tests/<name>.test.ts`, `__tests__/<name>.test.ts`
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Test Execution & Fix Cycle
|
||||
|
||||
**Config**: MAX_ITERATIONS=10, PASS_RATE_TARGET=95%, AFFECTED_TESTS_FIRST=true
|
||||
|
||||
Delegate to `commands/validate.md`:
|
||||
1. Run affected tests → parse results
|
||||
2. Pass rate met → run full suite
|
||||
3. Failures → select strategy → fix → re-run → repeat
|
||||
|
||||
**Strategy selection**:
|
||||
|
||||
| Condition | Strategy | Behavior |
|
||||
|-----------|----------|----------|
|
||||
| Iteration ≤ 3 or pass ≥ 80% | Conservative | Fix one critical failure at a time |
|
||||
| Critical failures < 5 | Surgical | Fix specific pattern everywhere |
|
||||
| Pass < 50% or iteration > 7 | Aggressive | Fix all failures in batch |
|
||||
|
||||
**Test commands**:
|
||||
|
||||
| Framework | Affected | Full Suite |
|
||||
|-----------|---------|------------|
|
||||
| vitest | `vitest run <files>` | `vitest run` |
|
||||
| jest | `jest <files> --no-coverage` | `jest --no-coverage` |
|
||||
| pytest | `pytest <files> -v` | `pytest -v` |
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Result Analysis
|
||||
|
||||
**Failure classification**:
|
||||
|
||||
| Severity | Patterns |
|
||||
|----------|----------|
|
||||
| Critical | SyntaxError, cannot find module, undefined |
|
||||
| High | Assertion failures, toBe/toEqual |
|
||||
| Medium | Timeout, async errors |
|
||||
| Low | Warnings, deprecations |
|
||||
|
||||
**Report routing**:
|
||||
|
||||
| Condition | Type |
|
||||
|-----------|------|
|
||||
| Pass rate ≥ target | test_result (success) |
|
||||
| Pass rate < target after max iterations | fix_required |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Framework not detected | Prompt user |
|
||||
| No tests found | Report to coordinator |
|
||||
| Infinite fix loop | Abort after MAX_ITERATIONS |
|
||||
@@ -1,187 +0,0 @@
|
||||
# Command: generate-doc
|
||||
|
||||
## Purpose
|
||||
|
||||
Multi-CLI document generation for 4 document types. Each uses parallel or staged CLI analysis, then synthesizes into templated documents.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Document standards | `../../specs/document-standards.md` | Yes |
|
||||
| Template | From routing table below | Yes |
|
||||
| Spec config | `<session-folder>/spec/spec-config.json` | Yes |
|
||||
| Discovery context | `<session-folder>/spec/discovery-context.json` | Yes |
|
||||
| Discussion feedback | `<session-folder>/discussions/<discuss-file>` | If exists |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
|
||||
### Document Type Routing
|
||||
|
||||
| Doc Type | Task | Template | Discussion Input | Output |
|
||||
|----------|------|----------|-----------------|--------|
|
||||
| product-brief | DRAFT-001 | templates/product-brief.md | discuss-001-scope.md | spec/product-brief.md |
|
||||
| requirements | DRAFT-002 | templates/requirements-prd.md | discuss-002-brief.md | spec/requirements/_index.md |
|
||||
| architecture | DRAFT-003 | templates/architecture-doc.md | discuss-003-requirements.md | spec/architecture/_index.md |
|
||||
| epics | DRAFT-004 | templates/epics-template.md | discuss-004-architecture.md | spec/epics/_index.md |
|
||||
|
||||
### Progressive Dependencies
|
||||
|
||||
Each doc type requires all prior docs: discovery-context → product-brief → requirements/_index → architecture/_index.
|
||||
|
||||
## Phase 3: Document Generation
|
||||
|
||||
### Shared Context Block
|
||||
|
||||
Built from spec-config and discovery-context for all CLI prompts:
|
||||
|
||||
```
|
||||
SEED: <topic>
|
||||
PROBLEM: <problem_statement>
|
||||
TARGET USERS: <target_users>
|
||||
DOMAIN: <domain>
|
||||
CONSTRAINTS: <constraints>
|
||||
FOCUS AREAS: <focus_areas>
|
||||
CODEBASE CONTEXT: <existing_patterns, tech_stack> (if discovery-context exists)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### DRAFT-001: Product Brief
|
||||
|
||||
**Strategy**: 3-way parallel CLI analysis, then synthesize.
|
||||
|
||||
| Perspective | CLI Tool | Focus |
|
||||
|-------------|----------|-------|
|
||||
| Product | gemini | Vision, market fit, success metrics, scope |
|
||||
| Technical | codex | Feasibility, constraints, integration complexity |
|
||||
| User | claude | Personas, journey maps, pain points, UX |
|
||||
|
||||
**CLI call template** (one per perspective, all `run_in_background: true`):
|
||||
|
||||
```bash
|
||||
Bash(command="ccw cli -p \"PURPOSE: <perspective> analysis for specification.\n<shared-context>\nTASK: <perspective-specific tasks>\nMODE: analysis\nEXPECTED: <structured output>\nCONSTRAINTS: <perspective scope>\" --tool <tool> --mode analysis", run_in_background=true)
|
||||
```
|
||||
|
||||
**Synthesis flow** (after all 3 return):
|
||||
|
||||
```
|
||||
3 CLI outputs received
|
||||
├─ Identify convergent themes (2+ perspectives agree)
|
||||
├─ Identify conflicts (e.g., product wants X, technical says infeasible)
|
||||
├─ Extract unique insights per perspective
|
||||
├─ Integrate discussion feedback (if exists)
|
||||
└─ Fill template → Write to spec/product-brief.md
|
||||
```
|
||||
|
||||
**Template sections**: Vision, Problem Statement, Target Users, Goals, Scope, Success Criteria, Assumptions.
|
||||
|
||||
---
|
||||
|
||||
### DRAFT-002: Requirements/PRD
|
||||
|
||||
**Strategy**: Single CLI expansion, then structure into individual requirement files.
|
||||
|
||||
| Step | Tool | Action |
|
||||
|------|------|--------|
|
||||
| 1 | gemini | Generate functional (REQ-NNN) and non-functional (NFR-type-NNN) requirements |
|
||||
| 2 | (local) | Integrate discussion feedback |
|
||||
| 3 | (local) | Write individual files + _index.md |
|
||||
|
||||
**CLI prompt focus**: For each product-brief goal, generate 3-7 functional requirements with user stories, acceptance criteria, and MoSCoW priority. Generate NFR categories: performance, security, scalability, usability.
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/requirements/
|
||||
├─ _index.md (summary table + MoSCoW breakdown)
|
||||
├─ REQ-001-<slug>.md (individual functional requirement)
|
||||
├─ REQ-002-<slug>.md
|
||||
├─ NFR-perf-001-<slug>.md (non-functional)
|
||||
└─ NFR-sec-001-<slug>.md
|
||||
```
|
||||
|
||||
Each requirement file has: YAML frontmatter (id, title, priority, status, traces), description, user story, acceptance criteria.
|
||||
|
||||
---
|
||||
|
||||
### DRAFT-003: Architecture
|
||||
|
||||
**Strategy**: 2-stage CLI (design + critical review).
|
||||
|
||||
| Stage | Tool | Purpose |
|
||||
|-------|------|---------|
|
||||
| 1 | gemini | Architecture design: style, components, tech stack, ADRs, data model, security |
|
||||
| 2 | codex | Critical review: challenge ADRs, identify bottlenecks, rate quality 1-5 |
|
||||
|
||||
Stage 2 runs after stage 1 completes (sequential dependency).
|
||||
|
||||
**After both complete**:
|
||||
1. Integrate discussion feedback
|
||||
2. Map codebase integration points (from discovery-context.relevant_files)
|
||||
3. Write individual ADR files + _index.md
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/architecture/
|
||||
├─ _index.md (overview, component diagram, tech stack, data model, API, security)
|
||||
├─ ADR-001-<slug>.md (individual decision record)
|
||||
└─ ADR-002-<slug>.md
|
||||
```
|
||||
|
||||
Each ADR file has: YAML frontmatter (id, title, status, traces), context, decision, alternatives with pros/cons, consequences, review feedback.
|
||||
|
||||
---
|
||||
|
||||
### DRAFT-004: Epics & Stories
|
||||
|
||||
**Strategy**: Single CLI decomposition, then structure into individual epic files.
|
||||
|
||||
| Step | Tool | Action |
|
||||
|------|------|--------|
|
||||
| 1 | gemini | Decompose requirements into 3-7 Epics with Stories, dependency map, MVP subset |
|
||||
| 2 | (local) | Integrate discussion feedback |
|
||||
| 3 | (local) | Write individual EPIC files + _index.md |
|
||||
|
||||
**CLI prompt focus**: Group requirements by domain, generate EPIC-NNN with STORY-EPIC-NNN children, define MVP subset, create Mermaid dependency diagram, recommend execution order.
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/epics/
|
||||
├─ _index.md (overview table, dependency map, execution order, MVP scope)
|
||||
├─ EPIC-001-<slug>.md (individual epic with stories)
|
||||
└─ EPIC-002-<slug>.md
|
||||
```
|
||||
|
||||
Each epic file has: YAML frontmatter (id, title, priority, mvp, size, requirements, architecture, dependencies), stories with user stories and acceptance criteria.
|
||||
|
||||
All generated documents include YAML frontmatter: session_id, phase, document_type, status=draft, generated_at, version, dependencies.
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
| Check | What to Verify |
|
||||
|-------|---------------|
|
||||
| has_frontmatter | Document starts with valid YAML frontmatter |
|
||||
| sections_complete | All template sections present in output |
|
||||
| cross_references | session_id matches spec-config |
|
||||
| discussion_integrated | Feedback reflected (if feedback exists) |
|
||||
| files_written | All expected files exist (individual + _index.md) |
|
||||
|
||||
### Result Routing
|
||||
|
||||
| Outcome | Message Type | Content |
|
||||
|---------|-------------|---------|
|
||||
| All checks pass | draft_ready | Doc type, output path, summary |
|
||||
| Validation issues | draft_ready (with warnings) | Doc type, output path, issues list |
|
||||
| Critical failure | error | Missing template, CLI failure |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Prior doc not found | Notify coordinator, request prerequisite task completion |
|
||||
| Template not found | Error, report missing template path |
|
||||
| CLI tool fails | Retry with fallback tool (gemini → codex → claude) |
|
||||
| Discussion contradicts prior docs | Note conflict in document, flag for next discussion round |
|
||||
| Partial CLI output | Use available data, note gaps in document |
|
||||
@@ -1,96 +0,0 @@
|
||||
# Role: writer
|
||||
|
||||
Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation. Maps to spec-generator Phases 2-5.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `writer` | **Prefix**: `DRAFT-*` | **Tag**: `[writer]`
|
||||
- **Responsibility**: Load Context → Generate Document → Incorporate Feedback → Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process DRAFT-* tasks
|
||||
- Read templates before generating (from `../../templates/`)
|
||||
- Follow document-standards.md (from `../../specs/`)
|
||||
- Integrate discussion feedback when available
|
||||
- Generate proper YAML frontmatter
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks for other roles
|
||||
- Skip template loading
|
||||
- Modify discussion records
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| draft_ready | → coordinator | Document writing complete |
|
||||
| draft_revision | → coordinator | Document revised per feedback |
|
||||
| error | → coordinator | Template missing, insufficient context |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/generate-doc.md | Multi-CLI document generation |
|
||||
| gemini, codex, claude CLI | Multi-perspective content generation |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context & Discussion Loading
|
||||
|
||||
**Objective**: Load all required inputs for document generation.
|
||||
|
||||
**Document type routing**:
|
||||
|
||||
| Task Subject Contains | Doc Type | Template | Discussion Input |
|
||||
|----------------------|----------|----------|-----------------|
|
||||
| Product Brief | product-brief | templates/product-brief.md | discuss-001-scope.md |
|
||||
| Requirements / PRD | requirements | templates/requirements-prd.md | discuss-002-brief.md |
|
||||
| Architecture | architecture | templates/architecture-doc.md | discuss-003-requirements.md |
|
||||
| Epics | epics | templates/epics-template.md | discuss-004-architecture.md |
|
||||
|
||||
**Progressive dependency loading**:
|
||||
|
||||
| Doc Type | Requires |
|
||||
|----------|----------|
|
||||
| product-brief | discovery-context.json |
|
||||
| requirements | + product-brief.md |
|
||||
| architecture | + requirements/_index.md |
|
||||
| epics | + architecture/_index.md |
|
||||
|
||||
**Success**: Template loaded, discussion feedback loaded (if exists), prior docs loaded.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Document Generation
|
||||
|
||||
**Objective**: Generate document using template and multi-CLI analysis.
|
||||
|
||||
Delegate to `commands/generate-doc.md` with: doc type, session folder, spec config, discussion feedback, prior docs.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Self-Validation
|
||||
|
||||
**Objective**: Verify document meets standards.
|
||||
|
||||
| Check | What to Verify |
|
||||
|-------|---------------|
|
||||
| has_frontmatter | Starts with YAML frontmatter |
|
||||
| sections_complete | All template sections present |
|
||||
| cross_references | session_id included |
|
||||
| discussion_integrated | Reflects feedback (if exists) |
|
||||
|
||||
**Report**: doc type, validation status, summary, output path.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Prior doc not found | Notify coordinator, request prerequisite |
|
||||
| CLI failure | Retry with fallback tool |
|
||||
| Discussion contradicts prior docs | Note conflict, flag for next discussion |
|
||||
Reference in New Issue
Block a user