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/SKILL.md
+++ b/.claude/skills/team-lifecycle-v3/SKILL.md
@@ -6,440 +6,218 @@ allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), Task

 # Team Lifecycle v3

-Enhanced lifecycle: specification → implementation → testing → review with parallel execution, conditional routing, and dynamic specialist role injection. Built on **team-worker agent architecture** with **artifact contracts** and **automatic discovery**.
+Enhanced lifecycle: specification → implementation → testing → review with parallel execution, conditional routing, and dynamic specialist role injection.

+## Purpose

-## Architecture
+Team Lifecycle v3 orchestrates multi-agent software development workflows from initial requirements through implementation, testing, and review. It automatically coordinates specialized agents, manages artifact dependencies, validates quality gates, and dynamically injects expert roles based on task complexity.
+
+**Key Capabilities**:
+- Parallel execution of independent tasks
+- Dynamic specialist role injection (security, performance, data, devops, ML)
+- Artifact-based validation gating
+- Conditional routing based on complexity assessment
+- Priority-based task scheduling (P0/P1/P2)
+- Quality checkpoints with user feedback loops
+
+## Problem Statement
+
+Complex software development tasks require diverse expertise—security audits, performance optimization, data pipeline design, DevOps configuration, and ML model integration. Coordinating multiple specialized agents manually is error-prone, inefficient, and difficult to scale. Developers face several challenges:
+
+1. **Manual Coordination Overhead**: Tracking dependencies between agents, ensuring artifacts are validated before downstream work begins, and managing parallel execution requires constant human oversight.
+
+2. **Expertise Gaps**: Not all tasks require all specialists. Injecting the right expert roles at the right time based on task complexity and keywords is a manual, subjective process prone to under- or over-staffing.
+
+3. **Quality Assurance Bottlenecks**: Without automated quality gates and validation checkpoints, defects propagate downstream, requiring expensive rework.
+
+4. **Lack of Observability**: Understanding where a multi-agent workflow is stalled, which artifacts are blocking progress, and what actions are needed requires manual inspection of scattered state.
+
+Team Lifecycle v3 solves these problems by providing an event-driven orchestration system that automatically manages agent coordination, artifact validation, specialist injection, and quality checkpoints—turning multi-agent workflows into a repeatable, observable, and scalable process.
+
+## Goals
+
+- **Automated Agent Coordination**: Spawn workers based on task dependencies, manage parallel execution, and handle completion callbacks without manual intervention.
+- **Artifact-Based Validation Gating**: Block downstream work until upstream artifacts pass validation, preventing defect propagation.
+- **Dynamic Specialist Injection**: Analyze task descriptions and complexity to automatically inject expert roles (security, performance, data, devops, ML) when needed.
+- **Conditional Routing**: Route tasks to appropriate implementation strategies (direct, orchestrated, architecture-first) based on quantifiable complexity assessment.
+- **Priority-Based Scheduling**: Execute critical-path tasks (P0) before dependent tasks (P1/P2), optimizing workflow throughput.
+- **Quality Checkpoints**: Pause at key milestones for user review, with actionable commands (resume, improve, revise, recheck) to maintain quality.
+- **Session Persistence**: Support pause/resume across process restarts, preserving artifact registry and task state.
+- **Observability**: Provide clear status reporting, task state visibility, and actionable error messages.
+
+## Non-Goals
+
+- **General-Purpose Workflow Engine**: Team Lifecycle v3 is specialized for software development workflows with agent coordination. It is not a generic DAG executor or distributed job scheduler.
+- **Project Management Tool**: The system does not manage backlogs, sprints, or roadmaps. It executes individual tasks with clear requirements.
+- **Prescriptive Agent Implementations**: The skill defines role specifications and contracts but does not mandate specific agent implementations or tools.
+- **Ticket/PR Management**: State transitions, comments, and PR creation are the responsibility of individual agents using their own tools, not the orchestrator.
+- **Approval/Sandbox Policies**: The skill does not enforce specific approval workflows or sandboxing. Implementations may add these based on their trust model.
+- **Real-Time Collaboration**: The system is event-driven with asynchronous agent execution, not a real-time collaborative editing environment.
+
+## Mandatory Reading
+
+Before using this skill, read these documents to understand the foundational concepts:
+
+| Document | Purpose | Priority |
+|----------|---------|----------|
+| [specs/core-concepts.md](specs/core-concepts.md) | Foundational principles: team-worker architecture, artifact contracts, quality gating, dynamic role injection, priority scheduling | **P0 - Critical** |
+| [specs/artifact-contract-spec.md](specs/artifact-contract-spec.md) | Artifact manifest schema and validation rules | **P0 - Critical** |
+| [specs/execution-flow.md](specs/execution-flow.md) | End-to-end execution walkthrough with pipeline definitions | **P1 - High** |
+
+## Documentation Structure
+
+This skill is organized into the following directories:
+
+### `/roles` - Agent Role Specifications
+
+- **`coordinator/`**: Orchestrator agent that manages workflow, task dependencies, and role injection
+  - `role.md`: Coordinator specification
+  - `commands/`: User command handlers (dispatch, monitor)
+- **`pipeline/`**: Core pipeline roles (always present)
+  - `analyst.md`, `writer.md`, `planner.md`, `executor.md`, `tester.md`, `reviewer.md`
+  - `architect.md`, `fe-developer.md`, `fe-qa.md` (consulting roles)
+- **`specialists/`**: Specialist roles (dynamically injected)
+  - `orchestrator.role.md`, `security-expert.role.md`, `performance-optimizer.role.md`
+  - `data-engineer.role.md`, `devops-engineer.role.md`, `ml-engineer.role.md`
+
+### `/specs` - Specifications and Standards
+
+- **`core-concepts.md`**: Foundational principles (mandatory reading)
+- **`execution-flow.md`**: End-to-end execution walkthrough
+- **`artifact-contract-spec.md`**: Artifact manifest schema
+- **`quality-gates.md`**: Quality validation criteria
+- **`document-standards.md`**: Document formatting standards
+- **`team-config.json`**: Role registry and pipeline definitions
+
+### `/templates` - Document Templates
+
+- `product-brief.md`: DRAFT-001 template
+- `requirements-prd.md`: DRAFT-002 template
+- `architecture-doc.md`: DRAFT-003 template
+- `epics-template.md`: DRAFT-004 template
+
+### `/subagents` - Utility Subagents
+
+- `discuss-subagent.md`: 3-round discussion protocol
+- `explorer-subagent.md`: Shared exploration with cache
+- `doc-generator-subagent.md`: Template-based doc generation
+
+## Quick Start
+
+### Basic Usage

 ```
-+---------------------------------------------------+
-|  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]
+Skill(skill="team-lifecycle-v3", args="<task description>")
 ```

-## Role Router
-
-Coordinator-only. Workers spawned as `team-worker` agents.
-
-### Role Registry
-
-| Role | Spec | Task Prefix | Type | Inner Loop | Injection |
-|------|------|-------------|------|------------|-----------|
-| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | - | Always |
-| analyst | [role-specs/analyst.md](role-specs/analyst.md) | RESEARCH-* | pipeline | false | Always |
-| writer | [role-specs/writer.md](role-specs/writer.md) | DRAFT-* | pipeline | true | Always |
-| planner | [role-specs/planner.md](role-specs/planner.md) | PLAN-* | pipeline | true | Always |
-| executor | [role-specs/executor.md](role-specs/executor.md) | IMPL-* | pipeline | true | Always |
-| tester | [role-specs/tester.md](role-specs/tester.md) | TEST-* | pipeline | false | Always |
-| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* + QUALITY-* + IMPROVE-* | pipeline | false | Always |
-| architect | [role-specs/architect.md](role-specs/architect.md) | ARCH-* | consulting | false | High complexity |
-| fe-developer | [role-specs/fe-developer.md](role-specs/fe-developer.md) | DEV-FE-* | frontend | false | Frontend tasks |
-| fe-qa | [role-specs/fe-qa.md](role-specs/fe-qa.md) | QA-FE-* | frontend | false | Frontend tasks |
-| **orchestrator** | [role-specs/orchestrator.md](role-specs/orchestrator.md) | ORCH-* | specialist | false | **Multi-module** |
-| **security-expert** | [role-specs/security-expert.md](role-specs/security-expert.md) | SECURITY-* | specialist | false | **security keywords** |
-| **performance-optimizer** | [role-specs/performance-optimizer.md](role-specs/performance-optimizer.md) | PERF-* | specialist | false | **performance keywords** |
-| **data-engineer** | [role-specs/data-engineer.md](role-specs/data-engineer.md) | DATA-* | specialist | false | **data keywords** |
-| **devops-engineer** | [role-specs/devops-engineer.md](role-specs/devops-engineer.md) | DEVOPS-* | specialist | false | **devops keywords** |
-| **ml-engineer** | [role-specs/ml-engineer.md](role-specs/ml-engineer.md) | ML-* | specialist | false | **ML keywords** |
-
-### CLI Tool Usage in Workers
-
-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 |
-
-### Coordinator-Only Utility Members
-
-**⚠️ COORDINATOR ONLY**: Utility members can only be spawned by Coordinator.
-Workers CANNOT call Agent() to spawn utility members.
-
-Coordinator can spawn utility members for team-level orchestration:
-
-| Utility Member | Purpose | When | Callable By |
-|----------------|---------|------|-------------|
-| explorer | Parallel multi-angle exploration | High complexity analysis | **Coordinator only** |
-| discussant | Aggregate multi-CLI critique | Critical decision points | **Coordinator only** |
-
-### Worker Alternatives
-
-Workers needing similar capabilities must use CLI tools:
-
-| Capability | CLI Command | Example |
-|------------|-------------|---------|
-| Codebase exploration | `ccw cli --tool gemini --mode analysis` | Explore architecture patterns |
-| Multi-perspective critique | Parallel CLI calls | Security + performance + quality reviews |
-| Document generation | `ccw cli --tool gemini --mode write` | Generate PRD from research |
-
-### 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-* |
-
-### Dispatch
-
-Always route to coordinator. Coordinator reads `roles/coordinator/role.md`.
-
-### Orchestration Mode
-
-**Invocation**: `Skill(skill="team-lifecycle-v3", args="task description")`
-
-**Lifecycle**:
+**Example**:
 ```
-User provides task description
-  -> coordinator Phase 1-3: clarify -> TeamCreate -> analyze complexity -> inject roles -> create task chain
-  -> coordinator Phase 4: spawn first batch workers (background) -> STOP
-  -> Worker executes -> SendMessage callback -> coordinator advances
-  -> Loop until pipeline complete -> Phase 5 report + completion action
+Skill(skill="team-lifecycle-v3", args="Implement user authentication with OAuth2")
 ```

-**User Commands**:
+### Execution Flow
+
+1. **User provides task description** → Coordinator clarifies requirements
+2. **Coordinator creates team** → TeamCreate with session folder
+3. **Coordinator analyzes complexity** → Injects specialist roles if needed
+4. **Coordinator creates task chain** → Based on pipeline selection (spec-only, impl-only, full-lifecycle)
+5. **Coordinator spawns first batch** → Workers execute in background
+6. **Workers report completion** → SendMessage callback to coordinator
+7. **Coordinator advances pipeline** → Spawns next ready tasks
+8. **Quality checkpoints** → User can review, improve, or revise
+9. **Coordinator generates report** → Final summary and completion action
+
+### User Commands
+
+During execution, you can use these 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 |
+| `check` / `status` | View current execution status |
+| `resume` / `continue` | Advance to next step |
+| `revise <TASK-ID> [feedback]` | Revise specific task with feedback |
+| `feedback <text>` | Provide feedback for targeted revision |
+| `recheck` | Re-run quality check |
+| `improve [dimension]` | Auto-improve weakest quality dimension |

---
+## Pipeline Options

-## Coordinator Spawn Template
+The coordinator selects the appropriate pipeline based on task requirements:

+### Spec-only Pipeline (6 tasks)
 ```
-Agent({
-  subagent_type: "team-worker",
-  description: "Spawn <role> worker",
-  team_name: <team-name>,
-  name: "<role>",
-  run_in_background: true,
-  prompt: `## Role Assignment
-role: <role>
-role_spec: .claude/skills/team-lifecycle-v3/role-specs/<role>.md
-session: <session-folder>
-session_id: <session-id>
-team_name: <team-name>
-requirement: <task-description>
-inner_loop: <true|false>
-priority: <P0|P1|P2>
-
-Read role_spec file to load Phase 2-4 domain instructions.
-Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
-})
+RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
 ```
+Use for: Documentation, requirements gathering, design work

---
-
-## Pipeline Definitions
-
-### Spec-only (6 tasks, 3 discuss)
-
+### Impl-only Pipeline (4 tasks)
 ```
-RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> DRAFT-003 -> DRAFT-004 -> QUALITY-001(+D3)
+PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
 ```
+Use for: Quick implementations with clear requirements

-### Impl-only (4 tasks)
-
+### Full-lifecycle Pipeline (10 tasks)
 ```
-PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001
+[Spec pipeline] → PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
 ```
+Use for: Complete feature development from requirements to implementation

-### Full-lifecycle (10 tasks, v2 compatible)
+## Advanced Features

-```
-[Spec pipeline] -> PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 + REVIEW-001
-```
+### Dynamic Role Injection

-### Enhanced Parallel Pipeline (v3 NEW)
+Specialist roles are automatically injected based on keywords in task description:

-```
-RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> DRAFT-003 -> DRAFT-004 -> QUALITY-001(+D3)
-                                                                                    |
-                                                                                    v
-                                                                              PLAN-001 (complexity assessment)
-                                                                                    |
-                                                                    +---------------+---------------+
-                                                                    |               |               |
-                                                              Low: IMPL-001   Med: ORCH-001   High: ARCH-001
-                                                                    |          -> IMPL-*         -> ORCH-001
-                                                                    |                                -> IMPL-*
-                                                                    v
-                                                              IMPL-001 || DEV-FE-001 (parallel, P0)
-                                                                    |
-                                                                    v
-                                                              TEST-001 || QA-FE-001 (parallel, P1)
-                                                                    |
-                                                                    v
-                                                              REVIEW-001 (P1)
-```
+- **security**, **vulnerability**, **OWASP** → `security-expert`
+- **performance**, **optimization**, **bottleneck** → `performance-optimizer`
+- **data**, **pipeline**, **ETL**, **schema** → `data-engineer`
+- **devops**, **CI/CD**, **deployment**, **docker** → `devops-engineer`
+- **ML**, **model**, **training**, **inference** → `ml-engineer`

-### Conditional Routing (v3 NEW)
+### Conditional Routing

-PLAN-001 assesses complexity and routes accordingly:
+PLAN-001 assesses complexity and routes to appropriate implementation strategy:

-| 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) |
+- **Low complexity** (1-2 modules) → Direct implementation
+- **Medium complexity** (3-4 modules) → Orchestrated parallel implementation
+- **High complexity** (5+ modules) → Architecture design + orchestrated implementation

-### Dynamic Injection Example (v3 NEW)
+### Quality Checkpoints

-Task description: "Implement user authentication with OAuth2, add security audit, optimize login performance"
+At key milestones, the coordinator pauses for user review:

-Injected roles:
- security-expert (keyword: security, audit)
- performance-optimizer (keyword: optimize, performance)
+- **Spec Phase Complete** (QUALITY-001): Review specification quality, choose to proceed, improve, or revise
+- **Implementation Complete**: Review code quality and test coverage

-Pipeline becomes:
-```
-PLAN-001 -> IMPL-001 || SECURITY-001 || PERF-001 -> TEST-001 -> REVIEW-001
-```
+## Troubleshooting

-### Cadence Control
+### Common Issues

-**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
+| Issue | Solution |
+|-------|----------|
+| Pipeline stalled | Use `status` to check task states, `resume` to advance |
+| Quality gate failed | Use `improve` to auto-improve or `revise <TASK-ID>` to manually fix |
+| Wrong specialist injected | Provide clearer keywords in task description |
+| Session lost after restart | Use session resume to restore from `.workflow/.team/TLS-*` |

-```
-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 (skips coordinator for simple linear successors)
-======================================================================
-  [Worker A] Phase 5 complete
-    +- 1 ready task? simple successor?
-    |   --> spawn team-worker B directly
-    |   --> log fast_advance to message bus
-    +- complex case? --> SendMessage to coordinator
-======================================================================
-```
-
-### Checkpoints
-
-| Trigger | Position | Behavior |
-|---------|----------|----------|
-| Spec->Impl transition | QUALITY-001 completed | Display checkpoint, pause for user |
-| Complexity routing | PLAN-001 completed | Display routing decision, continue |
-| Parallel merge | All parallel tasks complete | Validate integration, continue |
-| GC loop max | QA-FE max 2 rounds | Stop iteration, report |
-| Pipeline stall | No ready + no running | Report to user |
-
-**Checkpoint Output Template** (QUALITY-001):
-
-```
-[coordinator] ══════════════════════════════════════════
-[coordinator] SPEC PHASE COMPLETE
-[coordinator] Quality Gate: <PASS|REVIEW|FAIL> (<score>%)
-[coordinator]
-[coordinator] Dimension Scores:
-[coordinator]   Completeness:  <bar> <n>%
-[coordinator]   Consistency:   <bar> <n>%
-[coordinator]   Traceability:  <bar> <n>%
-[coordinator]   Depth:         <bar> <n>%
-[coordinator]   Coverage:      <bar> <n>%
-[coordinator]
-[coordinator] Available Actions:
-[coordinator]   resume              -> Proceed to implementation
-[coordinator]   improve             -> Auto-improve weakest dimension
-[coordinator]   revise <TASK-ID>    -> Revise specific document
-[coordinator]   recheck             -> Re-run quality check
-[coordinator]   feedback <text>     -> Inject feedback
-[coordinator] ══════════════════════════════════════════
-```
-
-### Task Metadata Registry
-
-| Task ID | Role | Phase | Dependencies | Discuss | Priority |
-|---------|------|-------|-------------|---------|----------|
-| RESEARCH-001 | analyst | spec | (none) | DISCUSS-001 | P0 |
-| DRAFT-001 | writer | spec | RESEARCH-001 | self-validate | P0 |
-| DRAFT-002 | writer | spec | DRAFT-001 | DISCUSS-002 | P0 |
-| DRAFT-003 | writer | spec | DRAFT-002 | self-validate | P0 |
-| DRAFT-004 | writer | spec | DRAFT-003 | self-validate | P0 |
-| QUALITY-001 | reviewer | spec | DRAFT-004 | DISCUSS-003 | P0 |
-| PLAN-001 | planner | impl | (none or QUALITY-001) | - | P0 |
-| ARCH-001 | architect | impl | PLAN-001 | - | P0 (if High complexity) |
-| ORCH-001 | orchestrator | impl | PLAN-001 or ARCH-001 | - | P0 (if Med/High complexity) |
-| IMPL-001 | executor | impl | PLAN-001 or ORCH-001 | - | P0 |
-| DEV-FE-001 | fe-developer | impl | PLAN-001 or ORCH-001 | - | P0 (parallel with IMPL-001) |
-| TEST-001 | tester | impl | IMPL-001 | - | P1 |
-| QA-FE-001 | fe-qa | impl | DEV-FE-001 | - | P1 (parallel with TEST-001) |
-| REVIEW-001 | reviewer | impl | IMPL-001 | - | P1 |
-| SECURITY-001 | security-expert | impl | IMPL-001 | - | P0 (if injected) |
-| PERF-001 | performance-optimizer | impl | IMPL-001 | - | P1 (if injected) |
-| DATA-001 | data-engineer | impl | PLAN-001 | - | P0 (if injected, parallel) |
-| DEVOPS-001 | devops-engineer | impl | IMPL-001 | - | P1 (if injected) |
-| ML-001 | ml-engineer | impl | PLAN-001 | - | P0 (if injected, parallel) |
-
---
-
-## v3 Artifact Contract
-
-All workers generate `artifact-manifest.json` alongside 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:
-
-| Status | Action |
-|--------|--------|
-| `passed` | Spawn next worker |
-| `failed` | Block spawn, trigger fix loop |
-| `pending` | Wait or prompt manual validation |
-
-### Artifact Registry
-
-Coordinator maintains in-memory artifact registry for automatic discovery:
-
-```json
-{
-  "artifacts": {
-    "<artifact-id>": {
-      "manifest": { ... },
-      "discovered_at": "timestamp",
-      "consumed_by": ["<role-name>"]
-    }
-  }
-}
-```
-
-Workers read `context-artifacts.json` in Phase 2 to discover upstream artifacts automatically.
-
---
-
-## Session Directory
-
-```
-.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
-
-## Shared Resources
-
-| Resource | Path | Usage |
-|----------|------|-------|
-| Document Standards | [specs/document-standards.md](specs/document-standards.md) | YAML frontmatter, naming, structure |
-| Quality Gates | [specs/quality-gates.md](specs/quality-gates.md) | Per-phase quality gates |
-| Team Config | [specs/team-config.json](specs/team-config.json) | Role registry, pipeline definitions |
-| Artifact Contract | [specs/artifact-contract-spec.md](specs/artifact-contract-spec.md) | Artifact manifest schema |
-| Role Library | [specs/role-library/](specs/role-library/) | Dynamic role definitions |
-| Product Brief Template | [templates/product-brief.md](templates/product-brief.md) | DRAFT-001 |
-| Requirements Template | [templates/requirements-prd.md](templates/requirements-prd.md) | DRAFT-002 |
-| Architecture Template | [templates/architecture-doc.md](templates/architecture-doc.md) | DRAFT-003 |
-| Epics Template | [templates/epics-template.md](templates/epics-template.md) | DRAFT-004 |
-| Discuss Subagent | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | 3-round discuss protocol |
-| Explorer Subagent | [subagents/explorer-subagent.md](subagents/explorer-subagent.md) | Shared exploration with cache |
-| Doc Generator Subagent | [subagents/doc-generator-subagent.md](subagents/doc-generator-subagent.md) | Template-based doc generation |
-
-## Error Handling
+### Error Handling

 | Scenario | Resolution |
 |----------|------------|
 | Unknown command | Error with available command list |
 | Role spec file not found | Error with expected path |
-| Command file not found | Fallback to inline execution |
-| Discuss subagent fails | Worker proceeds without discuss, logs warning |
-| Fast-advance spawns wrong task | Coordinator reconciles on next callback |
 | Artifact validation fails | Block downstream, trigger fix loop |
 | Dynamic role injection fails | Log warning, continue with core roles |
-| Priority conflict | P0 > P1 > P2, FIFO within same priority |
 | Parallel merge timeout | Report stall, prompt user intervention |
+
+## Reference Documents
+
+For detailed information, see:
+
+- [specs/core-concepts.md](specs/core-concepts.md) - Foundational principles
+- [specs/execution-flow.md](specs/execution-flow.md) - Detailed execution walkthrough
+- [specs/artifact-contract-spec.md](specs/artifact-contract-spec.md) - Artifact manifest specification
+- [specs/quality-gates.md](specs/quality-gates.md) - Quality validation criteria
+- [specs/document-standards.md](specs/document-standards.md) - Document formatting standards
+- [roles/coordinator/role.md](roles/coordinator/role.md) - Coordinator specification
+- [roles/README.md](roles/README.md) - Role directory guide