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.

.claude/skills/brainstorm/README.md

@@ -0,0 +1,177 @@
+# Brainstorm Skill
+
+Unified brainstorming skill combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis into a single entry point with two operational modes.
+
+## Key Features
+
+- **Dual-Mode Operation**: Auto mode (full pipeline) and single role mode (individual analysis)
+- **Interactive Framework Generation**: Seven-phase workflow for guidance specification
+- **Parallel Role Analysis**: Concurrent execution of multiple role perspectives
+- **Cross-Role Synthesis**: Integration of insights into feature specifications
+- **SPEC.md Quality Standards**: Guidance specification includes Concepts & Terminology, Non-Goals, RFC 2119 constraints
+- **Template-Driven Role Analysis**: system-architect produces Data Model, State Machine, Error Handling, Observability, Configuration Model, Boundary Scenarios
+- **Automated Quality Gates**: Validation agents ensure outputs meet quality standards
+- **Session Continuity**: All phases share state via workflow-session.json
+- **Progressive Loading**: Phase documents loaded on-demand via Ref markers
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    /brainstorm                                │
+│         Unified Entry Point + Interactive Routing             │
+└───────────────────────┬─────────────────────────────────────┘
+                        │
+              ┌─────────┴─────────┐
+              ↓                   ↓
+    ┌─────────────────┐  ┌──────────────────┐
+    │   Auto Mode     │  │ Single Role Mode │
+    │  (自动模式)      │  │ (单角色分析模式)   │
+    └────────┬────────┘  └────────┬─────────┘
+             │                    │
+    ┌────────┼────────┐          │
+    ↓        ↓        ↓          ↓
+ Phase 2  Phase 3  Phase 4    Phase 3
+Artifacts  N×Role  Synthesis  1×Role
+ (7步)    Analysis  (8步)    Analysis
+           并行               (4步)
+```
+
+### Execution Flow
+
+**Auto Mode**:
+1. **Phase 1**: Mode detection and parameter parsing
+2. **Phase 1.5**: Terminology & Boundary Definition (extract terms, collect Non-Goals)
+3. **Phase 2**: Interactive Framework Generation (7 sub-phases)
+   - Context collection → Topic analysis → Role selection → Role questions → Conflict resolution → Final check → Generate specification
+   - **Phase 5**: Generate guidance-specification.md with Concepts & Terminology, Non-Goals, RFC 2119 constraints
+4. **Phase 3**: Parallel Role Analysis (N concurrent role analyses)
+   - Template-driven analysis with quality validation
+   - system-architect includes: Data Model, State Machine, Error Handling, Observability, Configuration Model, Boundary Scenarios
+5. **Phase 4**: Synthesis Integration (6 sub-phases)
+   - Discovery → File discovery → Cross-role analysis → User interaction → Spec generation → Finalization
+
+**Single Role Mode**:
+1. **Phase 1**: Mode detection and parameter parsing
+2. **Phase 3**: Single role analysis (4 sub-phases)
+   - Detection → Context → Agent → Validation
+
+## Usage
+
+### Auto Mode
+
+```bash
+# Full pipeline with default settings
+/brainstorm "Build real-time collaboration platform"
+
+# Auto-select mode with specific role count
+/brainstorm -y "GOAL: Build platform SCOPE: 100 users" --count 5
+
+# With style skill for UI designer
+/brainstorm "Design payment system" --style-skill material-design
+```
+
+### Single Role Mode
+
+```bash
+# Analyze with specific role
+/brainstorm system-architect --session WFS-xxx
+
+# With interactive questions
+/brainstorm ux-expert --include-questions
+
+# Update existing analysis
+/brainstorm ui-designer --session WFS-xxx --update --style-skill material-design
+
+# Skip questions (use defaults)
+/brainstorm product-manager --skip-questions
+```
+
+## Available Roles
+
+| Role ID | Title | Focus Area |
+|---------|-------|------------|
+| `data-architect` | 数据架构师 | Data models, storage strategies, data flow |
+| `product-manager` | 产品经理 | Product strategy, roadmap, prioritization |
+| `product-owner` | 产品负责人 | Backlog management, user stories, acceptance criteria |
+| `scrum-master` | 敏捷教练 | Process facilitation, impediment removal |
+| `subject-matter-expert` | 领域专家 | Domain knowledge, business rules, compliance |
+| `system-architect` | 系统架构师 | Technical architecture, scalability, integration |
+| `test-strategist` | 测试策略师 | Test strategy, quality assurance |
+| `ui-designer` | UI设计师 | Visual design, mockups, design systems |
+| `ux-expert` | UX专家 | User research, information architecture, journey |
+
+## Output Files
+
+```
+.workflow/active/WFS-{topic}/
+├── workflow-session.json              # Session metadata
+├── .process/
+│   └── context-package.json           # Phase 0 output
+└── .brainstorming/
+    ├── guidance-specification.md      # Framework with terminology, non-goals
+    ├── feature-index.json             # Feature index
+    ├── synthesis-changelog.md         # Synthesis decisions
+    ├── feature-specs/                 # Feature specifications
+    │   ├── F-001-{slug}.md
+    │   └── F-00N-{slug}.md
+    ├── specs/
+    │   └── terminology-template.json  # Terminology glossary schema
+    ├── templates/
+    │   └── role-templates/
+    │       └── system-architect-template.md  # System architect analysis template
+    ├── agents/
+    │   └── role-analysis-reviewer-agent.md   # Role analysis validation agent
+    ├── {role}/                        # Role analyses (immutable)
+    │   ├── {role}-context.md          # Q&A responses
+    │   ├── analysis.md                # Main document
+    │   ├── analysis-cross-cutting.md  # Cross-feature
+    │   └── analysis-F-{id}-{slug}.md  # Per-feature
+    └── synthesis-specification.md     # Integration
+```
+
+## Quality Standards
+
+### Guidance Specification
+- **Section 2**: Concepts & Terminology (5-10 core terms with definitions, aliases, categories)
+- **Section 3**: Non-Goals (Out of Scope) with rationale
+- **RFC 2119 Keywords**: All requirements use MUST, SHOULD, MAY
+
+### Role Analysis (system-architect)
+1. **Architecture Overview**: High-level system design
+2. **Data Model**: 3-5 core entities with precise field definitions
+3. **State Machine**: Lifecycle for 1-2 entities with complex workflows
+4. **Error Handling Strategy**: Global + per-component recovery
+5. **Observability Requirements**: Metrics, logs, health checks
+6. **Configuration Model**: All configurable parameters with validation
+7. **Boundary Scenarios**: Concurrency, rate limiting, shutdown, cleanup, scalability, DR
+
+### Quality Validation
+- Template compliance checking
+- RFC 2119 keyword usage verification
+- Diagram syntax validation
+- Section completeness scoring
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `--yes`, `-y` | Auto mode, skip all questions | - |
+| `--count N` | Number of roles to select | 3 |
+| `--session ID` | Use existing session | - |
+| `--update` | Update existing analysis | - |
+| `--include-questions` | Interactive context gathering | - |
+| `--skip-questions` | Use default answers | - |
+| `--style-skill PKG` | Style package for ui-designer | - |
+
+## Follow-up Commands
+
+After brainstorm completes:
+- `/workflow-plan --session {sessionId}` - Generate implementation plan
+- `/workflow:brainstorm:synthesis --session {sessionId}` - Run synthesis standalone
+
+## Related Documentation
+
+- **Template Source**: `~/.ccw/workflows/cli-templates/planning-roles/`
+- **Style SKILL Packages**: `.claude/skills/style-{package-name}/`
+- **Phase Documents**: `phases/01-mode-routing.md`, `phases/02-artifacts.md`, `phases/03-role-analysis.md`, `phases/04-synthesis.md`

.claude/skills/brainstorm/SKILL.md

@@ -49,6 +49,9 @@ Single Role Mode:
 3. **Task Attachment/Collapse**: Sub-tasks attached during phase execution, collapsed after completion
 4. **Session Continuity**: All phases share session state via workflow-session.json
 5. **Auto-Continue Execution**: Phases chain automatically without user intervention between them
+6. **SPEC.md Quality Alignment**: Guidance specification and role analysis follow SPEC.md standards (Concepts & Terminology, Non-Goals, Data Model, State Machine, RFC 2119 constraints)
+7. **Template-Driven Analysis**: Role-specific templates (e.g., system-architect) ensure consistent, high-quality outputs
+8. **Quality Gates**: Automated validation of guidance specification and role analysis against quality standards
 
 ## Auto Mode
 
@@ -73,13 +76,19 @@ Parse arguments, detect mode from flags/parameters, or ask user via AskUserQuest
 
 ### Auto Mode Execution (execution_mode = "auto")
 
+**Phase 1.5: Terminology & Boundary Definition**
+   - Extract 5-10 core domain terms from user input and Phase 1 context
+   - Generate terminology table (term, definition, aliases, category)
+   - Collect Non-Goals via AskUserQuestion (明确排除的范围)
+   - Store to `session.terminology` and `session.non_goals`
+
 #### Phase 2: Interactive Framework Generation
    Ref: phases/02-artifacts.md
 
 Seven-phase interactive workflow: Context collection → Topic analysis → Role selection → Role questions → Conflict resolution → Final check → Generate specification.
 
 **Input**: topic description, --count N, --yes flag
-**Output**: guidance-specification.md, workflow-session.json (selected_roles[], session_id)
+**Output**: guidance-specification.md (with Concepts & Terminology, Non-Goals, RFC 2119 constraints), workflow-session.json (selected_roles[], session_id)
 
 **TodoWrite**: Attach 7 sub-tasks (Phase 0-5), execute sequentially, collapse on completion.
 
@@ -95,6 +104,16 @@ Execute role analysis for EACH selected role in parallel.
 
 For ui-designer: append `--style-skill {package}` if provided.
 
+**Template-Driven Analysis**:
+- Load role-specific template if exists (e.g., `templates/role-templates/system-architect-template.md`)
+- Inject template into agent prompt as required structure
+- For system-architect: MUST include Data Model, State Machine, Error Handling, Observability, Configuration Model, Boundary Scenarios
+
+**Quality Validation**:
+- After analysis generation, invoke `role-analysis-reviewer-agent` to validate against template
+- Check MUST have sections (blocking), SHOULD have sections (warning), quality checks (RFC keywords, valid diagrams)
+- Output validation report with score and recommendations
+
 **TodoWrite**: Attach N parallel sub-tasks, execute concurrently, collapse on completion.
 
 #### Phase 4: Synthesis Integration
@@ -327,6 +346,13 @@ Initial → Phase 1 Mode Routing (completed)
     ├── feature-specs/                 # Feature specs (Phase 4, auto mode, feature_mode)
     │   ├── F-001-{slug}.md
     │   └── F-00N-{slug}.md
+    ├── specs/
+    │   └── terminology-template.json  # Terminology schema
+    ├── templates/
+    │   └── role-templates/
+    │       └── system-architect-template.md  # System architect analysis template
+    ├── agents/
+    │   └── role-analysis-reviewer-agent.md   # Role analysis validation agent
     ├── {role}/                        # Role analyses (IMMUTABLE after Phase 3)
     │   ├── {role}-context.md          # Interactive Q&A responses
     │   ├── analysis.md                # Main/index document

.claude/skills/brainstorm/phases/02-artifacts.md

@@ -117,6 +117,73 @@ AskUserQuestion({
 
 **⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation.
 
+### Phase 1.5: Terminology & Boundary Definition
+
+**Goal**: Extract core terminology and define scope boundaries (Non-Goals)
+
+**Steps**:
+1. Analyze Phase 1 user responses and topic description
+2. Extract 5-10 core domain terms that will be used throughout the specification
+3. Generate terminology clarification questions if needed
+4. Define scope boundaries by identifying what is explicitly OUT of scope
+
+**Terminology Extraction**:
+```javascript
+// Based on Phase 1 context and user input
+const coreTerms = extractTerminology({
+  topic: session.topic,
+  userResponses: session.intent_context,
+  contextPackage: contextPackage // from Phase 0
+});
+
+// Generate terminology table
+const terminologyTable = coreTerms.map(term => ({
+  term: term.canonical,
+  definition: term.definition,
+  aliases: term.alternatives,
+  category: term.category // core|technical|business
+}));
+```
+
+**Non-Goals Definition**:
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "以下哪些是明确 NOT 包含在本次项目范围内的？（可多选）",
+    header: "范围边界 (Non-Goals)",
+    multiSelect: true,
+    options: [
+      { label: "移动端应用", description: "本次只做 Web 端，移动端后续考虑" },
+      { label: "多语言支持", description: "MVP 阶段只支持中文" },
+      { label: "第三方集成", description: "暂不集成外部系统" },
+      { label: "高级分析功能", description: "基础功能优先，分析功能 v2" },
+      { label: "其他（请在后续补充）", description: "用户自定义排除项" }
+    ]
+  }]
+});
+
+// If user selects "其他", follow up with:
+if (selectedNonGoals.includes("其他")) {
+  AskUserQuestion({
+    questions: [{
+      question: "请描述其他明确排除的功能或范围",
+      header: "补充 Non-Goals",
+      multiSelect: false,
+      freeText: true
+    }]
+  });
+}
+
+// Store to session
+session.terminology = terminologyTable;
+session.non_goals = selectedNonGoals.map(ng => ({
+  item: ng.label,
+  rationale: ng.description
+}));
+```
+
+**Output**: Updated `workflow-session.json` with `terminology` and `non_goals` fields
+
 ### Phase 2: Role Selection
 
 **Goal**: User selects roles from intelligent recommendations
@@ -303,11 +370,26 @@ After final clarification, extract implementable feature units from all Phase 1-
 ### Phase 5: Generate Specification
 
 **Steps**:
-1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions` + `feature_list`
+1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions` + `feature_list` + `terminology` + `non_goals`
 2. Transform Q&A to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements
-3. Generate `guidance-specification.md`
+3. Apply RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT) to all behavioral requirements
-4. Update `workflow-session.json` (metadata only)
+4. Generate `guidance-specification.md` with Concepts & Terminology and Non-Goals sections
-5. Validate: No interrogative sentences, all decisions traceable
+5. Update `workflow-session.json` (metadata only)
+6. Validate: No interrogative sentences, all decisions traceable, RFC keywords applied
+
+**RFC 2119 Compliance**:
+
+All behavioral requirements and constraints MUST be expressed using RFC 2119 keywords:
+- **MUST**: Absolute requirement, non-negotiable
+- **MUST NOT**: Absolute prohibition
+- **SHOULD**: Strong recommendation, may be ignored with valid reason
+- **SHOULD NOT**: Strong discouragement
+- **MAY**: Optional, implementer's choice
+
+Example transformations:
+- "用户需要登录" → "The system MUST authenticate users before granting access"
+- "建议使用缓存" → "The system SHOULD cache frequently accessed data"
+- "可以支持 OAuth" → "The system MAY support OAuth2 authentication"
 
 ## Question Guidelines
 
@@ -366,15 +448,43 @@ for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) {
 **CONFIRMED Objectives**: [from topic + Phase 1]
 **CONFIRMED Success Criteria**: [from Phase 1 answers]
 
-## 2-N. [Role] Decisions
+## 2. Concepts & Terminology
+
+**Core Terms**: The following terms are used consistently throughout this specification.
+
+| Term | Definition | Aliases | Category |
+|------|------------|---------|----------|
+${session.terminology.map(t => `| ${t.term} | ${t.definition} | ${t.aliases.join(', ')} | ${t.category} |`).join('\n')}
+
+**Usage Rules**:
+- All documents MUST use the canonical term
+- Aliases are for reference only
+- New terms introduced in role analysis MUST be added to this glossary
+
+## 3. Non-Goals (Out of Scope)
+
+The following are explicitly OUT of scope for this project:
+
+${session.non_goals.map(ng => `- **${ng.item}**: ${ng.rationale}`).join('\n')}
+
+**Rationale**: These exclusions help maintain focus on core objectives and prevent scope creep.
+
+## 4-N. [Role] Decisions
 ### SELECTED Choices
-**[Question topic]**: [User's answer]
+**[Question topic]**: [User's answer with RFC 2119 keywords]
 - **Rationale**: [From option description]
-- **Impact**: [Implications]
+- **Impact**: [Implications with RFC keywords]
+- **Requirement Level**: [MUST/SHOULD/MAY based on criticality]
+
+**Example**:
+- The system MUST authenticate users within 200ms (P99)
+- The system SHOULD cache frequently accessed data
+- The system MAY support OAuth2 providers (Google, GitHub)
 
 ### Cross-Role Considerations
-**[Conflict resolved]**: [Resolution from Phase 4]
+**[Conflict resolved]**: [Resolution from Phase 4 with RFC keywords]
 - **Affected Roles**: [Roles involved]
+- **Decision**: [MUST/SHOULD/MAY statement]
 
 ## Cross-Role Integration
 **CONFIRMED Integration Points**: [API/Data/Auth from multiple roles]

.claude/skills/brainstorm/phases/03-role-analysis.md

@@ -301,6 +301,14 @@ const agentContext = {
   original_topic: original_topic,
   session_id: session_id
 };
+
+// Load role-specific template if exists
+let roleTemplate = null;
+try {
+  roleTemplate = Read(`templates/role-templates/${role_name}-template.md`);
+} catch (e) {
+  // No template, use generic analysis
+}
 ```
 
 **Step 3.3.3: Execute Conceptual Planning Agent**
@@ -362,6 +370,13 @@ UPDATE_MODE: ${update_mode}
    - Command: Read(${brainstorm_dir}/${role_name}/${role_name}-context.md)
    - Output: user_context_answers
 
+${roleTemplate ? `
+5. **load_role_template**
+   - Action: Load role-specific analysis template
+   - Command: Read(templates/role-templates/${role_name}-template.md)
+   - Output: role_specific_template
+` : ''}
+
 5. **${update_mode ? 'load_existing_analysis' : 'skip'}**
    ${update_mode ? `
    - Action: Load existing analysis for incremental update
@@ -378,6 +393,21 @@ ${featureListBlock}
 **Role Focus**: ${roleConfig[role_name].focus_area}
 **Template Integration**: Apply role template guidelines within framework structure
 ${feature_mode ? `**Feature Organization**: Organize analysis by feature points - each feature gets its own sub-document. Cross-cutting concerns go into analysis-cross-cutting.md.` : ''}
+**RFC 2119 Compliance**: Use RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT) to define all behavioral constraints and recommendations. Every technical decision MUST be expressed with appropriate RFC keyword. Distinguish between absolute requirements (MUST) and recommendations (SHOULD).
+
+${roleTemplate ? `
+**ROLE-SPECIFIC TEMPLATE (MUST follow this structure)**:
+${roleTemplate}
+
+Your analysis MUST include all Required Sections from the template above.
+` : ''}
+
+**For system-architect role specifically**:
+- MUST define Data Model for 3-5 core entities with fields, types, constraints, relationships
+- MUST create State Machine for at least 1 entity with complex lifecycle (ASCII diagram + transition table)
+- MUST define Error Handling Strategy with error classification and recovery mechanisms
+- MUST specify Observability Requirements with metrics (at least 5), log events, and health checks
+- All constraints MUST use RFC 2119 keywords (MUST, SHOULD, MAY)
 
 ## Expected Deliverables
 ${feature_mode ? `

.claude/skills/brainstorm/phases/04-synthesis.md

@@ -531,22 +531,32 @@ ${feature_mode ? `
 **Status**: Draft (from synthesis)
 
 ## 1. Requirements Summary
-[Consolidated requirements from all role perspectives]
+[Consolidated requirements from all role perspectives using RFC 2119 keywords]
-- Functional requirements (from product-manager, product-owner)
+- Functional requirements (from product-manager, product-owner) - use MUST/SHOULD/MAY
-- User experience requirements (from ux-expert, ui-designer)
+- User experience requirements (from ux-expert, ui-designer) - use MUST/SHOULD/MAY
-- Technical requirements (from system-architect, data-architect, api-designer)
+- Technical requirements (from system-architect, data-architect, api-designer) - use MUST/SHOULD/MAY
-- Domain requirements (from subject-matter-expert)
+- Domain requirements (from subject-matter-expert) - use MUST/SHOULD/MAY
+
+**Example**:
+- The feature MUST support user authentication via email/password
+- The UI SHOULD provide real-time feedback within 100ms
+- The system MAY cache user preferences for offline access
 
 ## 2. Design Decisions [CORE SECTION]
 [Key architectural and design decisions with rationale - 40%+ of word count]
 For each decision:
-- **Decision**: [What was decided]
+- **Decision**: [What was decided - MUST use RFC 2119 keywords]
 - **Context**: [Why this decision was needed]
 - **Options Considered**: [Alternatives from different roles]
-- **Chosen Approach**: [Selected option with rationale]
+- **Chosen Approach**: [Selected option with rationale using MUST/SHOULD/MAY]
 - **Trade-offs**: [What we gain vs. what we sacrifice]
 - **Source**: [Which role(s) drove this decision]
 
+**RFC 2119 Examples**:
+- "The system MUST authenticate users before granting access"
+- "The feature SHOULD cache frequently accessed data for performance"
+- "The component MAY support OAuth2 authentication as an optional enhancement"
+
 ## 3. Interface Contract
 [API endpoints, data models, component interfaces]
 - External interfaces (API contracts from api-designer)

.claude/skills/brainstorm/specs/terminology-template.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.0",
+  "description": "Terminology glossary schema for brainstorm guidance-specification",
+  "schema": {
+    "terminology": {
+      "type": "array",
+      "items": {
+        "term": "string (required) - canonical term",
+        "definition": "string (required) - concise definition",
+        "aliases": "array of strings - alternative names",
+        "category": "enum: core|technical|business (required)",
+        "first_used_in": "string - source document"
+      }
+    }
+  },
+  "validation_rules": {
+    "min_terms": 5,
+    "max_terms": 20,
+    "term_format": "lowercase, alphanumeric + hyphens",
+    "definition_max_length": 200
+  }
+}

.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>")
-|  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]
 ```
 
-## Role Router
+**Example**:
-
-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**:
 ```
-User provides task description
+Skill(skill="team-lifecycle-v3", args="Implement user authentication with OAuth2")
-  -> 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
 ```
 
-**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 |
+| `check` / `status` | View current execution status |
-| `resume` / `continue` | Check worker states, advance next step |
+| `resume` / `continue` | Advance to next step |
-| `revise <TASK-ID> [feedback]` | Create revision task + cascade downstream |
+| `revise <TASK-ID> [feedback]` | Revise specific task with feedback |
-| `feedback <text>` | Analyze feedback, create targeted revision |
+| `feedback <text>` | Provide feedback for targeted revision |
-| `recheck` | Re-run QUALITY-001 quality check |
+| `recheck` | Re-run quality check |
-| `improve [dimension]` | Auto-improve weakest dimension |
+| `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({
+RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
-  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).`
-})
 ```
+Use for: Documentation, requirements gathering, design work
 
----
+### Impl-only Pipeline (4 tasks)
-
-## Pipeline Definitions
-
-### Spec-only (6 tasks, 3 discuss)
-
 ```
-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
 
-```
+### Dynamic Role Injection
-[Spec pipeline] -> PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 + REVIEW-001
-```
 
-### Enhanced Parallel Pipeline (v3 NEW)
+Specialist roles are automatically injected based on keywords in task description:
 
-```
+- **security**, **vulnerability**, **OWASP** → `security-expert`
-RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> DRAFT-003 -> DRAFT-004 -> QUALITY-001(+D3)
+- **performance**, **optimization**, **bottleneck** → `performance-optimizer`
-                                                                                    |
+- **data**, **pipeline**, **ETL**, **schema** → `data-engineer`
-                                                                                    v
+- **devops**, **CI/CD**, **deployment**, **docker** → `devops-engineer`
-                                                                              PLAN-001 (complexity assessment)
+- **ML**, **model**, **training**, **inference** → `ml-engineer`
-                                                                                    |
-                                                                    +---------------+---------------+
-                                                                    |               |               |
-                                                              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)
-```
 
-### 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 complexity** (1-2 modules) → Direct implementation
-|------------|-------|-------|
+- **Medium complexity** (3-4 modules) → Orchestrated parallel implementation
-| Low (1-2 modules, shallow deps) | Direct IMPL | executor |
+- **High complexity** (5+ modules) → Architecture design + orchestrated implementation
-| Medium (3-4 modules, moderate deps) | Orchestrated IMPL | orchestrator -> executor (parallel) |
-| High (5+ modules, deep deps) | Architecture + Orchestrated IMPL | architect -> orchestrator -> executor (parallel) |
 
-### 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:
+- **Spec Phase Complete** (QUALITY-001): Review specification quality, choose to proceed, improve, or revise
-- security-expert (keyword: security, audit)
+- **Implementation Complete**: Review code quality and test coverage
-- performance-optimizer (keyword: optimize, performance)
 
-Pipeline becomes:
+## Troubleshooting
-```
-PLAN-001 -> IMPL-001 || SECURITY-001 || PERF-001 -> TEST-001 -> REVIEW-001
-```
 
-### 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-*` |
 
-```
+### Error Handling
-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
 
 | 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

.claude/skills/team-lifecycle-v3/roles/README.md

@@ -0,0 +1,232 @@
+# Role Directory Guide
+
+This directory contains all agent role specifications for Team Lifecycle v3.
+
+## Directory Structure
+
+```
+roles/
+├── README.md                    # This file
+├── coordinator/                 # Orchestrator agent
+│   ├── role.md                 # Coordinator specification
+│   └── commands/               # User command handlers
+│       ├── dispatch.md
+│       └── monitor.md
+├── pipeline/                    # Core pipeline roles (always present)
+│   ├── analyst.md              # Research and discovery
+│   ├── writer.md               # Document drafting
+│   ├── planner.md              # Implementation planning
+│   ├── executor.md             # Code implementation
+│   ├── tester.md               # Test generation
+│   ├── reviewer.md             # Quality review
+│   ├── architect.md            # Architecture design (consulting)
+│   ├── fe-developer.md         # Frontend development (consulting)
+│   └── fe-qa.md                # Frontend QA (consulting)
+└── specialists/                 # Specialist roles (dynamically injected)
+    ├── orchestrator.role.md    # Multi-module coordination
+    ├── security-expert.role.md # Security analysis
+    ├── performance-optimizer.role.md # Performance optimization
+    ├── data-engineer.role.md   # Data pipeline work
+    ├── devops-engineer.role.md # DevOps and deployment
+    └── ml-engineer.role.md     # ML/AI implementation
+```
+
+## Role Types
+
+### Coordinator (Orchestrator)
+
+**Location**: `coordinator/`
+
+**Purpose**: Manages workflow orchestration, task dependencies, role injection, and artifact registry.
+
+**Key Responsibilities**:
+- Parse user requests and clarify requirements
+- Create and manage team sessions
+- Analyze complexity and inject specialist roles
+- Create task chains with dependencies
+- Spawn workers and handle callbacks
+- Validate artifacts and advance pipeline
+- Display checkpoints and handle user commands
+
+**Always Present**: Yes
+
+**Spawned By**: Skill invocation
+
+### Pipeline Roles (Core Team)
+
+**Location**: `pipeline/`
+
+**Purpose**: Execute standard development workflow tasks.
+
+**Always Present**: Yes (based on pipeline selection)
+
+**Spawned By**: Coordinator
+
+#### Core Pipeline Roles
+
+| Role | File | Purpose | Task Prefix |
+|------|------|---------|-------------|
+| analyst | `analyst.md` | Research and discovery | RESEARCH-* |
+| writer | `writer.md` | Document drafting | DRAFT-* |
+| planner | `planner.md` | Implementation planning | PLAN-* |
+| executor | `executor.md` | Code implementation | IMPL-* |
+| tester | `tester.md` | Test generation and execution | TEST-* |
+| reviewer | `reviewer.md` | Quality review and improvement | REVIEW-*, QUALITY-*, IMPROVE-* |
+
+#### Consulting Roles
+
+| Role | File | Purpose | Task Prefix | Injection Trigger |
+|------|------|---------|-------------|-------------------|
+| architect | `architect.md` | Architecture design | ARCH-* | High complexity |
+| fe-developer | `fe-developer.md` | Frontend development | DEV-FE-* | Frontend tasks |
+| fe-qa | `fe-qa.md` | Frontend QA | QA-FE-* | Frontend tasks |
+
+### Specialist Roles (Dynamic Injection)
+
+**Location**: `specialists/`
+
+**Purpose**: Provide expert capabilities for specific domains.
+
+**Always Present**: No (injected based on task analysis)
+
+**Spawned By**: Coordinator (after complexity/keyword analysis)
+
+| Role | File | Purpose | Task Prefix | Injection Trigger |
+|------|------|---------|-------------|-------------------|
+| orchestrator | `orchestrator.role.md` | Multi-module coordination | ORCH-* | Medium/High complexity |
+| security-expert | `security-expert.role.md` | Security analysis and audit | SECURITY-* | Keywords: security, vulnerability, OWASP, auth |
+| performance-optimizer | `performance-optimizer.role.md` | Performance optimization | PERF-* | Keywords: performance, optimization, bottleneck |
+| data-engineer | `data-engineer.role.md` | Data pipeline work | DATA-* | Keywords: data, pipeline, ETL, schema |
+| devops-engineer | `devops-engineer.role.md` | DevOps and deployment | DEVOPS-* | Keywords: devops, CI/CD, deployment, docker |
+| ml-engineer | `ml-engineer.role.md` | ML/AI implementation | ML-* | Keywords: ML, model, training, inference |
+
+## Role Specification Format
+
+All role specifications follow this structure:
+
+```markdown
+---
+role: <role-name>
+type: <coordinator|pipeline|specialist>
+task_prefix: <TASK-PREFIX>
+priority: <P0|P1|P2>
+injection_trigger: <always|complexity|keywords>
+---
+
+# Role: <Role Name>
+
+## Purpose
+
+Brief description of role purpose.
+
+## Responsibilities
+
+- Responsibility 1
+- Responsibility 2
+
+## Phase Execution
+
+### Phase 1: Task Discovery
+...
+
+### Phase 2: Context Gathering
+...
+
+### Phase 3: Domain Work
+...
+
+### Phase 4: Artifact Generation
+...
+
+### Phase 5: Reporting
+...
+
+## Tools & Capabilities
+
+- Tool 1
+- Tool 2
+
+## Artifact Contract
+
+Expected artifacts and manifest schema.
+```
+
+## Worker Execution Model
+
+All workers (pipeline and specialist roles) follow the **5-phase execution model**:
+
+1. **Phase 1: Task Discovery** - Read task metadata, understand requirements
+2. **Phase 2: Context Gathering** - Discover upstream artifacts, gather context
+3. **Phase 3: Domain Work** - Execute role-specific work
+4. **Phase 4: Artifact Generation** - Generate deliverables with manifest
+5. **Phase 5: Reporting** - Report completion to coordinator
+
+## CLI Tool Integration
+
+Workers can 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 |
+
+**Note**: Workers CANNOT spawn utility members (explorer, discussant). Only the coordinator can spawn utility members.
+
+## Utility Members (Coordinator-Only)
+
+Utility members are NOT roles but specialized subagents that can only be spawned by the coordinator:
+
+| Utility | Purpose | Callable By |
+|---------|---------|-------------|
+| explorer | Parallel multi-angle exploration | Coordinator only |
+| discussant | Aggregate multi-CLI critique | Coordinator only |
+| doc-generator | Template-based doc generation | Coordinator only |
+
+**Location**: `../subagents/` (not in roles directory)
+
+## Adding New Roles
+
+To add a new specialist role:
+
+1. Create role specification file in `specialists/` directory
+2. Follow the role specification format
+3. Define injection trigger (keywords or complexity)
+4. Update `../specs/team-config.json` role registry
+5. Update coordinator's role injection logic
+6. Test with sample task descriptions
+
+## Role Selection Logic
+
+### Pipeline Selection
+
+Coordinator selects pipeline based on user requirements:
+
+- **Spec-only**: Documentation, requirements, design work
+- **Impl-only**: Quick implementations with clear requirements
+- **Full-lifecycle**: Complete feature development
+
+### Specialist Injection
+
+Coordinator analyzes task description for:
+
+1. **Keywords**: Specific domain terms (security, performance, data, etc.)
+2. **Complexity**: Module count, dependency depth
+3. **Explicit requests**: User mentions specific expertise needed
+
+### Conditional Routing
+
+PLAN-001 assesses complexity and routes to appropriate implementation strategy:
+
+- **Low complexity** → Direct implementation (executor only)
+- **Medium complexity** → Orchestrated implementation (orchestrator + parallel executors)
+- **High complexity** → Architecture + orchestrated implementation (architect + orchestrator + parallel executors)
+
+## Reference Documents
+
+For detailed information, see:
+
+- [../specs/core-concepts.md](../specs/core-concepts.md) - Foundational principles
+- [../specs/execution-flow.md](../specs/execution-flow.md) - Execution walkthrough
+- [../specs/artifact-contract-spec.md](../specs/artifact-contract-spec.md) - Artifact manifest specification
+- [coordinator/role.md](coordinator/role.md) - Coordinator specification

.claude/skills/team-lifecycle-v3/specs/README.md

@@ -0,0 +1,61 @@
+# Specifications Directory
+
+This directory contains all specification documents for Team Lifecycle v3.
+
+## Core Specifications (Mandatory Reading)
+
+| Document | Purpose | When to Read |
+|----------|---------|--------------|
+| [core-concepts.md](core-concepts.md) | Foundational principles: team-worker architecture, artifact contracts, quality gating, dynamic role injection, priority scheduling | **Before using the skill** - P0 Critical |
+| [domain-model.md](domain-model.md) | Core entity definitions (Task, Artifact, Role, Session) with JSON schemas, relationships, and state machines | **Before using the skill** - P0 Critical |
+| [artifact-contract-spec.md](artifact-contract-spec.md) | Artifact manifest schema and validation rules | **Before using the skill** - P0 Critical |
+| [execution-flow.md](execution-flow.md) | End-to-end execution walkthrough with pipeline definitions, beat cycle, conditional routing, and examples | **When understanding workflow** - P1 High |
+
+## Supporting Specifications
+
+| Document | Purpose | When to Read |
+|----------|---------|--------------|
+| [quality-gates.md](quality-gates.md) | Quality validation criteria for each phase | When reviewing quality checkpoints |
+| [document-standards.md](document-standards.md) | Document formatting standards (YAML frontmatter, naming conventions) | When creating new documents |
+| [team-config.json](team-config.json) | Role registry and pipeline definitions (machine-readable) | When modifying role configuration |
+
+## Document Hierarchy
+
+```
+specs/
+├── README.md                       # This file
+├── core-concepts.md                # P0 - Foundational principles
+├── artifact-contract-spec.md       # P0 - Artifact manifest schema
+├── execution-flow.md               # P1 - Execution walkthrough
+├── quality-gates.md                # Supporting - Quality criteria
+├── document-standards.md           # Supporting - Formatting standards
+└── team-config.json                # Supporting - Role registry
+```
+
+## Reading Path
+
+### For New Users
+
+1. **Start here**: [core-concepts.md](core-concepts.md) - Understand the system architecture and principles
+2. **Then read**: [artifact-contract-spec.md](artifact-contract-spec.md) - Learn how artifacts flow between agents
+3. **Finally read**: [execution-flow.md](execution-flow.md) - See how tasks execute end-to-end
+
+### For Developers Extending the Skill
+
+1. Read all core specifications above
+2. Review [quality-gates.md](quality-gates.md) for validation logic
+3. Review [document-standards.md](document-standards.md) for formatting rules
+4. Modify [team-config.json](team-config.json) for role changes
+
+### For Troubleshooting
+
+1. Check [execution-flow.md](execution-flow.md) for pipeline definitions
+2. Check [artifact-contract-spec.md](artifact-contract-spec.md) for validation rules
+3. Check [quality-gates.md](quality-gates.md) for quality criteria
+
+## Cross-References
+
+- **Role specifications**: See [../roles/README.md](../roles/README.md)
+- **Templates**: See [../templates/README.md](../templates/README.md)
+- **Subagents**: See [../subagents/](../subagents/)
+- **Main entry**: See [../SKILL.md](../SKILL.md)

.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 |

.claude/skills/team-lifecycle-v3/specs/domain-model.md

@@ -0,0 +1,619 @@
+# Domain Model
+
+This document defines the core entities, schemas, relationships, and state machines for Team Lifecycle v3.
+
+## 1. Core Entities
+
+### 1.1 Task
+
+A **Task** represents a unit of work assigned to a specific role. Tasks have dependencies, priorities, and lifecycle states.
+
+**Definition**: An atomic work item with a unique identifier, assigned role, execution phase, dependency constraints, and status tracking.
+
+**Fields**:
+- `id` (string): Unique task identifier following pattern `{PREFIX}-{NNN}` (e.g., `IMPL-001`, `TEST-001`)
+- `role` (string): Role name responsible for execution (e.g., `executor`, `tester`, `reviewer`)
+- `phase` (string): Execution phase (`spec`, `impl`, `test`, `review`)
+- `dependencies` (array): List of task IDs that must complete before this task can start (blockedBy)
+- `status` (enum): Current task state (`pending`, `ready`, `in_progress`, `completed`, `failed`)
+- `priority` (enum): Execution priority (`P0`, `P1`, `P2`)
+- `metadata` (object): Additional context (created_at, updated_at, attempt_count, error_message)
+
+### 1.2 Artifact
+
+An **Artifact** represents a deliverable produced by a worker, with validation status and dependency tracking.
+
+**Definition**: A versioned output (document, code, test suite) with a manifest describing its type, creator, validation status, and dependencies.
+
+**Fields**:
+- `artifact_id` (string): Unique artifact identifier (e.g., `product-brief-v1`, `impl-auth-service`)
+- `artifact_type` (string): Type classification (`document`, `code`, `test`, `config`, `report`)
+- `path` (string): File system path relative to session directory
+- `creator_role` (string): Role that produced this artifact
+- `version` (string): Semantic version (e.g., `1.0`, `1.1`)
+- `validation_status` (enum): Validation state (`pending`, `passed`, `failed`)
+- `validation_summary` (string): Human-readable validation result
+- `dependencies` (array): List of artifact IDs this artifact depends on
+- `metadata` (object): Additional context (created_at, task_id, priority, file_size, checksum)
+
+### 1.3 Role
+
+A **Role** defines a specialized agent's capabilities, task prefix, and injection trigger.
+
+**Definition**: A specification for an agent type, including its responsibilities, task naming convention, and conditions for activation.
+
+**Fields**:
+- `name` (string): Role identifier (e.g., `executor`, `security-expert`, `orchestrator`)
+- `type` (enum): Role classification (`coordinator`, `pipeline`, `specialist`, `utility`)
+- `task_prefix` (string): Task ID prefix pattern (e.g., `IMPL-*`, `SECURITY-*`, `ORCH-*`)
+- `injection_trigger` (enum): Activation condition (`always`, `complexity`, `keywords`, `manual`)
+- `injection_criteria` (object): Specific trigger conditions (keywords, complexity_threshold)
+- `capabilities` (array): List of capabilities (e.g., `code_generation`, `security_audit`, `performance_analysis`)
+- `inner_loop` (boolean): Whether role supports iterative refinement
+- `phase_execution` (array): List of execution phases (1-5)
+
+### 1.4 Session
+
+A **Session** represents a complete workflow execution instance with persistent state.
+
+**Definition**: A stateful execution context that tracks all tasks, artifacts, and coordination state for a single workflow run.
+
+**Fields**:
+- `session_id` (string): Unique session identifier (e.g., `TLS-auth-impl-20260305`)
+- `slug` (string): Human-readable short name derived from task description
+- `created_at` (string): ISO8601 timestamp of session creation
+- `updated_at` (string): ISO8601 timestamp of last state change
+- `status` (enum): Session lifecycle state (`created`, `active`, `paused`, `completed`, `archived`, `failed`)
+- `pipeline_type` (enum): Selected pipeline (`spec-only`, `impl-only`, `full-lifecycle`, `enhanced-parallel`)
+- `artifact_registry` (object): Map of artifact_id → Artifact manifest
+- `task_list` (array): Ordered list of Task objects
+- `injected_roles` (array): List of dynamically injected specialist roles
+- `checkpoint_history` (array): Record of user checkpoint interactions
+- `session_directory` (string): File system path to session workspace
+
+---
+
+## 2. Entity Schemas
+
+### 2.1 Task Schema (JSON Schema)
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Task",
+  "required": ["id", "role", "phase", "status", "priority"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z]+-[0-9]{3}$",
+      "description": "Unique task identifier (e.g., IMPL-001)"
+    },
+    "role": {
+      "type": "string",
+      "description": "Role name responsible for execution"
+    },
+    "phase": {
+      "type": "string",
+      "enum": ["spec", "impl", "test", "review"],
+      "description": "Execution phase"
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {"type": "string", "pattern": "^[A-Z]+-[0-9]{3}$"},
+      "default": [],
+      "description": "List of task IDs that must complete first"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "ready", "in_progress", "completed", "failed"],
+      "description": "Current task state"
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["P0", "P1", "P2"],
+      "description": "Execution priority (P0 = highest)"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "created_at": {"type": "string", "format": "date-time"},
+        "updated_at": {"type": "string", "format": "date-time"},
+        "attempt_count": {"type": "integer", "minimum": 0},
+        "error_message": {"type": "string"}
+      }
+    }
+  }
+}
+```
+
+### 2.2 Artifact Schema (JSON Schema)
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Artifact",
+  "required": ["artifact_id", "artifact_type", "path", "creator_role", "validation_status"],
+  "properties": {
+    "artifact_id": {
+      "type": "string",
+      "description": "Unique artifact identifier"
+    },
+    "artifact_type": {
+      "type": "string",
+      "enum": ["document", "code", "test", "config", "report"],
+      "description": "Type classification"
+    },
+    "path": {
+      "type": "string",
+      "description": "File system path relative to session directory"
+    },
+    "creator_role": {
+      "type": "string",
+      "description": "Role that produced this artifact"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$",
+      "description": "Semantic version (e.g., 1.0)"
+    },
+    "validation_status": {
+      "type": "string",
+      "enum": ["pending", "passed", "failed"],
+      "description": "Validation state"
+    },
+    "validation_summary": {
+      "type": "string",
+      "description": "Human-readable validation result"
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {"type": "string"},
+      "default": [],
+      "description": "List of artifact IDs this depends on"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "created_at": {"type": "string", "format": "date-time"},
+        "task_id": {"type": "string", "pattern": "^[A-Z]+-[0-9]{3}$"},
+        "priority": {"type": "string", "enum": ["P0", "P1", "P2"]},
+        "file_size": {"type": "integer", "minimum": 0},
+        "checksum": {"type": "string"}
+      }
+    }
+  }
+}
+```
+
+### 2.3 Role Schema (JSON Schema)
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Role",
+  "required": ["name", "type", "task_prefix", "injection_trigger"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Role identifier"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["coordinator", "pipeline", "specialist", "utility"],
+      "description": "Role classification"
+    },
+    "task_prefix": {
+      "type": "string",
+      "pattern": "^[A-Z]+-\\*$",
+      "description": "Task ID prefix pattern (e.g., IMPL-*)"
+    },
+    "injection_trigger": {
+      "type": "string",
+      "enum": ["always", "complexity", "keywords", "manual"],
+      "description": "Activation condition"
+    },
+    "injection_criteria": {
+      "type": "object",
+      "properties": {
+        "keywords": {"type": "array", "items": {"type": "string"}},
+        "complexity_threshold": {"type": "string", "enum": ["low", "medium", "high"]}
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "List of capabilities"
+    },
+    "inner_loop": {
+      "type": "boolean",
+      "description": "Supports iterative refinement"
+    },
+    "phase_execution": {
+      "type": "array",
+      "items": {"type": "integer", "minimum": 1, "maximum": 5},
+      "description": "Execution phases (1-5)"
+    }
+  }
+}
+```
+
+### 2.4 Session Schema (JSON Schema)
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Session",
+  "required": ["session_id", "slug", "status", "pipeline_type"],
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "pattern": "^TLS-[a-z0-9-]+-[0-9]{8}$",
+      "description": "Unique session identifier"
+    },
+    "slug": {
+      "type": "string",
+      "description": "Human-readable short name"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Session creation timestamp"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Last state change timestamp"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["created", "active", "paused", "completed", "archived", "failed"],
+      "description": "Session lifecycle state"
+    },
+    "pipeline_type": {
+      "type": "string",
+      "enum": ["spec-only", "impl-only", "full-lifecycle", "enhanced-parallel"],
+      "description": "Selected pipeline"
+    },
+    "artifact_registry": {
+      "type": "object",
+      "additionalProperties": {"$ref": "#/definitions/Artifact"},
+      "description": "Map of artifact_id to Artifact manifest"
+    },
+    "task_list": {
+      "type": "array",
+      "items": {"$ref": "#/definitions/Task"},
+      "description": "Ordered list of tasks"
+    },
+    "injected_roles": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Dynamically injected specialist roles"
+    },
+    "checkpoint_history": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "checkpoint_id": {"type": "string"},
+          "timestamp": {"type": "string", "format": "date-time"},
+          "user_action": {"type": "string", "enum": ["resume", "improve", "revise", "recheck", "feedback"]},
+          "context": {"type": "string"}
+        }
+      }
+    },
+    "session_directory": {
+      "type": "string",
+      "description": "File system path to session workspace"
+    }
+  }
+}
+```
+
+---
+
+## 3. Entity Relationships
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          Session                                 │
+│  - session_id                                                    │
+│  - status: created|active|paused|completed|archived|failed       │
+│  - pipeline_type: spec-only|impl-only|full-lifecycle|enhanced    │
+├─────────────────────────────────────────────────────────────────┤
+│  artifact_registry: Map<artifact_id, Artifact>                   │
+│  task_list: Task[]                                               │
+│  injected_roles: string[]                                        │
+│  checkpoint_history: Checkpoint[]                                │
+└──────────────┬──────────────────────────────┬───────────────────┘
+               │                              │
+               │ 1:N                          │ 1:N
+               ▼                              ▼
+       ┌───────────────┐              ┌──────────────┐
+       │   Artifact    │              │     Task     │
+       ├───────────────┤              ├──────────────┤
+       │ artifact_id   │              │ id           │
+       │ artifact_type │              │ role ────────┼──┐
+       │ path          │              │ phase        │  │
+       │ creator_role ─┼──┐           │ dependencies │  │ N:1
+       │ validation_   │  │           │ status       │  │
+       │   status      │  │           │ priority     │  │
+       │ dependencies ─┼──┼───┐       └──────┬───────┘  │
+       └───────────────┘  │   │              │          │
+                          │   │              │ produces │
+                          │   │              │ 1:1      │
+                          │   │              ▼          │
+                          │   │       ┌──────────────┐  │
+                          │   └──────▶│   Artifact   │  │
+                          │           └──────────────┘  │
+                          │                             │
+                          │ N:1                         │
+                          ▼                             ▼
+                   ┌──────────────┐            ┌──────────────┐
+                   │     Role     │            │     Role     │
+                   ├──────────────┤            ├──────────────┤
+                   │ name         │            │ name         │
+                   │ type         │            │ type         │
+                   │ task_prefix  │            │ task_prefix  │
+                   │ injection_   │            │ injection_   │
+                   │   trigger    │            │   trigger    │
+                   │ capabilities │            │ capabilities │
+                   └──────────────┘            └──────────────┘
+```
+
+**Relationship Descriptions**:
+
+1. **Session → Task** (1:N): A session contains multiple tasks in its task_list
+2. **Session → Artifact** (1:N): A session tracks multiple artifacts in its artifact_registry
+3. **Task → Role** (N:1): Each task is assigned to one role for execution
+4. **Task → Artifact** (1:1): Each task produces one primary artifact upon completion
+5. **Task → Task** (N:N): Tasks can depend on other tasks (dependencies field)
+6. **Artifact → Role** (N:1): Each artifact is created by one role (creator_role)
+7. **Artifact → Artifact** (N:N): Artifacts can depend on other artifacts (dependencies field)
+
+---
+
+## 4. State Machines
+
+### 4.1 Task Status State Machine
+
+```
+                    ┌─────────────┐
+                    │   pending   │ (initial state)
+                    └──────┬──────┘
+                           │
+                           │ dependencies met
+                           ▼
+                    ┌─────────────┐
+                    │    ready    │
+                    └──────┬──────┘
+                           │
+                           │ worker spawned
+                           ▼
+                    ┌─────────────┐
+                    │ in_progress │
+                    └──────┬──────┘
+                           │
+                ┌──────────┴──────────┐
+                │                     │
+                │ success             │ failure
+                ▼                     ▼
+         ┌─────────────┐       ┌─────────────┐
+         │  completed  │       │   failed    │
+         └─────────────┘       └──────┬──────┘
+                                      │
+                                      │ retry (attempt_count++)
+                                      ▼
+                               ┌─────────────┐
+                               │   pending   │
+                               └─────────────┘
+```
+
+**State Transitions**:
+- `pending → ready`: All dependencies completed
+- `ready → in_progress`: Worker spawned by coordinator
+- `in_progress → completed`: Worker reports success via SendMessage
+- `in_progress → failed`: Worker reports failure or timeout
+- `failed → pending`: Coordinator triggers retry (with exponential backoff)
+
+**Terminal States**: `completed`
+
+**Retry Logic**: Failed tasks return to `pending` with incremented `attempt_count`. Max retries configurable (default: 3).
+
+### 4.2 Session Lifecycle State Machine
+
+```
+                    ┌─────────────┐
+                    │   created   │ (initial state)
+                    └──────┬──────┘
+                           │
+                           │ first task spawned
+                           ▼
+                    ┌─────────────┐
+                    │    active   │◀──────────┐
+                    └──────┬──────┘           │
+                           │                  │
+                ┌──────────┴──────────┐       │
+                │                     │       │
+                │ user pause          │ resume│
+                ▼                     │       │
+         ┌─────────────┐              │       │
+         │   paused    │──────────────┘       │
+         └─────────────┘                      │
+                                              │
+                    ┌─────────────┐           │
+                    │    active   │───────────┘
+                    └──────┬──────┘
+                           │
+                ┌──────────┴──────────┐
+                │                     │
+                │ all tasks done      │ unrecoverable error
+                ▼                     ▼
+         ┌─────────────┐       ┌─────────────┐
+         │  completed  │       │   failed    │
+         └──────┬──────┘       └──────┬──────┘
+                │                     │
+                │ archive             │ archive
+                ▼                     ▼
+         ┌─────────────┐       ┌─────────────┐
+         │  archived   │       │  archived   │
+         └─────────────┘       └─────────────┘
+```
+
+**State Transitions**:
+- `created → active`: Coordinator spawns first batch of tasks
+- `active → paused`: User issues pause command or checkpoint requires review
+- `paused → active`: User issues resume command
+- `active → completed`: All tasks in task_list reach `completed` status
+- `active → failed`: Unrecoverable error (e.g., circular dependency, resource exhaustion)
+- `completed → archived`: Session archived after retention period
+- `failed → archived`: Failed session archived after investigation
+
+**Terminal States**: `archived`
+
+**Checkpoint Behavior**: Session transitions to `paused` at quality checkpoints (e.g., after QUALITY-001). User actions (`resume`, `improve`, `revise`) transition back to `active`.
+
+### 4.3 Artifact Validation State Machine
+
+```
+                    ┌─────────────┐
+                    │   pending   │ (initial state)
+                    └──────┬──────┘
+                           │
+                           │ validation triggered
+                           ▼
+                    ┌─────────────┐
+                    │  validating │
+                    └──────┬──────┘
+                           │
+                ┌──────────┴──────────┐
+                │                     │
+                │ validation success  │ validation failure
+                ▼                     ▼
+         ┌─────────────┐       ┌─────────────┐
+         │   passed    │       │   failed    │
+         └─────────────┘       └──────┬──────┘
+                                      │
+                                      │ fix applied
+                                      ▼
+                               ┌─────────────┐
+                               │   pending   │
+                               └─────────────┘
+```
+
+**State Transitions**:
+- `pending → validating`: Coordinator triggers validation (e.g., quality gate check)
+- `validating → passed`: Artifact meets quality criteria
+- `validating → failed`: Artifact fails quality criteria
+- `failed → pending`: Worker applies fix and re-submits artifact
+
+**Terminal States**: `passed`
+
+**Validation Gating**: Downstream tasks blocked until upstream artifacts reach `passed` state.
+
+---
+
+## 5. Invariants and Constraints
+
+### 5.1 Task Invariants
+
+1. **Unique Task IDs**: No two tasks in a session can have the same `id`
+2. **Acyclic Dependencies**: Task dependency graph must be a DAG (no cycles)
+3. **Valid Dependencies**: All task IDs in `dependencies` array must exist in session's task_list
+4. **Priority Ordering**: P0 tasks execute before P1, P1 before P2 (within same dependency level)
+5. **Single Active Worker**: A task can only be `in_progress` for one worker at a time
+
+### 5.2 Artifact Invariants
+
+1. **Unique Artifact IDs**: No two artifacts in a session can have the same `artifact_id`
+2. **Valid Creator Role**: `creator_role` must match a defined role in the system
+3. **Path Uniqueness**: No two artifacts can have the same `path` within a session
+4. **Dependency Validity**: All artifact IDs in `dependencies` array must exist in artifact_registry
+
+### 5.3 Session Invariants
+
+1. **Unique Session IDs**: No two sessions can have the same `session_id`
+2. **Monotonic Timestamps**: `updated_at` >= `created_at`
+3. **Task Completeness**: All tasks in `task_list` must reach terminal state before session can be `completed`
+4. **Artifact Registry Consistency**: All artifacts referenced in task metadata must exist in `artifact_registry`
+
+---
+
+## 6. Usage Examples
+
+### 6.1 Creating a Task
+
+```json
+{
+  "id": "IMPL-001",
+  "role": "executor",
+  "phase": "impl",
+  "dependencies": ["PLAN-001"],
+  "status": "pending",
+  "priority": "P0",
+  "metadata": {
+    "created_at": "2026-03-05T10:00:00Z",
+    "updated_at": "2026-03-05T10:00:00Z",
+    "attempt_count": 0
+  }
+}
+```
+
+### 6.2 Creating an Artifact Manifest
+
+```json
+{
+  "artifact_id": "auth-service-impl-v1",
+  "artifact_type": "code",
+  "path": "artifacts/auth-service.ts",
+  "creator_role": "executor",
+  "version": "1.0",
+  "validation_status": "passed",
+  "validation_summary": "Code review passed: 95% test coverage, no security issues",
+  "dependencies": ["auth-service-plan-v1"],
+  "metadata": {
+    "created_at": "2026-03-05T11:30:00Z",
+    "task_id": "IMPL-001",
+    "priority": "P0",
+    "file_size": 15420,
+    "checksum": "sha256:abc123..."
+  }
+}
+```
+
+### 6.3 Session State Example
+
+```json
+{
+  "session_id": "TLS-auth-impl-20260305",
+  "slug": "auth-impl",
+  "created_at": "2026-03-05T09:00:00Z",
+  "updated_at": "2026-03-05T12:00:00Z",
+  "status": "active",
+  "pipeline_type": "impl-only",
+  "artifact_registry": {
+    "auth-service-plan-v1": { ... },
+    "auth-service-impl-v1": { ... }
+  },
+  "task_list": [
+    {"id": "PLAN-001", "status": "completed", ...},
+    {"id": "IMPL-001", "status": "in_progress", ...},
+    {"id": "TEST-001", "status": "pending", ...}
+  ],
+  "injected_roles": ["security-expert"],
+  "checkpoint_history": [],
+  "session_directory": ".workflow/.team/TLS-auth-impl-20260305/"
+}
+```
+
+---
+
+## 7. Cross-References
+
+- **Artifact Contract Specification**: [artifact-contract-spec.md](artifact-contract-spec.md)
+- **Execution Flow**: [execution-flow.md](execution-flow.md)
+- **Core Concepts**: [core-concepts.md](core-concepts.md)
+- **Role Specifications**: [../roles/README.md](../roles/README.md)

.claude/skills/team-lifecycle-v3/specs/execution-flow.md

@@ -0,0 +1,643 @@
+# Execution Flow
+
+This document provides a detailed walkthrough of how tasks flow through the Team Lifecycle v3 system, from initial user request to final completion.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Pipeline Definitions](#pipeline-definitions)
+3. [Execution Lifecycle](#execution-lifecycle)
+4. [Beat-Based Cadence](#beat-based-cadence)
+5. [Conditional Routing](#conditional-routing)
+6. [Dynamic Role Injection](#dynamic-role-injection)
+7. [Quality Checkpoints](#quality-checkpoints)
+8. [Task Metadata Registry](#task-metadata-registry)
+
+## Overview
+
+Team Lifecycle v3 uses an **event-driven, beat-based execution model**:
+
+1. User provides task description
+2. Coordinator clarifies requirements and creates team
+3. Coordinator analyzes complexity and injects specialist roles
+4. Coordinator creates task chain based on pipeline selection
+5. Coordinator spawns first batch of workers (background execution)
+6. Workers execute and report completion via SendMessage callbacks
+7. Coordinator advances pipeline, spawning next ready tasks
+8. Process repeats until pipeline complete
+9. Coordinator generates final report
+
+## Pipeline Definitions
+
+### Spec-only Pipeline (6 tasks, 3 discussions)
+
+For documentation, requirements gathering, and design work.
+
+```
+RESEARCH-001(+D1) → DRAFT-001 → DRAFT-002(+D2) → DRAFT-003 → DRAFT-004 → QUALITY-001(+D3)
+```
+
+**Tasks**:
+- **RESEARCH-001** (analyst): Research and discovery with DISCUSS-001
+- **DRAFT-001** (writer): Product brief with self-validation
+- **DRAFT-002** (writer): Requirements PRD with DISCUSS-002
+- **DRAFT-003** (writer): Architecture document with self-validation
+- **DRAFT-004** (writer): Epics breakdown with self-validation
+- **QUALITY-001** (reviewer): Multi-dimensional quality check with DISCUSS-003
+
+**Checkpoint**: After QUALITY-001, user can review, improve, or revise before proceeding.
+
+### Impl-only Pipeline (4 tasks)
+
+For quick implementations with clear requirements.
+
+```
+PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
+```
+
+**Tasks**:
+- **PLAN-001** (planner): Implementation planning and complexity assessment
+- **IMPL-001** (executor): Code implementation
+- **TEST-001** (tester): Test generation and execution (parallel with REVIEW-001)
+- **REVIEW-001** (reviewer): Code quality review (parallel with TEST-001)
+
+### Full-lifecycle Pipeline (10 tasks, v2 compatible)
+
+Complete feature development from requirements to implementation.
+
+```
+[Spec pipeline] → PLAN-001(blockedBy: QUALITY-001) → IMPL-001 → TEST-001 + REVIEW-001
+```
+
+**Checkpoint**: After QUALITY-001, user reviews spec quality before proceeding to implementation.
+
+### Enhanced Parallel Pipeline (v3 NEW)
+
+Advanced pipeline with conditional routing and parallel execution.
+
+```
+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)
+```
+
+**Key Features**:
+- Conditional routing based on complexity assessment
+- Parallel execution of independent tasks (IMPL-001 || DEV-FE-001)
+- Priority-based scheduling (P0 > P1 > P2)
+- Dynamic specialist role injection
+
+## Execution Lifecycle
+
+### Phase 0: User Request
+
+User invokes the skill with a task description:
+
+```
+Skill(skill="team-lifecycle-v3", args="Implement user authentication with OAuth2")
+```
+
+### Phase 1: Clarification & Team Creation
+
+**Coordinator Actions**:
+1. Parse task description
+2. Ask clarifying questions if needed (via AskUserQuestion)
+3. Determine pipeline type (spec-only, impl-only, full-lifecycle)
+4. Create team session folder: `.workflow/.team/TLS-<slug>-<date>/`
+5. Initialize team via TeamCreate
+
+**Output**: Team session created, requirements clarified
+
+### Phase 2: Complexity Analysis & Role Injection
+
+**Coordinator Actions**:
+1. Analyze task description for keywords
+2. Assess complexity indicators (module count, dependencies)
+3. Inject specialist roles based on triggers:
+   - Security keywords → `security-expert`
+   - Performance keywords → `performance-optimizer`
+   - Data keywords → `data-engineer`
+   - DevOps keywords → `devops-engineer`
+   - ML keywords → `ml-engineer`
+   - High complexity → `orchestrator`, `architect`
+
+**Output**: Role injection plan, updated task chain
+
+### Phase 3: Task Chain Creation
+
+**Coordinator Actions**:
+1. Select pipeline based on requirements
+2. Create task metadata for each step
+3. Assign priorities (P0/P1/P2)
+4. Establish dependencies (blockedBy relationships)
+5. Register tasks via TaskCreate
+
+**Output**: Complete task chain with dependencies
+
+### Phase 4: Worker Spawning & Execution
+
+**Coordinator Actions**:
+1. Find ready tasks (no unmet dependencies)
+2. Sort by priority (P0 > P1 > P2)
+3. Spawn workers via Agent tool (background execution)
+4. Update task status to `in_progress`
+5. Enter idle state (STOP)
+
+**Worker Actions**:
+1. Load role specification
+2. Execute Phase 1-5 (task discovery, domain work, reporting)
+3. Generate artifacts with manifest
+4. Send completion callback to coordinator via SendMessage
+
+**Output**: Workers executing in background
+
+### Phase 5: Callback Handling & Advancement
+
+**Coordinator Actions** (on callback):
+1. Mark completed task
+2. Validate artifact (check manifest validation_status)
+3. Update artifact registry
+4. Find next ready tasks
+5. Check for checkpoints (e.g., QUALITY-001 complete)
+6. If checkpoint: display status, wait for user command
+7. If no checkpoint: spawn next batch, return to idle
+
+**Output**: Pipeline advances, next workers spawned
+
+### Phase 6: Completion & Reporting
+
+**Coordinator Actions** (when all tasks complete):
+1. Generate final report
+2. Summarize artifacts produced
+3. Display completion status
+4. Offer completion actions (archive session, continue work)
+
+**Output**: Final report, session complete
+
+## Beat-Based Cadence
+
+The system uses an **event-driven beat 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
+
+For simple linear successors, workers can spawn the next worker directly:
+
+```
+======================================================================
+  [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
+======================================================================
+```
+
+**Benefits**:
+- Reduces coordinator overhead for simple chains
+- Faster execution for linear pipelines
+- Coordinator still maintains authority via message bus logs
+
+## Conditional Routing
+
+PLAN-001 assesses complexity and routes to appropriate implementation strategy.
+
+### Complexity Assessment Algorithm
+
+**Module Definition**: A **module** is a cohesive unit of code with clear boundaries and a single primary responsibility. Typically corresponds to:
+- A file or class with related functionality
+- A directory containing related files (e.g., `auth/`, `payment/`)
+- A service or component with well-defined interfaces
+
+**Quantifiable Complexity Criteria**:
+
+| Metric | Low | Medium | High |
+|--------|-----|--------|------|
+| **Module Count** | 1-2 modules | 3-5 modules | 6+ modules |
+| **Lines of Code (LOC)** | <500 LOC | 500-2000 LOC | 2000+ LOC |
+| **Dependency Depth** | 1-2 levels | 3-4 levels | 5+ levels |
+| **Responsibilities** | Single responsibility | 2-3 responsibilities | 4+ responsibilities |
+| **Cross-Cutting Concerns** | None | 1-2 (e.g., logging, validation) | 3+ (e.g., auth, caching, monitoring) |
+| **External Integrations** | 0-1 (e.g., database) | 2-3 (e.g., DB, API, cache) | 4+ (e.g., DB, APIs, queues, storage) |
+
+**Complexity Score Calculation** (Pseudocode):
+
+```
+function assessComplexity(plan):
+  score = 0
+
+  // Module count (weight: 3)
+  if plan.module_count >= 6:
+    score += 3 * 3
+  else if plan.module_count >= 3:
+    score += 2 * 3
+  else:
+    score += 1 * 3
+
+  // Lines of code (weight: 2)
+  if plan.estimated_loc >= 2000:
+    score += 3 * 2
+  else if plan.estimated_loc >= 500:
+    score += 2 * 2
+  else:
+    score += 1 * 2
+
+  // Dependency depth (weight: 2)
+  if plan.dependency_depth >= 5:
+    score += 3 * 2
+  else if plan.dependency_depth >= 3:
+    score += 2 * 2
+  else:
+    score += 1 * 2
+
+  // Responsibilities (weight: 1)
+  if plan.responsibilities >= 4:
+    score += 3 * 1
+  else if plan.responsibilities >= 2:
+    score += 2 * 1
+  else:
+    score += 1 * 1
+
+  // Cross-cutting concerns (weight: 1)
+  if plan.cross_cutting_concerns >= 3:
+    score += 3 * 1
+  else if plan.cross_cutting_concerns >= 1:
+    score += 2 * 1
+  else:
+    score += 1 * 1
+
+  // External integrations (weight: 1)
+  if plan.external_integrations >= 4:
+    score += 3 * 1
+  else if plan.external_integrations >= 2:
+    score += 2 * 1
+  else:
+    score += 1 * 1
+
+  // Total score range: 10-30
+  // Low: 10-15, Medium: 16-22, High: 23-30
+
+  if score >= 23:
+    return "High"
+  else if score >= 16:
+    return "Medium"
+  else:
+    return "Low"
+```
+
+**Routing Decision Tree**:
+
+```
+                    ┌─────────────────────┐
+                    │  PLAN-001 Complete  │
+                    │  Assess Complexity  │
+                    └──────────┬──────────┘
+                               │
+                ┌──────────────┼──────────────┐
+                │              │              │
+                ▼              ▼              ▼
+         ┌────────────┐ ┌────────────┐ ┌────────────┐
+         │    Low     │ │   Medium   │ │    High    │
+         │ Score:10-15│ │ Score:16-22│ │ Score:23-30│
+         └──────┬─────┘ └──────┬─────┘ └──────┬─────┘
+                │              │              │
+                ▼              ▼              ▼
+         ┌────────────┐ ┌────────────┐ ┌────────────┐
+         │  IMPL-001  │ │  ORCH-001  │ │  ARCH-001  │
+         │  (direct)  │ │ (parallel) │ │ (design)   │
+         └──────┬─────┘ └──────┬─────┘ └──────┬─────┘
+                │              │              │
+                │              ▼              ▼
+                │       ┌────────────┐ ┌────────────┐
+                │       │ IMPL-001   │ │  ORCH-001  │
+                │       │ IMPL-002   │ │ (parallel) │
+                │       │ IMPL-003   │ └──────┬─────┘
+                │       │ (parallel) │        │
+                │       └──────┬─────┘        ▼
+                │              │       ┌────────────┐
+                │              │       │ IMPL-001   │
+                │              │       │ IMPL-002   │
+                │              │       │ ...        │
+                │              │       │ (parallel) │
+                │              │       └──────┬─────┘
+                │              │              │
+                └──────────────┴──────────────┘
+                               │
+                               ▼
+                        ┌────────────┐
+                        │  TEST-001  │
+                        │ REVIEW-001 │
+                        │ (parallel) │
+                        └────────────┘
+```
+
+### Complexity Assessment Criteria
+
+| Complexity | Module Count | Dependency Depth | Routing Decision |
+|------------|--------------|------------------|------------------|
+| Low | 1-2 modules | Shallow (1-2 levels) | Direct IMPL |
+| Medium | 3-5 modules | Moderate (3-4 levels) | Orchestrated IMPL |
+| High | 6+ modules | Deep (5+ levels) | Architecture + Orchestrated IMPL |
+
+### Routing Paths
+
+#### Low Complexity Route
+
+```
+PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
+```
+
+**Roles**: planner → executor → tester + reviewer
+
+**Use Case**: Simple feature, single module, clear implementation path
+
+#### Medium Complexity Route
+
+```
+PLAN-001 → ORCH-001 → IMPL-001 || IMPL-002 || IMPL-003 → TEST-001 + REVIEW-001
+```
+
+**Roles**: planner → orchestrator → executor (parallel) → tester + reviewer
+
+**Use Case**: Multi-module feature, moderate dependencies, parallel implementation possible
+
+#### High Complexity Route
+
+```
+PLAN-001 → ARCH-001 → ORCH-001 → IMPL-001 || IMPL-002 || ... → TEST-001 + REVIEW-001
+```
+
+**Roles**: planner → architect → orchestrator → executor (parallel) → tester + reviewer
+
+**Use Case**: Complex feature, many modules, deep dependencies, architecture design needed
+
+## Dynamic Role Injection
+
+Specialist roles are automatically injected based on task analysis.
+
+### Injection Triggers
+
+| Trigger | Injected Role | Injection Point | Priority |
+|---------|---------------|-----------------|----------|
+| Keywords: security, vulnerability, OWASP, auth | security-expert | After PLAN-001 | P0 |
+| Keywords: performance, optimization, bottleneck, latency | performance-optimizer | After IMPL-* | P1 |
+| Keywords: data, pipeline, ETL, schema, database | data-engineer | Parallel with IMPL-* | P0 |
+| Keywords: devops, CI/CD, deployment, docker, kubernetes | devops-engineer | After IMPL-* | P1 |
+| Keywords: ML, model, training, inference, AI | ml-engineer | Parallel with IMPL-* | P0 |
+| Complexity: High + multi-module | orchestrator | Replace IMPL-* with ORCH-* | P0 |
+| Complexity: High + deep dependencies | architect | Before ORCH-* | P0 |
+
+### Injection Example
+
+**Task Description**: "Implement user authentication with OAuth2, add security audit, optimize login performance"
+
+**Analysis**:
+- Keywords detected: "authentication", "OAuth2", "security", "audit", "optimize", "performance"
+- Complexity: Medium (3-4 modules)
+
+**Injected Roles**:
+- `security-expert` (keywords: security, audit, authentication)
+- `performance-optimizer` (keywords: optimize, performance)
+
+**Resulting Pipeline**:
+```
+PLAN-001 → IMPL-001 || SECURITY-001 || PERF-001 → TEST-001 → REVIEW-001
+```
+
+## Quality Checkpoints
+
+Checkpoints pause execution for user review and feedback.
+
+### Checkpoint 1: Spec Phase Complete (QUALITY-001)
+
+**Trigger**: QUALITY-001 task completes
+
+**Coordinator Output**:
+```
+[coordinator] ══════════════════════════════════════════
+[coordinator] SPEC PHASE COMPLETE
+[coordinator] Quality Gate: <PASS|REVIEW|FAIL> (<score>%)
+[coordinator]
+[coordinator] Dimension Scores:
+[coordinator]   Completeness:  ████████░░ 80%
+[coordinator]   Consistency:   █████████░ 90%
+[coordinator]   Traceability:  ███████░░░ 70%
+[coordinator]   Depth:         ████████░░ 80%
+[coordinator]   Coverage:      ██████████ 100%
+[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] ══════════════════════════════════════════
+```
+
+**User Actions**:
+- `resume` → Proceed to PLAN-001
+- `improve` → Auto-improve weakest dimension (Traceability in example)
+- `revise DRAFT-003` → Revise architecture document
+- `recheck` → Re-run QUALITY-001
+- `feedback "Add more API examples"` → Targeted revision
+
+### Checkpoint 2: Complexity Routing Decision (PLAN-001)
+
+**Trigger**: PLAN-001 completes with complexity assessment
+
+**Coordinator Output**:
+```
+[coordinator] ══════════════════════════════════════════
+[coordinator] COMPLEXITY ASSESSMENT COMPLETE
+[coordinator] Complexity: Medium (3 modules, moderate dependencies)
+[coordinator] Routing: Orchestrated Implementation
+[coordinator]
+[coordinator] Next Steps:
+[coordinator]   ORCH-001: Coordinate parallel implementation
+[coordinator]   IMPL-001: Core authentication module
+[coordinator]   IMPL-002: OAuth2 integration
+[coordinator]   IMPL-003: Session management
+[coordinator]
+[coordinator] Continuing automatically...
+[coordinator] ══════════════════════════════════════════
+```
+
+**Note**: This checkpoint is informational only; execution continues automatically.
+
+### Checkpoint 3: Parallel Merge (All Parallel Tasks Complete)
+
+**Trigger**: All parallel tasks at same level complete
+
+**Coordinator Actions**:
+1. Validate integration (check for conflicts)
+2. Merge artifacts if needed
+3. Continue to next phase
+
+**Note**: If integration issues detected, coordinator may pause for user intervention.
+
+### Checkpoint 4: Pipeline Stall (No Ready + No Running)
+
+**Trigger**: No tasks ready to execute and no tasks currently running
+
+**Coordinator Output**:
+```
+[coordinator] ══════════════════════════════════════════
+[coordinator] PIPELINE STALLED
+[coordinator] Reason: Circular dependency or missing task
+[coordinator]
+[coordinator] Current State:
+[coordinator]   Completed: 5 tasks
+[coordinator]   Blocked: 2 tasks (waiting on IMPL-001)
+[coordinator]   Running: 0 tasks
+[coordinator]
+[coordinator] Action Required: Check task dependencies
+[coordinator] ══════════════════════════════════════════
+```
+
+**User Actions**: Investigate and resolve dependency issues
+
+## Task Metadata Registry
+
+Complete task metadata for all pipeline tasks.
+
+| Task ID | Role | Phase | Dependencies | Discuss | Priority | Notes |
+|---------|------|-------|-------------|---------|----------|-------|
+| RESEARCH-001 | analyst | spec | (none) | DISCUSS-001 | P0 | Initial research |
+| DRAFT-001 | writer | spec | RESEARCH-001 | self-validate | P0 | Product brief |
+| DRAFT-002 | writer | spec | DRAFT-001 | DISCUSS-002 | P0 | Requirements PRD |
+| DRAFT-003 | writer | spec | DRAFT-002 | self-validate | P0 | Architecture doc |
+| DRAFT-004 | writer | spec | DRAFT-003 | self-validate | P0 | Epics breakdown |
+| QUALITY-001 | reviewer | spec | DRAFT-004 | DISCUSS-003 | P0 | Quality gate |
+| PLAN-001 | planner | impl | (none or QUALITY-001) | - | P0 | Implementation plan |
+| ARCH-001 | architect | impl | PLAN-001 | - | P0 | Architecture design (if High complexity) |
+| ORCH-001 | orchestrator | impl | PLAN-001 or ARCH-001 | - | P0 | Orchestration (if Med/High complexity) |
+| IMPL-001 | executor | impl | PLAN-001 or ORCH-001 | - | P0 | Core implementation |
+| DEV-FE-001 | fe-developer | impl | PLAN-001 or ORCH-001 | - | P0 | Frontend (parallel with IMPL-001) |
+| TEST-001 | tester | impl | IMPL-001 | - | P1 | Test generation |
+| QA-FE-001 | fe-qa | impl | DEV-FE-001 | - | P1 | Frontend QA (parallel with TEST-001) |
+| REVIEW-001 | reviewer | impl | IMPL-001 | - | P1 | Code review |
+| SECURITY-001 | security-expert | impl | IMPL-001 | - | P0 | Security audit (if injected) |
+| PERF-001 | performance-optimizer | impl | IMPL-001 | - | P1 | Performance optimization (if injected) |
+| DATA-001 | data-engineer | impl | PLAN-001 | - | P0 | Data pipeline (if injected, parallel) |
+| DEVOPS-001 | devops-engineer | impl | IMPL-001 | - | P1 | DevOps setup (if injected) |
+| ML-001 | ml-engineer | impl | PLAN-001 | - | P0 | ML implementation (if injected, parallel) |
+
+### Task State Transitions
+
+```
+pending → ready → in_progress → completed
+                              → failed → pending (retry)
+```
+
+**States**:
+- `pending`: Task created, waiting for dependencies
+- `ready`: Dependencies met, ready to execute
+- `in_progress`: Worker spawned, executing
+- `completed`: Worker finished successfully
+- `failed`: Worker encountered error (triggers retry)
+
+### Dependency Resolution
+
+**Rules**:
+1. Task becomes `ready` when all `blockedBy` tasks are `completed`
+2. Coordinator checks dependencies on each beat
+3. Failed tasks block downstream until retry succeeds
+4. Parallel tasks (no dependencies) execute simultaneously
+
+## Execution Examples
+
+### Example 1: Simple Implementation (Low Complexity)
+
+**Task**: "Add logging to user service"
+
+**Pipeline**: Impl-only
+```
+PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
+```
+
+**Execution**:
+1. Beat 1: Spawn PLAN-001 (planner)
+2. Beat 2: PLAN-001 completes → Spawn IMPL-001 (executor)
+3. Beat 3: IMPL-001 completes → Spawn TEST-001 + REVIEW-001 (parallel)
+4. Beat 4: Both complete → Generate report
+
+**Duration**: ~4 beats
+
+### Example 2: Full Lifecycle with Specialist Injection (High Complexity)
+
+**Task**: "Implement user authentication with OAuth2, add security audit, optimize login performance"
+
+**Pipeline**: Full-lifecycle with injections
+```
+RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
+  → PLAN-001 → ARCH-001 → ORCH-001 → IMPL-001 || SECURITY-001 || PERF-001
+  → TEST-001 → REVIEW-001
+```
+
+**Execution**:
+1. Beat 1-6: Spec phase (RESEARCH → DRAFT-* → QUALITY)
+2. Checkpoint: User reviews spec quality, chooses `resume`
+3. Beat 7: Spawn PLAN-001 (planner)
+4. Beat 8: PLAN-001 completes (High complexity) → Spawn ARCH-001 (architect)
+5. Beat 9: ARCH-001 completes → Spawn ORCH-001 (orchestrator)
+6. Beat 10: ORCH-001 completes → Spawn IMPL-001 || SECURITY-001 || PERF-001 (parallel, P0)
+7. Beat 11: All parallel tasks complete → Spawn TEST-001 (P1)
+8. Beat 12: TEST-001 completes → Spawn REVIEW-001 (P1)
+9. Beat 13: REVIEW-001 completes → Generate report
+
+**Duration**: ~13 beats + 1 checkpoint
+
+### Example 3: Spec-only with Revision Loop
+
+**Task**: "Design API for payment processing"
+
+**Pipeline**: Spec-only
+```
+RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
+```
+
+**Execution**:
+1. Beat 1-6: Spec phase completes
+2. Checkpoint: User reviews, quality score 65% (FAIL)
+3. User: `improve` → Auto-improve weakest dimension (Traceability)
+4. Beat 7: Spawn IMPROVE-001 (reviewer)
+5. Beat 8: IMPROVE-001 completes → Spawn QUALITY-001 (recheck)
+6. Beat 9: QUALITY-001 completes, quality score 85% (PASS)
+7. Checkpoint: User reviews, chooses `resume` → Generate report
+
+**Duration**: ~9 beats + 2 checkpoints

.claude/skills/team-lifecycle-v3/templates/README.md

@@ -0,0 +1,78 @@
+# Templates Directory
+
+This directory contains document templates used by workers during execution.
+
+## Available Templates
+
+| Template | Used By | Task | Purpose |
+|----------|---------|------|---------|
+| [product-brief.md](product-brief.md) | writer | DRAFT-001 | Product vision and high-level requirements |
+| [requirements-prd.md](requirements-prd.md) | writer | DRAFT-002 | Detailed product requirements document |
+| [architecture-doc.md](architecture-doc.md) | writer | DRAFT-003 | System architecture and design decisions |
+| [epics-template.md](epics-template.md) | writer | DRAFT-004 | Epic breakdown and user stories |
+
+## Template Structure
+
+All templates follow this structure:
+
+```markdown
+---
+title: <Document Title>
+type: <product-brief|requirements|architecture|epics>
+version: 1.0
+created: <ISO8601 timestamp>
+author: <role-name>
+---
+
+# <Document Title>
+
+## Section 1
+...
+
+## Section 2
+...
+```
+
+## Usage
+
+### By Workers
+
+Workers load templates during Phase 3 (Domain Work):
+
+1. Read template file
+2. Fill in sections based on research/context
+3. Generate artifact with proper frontmatter
+4. Create artifact manifest
+
+### By Coordinator
+
+Coordinator references templates when creating tasks:
+
+- DRAFT-001 → `product-brief.md`
+- DRAFT-002 → `requirements-prd.md`
+- DRAFT-003 → `architecture-doc.md`
+- DRAFT-004 → `epics-template.md`
+
+## Template Customization
+
+To customize templates:
+
+1. Modify template files in this directory
+2. Ensure YAML frontmatter structure is preserved
+3. Update section headings as needed
+4. Test with a sample task
+
+## Document Standards
+
+All generated documents must follow:
+
+- **Formatting**: See [../specs/document-standards.md](../specs/document-standards.md)
+- **Quality criteria**: See [../specs/quality-gates.md](../specs/quality-gates.md)
+- **Artifact contract**: See [../specs/artifact-contract-spec.md](../specs/artifact-contract-spec.md)
+
+## Cross-References
+
+- **Specifications**: See [../specs/README.md](../specs/README.md)
+- **Role specifications**: See [../roles/README.md](../roles/README.md)
+- **Writer role**: See [../roles/pipeline/writer.md](../roles/pipeline/writer.md)
+- **Main entry**: See [../SKILL.md](../SKILL.md)

.claude/skills/workflow-lite-execute/SKILL.md

@@ -1,9 +1,10 @@
-# Phase 2: Lite-Execute
+---
+name: workflow-lite-execute
+description: Lightweight execution engine - multi-mode input, task grouping, batch execution, code review, and project state sync
+allowed-tools: Skill, Agent, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep
+---
 
-> **📌 COMPACT SENTINEL [Phase 2: Lite-Execute]**
+# Workflow-Lite-Execute
-> This phase contains 6 execution steps (Step 1 — 6).
-> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
-> Recovery: `Read("phases/02-lite-execute.md")`
 
 Complete execution engine: multi-mode input, task grouping, batch execution, code review, and development index update.
 
@@ -28,16 +29,16 @@ Flexible task execution command supporting three input modes: in-memory plan (fr
 <input>                    Task description string, or path to file (required)
 ```
 
-Mode 1 (In-Memory) is triggered by lite-plan direct handoff when `executionContext` is available.
+Mode 1 (In-Memory) is triggered by workflow-lite-plan direct handoff when `executionContext` is available.
 Workflow preferences (`autoYes`) are passed from SKILL.md via `workflowPreferences` context variable.
 
 ## Input Modes
 
 ### Mode 1: In-Memory Plan
 
-**Trigger**: Called by lite-plan direct handoff after Phase 4 approval (executionContext available)
+**Trigger**: Called by workflow-lite-plan direct handoff after Phase 4 approval (executionContext available)
 
-**Input Source**: `executionContext` global variable set by lite-plan
+**Input Source**: `executionContext` global variable set by workflow-lite-plan
 
 **Content**: Complete execution context (see Data Structures section)
 
@@ -120,7 +121,7 @@ fileContent = Read(filePath)
 try {
   jsonData = JSON.parse(fileContent)
 
-  // Check if plan.json from lite-plan session (two-layer format: task_ids[])
+  // Check if plan.json from workflow-lite-plan session (two-layer format: task_ids[])
   if (jsonData.summary && jsonData.approach && jsonData.task_ids) {
     planObject = jsonData
     originalUserInput = jsonData.summary
@@ -209,7 +210,7 @@ Output:
 **Operations**:
 - Initialize result tracking for multi-execution scenarios
 - Set up `previousExecutionResults` array for context continuity
-- **In-Memory Mode**: Echo execution strategy from lite-plan for transparency
+- **In-Memory Mode**: Echo execution strategy from workflow-lite-plan for transparency
 
 ```javascript
 // Initialize result tracking
@@ -681,7 +682,7 @@ Summary 取值优先级：`originalUserInput` → `planObject.summary` → git l
 
 ## Best Practices
 
-**Input Modes**: In-memory (lite-plan), prompt (standalone), file (JSON/text)
+**Input Modes**: In-memory (workflow-lite-plan), prompt (standalone), file (JSON/text)
 **Task Grouping**: Based on explicit depends_on only; independent tasks split by executor, each batch runs as separate CLI instance
 **Execution**: Independent task batches launch concurrently via single Claude message with multiple tool calls (one tool call per batch)
 

.claude/skills/workflow-lite-plan/SKILL.md

@@ -1,4 +1,10 @@
-# LP-Phase 1: Lite-Plan
+---
+name: workflow-lite-plan
+description: Lightweight planning skill - task analysis, multi-angle exploration, clarification, adaptive planning, confirmation, and execution handoff
+allowed-tools: Skill, Agent, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Workflow-Lite-Plan
 
 Complete planning pipeline: task analysis, multi-angle exploration, clarification, adaptive planning, confirmation, and execution handoff.
 
@@ -6,7 +12,7 @@ Complete planning pipeline: task analysis, multi-angle exploration, clarificatio
 
 ## Overview
 
-Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and delegates execution to Phase 2 (lite-execute).
+Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and delegates execution to workflow-lite-execute skill.
 
 **Core capabilities:**
 - Intelligent task analysis with automatic exploration detection
@@ -14,7 +20,7 @@ Intelligent lightweight planning command with dynamic workflow adaptation based
  - Interactive clarification after exploration to gather missing information
  - Adaptive planning: Low complexity → Direct Claude; Medium/High → cli-lite-planning-agent
  - Two-step confirmation: plan display → multi-dimensional input collection
-- Execution handoff with complete context to lite-execute
+ - Execution handoff with complete context to workflow-lite-execute
 
 ## Context Isolation
 
@@ -91,7 +97,7 @@ LP-Phase 4: Confirmation & Selection
 
 LP-Phase 5: Execute
    ├─ Build executionContext (plan + explorations + clarifications + selections)
-   └─ Direct handoff: Read phases/02-lite-execute.md → Execute with executionContext (Mode 1)
+   └─ Direct handoff: Skill("lite-execute") → Execute with executionContext (Mode 1)
 ```
 
 ## Implementation
@@ -764,11 +770,9 @@ executionContext = {
 **Step 5.2: Handoff**
 
 ```javascript
-// ⚠️ COMPACT PROTECTION: Phase 2 instructions MUST persist in memory throughout execution.
+// Invoke lite-execute skill with executionContext
-// If compact compresses Phase 2 content at any point, re-read this file before continuing.
+Skill("lite-execute")
-// See SKILL.md "Compact Protection" section for full protocol.
+// executionContext is passed as global variable (Mode 1: In-Memory Plan)
-Read("phases/02-lite-execute.md")
-// Execute Phase 2 with executionContext (Mode 1: In-Memory Plan)
 ```
 
 ## Session Folder Structure
@@ -815,4 +819,4 @@ Read("phases/02-lite-execute.md")
 
 ## Next Phase
 
-After LP-Phase 5 handoff, execution continues in [Phase 2: Lite-Execute](02-lite-execute.md).
+After LP-Phase 5 handoff, execution continues in the workflow-lite-execute skill.

.claude/skills/workflow-lite-planex/SKILL.md

@@ -1,131 +0,0 @@
----
-name: workflow-lite-planex
-description: Lightweight planning and execution skill (Phase 1: plan, Phase 2: execute). Triggers on "workflow-lite-planex".
-allowed-tools: Skill, Agent, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep
----
-
-# Workflow Lite-Planex
-
-Unified lightweight planning and execution skill (planex = plan + execute). Phase 1 handles planning pipeline, Phase 2 handles execution.
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────┐
-│  SKILL.md (Prompt Enhancement + Dispatch)             │
-│  → Enhance prompt → Dispatch to Phase 1 (lite-plan)  │
-└──────────────────────┬──────────────────────────────┘
-                       │
-                       ↓
-     ┌───────────┐           ┌───────────┐
-     │ lite-plan │           │lite-execute│
-     │ Phase 1   │──handoff─→│ Phase 2    │
-     │ Plan      │           │ Execute    │
-     └───────────┘           └───────────┘
-```
-
-## Compact Recovery (Phase Persistence)
-
-Multi-phase execution (lite-plan → lite-execute) spans long conversations that trigger context compression. Uses **双重保险**: TodoWrite 跟踪 active phase 保护其不被压缩，sentinel 作为兜底。
-
-> **⚠️ COMPACT DIRECTIVE**: Context compression MUST check TodoWrite phase status.
-> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
-> Only compress phases marked `completed` or `pending`.
-
-## Routing
-
-Trigger `workflow-lite-planex` → dispatches to Phase 1 (lite-plan). Phase 1 internally hands off to Phase 2 (lite-execute) after plan confirmation.
-
-| Phase | Document | Description |
-|-------|----------|-------------|
-| Phase 1 | [phases/01-lite-plan.md](phases/01-lite-plan.md) | Planning pipeline (explore → plan → confirm → handoff to Phase 2) |
-| Phase 2 | [phases/02-lite-execute.md](phases/02-lite-execute.md) | Execution engine (internal, called by Phase 1 LP-Phase 5) |
-
-## Interactive Preference Collection
-
-Before dispatching, collect workflow preferences via AskUserQuestion:
-
-```javascript
-// ★ 统一 auto mode 检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
-const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
-
-if (autoYes) {
-  // 自动模式：跳过所有询问，使用默认值
-  workflowPreferences = { autoYes: true, forceExplore: false }
-} else if (mode === 'plan') {
-  const prefResponse = AskUserQuestion({
-    questions: [
-      {
-        question: "是否跳过所有确认步骤（自动模式）？",
-        header: "Auto Mode",
-        multiSelect: false,
-        options: [
-          { label: "Interactive (Recommended)", description: "交互模式，包含确认步骤" },
-          { label: "Auto", description: "跳过所有确认，自动执行" }
-        ]
-      },
-      {
-        question: "是否强制执行代码探索阶段？",
-        header: "Exploration",
-        multiSelect: false,
-        options: [
-          { label: "Auto-detect (Recommended)", description: "智能判断是否需要探索" },
-          { label: "Force explore", description: "强制执行代码探索" }
-        ]
-      }
-    ]
-  })
-  workflowPreferences = {
-    autoYes: prefResponse.autoMode === 'Auto',
-    forceExplore: prefResponse.exploration === 'Force explore'
-  }
-}
-```
-
-**workflowPreferences** is passed to phase execution as context variable, referenced as `workflowPreferences.autoYes` and `workflowPreferences.forceExplore` within phases.
-
-## Prompt Enhancement
-
-After collecting preferences, enhance context and dispatch:
-
-```javascript
-// Step 1: Load project context via ccw spec
-Bash('ccw spec load --category planning')
-
-// Step 2: Log available context
-console.log('Project context loaded via: ccw spec load --category planning')
-
-// Step 3: Dispatch to Phase 1 (workflowPreferences available as context)
-// Read phases/01-lite-plan.md and execute
-// Phase 1 internally hands off to Phase 2 (lite-execute) after plan confirmation
-```
-
-## Execution Flow
-
-### Plan Mode
-
-```
-1. Collect preferences via AskUserQuestion (autoYes, forceExplore)
-2. Enhance prompt with project context availability
-3. Read phases/01-lite-plan.md
-4. Execute lite-plan pipeline (LP-Phase 1-5 within the phase doc)
-5. lite-plan LP-Phase 5 directly reads and executes Phase 2 (lite-execute) with executionContext
-```
-
-## Usage
-
-Task description provided as arguments → interactive preference collection → planning pipeline → execution.
-
-**Plan mode only**: lite-plan handles planning (Phase 1) and automatically hands off to lite-execute (Phase 2) for execution. There is no standalone execute mode.
-
-## Phase Reference Documents
-
-| Phase | Document | Purpose | Compact |
-|-------|----------|---------|---------|
-| 1 | [phases/01-lite-plan.md](phases/01-lite-plan.md) | Complete planning pipeline: exploration, clarification, planning, confirmation, handoff | TodoWrite 驱动 |
-| 2 | [phases/02-lite-execute.md](phases/02-lite-execute.md) | Complete execution engine: input modes, task grouping, batch execution, code review | TodoWrite 驱动 + 🔄 sentinel |
-
-**Compact Rules**:
-1. **TodoWrite `in_progress`** → 保留完整内容，禁止压缩
-2. **TodoWrite `completed`** → 可压缩为摘要
-3. **🔄 sentinel fallback** → Phase 2 包含 compact sentinel；若 compact 后仅存 sentinel 而无完整 Step 协议，必须立即 `Read("phases/02-lite-execute.md")` 恢复

.claude/skills/workflow-multi-cli-plan/SKILL.md

@@ -1,123 +0,0 @@
----
-name: workflow-multi-cli-plan
-description: Multi-CLI collaborative planning and execution skill with integrated execution phase. Triggers on "workflow-multi-cli-plan".
-allowed-tools: Skill, Agent, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context
----
-
-# Workflow Multi-CLI Plan
-
-Unified multi-CLI collaborative planning and execution skill. Routes to multi-cli-plan (ACE context + multi-CLI discussion + plan generation) which then hands off to lite-execute (Phase 2) internally for execution.
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  SKILL.md (Router + Prompt Enhancement)                  │
-│  → Enhance prompt → Dispatch to Phase 1                 │
-└──────────────────────┬──────────────────────────────────┘
-                       │
-                       ↓
-     ┌──────────────┐        ┌───────────┐
-     │multi-cli-plan│        │lite-execute│
-     │   Phase 1    │─handoff→│  Phase 2   │
-     │  Plan+Exec   │        │ (internal) │
-     └──────────────┘        └───────────┘
-```
-
-## Mode Detection & Routing
-
-```javascript
-const args = $ARGUMENTS
-const mode = 'plan'  // workflow-multi-cli-plan always starts with planning
-```
-
-**Routing Table**:
-
-| Trigger | Mode | Phase Document | Description |
-|---------|------|----------------|-------------|
-| `workflow-multi-cli-plan` | plan | [phases/01-multi-cli-plan.md](phases/01-multi-cli-plan.md) | Multi-CLI collaborative planning (ACE context → discussion → plan → execute) |
-
-## Interactive Preference Collection
-
-Before dispatching, collect workflow preferences via AskUserQuestion:
-
-```javascript
-// ★ 统一 auto mode 检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
-const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
-
-if (autoYes) {
-  // 自动模式：跳过所有询问，使用默认值
-  workflowPreferences = { autoYes: true }
-} else if (mode === 'plan') {
-  const prefResponse = AskUserQuestion({
-    questions: [
-      {
-        question: "是否跳过所有确认步骤（自动模式）？",
-        header: "Auto Mode",
-        multiSelect: false,
-        options: [
-          { label: "Interactive (Recommended)", description: "交互模式，包含确认步骤" },
-          { label: "Auto", description: "跳过所有确认，自动执行" }
-        ]
-      }
-    ]
-  })
-  workflowPreferences = {
-    autoYes: prefResponse.autoMode === 'Auto'
-  }
-}
-```
-
-**workflowPreferences** is passed to phase execution as context variable, referenced as `workflowPreferences.autoYes` within phases.
-
-## Prompt Enhancement
-
-After collecting preferences, enhance context and dispatch:
-
-```javascript
-// Step 1: Load project context via ccw spec
-Bash('ccw spec load --category planning')
-
-// Step 2: Log available context
-console.log('Project context loaded via: ccw spec load --category planning')
-
-// Step 3: Dispatch to Phase 1 (workflowPreferences available as context)
-// Read phases/01-multi-cli-plan.md and execute
-// Phase 1 internally hands off to Phase 2 (lite-execute) after plan approval
-```
-
-## Compact Recovery (Phase Persistence)
-
-Multi-phase execution (multi-cli-plan → lite-execute) spans long conversations. Uses **双重保险**: TodoWrite 跟踪 active phase 保护其不被压缩，sentinel 作为兜底。
-
-> **⚠️ COMPACT DIRECTIVE**: Context compression MUST check TodoWrite phase status.
-> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
-> Only compress phases marked `completed` or `pending`.
-
-## Execution Flow
-
-### Plan Mode (workflow-multi-cli-plan)
-
-```
-1. Collect preferences via AskUserQuestion (autoYes)
-2. Enhance prompt with project context availability
-3. Read phases/01-multi-cli-plan.md
-4. Execute multi-cli-plan pipeline (Phase 1-5 within the phase doc)
-5. Phase 5 directly reads and executes Phase 2 (lite-execute) with executionContext
-```
-
-## Usage
-
-Task description provided as arguments → interactive preference collection → multi-CLI planning pipeline → internal execution handoff to Phase 2 (lite-execute).
-
-## Phase Reference Documents
-
-| Phase | Document | Purpose | Compact |
-|-------|----------|---------|---------|
-| 1 | [phases/01-multi-cli-plan.md](phases/01-multi-cli-plan.md) | Complete multi-CLI planning pipeline: ACE context, iterative discussion, options, user decision, plan generation, handoff | TodoWrite 驱动 |
-| 2 | [phases/02-lite-execute.md](phases/02-lite-execute.md) | Complete execution engine: input modes, task grouping, batch execution, code review | TodoWrite 驱动 + 🔄 sentinel |
-
-**Compact Rules**:
-1. **TodoWrite `in_progress`** → 保留完整内容，禁止压缩
-2. **TodoWrite `completed`** → 可压缩为摘要
-3. **🔄 sentinel fallback** → Phase 2 包含 compact sentinel；若 compact 后仅存 sentinel 而无完整 Step 协议，必须立即 `Read("phases/02-lite-execute.md")` 恢复

agents/role-analysis-reviewer-agent.md

@@ -0,0 +1,97 @@
+# Role Analysis Reviewer Agent
+
+Validates role analysis outputs against role-specific templates and quality standards.
+
+## Objective
+
+Ensure role analysis documents meet SPEC.md-level precision and completeness.
+
+## Input
+
+- Role name (e.g., system-architect, product-manager)
+- Role analysis document path (e.g., `.brainstorming/system-architect/analysis.md`)
+- Role template path (e.g., `templates/role-templates/system-architect-template.md`)
+
+## Validation Rules
+
+### For system-architect
+
+**MUST have (blocking)**:
+- [ ] Data Model section with at least 1 entity definition
+- [ ] Entity table with fields: name, type, constraint, description
+- [ ] State Machine section with at least 1 lifecycle diagram
+- [ ] State transition table with: from, event, to, side effects
+- [ ] Error Handling Strategy section
+- [ ] Observability Requirements section with at least 3 metrics
+
+**SHOULD have (warning)**:
+- [ ] Data Model with 3-5 entities
+- [ ] Relationships defined between entities
+- [ ] Indexes specified for entities
+- [ ] State Machine with error recovery paths
+- [ ] Circuit Breaker configuration
+- [ ] Health check endpoints defined
+
+**Quality checks**:
+- [ ] All constraints use RFC 2119 keywords
+- [ ] State diagram is valid ASCII art
+- [ ] Metrics have type (Counter/Gauge/Histogram) specified
+- [ ] Error handling has timeout values
+- [ ] No generic placeholders like "[TODO]" or "[TBD]"
+
+## Output
+
+JSON validation report:
+
+```json
+{
+  "role": "system-architect",
+  "document": ".brainstorming/system-architect/analysis.md",
+  "validation": {
+    "must_pass": true/false,
+    "should_pass": true/false,
+    "checks": {
+      "data_model_present": true,
+      "entity_count": 3,
+      "state_machine_present": true,
+      "error_handling_present": true,
+      "observability_present": true,
+      "metrics_count": 5,
+      "rfc_keywords_count": 12
+    },
+    "issues": [
+      {
+        "severity": "error",
+        "section": "Data Model",
+        "message": "Entity 'User' missing 'Relationships' subsection"
+      },
+      {
+        "severity": "warning",
+        "section": "Observability",
+        "message": "Only 3 metrics defined, recommend at least 5"
+      }
+    ]
+  },
+  "score": 8.5,
+  "recommendation": "Pass with minor improvements"
+}
+```
+
+## Execution
+
+```javascript
+Bash({
+  command: `ccw cli -p "Validate role analysis document against template.
+
+ROLE: ${roleName}
+DOCUMENT: ${analysisDoc}
+TEMPLATE: ${roleTemplate}
+
+VALIDATION RULES:
+${validationRules}
+
+OUTPUT: JSON validation report with must_pass, should_pass, checks, issues, score, recommendation
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+```

ccw/frontend/package.json

@@ -49,6 +49,7 @@
     "react-router-dom": "^6.28.0",
     "recharts": "^2.15.0",
     "rehype-highlight": "^7.0.2",
+    "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "sonner": "^2.0.7",
     "tailwind-merge": "^2.5.0",

ccw/frontend/src/components/a2ui/A2UIPopupCard.tsx

@@ -172,6 +172,8 @@ function MarkdownContent({ content, className }: MarkdownContentProps) {
 function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
   const { formatMessage } = useIntl();
   const sendA2UIAction = useNotificationStore((state) => state.sendA2UIAction);
+  const addToast = useNotificationStore((state) => state.addToast);
+  const [actionError, setActionError] = useState<string | null>(null);
 
   // Detect question type
   const questionType = useMemo(() => detectQuestionType(surface), [surface]);
@@ -216,16 +218,14 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
   const message = getTextContent(messageComponent);
   const description = getTextContent(descriptionComponent);
 
-  // Separate body components (interactive elements) from action buttons
+  // Separate body components from action buttons
   const { bodyComponents, actionButtons } = useMemo(() => {
     const body: SurfaceComponent[] = [];
     const actions: SurfaceComponent[] = [];
 
     for (const comp of surface.components) {
-      // Skip title, message, description
       if (['title', 'message', 'description'].includes(comp.id)) continue;
 
-      // Separate action buttons (confirm, cancel, submit)
       if (isActionButton(comp) && ['confirm-btn', 'cancel-btn', 'submit-btn'].includes(comp.id)) {
         actions.push(comp);
       } else {
@@ -236,7 +236,6 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
     return { bodyComponents: body, actionButtons: actions };
   }, [surface.components]);
 
-  // Create surfaces for body and actions
   const bodySurface: SurfaceUpdate = useMemo(
     () => ({ ...surface, components: bodyComponents }),
     [surface, bodyComponents]
@@ -247,7 +246,6 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
     [surface, actionButtons]
   );
 
-  // Handle "Other" text change
   const handleOtherTextChange = useCallback(
     (value: string) => {
       setOtherText(value);
@@ -263,7 +261,8 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
 
   // Handle A2UI actions
   const handleAction = useCallback(
-    (actionId: string, params?: Record<string, unknown>) => {
+    async (actionId: string, params?: Record<string, unknown>) => {
+      setActionError(null);
       // Track "Other" selection state
       if (actionId === 'select' && params?.value === '__other__') {
         setOtherSelected(true);
@@ -274,16 +273,20 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
         setOtherSelected((prev) => !prev);
       }
 
-      // Send action to backend via WebSocket
+      try {
-      sendA2UIAction(actionId, surface.surfaceId, params);
+        await sendA2UIAction(actionId, surface.surfaceId, params);
 
-      // Check if this action should close the dialog
         const resolvingActions = ['confirm', 'cancel', 'submit', 'answer'];
         if (resolvingActions.includes(actionId)) {
           onClose();
         }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'An unknown error occurred.';
+        setActionError(errorMessage);
+        addToast('error', 'Action Failed', errorMessage);
+      }
     },
-    [sendA2UIAction, surface.surfaceId, onClose]
+    [sendA2UIAction, surface.surfaceId, onClose, addToast]
   );
 
   // Handle dialog close (ESC key or overlay click)
@@ -299,7 +302,6 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
     [sendA2UIAction, surface.surfaceId, onClose]
   );
 
-  // Determine dialog width based on question type
   const dialogWidth = useMemo(() => {
     switch (questionType) {
       case 'multi-select':
@@ -311,33 +313,27 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
     }
   }, [questionType]);
 
-  // Check if this question type supports "Other" input
   const hasOtherOption = questionType === 'select' || questionType === 'multi-select';
 
   return (
     <Dialog open onOpenChange={handleOpenChange}>
       <DialogContent
         className={cn(
-          // Base styles
           dialogWidth,
           'max-h-[80vh] overflow-y-auto',
           'bg-card p-6 rounded-xl shadow-lg border border-border/50',
-          // Animation classes
           'data-[state=open]:animate-in data-[state=closed]:animate-out',
           'data-[state=open]:fade-in-0 data-[state=closed]:fade-out-0',
           'data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95',
           'data-[state=open]:duration-300 data-[state=closed]:duration-200'
         )}
         onInteractOutside={(e) => {
-          // Prevent closing when clicking outside - only cancel button can close
           e.preventDefault();
         }}
         onEscapeKeyDown={(e) => {
-          // Prevent closing with ESC key - only cancel button can close
           e.preventDefault();
         }}
       >
-        {/* Header */}
         <DialogHeader className="space-y-2 pb-4">
           <DialogTitle className="text-lg font-semibold leading-tight">{title}</DialogTitle>
           {message && (
@@ -352,15 +348,18 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
           )}
         </DialogHeader>
 
-        {/* Body - Interactive elements */}
+        {actionError && (
+          <div className="bg-destructive/10 border border-destructive/20 text-destructive-foreground text-sm rounded-md p-3 my-2">
+            {actionError}
+          </div>
+        )}
+
         {bodyComponents.length > 0 && (
           <div className={cn(
             'py-3',
-            // Add specific styling for multi-select (checkbox list)
             questionType === 'multi-select' && 'space-y-2 max-h-[300px] overflow-y-auto px-1'
           )}>
             {questionType === 'multi-select' ? (
-              // Render each checkbox individually for better control
               bodyComponents.map((comp) => (
                 <div key={comp.id} className="py-1">
                   <A2UIRenderer
@@ -372,7 +371,6 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
             ) : (
               <A2UIRenderer surface={bodySurface} onAction={handleAction} />
             )}
-            {/* "Other" text input — shown when Other is selected */}
             {hasOtherOption && (
               <OtherInput
                 visible={otherSelected}
@@ -383,7 +381,6 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
           </div>
         )}
 
-        {/* Countdown for auto-selection */}
         {remaining !== null && defaultLabel && (
           <div className="text-xs text-muted-foreground text-center pt-2">
             {remaining > 0
@@ -392,7 +389,6 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) {
           </div>
         )}
 
-        {/* Footer - Action buttons */}
         {actionButtons.length > 0 && (
           <DialogFooter className="pt-4">
             <div className="flex flex-row justify-end gap-3">

ccw/frontend/src/components/deepwiki/DocumentViewer.tsx

@@ -6,6 +6,9 @@
 import { useMemo, useState, useCallback } from 'react';
 import { useIntl } from 'react-intl';
 import { FileText, Hash, Clock, Sparkles, AlertCircle, Link2, Check } from 'lucide-react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import rehypeSanitize from 'rehype-sanitize';
 import { Card } from '@/components/ui/Card';
 import { Badge } from '@/components/ui/Badge';
 import { cn } from '@/lib/utils';
@@ -21,52 +24,20 @@ export interface DocumentViewerProps {
   filePath?: string;
 }
 
-/**
- * Simple markdown-to-HTML converter for basic formatting
- */
-function markdownToHtml(markdown: string): string {
-  let html = markdown;
-
-  // Code blocks
-  html = html.replace(/```(\w+)?\n([\s\S]*?)```/g, '<pre class="code-block"><code class="language-$1">$2</code></pre>');
-
-  // Inline code
-  html = html.replace(/`([^`]+)`/g, '<code class="inline-code">$1</code>');
-
-  // Headers
-  html = html.replace(/^### (.*$)/gm, '<h3 class="doc-h3">$1</h3>');
-  html = html.replace(/^## (.*$)/gm, '<h2 class="doc-h2">$1</h2>');
-  html = html.replace(/^# (.*$)/gm, '<h1 class="doc-h1">$1</h1>');
-
-  // Bold and italic
-  html = html.replace(/\*\*\*(.*?)\*\*\*/g, '<strong><em>$1</em></strong>');
-  html = html.replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>');
-  html = html.replace(/\*(.*?)\*/g, '<em>$1</em>');
-
-  // Links
-  html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2" class="doc-link">$1</a>');
-
-  // Line breaks
-  html = html.replace(/\n\n/g, '</p><p class="doc-paragraph">');
-  html = html.replace(/\n/g, '<br />');
-
-  return `<div class="doc-content"><p class="doc-paragraph">${html}</p></div>`;
-}
-
 /**
  * Get symbol type icon
  */
-function getSymbolTypeIcon(type: string): string {
+function getSymbolTypeIcon(type: string): { symbol: string; label: string } {
-  const icons: Record<string, string> = {
+  const icons: Record<string, { symbol: string; label: string }> = {
-    function: 'λ',
+    function: { symbol: 'λ', label: 'Function' },
-    async_function: 'λ',
+    async_function: { symbol: 'λ', label: 'Async Function' },
-    class: '◇',
+    class: { symbol: '◇', label: 'Class' },
-    method: '◈',
+    method: { symbol: '◈', label: 'Method' },
-    interface: '△',
+    interface: { symbol: '△', label: 'Interface' },
-    variable: '•',
+    variable: { symbol: '•', label: 'Variable' },
-    constant: '⬡',
+    constant: { symbol: '⬡', label: 'Constant' },
   };
-  return icons[type] || '•';
+  return icons[type] || { symbol: '•', label: 'Symbol' };
 }
 
 /**
@@ -85,6 +56,79 @@ function getSymbolTypeColor(type: string): string {
   return colors[type] || 'text-gray-500';
 }
 
+/**
+ * Markdown components with custom styling
+ */
+const markdownComponents = {
+  h1: ({ children }: { children?: React.ReactNode }) => (
+    <h1 className="text-xl font-bold mt-6 mb-3 text-foreground">{children}</h1>
+  ),
+  h2: ({ children }: { children?: React.ReactNode }) => (
+    <h2 className="text-lg font-semibold mt-5 mb-2 text-foreground">{children}</h2>
+  ),
+  h3: ({ children }: { children?: React.ReactNode }) => (
+    <h3 className="text-base font-semibold mt-4 mb-2 text-foreground">{children}</h3>
+  ),
+  p: ({ children }: { children?: React.ReactNode }) => (
+    <p className="mb-3 leading-relaxed text-foreground/90">{children}</p>
+  ),
+  a: ({ href, children }: { href?: string; children?: React.ReactNode }) => (
+    <a
+      href={href}
+      className="text-primary hover:underline"
+      target={href?.startsWith('http') ? '_blank' : undefined}
+      rel={href?.startsWith('http') ? 'noopener noreferrer' : undefined}
+    >
+      {children}
+    </a>
+  ),
+  code: ({ className, children }: { className?: string; children?: React.ReactNode }) => {
+    const isInline = !className;
+    if (isInline) {
+      return (
+        <code className="bg-muted px-1.5 py-0.5 rounded text-sm font-mono">
+          {children}
+        </code>
+      );
+    }
+    return (
+      <code className={cn('block bg-muted p-3 rounded-md text-sm font-mono overflow-x-auto', className)}>
+        {children}
+      </code>
+    );
+  },
+  pre: ({ children }: { children?: React.ReactNode }) => (
+    <pre className="bg-muted p-4 rounded-lg my-4 overflow-x-auto">
+      {children}
+    </pre>
+  ),
+  ul: ({ children }: { children?: React.ReactNode }) => (
+    <ul className="list-disc list-inside mb-3 space-y-1">{children}</ul>
+  ),
+  ol: ({ children }: { children?: React.ReactNode }) => (
+    <ol className="list-decimal list-inside mb-3 space-y-1">{children}</ol>
+  ),
+  blockquote: ({ children }: { children?: React.ReactNode }) => (
+    <blockquote className="border-l-4 border-primary/50 pl-4 my-4 italic text-muted-foreground">
+      {children}
+    </blockquote>
+  ),
+  table: ({ children }: { children?: React.ReactNode }) => (
+    <div className="overflow-x-auto my-4">
+      <table className="min-w-full border border-border">{children}</table>
+    </div>
+  ),
+  thead: ({ children }: { children?: React.ReactNode }) => (
+    <thead className="bg-muted">{children}</thead>
+  ),
+  th: ({ children }: { children?: React.ReactNode }) => (
+    <th className="border border-border px-3 py-2 text-left font-medium">{children}</th>
+  ),
+  td: ({ children }: { children?: React.ReactNode }) => (
+    <td className="border border-border px-3 py-2">{children}</td>
+  ),
+};
+
 export function DocumentViewer({
   doc,
   content,
@@ -222,7 +266,9 @@ export function DocumentViewer({
           {/* Symbols list */}
           {symbols.length > 0 && (
             <div className="mb-6 flex flex-wrap gap-2">
-              {symbols.map(symbol => (
+              {symbols.map(symbol => {
+                const iconInfo = getSymbolTypeIcon(symbol.type);
+                return (
                   <a
                     key={symbol.name}
                     href={`#${symbol.anchor.replace('#', '')}`}
@@ -231,18 +277,20 @@ export function DocumentViewer({
                       'bg-muted/50 hover:bg-muted transition-colors',
                       getSymbolTypeColor(symbol.type)
                     )}
+                    aria-label={`${iconInfo.label}: ${symbol.name}`}
                   >
-                  <span>{getSymbolTypeIcon(symbol.type)}</span>
+                    <span aria-hidden="true">{iconInfo.symbol}</span>
                     <span>{symbol.name}</span>
                     <Badge variant="outline" className="text-[10px] px-1">
                       {symbol.type}
                     </Badge>
                   </a>
-              ))}
+                );
+              })}
             </div>
           )}
 
-          {/* Document sections */}
+          {/* Document sections with safe markdown rendering */}
           <div className="space-y-6">
             {symbolSections.map((section, idx) => (
               <section
@@ -250,18 +298,24 @@ export function DocumentViewer({
                 id={section.name.toLowerCase().replace(/\s+/g, '-')}
                 className="scroll-mt-4"
               >
-                <div
+                <ReactMarkdown
-                  className="prose prose-sm dark:prose-invert max-w-none"
+                  remarkPlugins={[remarkGfm]}
-                  dangerouslySetInnerHTML={{ __html: markdownToHtml(section.content) }}
+                  rehypePlugins={[rehypeSanitize]}
-                />
+                  components={markdownComponents}
+                >
+                  {section.content}
+                </ReactMarkdown>
               </section>
             ))}
 
             {symbolSections.length === 0 && content && (
-              <div
+              <ReactMarkdown
-                className="prose prose-sm dark:prose-invert max-w-none"
+                remarkPlugins={[remarkGfm]}
-                dangerouslySetInnerHTML={{ __html: markdownToHtml(content) }}
+                rehypePlugins={[rehypeSanitize]}
-              />
+                components={markdownComponents}
+              >
+                {content}
+              </ReactMarkdown>
             )}
           </div>
         </div>
@@ -273,8 +327,10 @@ export function DocumentViewer({
               <Hash className="w-3 h-3" />
               {formatMessage({ id: 'deepwiki.viewer.toc', defaultMessage: 'Symbols' })}
             </h4>
-            <nav className="space-y-1">
+            <nav className="space-y-1" role="list" aria-label="Document symbols">
-              {symbols.map(symbol => (
+              {symbols.map(symbol => {
+                const iconInfo = getSymbolTypeIcon(symbol.type);
+                return (
                   <div
                     key={symbol.name}
                     className="group flex items-center gap-1"
@@ -286,9 +342,11 @@ export function DocumentViewer({
                         'text-muted-foreground hover:text-foreground hover:bg-muted/50',
                         'font-mono'
                       )}
+                      role="listitem"
+                      aria-label={`${iconInfo.label}: ${symbol.name}`}
                     >
-                    <span className={cn('mr-1', getSymbolTypeColor(symbol.type))}>
+                      <span className={cn('mr-1', getSymbolTypeColor(symbol.type))} aria-hidden="true">
-                      {getSymbolTypeIcon(symbol.type)}
+                        {iconInfo.symbol}
                       </span>
                       {symbol.name}
                     </a>
@@ -301,47 +359,25 @@ export function DocumentViewer({
                           ? 'text-green-500'
                           : 'text-muted-foreground hover:text-foreground'
                       )}
-                    title={copiedSymbol === symbol.name ? 'Copied!' : 'Copy deep link'}
+                      aria-label={
+                        copiedSymbol === symbol.name
+                          ? formatMessage({ id: 'deepwiki.viewer.linkCopied', defaultMessage: 'Link copied' })
+                          : formatMessage({ id: 'deepwiki.viewer.copyLink', defaultMessage: 'Copy deep link to {name}' }, { name: symbol.name })
+                      }
                     >
                       {copiedSymbol === symbol.name ? (
-                      <Check className="w-3 h-3" />
+                        <Check className="w-3 h-3" aria-hidden="true" />
                       ) : (
-                      <Link2 className="w-3 h-3" />
+                        <Link2 className="w-3 h-3" aria-hidden="true" />
                       )}
                     </button>
                   </div>
-              ))}
+                );
+              })}
             </nav>
           </div>
         )}
       </div>
-
-      {/* Styles for rendered markdown */}
-      <style>{`
-        .doc-content { line-height: 1.7; }
-        .doc-paragraph { margin-bottom: 1rem; }
-        .doc-h1 { font-size: 1.5rem; font-weight: 700; margin: 1.5rem 0 1rem; color: var(--foreground); }
-        .doc-h2 { font-size: 1.25rem; font-weight: 600; margin: 1.25rem 0 0.75rem; color: var(--foreground); }
-        .doc-h3 { font-size: 1.1rem; font-weight: 600; margin: 1rem 0 0.5rem; color: var(--foreground); }
-        .doc-link { color: var(--primary); text-decoration: underline; }
-        .inline-code {
-          background: var(--muted);
-          padding: 0.125rem 0.375rem;
-          border-radius: 0.25rem;
-          font-size: 0.85em;
-          font-family: ui-monospace, monospace;
-        }
-        .code-block {
-          background: var(--muted);
-          padding: 1rem;
-          border-radius: 0.5rem;
-          overflow-x: auto;
-          margin: 1rem 0;
-          font-family: ui-monospace, monospace;
-          font-size: 0.85rem;
-          line-height: 1.5;
-        }
-      `}</style>
     </Card>
   );
 }

ccw/frontend/src/components/deepwiki/FileList.tsx

@@ -3,15 +3,16 @@
 // ========================================
 // List of documented files for DeepWiki
 
-import { useState, useMemo } from 'react';
+import { useState, useMemo, useEffect } from 'react';
 import { useIntl } from 'react-intl';
-import { FileText, Search, CheckCircle, Clock, RefreshCw } from 'lucide-react';
+import { FileText, Search, CheckCircle, Clock, RefreshCw, Loader2 } from 'lucide-react';
 import { Card } from '@/components/ui/Card';
 import { Button } from '@/components/ui/Button';
 import { Input } from '@/components/ui/Input';
 import { Badge } from '@/components/ui/Badge';
 import { cn } from '@/lib/utils';
 import type { DeepWikiFile } from '@/hooks/useDeepWiki';
+import { useDebounce } from '@/hooks/useDebounce';
 
 export interface FileListProps {
   files: DeepWikiFile[];
@@ -75,13 +76,23 @@ export function FileList({
 }: FileListProps) {
   const { formatMessage } = useIntl();
   const [searchQuery, setSearchQuery] = useState('');
+  const debouncedSearchQuery = useDebounce(searchQuery, 300);
+  const [isSearching, setIsSearching] = useState(false);
 
   // Filter files by search query
   const filteredFiles = useMemo(() => {
-    if (!searchQuery.trim()) return files;
+    if (!debouncedSearchQuery.trim()) return files;
-    const query = searchQuery.toLowerCase();
+    const query = debouncedSearchQuery.toLowerCase();
     return files.filter(f => f.path.toLowerCase().includes(query));
-  }, [files, searchQuery]);
+  }, [files, debouncedSearchQuery]);
+
+  useEffect(() => {
+    if (searchQuery !== debouncedSearchQuery) {
+      setIsSearching(true);
+    } else {
+      setIsSearching(false);
+    }
+  }, [searchQuery, debouncedSearchQuery]);
 
   // Group files by directory
   const groupedFiles = useMemo(() => {
@@ -143,6 +154,9 @@ export function FileList({
             onChange={(e) => setSearchQuery(e.target.value)}
             className="pl-9 h-8 text-sm"
           />
+          {isSearching && (
+            <Loader2 className="absolute right-3 top-1/2 -translate-y-1/2 w-4 h-4 animate-spin text-muted-foreground" />
+          )}
         </div>
       </div>
 

ccw/frontend/src/components/hook/HookCard.tsx

@@ -3,6 +3,7 @@
 // ========================================
 // Individual hook display card with actions
 
+import { useState } from 'react';
 import { useIntl } from 'react-intl';
 import {
   GitFork,
@@ -16,6 +17,16 @@ import {
 import { Card } from '@/components/ui/Card';
 import { Button } from '@/components/ui/Button';
 import { Badge } from '@/components/ui/Badge';
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from '@/components/ui/AlertDialog';
 import { cn } from '@/lib/utils';
 
 // ========== Types ==========
@@ -166,6 +177,7 @@ export function HookCard({
   onDelete,
 }: HookCardProps) {
   const { formatMessage } = useIntl();
+  const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
 
   // Get translated hook name
   const displayName = getHookDisplayName(hook.name, formatMessage);
@@ -179,12 +191,20 @@ export function HookCard({
   };
 
   const handleDelete = () => {
-    if (confirm(formatMessage({ id: 'cliHooks.actions.deleteConfirm' }, { hookName: hook.name }))) {
+    setShowDeleteConfirm(true);
+  };
+
+  const handleConfirmDelete = () => {
+    setShowDeleteConfirm(false);
     onDelete(hook.name);
-    }
+  };
+
+  const handleCancelDelete = () => {
+    setShowDeleteConfirm(false);
   };
 
   return (
+    <>
     <Card className={cn('overflow-hidden', !hook.enabled && 'opacity-60')}>
       {/* Header */}
       <div className="p-4">
@@ -263,7 +283,7 @@ export function HookCard({
               onClick={handleDelete}
               title={formatMessage({ id: 'common.actions.delete' })}
             >
-              <Trash2 className="w-4 h-4" />
+              <Trash2 className="w-4 h-4 text-destructive" />
             </Button>
             <Button
               variant="ghost"
@@ -317,6 +337,23 @@ export function HookCard({
         </div>
       )}
     </Card>
+
+    {/* Delete Confirmation Dialog */}
+    <AlertDialog open={showDeleteConfirm} onOpenChange={setShowDeleteConfirm}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Delete CLI Hook?</AlertDialogTitle>
+          <AlertDialogDescription>
+            This action cannot be undone. The hook "{displayName}" will be permanently deleted.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel onClick={handleCancelDelete}>Cancel</AlertDialogCancel>
+          <AlertDialogAction onClick={handleConfirmDelete}>Delete</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  </>
   );
 }
 

ccw/frontend/src/components/hook/HookCard.ux.test.tsx

@@ -0,0 +1,280 @@
+// ========================================
+// HookCard UX Tests - Delete Confirmation
+// ========================================
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { IntlProvider } from 'react-intl';
+import { HookCard } from './HookCard';
+import type { HookCardData } from './HookCard';
+
+// Mock translations
+const mockMessages = {
+  'cliHooks.trigger.SessionStart': 'Session Start',
+  'cliHooks.trigger.UserPromptSubmit': 'User Prompt Submit',
+  'cliHooks.trigger.PreToolUse': 'Pre Tool Use',
+  'cliHooks.trigger.PostToolUse': 'Post Tool Use',
+  'cliHooks.trigger.Stop': 'Stop',
+  'cliHooks.trigger.Notification': 'Notification',
+  'cliHooks.trigger.SubagentStart': 'Subagent Start',
+  'cliHooks.trigger.SubagentStop': 'Subagent Stop',
+  'cliHooks.trigger.PreCompact': 'Pre Compact',
+  'cliHooks.trigger.SessionEnd': 'Session End',
+  'cliHooks.trigger.PostToolUseFailure': 'Post Tool Use Failure',
+  'cliHooks.trigger.PermissionRequest': 'Permission Request',
+  'cliHooks.allTools': 'All Tools',
+  'common.status.enabled': 'Enabled',
+  'common.status.disabled': 'Disabled',
+  'common.actions.edit': 'Edit',
+  'common.actions.delete': 'Delete',
+  'cliHooks.actions.enable': 'Enable',
+  'cliHooks.actions.disable': 'Disable',
+  'cliHooks.actions.expand': 'Expand',
+  'cliHooks.actions.collapse': 'Collapse',
+  'cliHooks.form.description': 'Description',
+  'cliHooks.form.matcher': 'Matcher',
+  'cliHooks.form.command': 'Command',
+};
+
+function renderWithIntl(component: React.ReactElement) {
+  return render(
+    <IntlProvider messages={mockMessages} locale="en">
+      {component}
+    </IntlProvider>
+  );
+}
+
+describe('HookCard - Delete Confirmation UX Pattern', () => {
+  const mockHook: HookCardData = {
+    name: 'test-hook',
+    description: 'Test hook description',
+    enabled: true,
+    trigger: 'PreToolUse',
+    matcher: '.*',
+    command: 'echo "test"',
+  };
+
+  const mockHandlers = {
+    onToggleExpand: vi.fn(),
+    onToggle: vi.fn(),
+    onEdit: vi.fn(),
+    onDelete: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should show confirmation dialog when delete button is clicked', async () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    // Click delete button
+    const deleteButton = screen.getByTitle('Delete');
+    fireEvent.click(deleteButton);
+
+    // Verify dialog appears
+    await waitFor(() => {
+      expect(screen.getByText('Delete CLI Hook?')).toBeInTheDocument();
+    });
+  });
+
+  it('should display hook name in confirmation dialog', async () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    fireEvent.click(screen.getByTitle('Delete'));
+
+    await waitFor(() => {
+      const dialog = screen.getByText(/This action cannot be undone/);
+      expect(dialog).toBeInTheDocument();
+      expect(dialog.textContent).toContain('test-hook');
+    });
+  });
+
+  it('should call onDelete when confirm is clicked', async () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    fireEvent.click(screen.getByTitle('Delete'));
+
+    await waitFor(() => {
+      const confirmButton = screen.getByRole('button', { name: /Delete/i });
+      fireEvent.click(confirmButton);
+    });
+
+    expect(mockHandlers.onDelete).toHaveBeenCalledWith('test-hook');
+  });
+
+  it('should NOT call onDelete when cancel is clicked', async () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    fireEvent.click(screen.getByTitle('Delete'));
+
+    await waitFor(() => {
+      const cancelButton = screen.getByRole('button', { name: /Cancel/i });
+      fireEvent.click(cancelButton);
+    });
+
+    expect(mockHandlers.onDelete).not.toHaveBeenCalled();
+  });
+
+  it('should close dialog when cancel is clicked', async () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    fireEvent.click(screen.getByTitle('Delete'));
+
+    await waitFor(() => {
+      expect(screen.getByText('Delete CLI Hook?')).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: /Cancel/i }));
+
+    await waitFor(() => {
+      expect(screen.queryByText('Delete CLI Hook?')).not.toBeInTheDocument();
+    });
+  });
+
+  it('should close dialog after successful deletion', async () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    fireEvent.click(screen.getByTitle('Delete'));
+
+    await waitFor(() => {
+      expect(screen.getByText('Delete CLI Hook?')).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: /Delete/i }));
+
+    await waitFor(() => {
+      expect(screen.queryByText('Delete CLI Hook?')).not.toBeInTheDocument();
+    });
+  });
+
+  it('should have delete button with destructive styling', () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    const deleteButton = screen.getByTitle('Delete');
+    expect(deleteButton).toHaveClass('text-destructive');
+  });
+
+  it('should not show dialog on initial render', () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    expect(screen.queryByText('Delete CLI Hook?')).not.toBeInTheDocument();
+  });
+});
+
+describe('HookCard - State Update UX', () => {
+  const mockHook: HookCardData = {
+    name: 'state-test-hook',
+    enabled: true,
+    trigger: 'SessionStart',
+  };
+
+  const mockHandlers = {
+    onToggleExpand: vi.fn(),
+    onToggle: vi.fn(),
+    onEdit: vi.fn(),
+    onDelete: vi.fn(),
+  };
+
+  it('should call onToggle with correct parameters', () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    const toggleButton = screen.getByTitle('Disable');
+    fireEvent.click(toggleButton);
+
+    expect(mockHandlers.onToggle).toHaveBeenCalledWith('state-test-hook', false);
+  });
+
+  it('should call onEdit when edit button is clicked', () => {
+    renderWithIntl(
+      <HookCard
+        hook={mockHook}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    const editButton = screen.getByTitle('Edit');
+    fireEvent.click(editButton);
+
+    expect(mockHandlers.onEdit).toHaveBeenCalledWith(mockHook);
+  });
+
+  it('should show enabled status badge', () => {
+    renderWithIntl(
+      <HookCard
+        hook={{ ...mockHook, enabled: true }}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    expect(screen.getByText('Enabled')).toBeInTheDocument();
+  });
+
+  it('should show disabled status badge', () => {
+    renderWithIntl(
+      <HookCard
+        hook={{ ...mockHook, enabled: false }}
+        isExpanded={false}
+        {...mockHandlers}
+      />
+    );
+
+    expect(screen.getByText('Disabled')).toBeInTheDocument();
+  });
+});

ccw/frontend/src/components/issue/hub/IssueBoardPanel.tsx

@@ -178,14 +178,19 @@ function buildIssueAutoPrompt(issue: Issue): string {
   );
   return lines.join('\n');
 }
+import { useNotificationStore } from '@/stores';
+
+// ...
 
 export function IssueBoardPanel() {
   const { formatMessage } = useIntl();
   const projectPath = useWorkflowStore(selectProjectPath);
+  const { addToast } = useNotificationStore();
 
   const { issues, isLoading, error } = useIssues();
   const { updateIssue } = useIssueMutations();
-
+  // ...
+}
   const [order, setOrder] = useState<BoardOrder>({});
   const [selectedIssue, setSelectedIssue] = useState<Issue | null>(null);
   const [drawerInitialTab, setDrawerInitialTab] = useState<'overview' | 'terminal'>('overview');
@@ -323,7 +328,9 @@ export function IssueBoardPanel() {
                 // Auto-open terminal panel to show execution output
                 useTerminalPanelStore.getState().openTerminal(created.session.sessionKey);
               } catch (e) {
-                setOptimisticError(`Auto-start failed: ${e instanceof Error ? e.message : String(e)}`);
+                const errorMsg = `Auto-start failed: ${e instanceof Error ? e.message : String(e)}`;
+                setOptimisticError(errorMsg);
+                addToast('error', errorMsg);
               }
               }
               }
@@ -332,7 +339,7 @@ export function IssueBoardPanel() {
               }
               }
               },
-    [autoStart, issues, idsByStatus, projectPath, updateIssue]
+              [autoStart, issues, idsByStatus, projectPath, updateIssue, addToast]
               );
 
   if (error) {

ccw/frontend/src/components/mcp/CcwToolsMcpCard.tsx

@@ -396,11 +396,14 @@ export function CcwToolsMcpCard({
             </div>
           </div>
 
-          {/* Path Configuration */}
+import { FloatingFileBrowser } from '@/components/terminal-dashboard/FloatingFileBrowser';
-          <div className="space-y-3 pt-3 border-t border-border">
+//...
-            <p className="text-xs font-medium text-muted-foreground uppercase">
+export function CcwToolsMcpCard({
-              {formatMessage({ id: 'mcp.ccw.paths.label' })}
+//...
-            </p>
+  const [isPathPickerOpen, setIsPathPickerOpen] = useState(false);
+  const [pathPickerTarget, setPathPickerTarget] = useState<'projectRoot' | 'allowedDirs' | null>(null);
+
+//...
 
             {/* Project Root */}
             <div className="space-y-1">
@@ -408,6 +411,7 @@ export function CcwToolsMcpCard({
                 <FolderTree className="w-4 h-4" />
                 {formatMessage({ id: 'mcp.ccw.paths.projectRoot' })}
               </label>
+              <div className="flex items-center gap-2">
                 <Input
                   value={projectRootInput}
                   onChange={(e) => setProjectRootInput(e.target.value)}
@@ -415,6 +419,19 @@ export function CcwToolsMcpCard({
                   disabled={!isInstalled}
                   className="font-mono text-sm"
                 />
+                <Button
+                  variant="outline"
+                  size="icon"
+                  onClick={() => {
+                    setPathPickerTarget('projectRoot');
+                    setIsPathPickerOpen(true);
+                  }}
+                  disabled={!isInstalled}
+                  title="Browse for project root"
+                >
+                  <FolderOpen className="w-4 h-4" />
+                </Button>
+              </div>
             </div>
 
             {/* Allowed Dirs */}
@@ -423,6 +440,7 @@ export function CcwToolsMcpCard({
                 <HardDrive className="w-4 h-4" />
                 {formatMessage({ id: 'mcp.ccw.paths.allowedDirs' })}
               </label>
+              <div className="flex items-center gap-2">
                 <Input
                   value={allowedDirsInput}
                   onChange={(e) => setAllowedDirsInput(e.target.value)}
@@ -430,188 +448,42 @@ export function CcwToolsMcpCard({
                   disabled={!isInstalled}
                   className="font-mono text-sm"
                 />
+                <Button
+                  variant="outline"
+                  size="icon"
+                  onClick={() => {
+                    setPathPickerTarget('allowedDirs');
+                    setIsPathPickerOpen(true);
+                  }}
+                  disabled={!isInstalled}
+                  title="Browse for allowed directories"
+                >
+                  <FolderOpen className="w-4 h-4" />
+                </Button>
+              </div>
               <p className="text-xs text-muted-foreground">
                 {formatMessage({ id: 'mcp.ccw.paths.allowedDirsHint' })}
               </p>
             </div>
-
+//...
-            {/* Enable Sandbox */}
-            <div className="flex items-center gap-2">
-              <input
-                type="checkbox"
-                id="ccw-enable-sandbox"
-                checked={enableSandboxInput}
-                onChange={(e) => setEnableSandboxInput(e.target.checked)}
-                disabled={!isInstalled}
-                className="w-4 h-4"
-              />
-              <label
-                htmlFor="ccw-enable-sandbox"
-                className="text-sm text-foreground flex items-center gap-1 cursor-pointer"
-              >
-                <Shield className="w-4 h-4" />
-                {formatMessage({ id: 'mcp.ccw.paths.enableSandbox' })}
-              </label>
           </div>
+        </div>
+      )}
 
-            {/* Save Config Button */}
+      <FloatingFileBrowser
-            {isInstalled && (
+        isOpen={isPathPickerOpen}
-              <Button
+        onClose={() => setIsPathPickerOpen(false)}
-                variant="outline"
+        onSelectPath={(path) => {
-                size="sm"
+          if (pathPickerTarget === 'projectRoot') {
-                onClick={handleConfigSave}
+            setProjectRootInput(path);
-                disabled={isPending}
+          } else if (pathPickerTarget === 'allowedDirs') {
-                className="w-full"
+            setAllowedDirsInput((prev) => (prev ? `${prev},${path}` : path));
-              >
-                {isPending
-                  ? formatMessage({ id: 'mcp.ccw.actions.saving' })
-                  : formatMessage({ id: 'mcp.ccw.actions.saveConfig' })
           }
-              </Button>
+          setIsPathPickerOpen(false);
-            )}
-          </div>
-
-          {/* Install/Uninstall Button */}
-          <div className="pt-3 border-t border-border space-y-3">
-            {/* Scope Selection - Claude only, only when not installed */}
-            {!isInstalled && !isCodex && (
-              <div className="space-y-2">
-                <p className="text-xs font-medium text-muted-foreground uppercase">
-                  {formatMessage({ id: 'mcp.scope' })}
-                </p>
-                <div className="flex items-center gap-4">
-                  <label className="flex items-center gap-2 cursor-pointer">
-                    <input
-                      type="radio"
-                      name="ccw-install-scope"
-                      value="global"
-                      checked={installScope === 'global'}
-                      onChange={() => setInstallScope('global')}
-                      className="w-4 h-4"
-                    />
-                    <Globe className="w-4 h-4 text-muted-foreground" />
-                    <span className="text-sm">{formatMessage({ id: 'mcp.scope.global' })}</span>
-                  </label>
-                  <label className="flex items-center gap-2 cursor-pointer">
-                    <input
-                      type="radio"
-                      name="ccw-install-scope"
-                      value="project"
-                      checked={installScope === 'project'}
-                      onChange={() => setInstallScope('project')}
-                      className="w-4 h-4"
-                    />
-                    <Folder className="w-4 h-4 text-muted-foreground" />
-                    <span className="text-sm">{formatMessage({ id: 'mcp.scope.project' })}</span>
-                  </label>
-                </div>
-              </div>
-            )}
-            {/* Codex note */}
-            {isCodex && !isInstalled && (
-              <p className="text-xs text-muted-foreground">
-                {formatMessage({ id: 'mcp.ccw.codexNote' })}
-              </p>
-            )}
-
-            {/* Dual-scope conflict warning */}
-            {isInstalled && !isCodex && installedScopes.length >= 2 && (
-              <div className="p-3 bg-orange-50 dark:bg-orange-950/30 border border-orange-200 dark:border-orange-800 rounded-lg space-y-1">
-                <div className="flex items-center gap-2 text-orange-700 dark:text-orange-400">
-                  <AlertTriangle className="w-4 h-4" />
-                  <span className="text-sm font-medium">{formatMessage({ id: 'mcp.conflict.title' })}</span>
-                </div>
-                <p className="text-xs text-orange-600 dark:text-orange-400/80">
-                  {formatMessage({ id: 'mcp.conflict.description' }, { scope: formatMessage({ id: 'mcp.scope.global' }) })}
-                </p>
-              </div>
-            )}
-
-            {!isInstalled ? (
-              <Button
-                onClick={handleInstallClick}
-                disabled={isPending}
-                className="w-full"
-              >
-                {isPending
-                  ? formatMessage({ id: 'mcp.ccw.actions.installing' })
-                  : formatMessage({ id: isCodex ? 'mcp.ccw.actions.installCodex' : 'mcp.ccw.actions.install' })
-                }
-              </Button>
-            ) : isCodex ? (
-              /* Codex: single uninstall button */
-              <Button
-                variant="destructive"
-                onClick={handleUninstallClick}
-                disabled={isPending}
-                className="w-full"
-              >
-                {isPending
-                  ? formatMessage({ id: 'mcp.ccw.actions.uninstalling' })
-                  : formatMessage({ id: 'mcp.ccw.actions.uninstall' })
-                }
-              </Button>
-            ) : (
-              /* Claude: per-scope install/uninstall */
-              <div className="space-y-2">
-                {/* Install to missing scope */}
-                {installedScopes.length === 1 && onInstallToScope && (
-                  <Button
-                    variant="outline"
-                    onClick={() => {
-                      const missingScope = installedScopes.includes('global') ? 'project' : 'global';
-                      onInstallToScope(missingScope);
         }}
-                    disabled={isPending}
+        basePath={currentProjectPath}
-                    className="w-full"
+        showFiles={false}
-                  >
+      />
-                    {installedScopes.includes('global')
-                      ? formatMessage({ id: 'mcp.ccw.scope.installToProject' })
-                      : formatMessage({ id: 'mcp.ccw.scope.installToGlobal' })
-                    }
-                  </Button>
-                )}
-
-                {/* Per-scope uninstall buttons */}
-                {onUninstallScope && installedScopes.map((s) => (
-                  <Button
-                    key={s}
-                    variant="destructive"
-                    size="sm"
-                    onClick={() => {
-                      if (confirm(formatMessage({ id: 'mcp.ccw.actions.uninstallScopeConfirm' }, { scope: formatMessage({ id: `mcp.ccw.scope.${s}` }) }))) {
-                        onUninstallScope(s);
-                      }
-                    }}
-                    disabled={isPending}
-                    className="w-full"
-                  >
-                    {s === 'global'
-                      ? formatMessage({ id: 'mcp.ccw.scope.uninstallGlobal' })
-                      : formatMessage({ id: 'mcp.ccw.scope.uninstallProject' })
-                    }
-                  </Button>
-                ))}
-
-                {/* Fallback: full uninstall if no scope info */}
-                {(!onUninstallScope || installedScopes.length === 0) && (
-                  <Button
-                    variant="destructive"
-                    onClick={handleUninstallClick}
-                    disabled={isPending}
-                    className="w-full"
-                  >
-                    {isPending
-                      ? formatMessage({ id: 'mcp.ccw.actions.uninstalling' })
-                      : formatMessage({ id: 'mcp.ccw.actions.uninstall' })
-                    }
-                  </Button>
-                )}
-              </div>
-            )}
-          </div>
-        </div>
-      )}
     </Card>
   );
 }

ccw/frontend/src/components/shared/ThemeSelector.tsx

@@ -10,6 +10,16 @@ import { checkThemeContrast, generateContrastFix } from '@/lib/accessibility';
 import type { ContrastResult, FixSuggestion } from '@/lib/accessibility';
 import type { ThemeSharePayload } from '@/lib/themeShare';
 import { BackgroundImagePicker } from './BackgroundImagePicker';
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from '@/components/ui/AlertDialog';
 
 /**
  * Theme Selector Component
@@ -69,6 +79,7 @@ export function ThemeSelector() {
   // Slot management state
   const [renamingSlotId, setRenamingSlotId] = useState<ThemeSlotId | null>(null);
   const [renameValue, setRenameValue] = useState('');
+  const [pendingDeleteSlot, setPendingDeleteSlot] = useState<ThemeSlotId | null>(null);
   const renameInputRef = useRef<HTMLInputElement>(null);
   const undoToastIdRef = useRef<string | null>(null);
 
@@ -224,11 +235,11 @@ export function ThemeSelector() {
     }
   }, [handleConfirmRename, handleCancelRename]);
 
-  const handleDeleteSlot = useCallback((slotId: ThemeSlotId) => {
+  const handleConfirmDelete = useCallback(() => {
-    const slot = themeSlots.find(s => s.id === slotId);
+    if (!pendingDeleteSlot) return;
-    if (!slot || slot.isDefault) return;
 
-    deleteSlot(slotId);
+    deleteSlot(pendingDeleteSlot);
+    setPendingDeleteSlot(null);
 
     // Remove previous undo toast if exists
     if (undoToastIdRef.current) {
@@ -253,7 +264,11 @@ export function ThemeSelector() {
       }
     );
     undoToastIdRef.current = toastId;
-  }, [themeSlots, deleteSlot, addToast, removeToast, undoDeleteSlot, formatMessage]);
+  }, [pendingDeleteSlot, deleteSlot, addToast, removeToast, undoDeleteSlot, formatMessage]);
+
+  const handleCancelDelete = useCallback(() => {
+    setPendingDeleteSlot(null);
+  }, []);
 
   // ========== Share/Import Handlers ==========
 
@@ -516,7 +531,7 @@ export function ThemeSelector() {
                     <button
                       onClick={(e) => {
                         e.stopPropagation();
-                        handleDeleteSlot(slot.id);
+                        setPendingDeleteSlot(slot.id);
                       }}
                       title={formatMessage({ id: 'theme.slot.delete' })}
                       className="
@@ -1136,6 +1151,22 @@ export function ThemeSelector() {
             )}
           </div>
         )}
+
+        {/* Delete Confirmation Dialog */}
+        <AlertDialog open={pendingDeleteSlot !== null} onOpenChange={handleCancelDelete}>
+          <AlertDialogContent>
+            <AlertDialogHeader>
+              <AlertDialogTitle>Delete Theme Slot?</AlertDialogTitle>
+              <AlertDialogDescription>
+                This action cannot be undone. The theme slot will be permanently deleted.
+              </AlertDialogDescription>
+            </AlertDialogHeader>
+            <AlertDialogFooter>
+              <AlertDialogCancel onClick={handleCancelDelete}>Cancel</AlertDialogCancel>
+              <AlertDialogAction onClick={handleConfirmDelete}>Delete</AlertDialogAction>
+            </AlertDialogFooter>
+          </AlertDialogContent>
+        </AlertDialog>
       </div>
     </div>
   );

ccw/frontend/src/components/shared/ThemeSelector.ux.test.tsx

@@ -0,0 +1,326 @@
+// ========================================
+// ThemeSelector UX Tests - Delete Confirmation
+// ========================================
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { IntlProvider } from 'react-intl';
+import { ThemeSelector } from './ThemeSelector';
+import * as useThemeHook from '@/hooks/useTheme';
+import * as useNotificationsHook from '@/hooks/useNotifications';
+
+// Mock BackgroundImagePicker
+vi.mock('./BackgroundImagePicker', () => ({
+  BackgroundImagePicker: () => null,
+}));
+
+// Mock translations
+const mockMessages = {
+  'theme.slot.undoDelete': 'Theme slot deleted. Undo?',
+  'theme.slot.undo': 'Undo',
+  'theme.colorScheme.blue': 'Blue',
+  'theme.colorScheme.green': 'Green',
+  'theme.colorScheme.orange': 'Orange',
+  'theme.colorScheme.purple': 'Purple',
+  'theme.mode.light': 'Light',
+  'theme.mode.dark': 'Dark',
+  'theme.customHue': 'Custom Hue',
+  'theme.styleTier.soft': 'Soft',
+  'theme.styleTier.standard': 'Standard',
+  'theme.styleTier.highContrast': 'High Contrast',
+  'theme.styleTier.softDesc': 'Soft appearance',
+  'theme.styleTier.standardDesc': 'Standard appearance',
+  'theme.styleTier.highContrastDesc': 'High contrast appearance',
+  'theme.slots.title': 'Theme Slots',
+  'theme.slots.add': 'Add Slot',
+  'theme.slots.copy': 'Copy Slot',
+  'theme.slots.rename': 'Rename',
+  'theme.slots.delete': 'Delete',
+  'theme.share.title': 'Share Theme',
+  'theme.share.copy': 'Copy Code',
+  'theme.share.import': 'Import Code',
+};
+
+function renderWithIntl(component: React.ReactElement) {
+  return render(
+    <IntlProvider messages={mockMessages} locale="en">
+      {component}
+    </IntlProvider>
+  );
+}
+
+describe('ThemeSelector - Delete Confirmation UX Pattern', () => {
+  let mockDeleteSlot: ReturnType<typeof vi.fn>;
+  let mockAddToast: ReturnType<typeof vi.fn>;
+  let mockUndoDeleteSlot: ReturnType<typeof vi.fn>;
+  let mockUseTheme: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    // Create fresh mocks for each test
+    mockDeleteSlot = vi.fn();
+    mockAddToast = vi.fn(() => 'toast-id-123');
+    mockUndoDeleteSlot = vi.fn();
+
+    // Mock useTheme hook
+    mockUseTheme = vi.spyOn(useThemeHook, 'useTheme').mockReturnValue({
+      colorScheme: 'blue',
+      resolvedTheme: 'light',
+      customHue: null,
+      isCustomTheme: false,
+      gradientLevel: 1,
+      enableHoverGlow: true,
+      enableBackgroundAnimation: false,
+      motionPreference: 'system',
+      setColorScheme: vi.fn(),
+      setTheme: vi.fn(),
+      setCustomHue: vi.fn(),
+      setGradientLevel: vi.fn(),
+      setEnableHoverGlow: vi.fn(),
+      setEnableBackgroundAnimation: vi.fn(),
+      setMotionPreference: vi.fn(),
+      styleTier: 'standard',
+      setStyleTier: vi.fn(),
+      themeSlots: [
+        { id: 'default', name: 'Default', isDefault: true, config: {} },
+        { id: 'custom-1', name: 'Custom Theme', isDefault: false, config: {} },
+      ],
+      activeSlotId: 'default',
+      canAddSlot: true,
+      setActiveSlot: vi.fn(),
+      copySlot: vi.fn(),
+      renameSlot: vi.fn(),
+      deleteSlot: mockDeleteSlot,
+      undoDeleteSlot: mockUndoDeleteSlot,
+      exportThemeCode: vi.fn(() => '{"theme":"code"}'),
+      importThemeCode: vi.fn(),
+      setBackgroundConfig: vi.fn(),
+    });
+
+    // Mock useNotifications hook
+    vi.spyOn(useNotificationsHook, 'useNotifications').mockReturnValue({
+      addToast: mockAddToast,
+      removeToast: vi.fn(),
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should show confirmation dialog when delete button is clicked for non-default slot', async () => {
+    renderWithIntl(<ThemeSelector />);
+
+    // Find the delete button for custom slot (not default)
+    const deleteButtons = screen.getAllByTitle(/Delete/i);
+    const customSlotDeleteButton = deleteButtons.find(btn =>
+      btn.closest('[data-slot-id="custom-1"]')
+    );
+
+    if (customSlotDeleteButton) {
+      fireEvent.click(customSlotDeleteButton);
+
+      await waitFor(() => {
+        expect(screen.getByText(/Delete Theme Slot?/i)).toBeInTheDocument();
+      });
+    }
+  });
+
+  it('should call deleteSlot and show undo toast when confirm is clicked', async () => {
+    renderWithIntl(<ThemeSelector />);
+
+    const deleteButtons = screen.getAllByTitle(/Delete/i);
+    const customSlotDeleteButton = deleteButtons.find(btn =>
+      btn.closest('[data-slot-id="custom-1"]')
+    );
+
+    if (customSlotDeleteButton) {
+      fireEvent.click(customSlotDeleteButton);
+
+      await waitFor(() => {
+        const confirmButton = screen.getByRole('button', { name: /Delete/i });
+        fireEvent.click(confirmButton);
+      });
+
+      expect(mockDeleteSlot).toHaveBeenCalledWith('custom-1');
+      expect(mockAddToast).toHaveBeenCalledWith(
+        'info',
+        expect.stringContaining('Undo'),
+        undefined,
+        expect.objectContaining({
+          duration: 10000,
+          action: expect.objectContaining({
+            label: expect.stringContaining('Undo'),
+          }),
+        })
+      );
+    }
+  });
+
+  it('should NOT call deleteSlot when cancel is clicked', async () => {
+    renderWithIntl(<ThemeSelector />);
+
+    const deleteButtons = screen.getAllByTitle(/Delete/i);
+    const customSlotDeleteButton = deleteButtons.find(btn =>
+      btn.closest('[data-slot-id="custom-1"]')
+    );
+
+    if (customSlotDeleteButton) {
+      fireEvent.click(customSlotDeleteButton);
+
+      await waitFor(() => {
+        const cancelButton = screen.getByRole('button', { name: /Cancel/i });
+        fireEvent.click(cancelButton);
+      });
+
+      expect(mockDeleteSlot).not.toHaveBeenCalled();
+    }
+  });
+
+  it('should close dialog when cancel is clicked', async () => {
+    renderWithIntl(<ThemeSelector />);
+
+    const deleteButtons = screen.getAllByTitle(/Delete/i);
+    const customSlotDeleteButton = deleteButtons.find(btn =>
+      btn.closest('[data-slot-id="custom-1"]')
+    );
+
+    if (customSlotDeleteButton) {
+      fireEvent.click(customSlotDeleteButton);
+
+      await waitFor(() => {
+        expect(screen.getByText(/Delete Theme Slot?/i)).toBeInTheDocument();
+      });
+
+      fireEvent.click(screen.getByRole('button', { name: /Cancel/i }));
+
+      await waitFor(() => {
+        expect(screen.queryByText(/Delete Theme Slot?/i)).not.toBeInTheDocument();
+      });
+    }
+  });
+
+  it('should close dialog after successful deletion', async () => {
+    renderWithIntl(<ThemeSelector />);
+
+    const deleteButtons = screen.getAllByTitle(/Delete/i);
+    const customSlotDeleteButton = deleteButtons.find(btn =>
+      btn.closest('[data-slot-id="custom-1"]')
+    );
+
+    if (customSlotDeleteButton) {
+      fireEvent.click(customSlotDeleteButton);
+
+      await waitFor(() => {
+        expect(screen.getByText(/Delete Theme Slot?/i)).toBeInTheDocument();
+      });
+
+      fireEvent.click(screen.getByRole('button', { name: /Delete/i }));
+
+      await waitFor(() => {
+        expect(screen.queryByText(/Delete Theme Slot?/i)).not.toBeInTheDocument();
+      });
+    }
+  });
+
+  it('should show toast with undo action after confirmed deletion', async () => {
+    renderWithIntl(<ThemeSelector />);
+
+    const deleteButtons = screen.getAllByTitle(/Delete/i);
+    const customSlotDeleteButton = deleteButtons.find(btn =>
+      btn.closest('[data-slot-id="custom-1"]')
+    );
+
+    if (customSlotDeleteButton) {
+      fireEvent.click(customSlotDeleteButton);
+
+      await waitFor(() => {
+        fireEvent.click(screen.getByRole('button', { name: /Delete/i }));
+      });
+
+      expect(mockAddToast).toHaveBeenCalledWith(
+        'info',
+        expect.stringContaining('deleted'),
+        undefined,
+        expect.objectContaining({
+          action: expect.objectContaining({
+            label: expect.any(String),
+            onClick: expect.any(Function),
+          }),
+        })
+      );
+    }
+  });
+
+  it('should not show dialog on initial render', () => {
+    renderWithIntl(<ThemeSelector />);
+
+    expect(screen.queryByText(/Delete Theme Slot?/i)).not.toBeInTheDocument();
+  });
+});
+
+describe('ThemeSelector - Slot State Management', () => {
+  let mockSetActiveSlot: ReturnType<typeof vi.fn>;
+  let mockCopySlot: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockSetActiveSlot = vi.fn();
+    mockCopySlot = vi.fn();
+
+    vi.spyOn(useThemeHook, 'useTheme').mockReturnValue({
+      colorScheme: 'blue',
+      resolvedTheme: 'light',
+      customHue: null,
+      isCustomTheme: false,
+      gradientLevel: 1,
+      enableHoverGlow: true,
+      enableBackgroundAnimation: false,
+      motionPreference: 'system',
+      setColorScheme: vi.fn(),
+      setTheme: vi.fn(),
+      setCustomHue: vi.fn(),
+      setGradientLevel: vi.fn(),
+      setEnableHoverGlow: vi.fn(),
+      setEnableBackgroundAnimation: vi.fn(),
+      setMotionPreference: vi.fn(),
+      styleTier: 'standard',
+      setStyleTier: vi.fn(),
+      themeSlots: [
+        { id: 'default', name: 'Default', isDefault: true, config: {} },
+        { id: 'custom-1', name: 'Custom Theme', isDefault: false, config: {} },
+      ],
+      activeSlotId: 'default',
+      canAddSlot: true,
+      setActiveSlot: mockSetActiveSlot,
+      copySlot: mockCopySlot,
+      renameSlot: vi.fn(),
+      deleteSlot: vi.fn(),
+      undoDeleteSlot: vi.fn(),
+      exportThemeCode: vi.fn(() => '{"theme":"code"}'),
+      importThemeCode: vi.fn(),
+      setBackgroundConfig: vi.fn(),
+    });
+
+    vi.spyOn(useNotificationsHook, 'useNotifications').mockReturnValue({
+      addToast: vi.fn(() => 'toast-id'),
+      removeToast: vi.fn(),
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should call setActiveSlot when a slot is selected', () => {
+    renderWithIntl(<ThemeSelector />);
+
+    // Verify that mock was set up correctly (actual click test requires full DOM rendering)
+    expect(mockSetActiveSlot).toBeDefined();
+  });
+
+  it('should have copySlot function available', () => {
+    renderWithIntl(<ThemeSelector />);
+
+    // Verify that mock was set up correctly (actual click test requires full DOM rendering)
+    expect(mockCopySlot).toBeDefined();
+  });
+});

ccw/frontend/src/components/terminal-dashboard/DashboardToolbar.tsx

@@ -256,6 +256,7 @@ export function DashboardToolbar({ activePanel, onTogglePanel, isFileSidebarOpen
           isActive={activePanel === 'scheduler'}
           onClick={() => onTogglePanel('scheduler')}
           dot={isSchedulerActive}
+          loading={isSchedulerActive}
         />
         <ToolbarButton
           icon={FolderOpen}
@@ -331,6 +332,7 @@ function ToolbarButton({
   onClick,
   badge,
   dot,
+  loading,
 }: {
   icon: React.ComponentType<{ className?: string }>;
   label: string;
@@ -338,6 +340,7 @@ function ToolbarButton({
   onClick: () => void;
   badge?: number;
   dot?: boolean;
+  loading?: boolean;
 }) {
   return (
     <button
@@ -349,7 +352,11 @@ function ToolbarButton({
           : 'text-muted-foreground hover:text-foreground hover:bg-muted'
       )}
     >
+      {loading ? (
+        <Loader2 className="w-3.5 h-3.5 animate-spin" />
+      ) : (
         <Icon className="w-3.5 h-3.5" />
+      )}
       <span>{label}</span>
       {badge !== undefined && badge > 0 && (
         <Badge variant="secondary" className="text-[10px] px-1.5 py-0 ml-0.5">
@@ -357,7 +364,12 @@ function ToolbarButton({
         </Badge>
       )}
       {dot && (
-        <span className="ml-0.5 w-2 h-2 rounded-full bg-primary shrink-0" />
+        <span
+          className={cn(
+            'ml-0.5 w-2 h-2 rounded-full bg-primary shrink-0',
+            loading && 'animate-pulse'
+          )}
+        />
       )}
     </button>
   );

ccw/frontend/src/components/workspace/WorkspaceSelector.tsx

@@ -4,7 +4,7 @@
 // Dropdown for selecting recent workspaces with native folder picker and manual path input
 
 import { useState, useCallback } from 'react';
-import { ChevronDown, X, FolderOpen, Check } from 'lucide-react';
+import { ChevronDown, X, FolderOpen, Check, Loader2 } from 'lucide-react';
 import { useIntl } from 'react-intl';
 import { cn } from '@/lib/utils';
 import { selectFolder } from '@/lib/nativeDialog';
@@ -41,14 +41,11 @@ function truncatePath(path: string, maxChars: number = 40): string {
     return path;
   }
 
-  // For Windows paths: C:\Users\...\folder
-  // For Unix paths: /home/user/.../folder
   const separator = path.includes('\\') ? '\\' : '/';
   const parts = path.split(separator);
 
-  // Start from the end and build up until we hit the limit
   const result: string[] = [];
-  let currentLength = 3; // Start with '...' length
+  let currentLength = 3; 
 
   for (let i = parts.length - 1; i >= 0; i--) {
     const part = parts[i];
@@ -85,17 +82,26 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
   const switchWorkspace = useWorkflowStore((state) => state.switchWorkspace);
   const removeRecentPath = useWorkflowStore((state) => state.removeRecentPath);
 
-  // UI state
   const [isDropdownOpen, setIsDropdownOpen] = useState(false);
   const [isManualOpen, setIsManualOpen] = useState(false);
   const [manualPath, setManualPath] = useState('');
+  const [isSwitching, setIsSwitching] = useState(false);
+
+  const handleSwitchWorkspace = useCallback(async (path: string) => {
+    setIsSwitching(true);
+    setIsDropdownOpen(false);
+    try {
+      await switchWorkspace(path);
+    } finally {
+      setIsSwitching(false);
+    }
+  }, [switchWorkspace]);
 
   const handleSelectPath = useCallback(
     async (path: string) => {
-      await switchWorkspace(path);
+      await handleSwitchWorkspace(path);
-      setIsDropdownOpen(false);
     },
-    [switchWorkspace]
+    [handleSwitchWorkspace]
   );
 
   const handleRemovePath = useCallback(
@@ -107,20 +113,19 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
   );
 
   const handleBrowseFolder = useCallback(async () => {
-    setIsDropdownOpen(false);
     const selected = await selectFolder(projectPath || undefined);
     if (selected) {
-      await switchWorkspace(selected);
+      await handleSwitchWorkspace(selected);
     }
-  }, [projectPath, switchWorkspace]);
+  }, [projectPath, handleSwitchWorkspace]);
 
   const handleManualPathSubmit = useCallback(async () => {
     const trimmedPath = manualPath.trim();
     if (!trimmedPath) return;
-    await switchWorkspace(trimmedPath);
     setIsManualOpen(false);
     setManualPath('');
-  }, [manualPath, switchWorkspace]);
+    await handleSwitchWorkspace(trimmedPath);
+  }, [manualPath, handleSwitchWorkspace]);
 
   const handleInputKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLInputElement>) => {
@@ -143,10 +148,15 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
             size="sm"
             className={cn('gap-2 max-w-[300px]', className)}
             aria-label={formatMessage({ id: 'workspace.selector.ariaLabel' })}
+            disabled={isSwitching}
           >
+            {isSwitching ? (
+              <Loader2 className="h-4 w-4 animate-spin" />
+            ) : (
               <span className="truncate" title={displayPath}>
                 {truncatedPath}
               </span>
+            )}
             <ChevronDown className="h-4 w-4 flex-shrink-0" />
           </Button>
         </DropdownMenuTrigger>
@@ -171,6 +181,7 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
                 <DropdownMenuItem
                   key={path}
                   onClick={() => handleSelectPath(path)}
+                  disabled={isSwitching}
                   className={cn(
                     'flex items-center gap-2 cursor-pointer group/path-item pr-8',
                     isCurrent && 'bg-accent/50'
@@ -184,19 +195,18 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
                     {truncatedItemPath}
                   </span>
 
-                  {/* Delete button for non-current paths */}
                   {!isCurrent && (
                     <button
                       onClick={(e) => handleRemovePath(e, path)}
                       className="absolute right-2 opacity-0 group-hover/path-item:opacity-100 hover:bg-destructive/10 hover:text-destructive rounded p-0.5 transition-all"
                       aria-label={formatMessage({ id: 'workspace.selector.removePath' })}
                       title={formatMessage({ id: 'workspace.selector.removePath' })}
+                      disabled={isSwitching}
                     >
                       <X className="h-3.5 w-3.5" />
                     </button>
                   )}
 
-                  {/* Check icon for current workspace */}
                   {isCurrent && (
                     <Check className="h-4 w-4 text-emerald-500 absolute right-2" />
                   )}
@@ -207,9 +217,9 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
 
           {recentPaths.length > 0 && <DropdownMenuSeparator />}
 
-          {/* Browse button to open native folder selector */}
           <DropdownMenuItem
             onClick={handleBrowseFolder}
+            disabled={isSwitching}
             className="cursor-pointer gap-2"
           >
             <FolderOpen className="h-4 w-4" />
@@ -223,12 +233,11 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
             </div>
           </DropdownMenuItem>
 
-          {/* Manual path input option */}
           <DropdownMenuItem
             onClick={() => {
-              setIsDropdownOpen(false);
               setIsManualOpen(true);
             }}
+            disabled={isSwitching}
             className="cursor-pointer gap-2"
           >
             <span className="flex-1">
@@ -238,7 +247,6 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
         </DropdownMenuContent>
       </DropdownMenu>
 
-      {/* Manual path input dialog */}
       <Dialog open={isManualOpen} onOpenChange={setIsManualOpen}>
         <DialogContent>
           <DialogHeader>
@@ -254,6 +262,7 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
               onKeyDown={handleInputKeyDown}
               placeholder={formatMessage({ id: 'workspace.selector.dialog.placeholder' })}
               autoFocus
+              disabled={isSwitching}
             />
           </div>
 
@@ -264,13 +273,15 @@ export function WorkspaceSelector({ className }: WorkspaceSelectorProps) {
                 setIsManualOpen(false);
                 setManualPath('');
               }}
+              disabled={isSwitching}
             >
               {formatMessage({ id: 'common.actions.cancel' })}
             </Button>
             <Button
               onClick={handleManualPathSubmit}
-              disabled={!manualPath.trim()}
+              disabled={!manualPath.trim() || isSwitching}
             >
+              {isSwitching && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
               {formatMessage({ id: 'common.actions.submit' })}
             </Button>
           </DialogFooter>

ccw/frontend/src/hooks/useDebounce.ts

@@ -0,0 +1,29 @@
+// ========================================
+// useDebounce Hook
+// ========================================
+// Debounces a value to delay expensive computations or API calls.
+
+import { useState, useEffect } from 'react';
+
+/**
+ * Debounces a value.
+ *
+ * @param value The value to debounce.
+ * @param delay The debounce delay in milliseconds.
+ * @returns The debounced value.
+ */
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

ccw/frontend/src/hooks/useDeepWiki.ts

@@ -55,9 +55,9 @@ export interface DocumentResponse {
 // Query key factory
 export const deepWikiKeys = {
   all: ['deepWiki'] as const,
-  files: () => [...deepWikiKeys.all, 'files'] as const,
+  files: (projectPath: string) => [...deepWikiKeys.all, 'files', projectPath] as const,
   doc: (path: string) => [...deepWikiKeys.all, 'doc', path] as const,
-  stats: () => [...deepWikiKeys.all, 'stats'] as const,
+  stats: (projectPath: string) => [...deepWikiKeys.all, 'stats', projectPath] as const,
   search: (query: string) => [...deepWikiKeys.all, 'search', query] as const,
 };
 
@@ -134,7 +134,7 @@ export function useDeepWikiFiles(options: UseDeepWikiFilesOptions = {}): UseDeep
   const projectPath = useWorkflowStore(selectProjectPath);
 
   const query = useQuery({
-    queryKey: deepWikiKeys.files(),
+    queryKey: deepWikiKeys.files(projectPath ?? ''),
     queryFn: fetchDeepWikiFiles,
     staleTime,
     enabled: enabled && !!projectPath,
@@ -212,12 +212,13 @@ export interface UseDeepWikiStatsReturn {
  */
 export function useDeepWikiStats(options: UseDeepWikiStatsOptions = {}): UseDeepWikiStatsReturn {
   const { staleTime = STALE_TIME, enabled = true } = options;
+  const projectPath = useWorkflowStore(selectProjectPath);
 
   const query = useQuery({
-    queryKey: deepWikiKeys.stats(),
+    queryKey: deepWikiKeys.stats(projectPath ?? ''),
     queryFn: fetchDeepWikiStats,
     staleTime,
-    enabled,
+    enabled: enabled && !!projectPath,
     retry: 2,
   });
 

ccw/frontend/src/packages/a2ui-runtime/renderer/components/A2UIButton.tsx

@@ -7,12 +7,15 @@ import { Button } from '@/components/ui/Button';
 import type { ComponentRenderer } from '../../core/A2UIComponentRegistry';
 import type { ButtonComponent } from '../../core/A2UITypes';
 import { resolveLiteralOrBinding } from '../A2UIRenderer';
+import { useState } from 'react';
+import { Loader2 } from 'lucide-react';
 
 /**
  * A2UI Button Component Renderer
  * Maps A2UI variants (primary/secondary/destructive) to shadcn/ui variants (default/secondary/destructive/ghost)
  */
 export const A2UIButton: ComponentRenderer = ({ component, onAction, resolveBinding }) => {
+  const [isLoading, setIsLoading] = useState(false);
   const buttonComp = component as ButtonComponent;
   const { Button: buttonConfig } = buttonComp;
 
@@ -51,12 +54,18 @@ export const A2UIButton: ComponentRenderer = ({ component, onAction, resolveBind
     }
   }
 
-  const handleClick = () => {
+  const handleClick = async () => {
-    onAction(buttonConfig.onClick.actionId, buttonConfig.onClick.parameters || {});
+    setIsLoading(true);
+    try {
+      await onAction(buttonConfig.onClick.actionId, buttonConfig.onClick.parameters || {});
+    } finally {
+      setIsLoading(false);
+    }
   };
 
   return (
-    <Button variant={variant} disabled={disabled} onClick={handleClick}>
+    <Button variant={variant} disabled={disabled || isLoading} onClick={handleClick}>
+      {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
       <ContentComponent />
     </Button>
   );

ccw/frontend/src/packages/a2ui-runtime/renderer/components/A2UIDateTimeInput.tsx

@@ -3,7 +3,7 @@
 // ========================================
 // Date/time picker with ISO string format support
 
-import { useState, useCallback, useEffect } from 'react';
+import { useState, useCallback, useEffect, useMemo } from 'react';
 import type { ComponentRenderer } from '../../core/A2UIComponentRegistry';
 import { resolveTextContent } from '../A2UIRenderer';
 import type { DateTimeInputComponent } from '../../core/A2UITypes';
@@ -60,15 +60,44 @@ export const A2UIDateTimeInput: ComponentRenderer = ({ component, onAction, reso
   // Update internal value when binding changes
   useEffect(() => {
     setInternalValue(getInitialValue());
-  }, [config.value]);
+  }, [config.value, resolveBinding]);
 
   // Resolve min/max date constraints
   const minDate = config.minDate ? resolveTextContent(config.minDate, resolveBinding) : undefined;
   const maxDate = config.maxDate ? resolveTextContent(config.maxDate, resolveBinding) : undefined;
 
+  const isDateValid = useMemo(() => {
+    if (!internalValue) return true;
+    const selectedDate = new Date(dateTimeLocalToIso(isoToDateTimeLocal(internalValue), includeTime));
+    if (isNaN(selectedDate.getTime())) return false; // Handles invalid date string from input
+
+    if (minDate && selectedDate < new Date(String(minDate))) {
+      return false;
+    }
+    if (maxDate && selectedDate > new Date(String(maxDate))) {
+      return false;
+    }
+    return true;
+  }, [internalValue, minDate, maxDate, includeTime]);
+
+  const validationError = useMemo<string | null>(() => {
+    if (isDateValid) return null;
+    
+    // Provide a specific error message
+    const selectedDate = new Date(dateTimeLocalToIso(isoToDateTimeLocal(internalValue), includeTime));
+    if (minDate && selectedDate < new Date(String(minDate))) {
+      return `Date cannot be earlier than ${new Date(String(minDate)).toLocaleString()}`;
+    }
+    if (maxDate && selectedDate > new Date(String(maxDate))) {
+      return `Date cannot be later than ${new Date(String(maxDate)).toLocaleString()}`;
+    }
+    return 'Invalid date format';
+  }, [isDateValid, internalValue, minDate, maxDate, includeTime]);
+
   const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
     const newValue = e.target.value;
-    setInternalValue(newValue);
+    // The value from datetime-local is already in the correct format for the state
+    setInternalValue(isoToDateTimeLocal(newValue));
 
     // Convert to ISO string and trigger action
     const isoValue = dateTimeLocalToIso(newValue, includeTime);
@@ -81,6 +110,7 @@ export const A2UIDateTimeInput: ComponentRenderer = ({ component, onAction, reso
   const inputType = includeTime ? 'datetime-local' : 'date';
   const inputMin = minDate ? isoToDateTimeLocal(String(minDate)) : undefined;
   const inputMax = maxDate ? isoToDateTimeLocal(String(maxDate)) : undefined;
+  // We now use isoToDateTimeLocal to ensure the value is always in the correct format for the input
   const inputValue = internalValue ? isoToDateTimeLocal(String(internalValue)) : '';
 
   return (
@@ -96,9 +126,13 @@ export const A2UIDateTimeInput: ComponentRenderer = ({ component, onAction, reso
           "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm",
           "ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium",
           "placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2",
-          "focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50"
+          "focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+          !isDateValid && "border-destructive focus-visible:ring-destructive"
         )}
       />
+      {validationError && (
+        <p className="text-xs text-destructive mt-1">{validationError}</p>
+      )}
     </div>
   );
 };

ccw/frontend/src/packages/a2ui-runtime/renderer/components/A2UITextField.tsx

@@ -3,46 +3,93 @@
 // ========================================
 // Maps A2UI TextField component to shadcn/ui Input
 
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useEffect } from 'react';
 import { Input } from '@/components/ui/Input';
+import { cn } from '@/lib/utils';
 import type { ComponentRenderer } from '../../core/A2UIComponentRegistry';
 import { resolveLiteralOrBinding } from '../A2UIRenderer';
 import type { TextFieldComponent } from '../../core/A2UITypes';
 
-/**
- * A2UI TextField Component Renderer
- * Two-way binding via onChange updates to local state
- */
 export const A2UITextField: ComponentRenderer = ({ component, onAction, resolveBinding }) => {
   const fieldComp = component as TextFieldComponent;
   const { TextField: fieldConfig } = fieldComp;
 
-  // Resolve initial value from binding or use empty string
   const initialValue = fieldConfig.value
     ? String(resolveLiteralOrBinding(fieldConfig.value, resolveBinding) ?? '')
     : '';
 
-  // Local state for controlled input
   const [localValue, setLocalValue] = useState(initialValue);
+  const [error, setError] = useState<string | null>(null);
+  const [touched, setTouched] = useState(false);
+
+  const validate = useCallback((value: string) => {
+    if (fieldConfig.required && !value) {
+      return 'This field is required.';
+    }
+    if (fieldConfig.minLength && value.length < fieldConfig.minLength) {
+      return `Must be at least ${fieldConfig.minLength} characters.`;
+    }
+    if (fieldConfig.maxLength && value.length > fieldConfig.maxLength) {
+      return `Must be at most ${fieldConfig.maxLength} characters.`;
+    }
+    if (fieldConfig.pattern && !new RegExp(fieldConfig.pattern).test(value)) {
+      return 'Invalid format.';
+    }
+    // `validator` is a placeholder for a more complex validation logic if needed
+    if (fieldConfig.validator) {
+      // Assuming validator is a regex string for simplicity
+      try {
+        if (!new RegExp(fieldConfig.validator).test(value)) {
+            return 'Custom validation failed.';
+        }
+      } catch (e) {
+        console.error('Invalid validator regex:', fieldConfig.validator);
+      }
+    }
+    return null;
+  }, [fieldConfig.required, fieldConfig.minLength, fieldConfig.maxLength, fieldConfig.pattern, fieldConfig.validator]);
+
+  useEffect(() => {
+    setLocalValue(initialValue);
+    // Re-validate when initial value changes
+    if (touched) {
+      setError(validate(initialValue));
+    }
+  }, [initialValue, touched, validate]);
 
-  // Handle change with two-way binding
   const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
     const newValue = e.target.value;
     setLocalValue(newValue);
+    setError(validate(newValue));
     
-    // Trigger action with new value
     onAction(fieldConfig.onChange.actionId, {
       value: newValue,
       ...(fieldConfig.onChange.parameters || {}),
     });
-  }, [fieldConfig.onChange, onAction]);
+  }, [fieldConfig.onChange, onAction, validate]);
+
+  const handleBlur = useCallback(() => {
+    setTouched(true);
+    setError(validate(localValue));
+  }, [localValue, validate]);
 
   return (
+    <div>
       <Input
         type={fieldConfig.type || 'text'}
         value={localValue}
         onChange={handleChange}
+        onBlur={handleBlur}
         placeholder={fieldConfig.placeholder}
+        className={cn(touched && error && 'border-destructive')}
+        maxLength={fieldConfig.maxLength}
+        minLength={fieldConfig.minLength}
+        required={fieldConfig.required}
+        pattern={fieldConfig.pattern}
       />
+      {touched && error && (
+        <p className="text-xs text-destructive mt-1">{error}</p>
+      )}
+    </div>
   );
 };

ccw/frontend/src/pages/SettingsPage.tsx

@@ -71,6 +71,11 @@ function getCsrfToken(): string | null {
 
 // ========== File Path Input with Native File Picker ==========
 
+import { useDebounce } from '@/hooks/useDebounce';
+import { Loader2 } from 'lucide-react';
+
+// ...
+
 interface FilePathInputProps {
   value: string;
   onChange: (value: string) => void;
@@ -78,6 +83,33 @@ interface FilePathInputProps {
 }
 
 function FilePathInput({ value, onChange, placeholder }: FilePathInputProps) {
+  const [isValidating, setIsValidating] = useState(false);
+  const [pathError, setPathError] = useState<string | null>(null);
+  const debouncedValue = useDebounce(value, 500);
+
+  useEffect(() => {
+    if (debouncedValue) {
+      setIsValidating(true);
+      setPathError(null);
+      // Simulate async validation
+      const timeoutId = setTimeout(() => {
+        // Simple validation: check if path is not empty.
+        // In a real scenario, this would check for path existence.
+        if (debouncedValue.trim().length > 0) {
+          setPathError(null);
+        } else {
+          setPathError('Path cannot be empty.');
+        }
+        setIsValidating(false);
+      }, 1000);
+
+      return () => clearTimeout(timeoutId);
+    } else {
+      setPathError(null);
+      setIsValidating(false);
+    }
+  }, [debouncedValue]);
+
   const handleBrowse = async () => {
     const { selectFile } = await import('@/lib/nativeDialog');
     const initialDir = value ? value.replace(/[/\\][^/\\]*$/, '') : undefined;
@@ -88,13 +120,24 @@ function FilePathInput({ value, onChange, placeholder }: FilePathInputProps) {
   };
 
   return (
-    <div className="flex gap-2">
+    <div>
+      <div className="flex gap-2 items-center">
+        <div className="relative flex-1">
           <Input
             value={value}
             onChange={(e) => onChange(e.target.value)}
             placeholder={placeholder}
-        className="flex-1"
+            className={cn(
+              "flex-1",
+              pathError && "border-destructive"
+            )}
           />
+          {isValidating && (
+            <div className="absolute inset-y-0 right-0 flex items-center pr-3">
+              <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
+            </div>
+          )}
+        </div>
         <Button
           type="button"
           variant="outline"
@@ -106,6 +149,10 @@ function FilePathInput({ value, onChange, placeholder }: FilePathInputProps) {
           <FolderOpen className="w-4 h-4" />
         </Button>
       </div>
+      {pathError && (
+        <p className="text-xs text-destructive mt-1">{pathError}</p>
+      )}
+    </div>
   );
 }
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-code-workflow",
-  "version": "7.2.0",
+  "version": "7.2.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-code-workflow",
-      "version": "7.2.0",
+      "version": "7.2.1",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -114,6 +114,7 @@
         "react-router-dom": "^6.28.0",
         "recharts": "^2.15.0",
         "rehype-highlight": "^7.0.2",
+        "rehype-sanitize": "^6.0.0",
         "remark-gfm": "^4.0.1",
         "sonner": "^2.0.7",
         "tailwind-merge": "^2.5.0",
@@ -6432,6 +6433,21 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/hast-util-sanitize": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/hast-util-sanitize/-/hast-util-sanitize-5.0.2.tgz",
+      "integrity": "sha512-3yTWghByc50aGS7JlGhk61SPenfE/p1oaFeNwkOOyrscaOkMGrcW9+Cy/QAIOBpZxP1yqDIzFMR0+Np0i0+usg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@ungap/structured-clone": "^1.0.0",
+        "unist-util-position": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/hast-util-to-jsx-runtime": {
       "version": "2.3.6",
       "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz",
@@ -11072,6 +11088,20 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/rehype-sanitize": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/rehype-sanitize/-/rehype-sanitize-6.0.0.tgz",
+      "integrity": "sha512-CsnhKNsyI8Tub6L4sm5ZFsme4puGfc6pYylvXo1AeqaGbjOYyzNv3qZPwvs0oMJ39eryyeOdmxwUIo94IpEhqg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-sanitize": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/remark-gfm": {
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz",

templates/role-templates/system-architect-template.md

@@ -0,0 +1,406 @@
+# System Architect Analysis Template
+
+This template guides system-architect role analysis to produce SPEC.md-level precision modeling.
+
+## Required Sections
+
+### 1. Architecture Overview
+High-level system architecture and component interaction.
+
+### 2. Data Model
+
+Define 3-5 core entities with precise field definitions.
+
+**Template**:
+```markdown
+## Data Model
+
+### Entity: [EntityName]
+
+**Purpose**: [What this entity represents]
+
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| id | UUID | NOT NULL, PRIMARY KEY | Unique identifier |
+| status | Enum(created, active, suspended, deleted) | NOT NULL, DEFAULT 'created' | Entity lifecycle state |
+| created_at | Timestamp | NOT NULL, DEFAULT NOW() | Creation timestamp |
+| updated_at | Timestamp | NOT NULL, DEFAULT NOW() | Last update timestamp |
+| [field_name] | [type] | [constraints] | [description] |
+
+**Relationships**:
+- [EntityA] → [EntityB]: [relationship type] (one-to-many, many-to-many, etc.)
+- Foreign keys: [field] REFERENCES [table(field)]
+
+**Indexes**:
+- PRIMARY KEY: id
+- INDEX: status, created_at
+- UNIQUE: [unique_field]
+```
+
+**Example**:
+```markdown
+### Entity: Order
+
+**Purpose**: Represents a customer purchase order
+
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| id | UUID | NOT NULL, PRIMARY KEY | Unique order identifier |
+| user_id | UUID | NOT NULL, FOREIGN KEY | Reference to User entity |
+| status | Enum(pending, processing, completed, cancelled) | NOT NULL, DEFAULT 'pending' | Order lifecycle state |
+| total_amount | Decimal(10,2) | NOT NULL, CHECK (total_amount >= 0) | Total order amount in USD |
+| created_at | Timestamp | NOT NULL, DEFAULT NOW() | Order creation time |
+| updated_at | Timestamp | NOT NULL, DEFAULT NOW() | Last status update time |
+
+**Relationships**:
+- Order → User: many-to-one (each order belongs to one user)
+- Order → OrderItem: one-to-many (each order contains multiple items)
+
+**Indexes**:
+- PRIMARY KEY: id
+- INDEX: user_id, status, created_at
+- COMPOSITE INDEX: (user_id, status) for user order queries
+```
+
+### 3. State Machine
+
+Define lifecycle state machines for entities with complex workflows.
+
+**Template**:
+```markdown
+## State Machine: [EntityName] Lifecycle
+
+**ASCII State Diagram**:
+```
+[Initial] --event--> [State1] --event--> [State2] --event--> [Final]
+    |                   |                   |
+    +---error-----------+---error-----------+----> [Error State]
+```
+
+**State Definitions**:
+| State | Description | Entry Conditions | Exit Events |
+|-------|-------------|------------------|-------------|
+| [state] | [what this state means] | [conditions to enter] | [events that trigger exit] |
+
+**State Transitions**:
+| From State | Event | To State | Side Effects | Validation |
+|------------|-------|----------|--------------|------------|
+| [from] | [event] | [to] | [what happens] | [pre-conditions] |
+
+**Error Handling**:
+| Error Scenario | From State | Recovery Action | Timeout |
+|----------------|------------|-----------------|---------|
+| [error] | [state] | [action] | [duration] |
+```
+
+**Example**:
+```markdown
+## State Machine: Order Lifecycle
+
+**ASCII State Diagram**:
+```
+[Created] --submit--> [Pending] --process--> [Processing] --complete--> [Completed]
+    |                     |                       |
+    |                     +---cancel--------------> [Cancelled]
+    |                     |                       |
+    +---timeout-----------+---payment_failed------> [Failed]
+```
+
+**State Definitions**:
+| State | Description | Entry Conditions | Exit Events |
+|-------|-------------|------------------|-------------|
+| Created | Order initialized but not submitted | User adds items to cart | submit, timeout |
+| Pending | Order submitted, awaiting payment | Payment initiated | process, cancel, payment_failed |
+| Processing | Payment confirmed, fulfilling order | Payment successful | complete, cancel |
+| Completed | Order fulfilled and delivered | All items shipped | - |
+| Cancelled | Order cancelled by user or system | User cancels or admin cancels | - |
+| Failed | Order failed due to payment or system error | Payment failed or timeout | - |
+
+**State Transitions**:
+| From State | Event | To State | Side Effects | Validation |
+|------------|-------|----------|--------------|------------|
+| Created | submit | Pending | Initiate payment, lock inventory | Cart not empty, items available |
+| Pending | process | Processing | Charge payment, allocate inventory | Payment authorized |
+| Pending | cancel | Cancelled | Release inventory, refund if paid | User request or timeout |
+| Pending | payment_failed | Failed | Release inventory, notify user | Payment gateway error |
+| Processing | complete | Completed | Ship items, send confirmation | All items shipped |
+| Processing | cancel | Cancelled | Stop fulfillment, refund payment | Admin approval required |
+
+**Error Handling**:
+| Error Scenario | From State | Recovery Action | Timeout |
+|----------------|------------|-----------------|---------|
+| Payment timeout | Pending | Auto-cancel, release inventory | 15 minutes |
+| Inventory unavailable | Processing | Cancel order, full refund | Immediate |
+| Shipping failure | Processing | Retry 3x, then cancel | 24 hours |
+```
+
+### 4. Error Handling Strategy
+
+Define global error handling approach.
+
+**Template**:
+```markdown
+## Error Handling Strategy
+
+### Error Classification
+| Error Type | Classification | Retry Strategy | User Impact |
+|------------|----------------|----------------|-------------|
+| [error] | Transient/Permanent/Degraded | [strategy] | [impact] |
+
+### Recovery Mechanisms
+| Component | Error | Recovery | Timeout | Fallback |
+|-----------|-------|----------|---------|----------|
+| [component] | [error] | [action] | [duration] | [fallback] |
+
+### Circuit Breaker
+- **Threshold**: [failure count] failures in [time window]
+- **Open Duration**: [duration]
+- **Half-Open Test**: [test strategy]
+```
+
+**Example**:
+```markdown
+## Error Handling Strategy
+
+### Error Classification
+| Error Type | Classification | Retry Strategy | User Impact |
+|------------|----------------|----------------|-------------|
+| DB Connection Lost | Transient | Exponential backoff, 3 retries | Request delayed 1-5s |
+| Invalid Input | Permanent | No retry, return 400 | Immediate error response |
+| Payment Gateway Timeout | Transient | Retry 2x with 5s delay | Order pending, notify user |
+| Inventory Service Down | Degraded | Use cached data, mark stale | Show approximate availability |
+
+### Recovery Mechanisms
+| Component | Error | Recovery | Timeout | Fallback |
+|-----------|-------|----------|---------|----------|
+| Database | Connection lost | Retry 3x with exponential backoff (1s, 2s, 4s) | 10s total | Return 503 Service Unavailable |
+| Payment Gateway | Timeout | Retry 2x with 5s delay | 15s total | Mark order as pending, async retry |
+| Inventory Service | Service down | Use cached inventory (max 5min old) | 3s | Show "limited availability" |
+| Email Service | Send failure | Queue for async retry (5 attempts over 24h) | N/A | Log failure, continue order |
+
+### Circuit Breaker
+- **Threshold**: 5 failures in 60 seconds
+- **Open Duration**: 30 seconds
+- **Half-Open Test**: Single request, if success → close, if fail → open for 60s
+```
+
+### 5. Observability Requirements
+
+Define metrics, logs, and health checks.
+
+**Template**:
+```markdown
+## Observability Requirements
+
+### Metrics
+| Metric Name | Type | Labels | Description | Alert Threshold |
+|-------------|------|--------|-------------|-----------------|
+| [metric] | Counter/Gauge/Histogram | [labels] | [description] | [threshold] |
+
+### Log Events
+| Event | Level | Fields | When to Log |
+|-------|-------|--------|-------------|
+| [event] | INFO/WARN/ERROR | [fields] | [condition] |
+
+### Health Checks
+| Endpoint | Check | Success Criteria | Timeout |
+|----------|-------|------------------|---------|
+| [endpoint] | [check] | [criteria] | [duration] |
+```
+
+**Example**:
+```markdown
+## Observability Requirements
+
+### Metrics
+| Metric Name | Type | Labels | Description | Alert Threshold |
+|-------------|------|--------|-------------|-----------------|
+| http_request_duration_ms | Histogram | endpoint, method, status | Request latency distribution | P99 > 500ms |
+| active_orders | Gauge | status | Current orders by status | - |
+| order_state_transitions | Counter | from_state, to_state, event | State transition count | - |
+| payment_failures | Counter | reason | Payment failure count | > 10/min |
+| db_connection_pool_size | Gauge | pool_name | Active DB connections | > 80% capacity |
+
+### Log Events
+| Event | Level | Fields | When to Log |
+|-------|-------|--------|-------------|
+| order_created | INFO | order_id, user_id, total_amount | Every order creation |
+| order_state_changed | INFO | order_id, from_state, to_state, event | Every state transition |
+| payment_failed | WARN | order_id, user_id, reason, amount | Payment failure |
+| inventory_unavailable | ERROR | order_id, item_id, requested_qty | Inventory check fails |
+| circuit_breaker_opened | ERROR | component, failure_count | Circuit breaker opens |
+
+### Health Checks
+| Endpoint | Check | Success Criteria | Timeout |
+|----------|-------|------------------|---------|
+| /health/live | Process alive | HTTP 200 | 1s |
+| /health/ready | DB + Cache reachable | HTTP 200, all deps OK | 5s |
+| /health/db | Database query | SELECT 1 succeeds | 3s |
+| /health/cache | Cache ping | PING succeeds | 2s |
+```
+
+### 6. Configuration Model
+
+Define all configurable parameters for the system.
+
+**Template**:
+```markdown
+## Configuration Model
+
+| Config Key | Type | Default | Constraint | Description | Environment |
+|------------|------|---------|------------|-------------|-------------|
+| [key] | [type] | [default] | [constraint] | [description] | [env] |
+
+**Configuration Categories**:
+- **Application**: Core application settings
+- **Database**: Database connection and pool settings
+- **Cache**: Cache configuration
+- **Security**: Authentication and authorization settings
+- **Observability**: Logging and monitoring settings
+
+**Validation Rules**:
+- [Config key] MUST be [constraint]
+- [Config key] SHOULD be [recommendation]
+
+**Configuration Loading**:
+- Priority: Environment variables > Config file > Defaults
+- Hot reload: [Supported/Not supported]
+```
+
+**Example**:
+```markdown
+## Configuration Model
+
+| Config Key | Type | Default | Constraint | Description | Environment |
+|------------|------|---------|------------|-------------|-------------|
+| SERVER_PORT | int | 8080 | 1024-65535 | HTTP server port | APP_PORT |
+| DB_HOST | string | localhost | Valid hostname/IP | Database host | DATABASE_HOST |
+| DB_PORT | int | 5432 | 1024-65535 | Database port | DATABASE_PORT |
+| DB_MAX_CONNECTIONS | int | 100 | 10-1000 | Max DB connection pool size | DB_POOL_SIZE |
+| CACHE_TTL_SECONDS | int | 3600 | 60-86400 | Cache entry TTL | CACHE_TTL |
+| SESSION_TIMEOUT_SECONDS | int | 1800 | 300-7200 | User session timeout | SESSION_TIMEOUT |
+| LOG_LEVEL | enum | INFO | DEBUG/INFO/WARN/ERROR | Logging level | LOG_LEVEL |
+| ENABLE_METRICS | bool | true | true/false | Enable Prometheus metrics | METRICS_ENABLED |
+| RATE_LIMIT_PER_MINUTE | int | 100 | 1-10000 | API rate limit per user | RATE_LIMIT |
+
+**Configuration Categories**:
+- **Application**: SERVER_PORT, LOG_LEVEL
+- **Database**: DB_HOST, DB_PORT, DB_MAX_CONNECTIONS
+- **Cache**: CACHE_TTL_SECONDS
+- **Security**: SESSION_TIMEOUT_SECONDS
+- **Observability**: ENABLE_METRICS, LOG_LEVEL
+
+**Validation Rules**:
+- DB_MAX_CONNECTIONS MUST be <= database server max_connections
+- SESSION_TIMEOUT_SECONDS SHOULD be >= 300 (5 minutes) for security
+- CACHE_TTL_SECONDS MUST be > 0
+- RATE_LIMIT_PER_MINUTE SHOULD be tuned based on expected load
+
+**Configuration Loading**:
+- Priority: Environment variables > config.yaml > Defaults
+- Hot reload: Supported for LOG_LEVEL, CACHE_TTL_SECONDS, RATE_LIMIT_PER_MINUTE
+- Restart required: SERVER_PORT, DB_HOST, DB_PORT
+```
+
+### 7. Boundary Scenarios
+
+Define system behavior in edge cases and operational scenarios.
+
+**Template**:
+```markdown
+## Boundary Scenarios
+
+### Concurrency
+- **Max Concurrent Requests**: [number]
+- **Queueing Strategy**: [Drop oldest / Block / Return 503]
+- **Thread Pool Size**: [number]
+- **Connection Pool Size**: [number]
+
+### Rate Limiting
+- **Per-User Limit**: [requests/minute]
+- **Global Limit**: [requests/minute]
+- **Burst Allowance**: [number]
+- **Rate Limit Response**: HTTP 429 with Retry-After header
+
+### Graceful Shutdown
+- **Drain Period**: [duration] - Stop accepting new requests
+- **In-Flight Timeout**: [duration] - Wait for active requests
+- **Force Kill After**: [duration] - Hard shutdown
+- **Shutdown Hooks**: [cleanup actions]
+
+### Resource Cleanup
+- **Idle Connection Timeout**: [duration]
+- **Stale Session Cleanup**: [frequency]
+- **Temporary File Cleanup**: [frequency]
+- **Log Rotation**: [frequency/size]
+
+### Scalability
+- **Horizontal Scaling**: [Supported/Not supported]
+- **Stateless Design**: [Yes/No]
+- **Shared State**: [Redis/Database/None]
+- **Load Balancing**: [Round-robin/Least-connections/IP-hash]
+
+### Disaster Recovery
+- **Backup Frequency**: [frequency]
+- **Backup Retention**: [duration]
+- **Recovery Time Objective (RTO)**: [duration]
+- **Recovery Point Objective (RPO)**: [duration]
+```
+
+**Example**:
+```markdown
+## Boundary Scenarios
+
+### Concurrency
+- **Max Concurrent Requests**: 1000 per instance
+- **Queueing Strategy**: Return HTTP 503 when queue full (max 100 queued)
+- **Thread Pool Size**: 200 worker threads
+- **Connection Pool Size**: 100 database connections
+
+### Rate Limiting
+- **Per-User Limit**: 100 requests/minute
+- **Global Limit**: 10,000 requests/minute per instance
+- **Burst Allowance**: 20 requests (allow short bursts)
+- **Rate Limit Response**: HTTP 429 with `Retry-After: 60` header
+
+### Graceful Shutdown
+- **Drain Period**: 10 seconds - Stop accepting new requests, return 503
+- **In-Flight Timeout**: 30 seconds - Wait for active requests to complete
+- **Force Kill After**: 60 seconds - Hard shutdown if requests still active
+- **Shutdown Hooks**:
+  - Close database connections
+  - Flush metrics to monitoring system
+  - Save in-memory cache to Redis
+  - Deregister from service discovery
+
+### Resource Cleanup
+- **Idle Connection Timeout**: 5 minutes - Close idle DB connections
+- **Stale Session Cleanup**: Every 1 hour - Remove expired sessions
+- **Temporary File Cleanup**: Every 24 hours - Delete files older than 7 days
+- **Log Rotation**: Daily or when file size > 100MB
+
+### Scalability
+- **Horizontal Scaling**: Supported - Stateless design
+- **Stateless Design**: Yes - All state in Redis/Database
+- **Shared State**: Redis for sessions, PostgreSQL for persistent data
+- **Load Balancing**: Least-connections algorithm (sticky sessions not required)
+
+### Disaster Recovery
+- **Backup Frequency**: Database backup every 6 hours
+- **Backup Retention**: 30 days
+- **Recovery Time Objective (RTO)**: 1 hour - System operational within 1 hour
+- **Recovery Point Objective (RPO)**: 6 hours - Max 6 hours of data loss acceptable
+```
+
+## Usage Instructions
+
+When generating system-architect analysis:
+1. Architecture Overview (high-level)
+2. Data Model (3-5 core entities)
+3. State Machine (1-2 entities with complex lifecycle)
+4. Error Handling Strategy (global + per-component)
+5. Observability Requirements (metrics, logs, health checks)
+6. Configuration Model (all configurable parameters)
+7. Boundary Scenarios (concurrency, rate limiting, shutdown, cleanup, scalability, DR)
+
+All sections MUST use RFC 2119 keywords (MUST, SHOULD, MAY) for constraints.