Claude-Code-Workflow/.claude/skills/team-lifecycle-v3/specs/core-concepts.md

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:

{
  "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