mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-07 16:41:06 +08:00
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.
This commit is contained in:
catlog22
61
.claude/skills/team-lifecycle-v3/specs/README.md
Normal file
61
.claude/skills/team-lifecycle-v3/specs/README.md
Normal file
@@ -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)
|
||||
264
.claude/skills/team-lifecycle-v3/specs/core-concepts.md
Normal file
264
.claude/skills/team-lifecycle-v3/specs/core-concepts.md
Normal file
@@ -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 |
|
||||
619
.claude/skills/team-lifecycle-v3/specs/domain-model.md
Normal file
619
.claude/skills/team-lifecycle-v3/specs/domain-model.md
Normal file
@@ -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)
|
||||
643
.claude/skills/team-lifecycle-v3/specs/execution-flow.md
Normal file
643
.claude/skills/team-lifecycle-v3/specs/execution-flow.md
Normal file
@@ -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
|
||||
@@ -1,65 +0,0 @@
|
||||
# Role Library - Team Lifecycle v3
|
||||
|
||||
Dynamic role specification library for team-lifecycle-v3. Role definitions are loaded at runtime to extend the built-in role detection table.
|
||||
|
||||
## Purpose
|
||||
|
||||
- Extend role inference beyond hardcoded defaults
|
||||
- Support domain-specific specialist roles
|
||||
- Enable dynamic role injection based on task keywords
|
||||
- Maintain backward compatibility with v2 core roles
|
||||
|
||||
## Role Categories
|
||||
|
||||
### Core Pipeline Roles (v2 inherited)
|
||||
- analyst, writer, planner, executor, tester, reviewer
|
||||
- architect, fe-developer, fe-qa
|
||||
|
||||
### Specialist Roles (v3 new)
|
||||
- **orchestrator**: Complex task decomposition and parallel coordination
|
||||
- **security-expert**: Security analysis and vulnerability scanning
|
||||
- **performance-optimizer**: Performance profiling and optimization
|
||||
- **data-engineer**: Data pipeline and schema design
|
||||
- **devops-engineer**: Infrastructure as code and CI/CD
|
||||
- **ml-engineer**: Machine learning pipeline implementation
|
||||
|
||||
## Dynamic Role Injection
|
||||
|
||||
Specialist roles are injected at runtime when coordinator detects matching keywords in task descriptions:
|
||||
|
||||
| Keywords | Injected Role |
|
||||
|----------|---------------|
|
||||
| security, vulnerability, OWASP | security-expert |
|
||||
| performance, optimization, bottleneck | performance-optimizer |
|
||||
| data, pipeline, ETL, schema | data-engineer |
|
||||
| devops, CI/CD, deployment, docker | devops-engineer |
|
||||
| machine learning, ML, model, training | ml-engineer |
|
||||
| orchestrate, complex, multi-module | orchestrator |
|
||||
|
||||
## Role Definition Format
|
||||
|
||||
Each role definition is a `.role.md` file with YAML frontmatter + description.
|
||||
|
||||
### Schema
|
||||
|
||||
```yaml
|
||||
---
|
||||
role: <role-name>
|
||||
keywords: [<keyword1>, <keyword2>, ...]
|
||||
responsibility_type: <Orchestration|Code generation|Validation|Read-only analysis>
|
||||
task_prefix: <PREFIX>
|
||||
default_inner_loop: <true|false>
|
||||
category: <domain-category>
|
||||
capabilities: [<capability1>, <capability2>, ...]
|
||||
---
|
||||
|
||||
<Role description and responsibilities>
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Role library is loaded by coordinator during Phase 1 (Requirements Collection) to extend role detection capabilities. Custom roles override built-in roles with same `role` identifier.
|
||||
|
||||
## Extensibility
|
||||
|
||||
Users can add custom role definitions by creating new `.role.md` files in this directory following the schema above.
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
role: data-engineer
|
||||
keywords: [data, pipeline, ETL, database, schema, migration, analytics]
|
||||
responsibility_type: Code generation
|
||||
task_prefix: DATA
|
||||
default_inner_loop: false
|
||||
category: data
|
||||
capabilities:
|
||||
- data_pipeline_design
|
||||
- schema_design
|
||||
- etl_implementation
|
||||
---
|
||||
|
||||
# Data Engineer
|
||||
|
||||
Designs and implements data pipelines, schemas, and ETL processes.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Design database schemas and data models
|
||||
- Implement ETL pipelines for data processing
|
||||
- Create data migration scripts
|
||||
- Optimize data storage and retrieval
|
||||
- Implement data validation and quality checks
|
||||
|
||||
## Typical Tasks
|
||||
|
||||
- Design and implement data warehouse schema
|
||||
- Build ETL pipeline for analytics
|
||||
- Create database migration scripts
|
||||
- Implement data validation framework
|
||||
|
||||
## Integration Points
|
||||
|
||||
- Called by coordinator when data keywords detected
|
||||
- Works with executor for backend integration
|
||||
- Coordinates with planner for data architecture
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
role: devops-engineer
|
||||
keywords: [devops, CI/CD, deployment, infrastructure, docker, kubernetes, terraform]
|
||||
responsibility_type: Code generation
|
||||
task_prefix: DEVOPS
|
||||
default_inner_loop: false
|
||||
category: devops
|
||||
capabilities:
|
||||
- infrastructure_as_code
|
||||
- ci_cd_pipeline
|
||||
- deployment_automation
|
||||
---
|
||||
|
||||
# DevOps Engineer
|
||||
|
||||
Implements infrastructure as code, CI/CD pipelines, and deployment automation.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Design and implement CI/CD pipelines
|
||||
- Create infrastructure as code (Terraform, CloudFormation)
|
||||
- Implement deployment automation
|
||||
- Configure monitoring and alerting
|
||||
- Manage containerization and orchestration
|
||||
|
||||
## Typical Tasks
|
||||
|
||||
- Set up CI/CD pipeline for new project
|
||||
- Implement infrastructure as code for cloud resources
|
||||
- Create Docker containerization strategy
|
||||
- Configure Kubernetes deployment
|
||||
|
||||
## Integration Points
|
||||
|
||||
- Called by coordinator when devops keywords detected
|
||||
- Works with executor for deployment integration
|
||||
- Coordinates with planner for infrastructure architecture
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
role: ml-engineer
|
||||
keywords: [machine learning, ML, model, training, inference, neural network, AI]
|
||||
responsibility_type: Code generation
|
||||
task_prefix: ML
|
||||
default_inner_loop: false
|
||||
category: machine-learning
|
||||
capabilities:
|
||||
- model_training
|
||||
- feature_engineering
|
||||
- model_deployment
|
||||
---
|
||||
|
||||
# ML Engineer
|
||||
|
||||
Implements machine learning pipelines, model training, and inference systems.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Design and implement ML training pipelines
|
||||
- Perform feature engineering and data preprocessing
|
||||
- Train and evaluate ML models
|
||||
- Implement model serving and inference
|
||||
- Monitor model performance and drift
|
||||
|
||||
## Typical Tasks
|
||||
|
||||
- Build ML training pipeline
|
||||
- Implement feature engineering pipeline
|
||||
- Deploy model serving infrastructure
|
||||
- Create model monitoring system
|
||||
|
||||
## Integration Points
|
||||
|
||||
- Called by coordinator when ML keywords detected
|
||||
- Works with data-engineer for data pipeline integration
|
||||
- Coordinates with planner for ML architecture
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
role: orchestrator
|
||||
keywords: [orchestrate, coordinate, complex, multi-module, decompose, parallel, dependency]
|
||||
responsibility_type: Orchestration
|
||||
task_prefix: ORCH
|
||||
default_inner_loop: false
|
||||
category: orchestration
|
||||
weight: 1.5
|
||||
capabilities:
|
||||
- task_decomposition
|
||||
- parallel_coordination
|
||||
- dependency_management
|
||||
---
|
||||
|
||||
# Orchestrator
|
||||
|
||||
Decomposes complex multi-module tasks into coordinated sub-tasks with dependency management and parallel execution support.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Analyze complex requirements and decompose into manageable sub-tasks
|
||||
- Coordinate parallel execution of multiple implementation tracks
|
||||
- Manage dependencies between sub-tasks
|
||||
- Integrate results from parallel workers
|
||||
- Validate integration points and cross-module consistency
|
||||
|
||||
## Typical Tasks
|
||||
|
||||
- Break down large features into frontend + backend + data components
|
||||
- Coordinate multi-team parallel development
|
||||
- Manage complex refactoring across multiple modules
|
||||
- Orchestrate migration strategies with phased rollout
|
||||
|
||||
## Integration Points
|
||||
|
||||
- Works with planner to receive high-level plans
|
||||
- Spawns multiple executor/fe-developer workers in parallel
|
||||
- Integrates with tester for cross-module validation
|
||||
- Reports to coordinator with integration status
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
role: performance-optimizer
|
||||
keywords: [performance, optimization, bottleneck, latency, throughput, profiling, benchmark]
|
||||
responsibility_type: Read-only analysis
|
||||
task_prefix: PERF
|
||||
default_inner_loop: false
|
||||
category: performance
|
||||
capabilities:
|
||||
- performance_profiling
|
||||
- bottleneck_identification
|
||||
- optimization_recommendations
|
||||
---
|
||||
|
||||
# Performance Optimizer
|
||||
|
||||
Analyzes code and architecture for performance bottlenecks and provides optimization recommendations.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Profile code execution and identify bottlenecks
|
||||
- Analyze database query performance
|
||||
- Review caching strategies and effectiveness
|
||||
- Assess resource utilization (CPU, memory, I/O)
|
||||
- Recommend optimization strategies
|
||||
|
||||
## Typical Tasks
|
||||
|
||||
- Performance audit of critical paths
|
||||
- Database query optimization review
|
||||
- Caching strategy assessment
|
||||
- Load testing analysis and recommendations
|
||||
|
||||
## Integration Points
|
||||
|
||||
- Called by coordinator when performance keywords detected
|
||||
- Works with reviewer for performance-focused code review
|
||||
- Reports findings with impact levels and optimization priorities
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
role: security-expert
|
||||
keywords: [security, vulnerability, OWASP, compliance, audit, penetration, threat]
|
||||
responsibility_type: Read-only analysis
|
||||
task_prefix: SECURITY
|
||||
default_inner_loop: false
|
||||
category: security
|
||||
capabilities:
|
||||
- vulnerability_scanning
|
||||
- threat_modeling
|
||||
- compliance_checking
|
||||
---
|
||||
|
||||
# Security Expert
|
||||
|
||||
Performs security analysis, vulnerability scanning, and compliance checking for code and architecture.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Scan code for OWASP Top 10 vulnerabilities
|
||||
- Perform threat modeling and attack surface analysis
|
||||
- Check compliance with security standards (GDPR, HIPAA, etc.)
|
||||
- Review authentication and authorization implementations
|
||||
- Assess data protection and encryption strategies
|
||||
|
||||
## Typical Tasks
|
||||
|
||||
- Security audit of authentication module
|
||||
- Vulnerability assessment of API endpoints
|
||||
- Compliance review for data handling
|
||||
- Threat modeling for new features
|
||||
|
||||
## Integration Points
|
||||
|
||||
- Called by coordinator when security keywords detected
|
||||
- Works with reviewer for security-focused code review
|
||||
- Reports findings with severity levels (Critical/High/Medium/Low)
|
||||
Reference in New Issue
Block a user