feat: Add Role Analysis Reviewer Agent and validation template

- Introduced Role Analysis Reviewer Agent to validate role analysis outputs against templates and quality standards. - Created a detailed validation ruleset for the system-architect role, including mandatory and recommended sections. - Added JSON validation report structure for output. - Implemented execution command for validation process. test: Add UX tests for HookCard component - Created comprehensive tests for HookCard component, focusing on delete confirmation UX pattern. - Verified confirmation dialog appearance, deletion functionality, and button interactions. - Ensured proper handling of state updates and visual feedback for enabled/disabled status. test: Add UX tests for ThemeSelector component - Developed tests for ThemeSelector component, emphasizing delete confirmation UX pattern. - Validated confirmation dialog display, deletion actions, and toast notifications for undo functionality. - Ensured proper management of theme slots and state updates. feat: Implement useDebounce hook - Added useDebounce hook to delay expensive computations or API calls, enhancing performance. feat: Create System Architect Analysis Template - Developed a comprehensive template for system architect role analysis, covering required sections such as architecture overview, data model, state machine, error handling strategy, observability requirements, configuration model, and boundary scenarios. - Included examples and templates for each section to guide users in producing SPEC.md-level precision modeling.
2026-03-07 16:41:06 +08:00 · 2026-03-05 19:58:10 +08:00
parent bc7a556985
commit 3fd55ebd4b
55 changed files with 4262 additions and 1138 deletions
--- a/.claude/skills/team-lifecycle-v3/specs/core-concepts.md
+++ b/.claude/skills/team-lifecycle-v3/specs/core-concepts.md
@@ -0,0 +1,264 @@
+# Core Concepts
+
+## Overview
+
+Team Lifecycle v3 is an enhanced multi-agent orchestration system that manages the complete software development lifecycle from specification to implementation, testing, and review. It uses a **team-worker agent architecture** with **artifact contracts** and **automatic discovery** to coordinate parallel execution across specialized roles.
+
+## Architecture
+
+```
+---------------------------------------------------+
+|  Skill(skill="team-lifecycle-v3")                  |
+|  args="task description"                           |
+-------------------+-------------------------------+
+                    |
+         Orchestration Mode (auto -> coordinator)
+                    |
+              Coordinator (inline)
+              Phase 0-5 orchestration
+              + Dynamic role injection
+              + Priority scheduling
+              + Artifact registry
+                    |
+    +----+-----+-------+-------+-------+-------+-------+
+    v    v     v       v       v       v       v       v
+ [team-worker agents, each loaded with a role-spec]
+
+  Core Pipeline (9 roles from v2):
+    analyst writer planner executor tester reviewer
+    architect fe-developer fe-qa
+
+  Specialist Roles (6 new roles, injected on-demand):
+    orchestrator security-expert performance-optimizer
+    data-engineer devops-engineer ml-engineer
+
+  Utility Members (3):
+    [explorer] [discussant] [doc-generator]
+```
+
+## Foundational Principles
+
+### 1. Team-Worker Agent Architecture
+
+The system uses a **coordinator-worker pattern**:
+
+- **Coordinator**: Orchestrates the workflow, manages task dependencies, injects specialist roles dynamically, and maintains the artifact registry
+- **Workers**: Specialized agents (analyst, writer, planner, executor, etc.) that execute specific tasks and produce artifacts
+- **Communication**: Workers report completion via `SendMessage` callbacks to the coordinator
+
+**Key Benefits**:
+- Clear separation of concerns (orchestration vs execution)
+- Parallel execution of independent tasks
+- Dynamic scaling with specialist role injection
+
+### 2. Artifact Contracts
+
+All workers generate **artifact manifests** alongside their deliverables for validation gating and automatic discovery.
+
+**Manifest Schema**:
+```json
+{
+  "artifact_id": "string",
+  "creator_role": "string",
+  "artifact_type": "string",
+  "version": "string",
+  "path": "string",
+  "dependencies": ["string"],
+  "validation_status": "pending|passed|failed",
+  "validation_summary": "string",
+  "metadata": {
+    "created_at": "ISO8601 timestamp",
+    "task_id": "string",
+    "priority": "P0|P1|P2"
+  }
+}
+```
+
+**Validation Gating**:
+- Coordinator checks `validation_status` before spawning downstream workers
+- `passed` → spawn next worker
+- `failed` → block spawn, trigger fix loop
+- `pending` → wait or prompt manual validation
+
+**Automatic Discovery**:
+- Coordinator maintains in-memory artifact registry
+- Workers read `context-artifacts.json` in Phase 2 to discover upstream artifacts automatically
+- No manual artifact passing required
+
+### 3. Quality Gating
+
+Quality gates ensure artifact quality before proceeding to next phase:
+
+- **Spec Phase Gate** (QUALITY-001): Multi-dimensional quality check
+  - Completeness, Consistency, Traceability, Depth, Coverage
+  - Checkpoint with user actions: resume, improve, revise, recheck, feedback
+- **Implementation Gate**: Test coverage and review approval
+- **Per-Artifact Validation**: Manifest-based validation status
+
+### 4. Dynamic Role Injection
+
+Coordinator analyzes task description and plan complexity to inject specialist roles at runtime:
+
+| Trigger | Injected Role | Injection Point |
+|---------|---------------|-----------------|
+| Keywords: security, vulnerability, OWASP | security-expert | After PLAN-001 |
+| Keywords: performance, optimization, bottleneck | performance-optimizer | After IMPL-* |
+| Keywords: data, pipeline, ETL, schema | data-engineer | Parallel with IMPL-* |
+| Keywords: devops, CI/CD, deployment, docker | devops-engineer | After IMPL-* |
+| Keywords: ML, model, training, inference | ml-engineer | Parallel with IMPL-* |
+| Complexity: High + multi-module | orchestrator | Replace IMPL-* with ORCH-* |
+
+**Benefits**:
+- Automatic expertise injection based on task requirements
+- No manual role configuration needed
+- Scales from simple to complex tasks
+
+### 5. Priority Scheduling
+
+Tasks are assigned priorities for execution ordering:
+
+- **P0**: Critical path tasks (RESEARCH, DRAFT, PLAN, core IMPL)
+- **P1**: Dependent tasks (TEST, REVIEW, QA)
+- **P2**: Optional enhancements
+
+**Scheduling Rules**:
+- P0 > P1 > P2
+- FIFO within same priority
+- Parallel execution for independent tasks at same priority
+
+### 6. Conditional Routing
+
+PLAN-001 assesses complexity and routes accordingly:
+
+| Complexity | Route | Roles |
+|------------|-------|-------|
+| Low (1-2 modules, shallow deps) | Direct IMPL | executor |
+| Medium (3-4 modules, moderate deps) | Orchestrated IMPL | orchestrator → executor (parallel) |
+| High (5+ modules, deep deps) | Architecture + Orchestrated IMPL | architect → orchestrator → executor (parallel) |
+
+### 7. Beat-Based Cadence
+
+Event-driven execution model where each beat = coordinator wake → process → spawn → STOP:
+
+```
+Beat Cycle (v3 Enhanced)
+======================================================================
+  Event                   Coordinator              Workers
+----------------------------------------------------------------------
+  callback/resume --> +- handleCallback -+
+                      |  mark completed   |
+                      |  check artifacts  |  <- v3: artifact validation
+                      |  update registry  |  <- v3: artifact registry
+                      +- handleSpawnNext -+
+                      |  find ready tasks |
+                      |  priority sort    |  <- v3: P0/P1/P2 scheduling
+                      |  inject roles     |  <- v3: dynamic injection
+                      |  spawn workers ---+--> [team-worker] Phase 1-5
+                      +- STOP (idle) -----+         |
+                                                     |
+  callback <-----------------------------------------+
+```
+
+**Fast-Advance Optimization**:
+- Workers can spawn simple linear successors directly
+- Skips coordinator for simple cases
+- Logs fast_advance to message bus
+
+## Role Types
+
+### Core Pipeline Roles (Always Present)
+
+| Role | Purpose | Task Prefix |
+|------|---------|-------------|
+| analyst | Research and discovery | RESEARCH-* |
+| writer | Document drafting | DRAFT-* |
+| planner | Implementation planning | PLAN-* |
+| executor | Code implementation | IMPL-* |
+| tester | Test generation and execution | TEST-* |
+| reviewer | Quality review and improvement | REVIEW-*, QUALITY-*, IMPROVE-* |
+
+### Consulting Roles (High Complexity)
+
+| Role | Purpose | Task Prefix |
+|------|---------|-------------|
+| architect | Architecture design | ARCH-* |
+| fe-developer | Frontend development | DEV-FE-* |
+| fe-qa | Frontend QA | QA-FE-* |
+
+### Specialist Roles (Dynamic Injection)
+
+| Role | Purpose | Task Prefix | Injection Trigger |
+|------|---------|-------------|-------------------|
+| orchestrator | Multi-module coordination | ORCH-* | Multi-module complexity |
+| security-expert | Security analysis | SECURITY-* | Security keywords |
+| performance-optimizer | Performance optimization | PERF-* | Performance keywords |
+| data-engineer | Data pipeline work | DATA-* | Data keywords |
+| devops-engineer | DevOps and deployment | DEVOPS-* | DevOps keywords |
+| ml-engineer | ML/AI implementation | ML-* | ML keywords |
+
+### Utility Members (Coordinator-Only)
+
+| Utility | Purpose | Callable By |
+|---------|---------|-------------|
+| explorer | Parallel multi-angle exploration | Coordinator only |
+| discussant | Aggregate multi-CLI critique | Coordinator only |
+
+**Note**: Workers cannot spawn utility members. Workers needing similar capabilities must use CLI tools (`ccw cli --tool gemini --mode analysis`).
+
+## CLI Tool Integration
+
+Workers use CLI tools for complex analysis:
+
+| Capability | CLI Command | Used By |
+|------------|-------------|---------|
+| Codebase exploration | `ccw cli --tool gemini --mode analysis` | analyst, planner, architect |
+| Multi-perspective critique | `ccw cli --tool gemini --mode analysis` (parallel) | analyst, writer, reviewer |
+| Document generation | `ccw cli --tool gemini --mode write` | writer |
+
+## Session Management
+
+### Session Directory Structure
+
+```
+.workflow/.team/TLS-<slug>-<date>/
+-- team-session.json
+-- artifact-registry.json          <- v3 NEW
+-- spec/
+|   +-- spec-config.json
+|   +-- discovery-context.json
+|   +-- product-brief.md
+|   +-- requirements/
+|   +-- architecture/
+|   +-- epics/
+|   +-- readiness-report.md
+-- discussions/
+-- plan/
+|   +-- plan.json
+|   +-- .task/TASK-*.json
+-- explorations/
+-- artifacts/                      <- v3 NEW: artifact manifests
+|   +-- artifact-manifest-*.json
+-- .msg/
+-- shared-memory.json
+```
+
+### Session Resume
+
+1. Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions
+2. Multiple matches → AskUserQuestion
+3. Audit TaskList → reconcile session state
+4. Reset in_progress → pending (interrupted tasks)
+5. Rebuild team, spawn needed workers only
+6. Restore artifact registry from session
+7. Kick first executable task
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | Output execution status, no advancement |
+| `resume` / `continue` | Check worker states, advance next step |
+| `revise <TASK-ID> [feedback]` | Create revision task + cascade downstream |
+| `feedback <text>` | Analyze feedback, create targeted revision |
+| `recheck` | Re-run QUALITY-001 quality check |
+| `improve [dimension]` | Auto-improve weakest dimension |