Claude-Code-Workflow/.claude/skills/team-lifecycle-v3/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
team-lifecycle-v3	Enhanced lifecycle with parallel execution, conditional routing, dynamic role injection, and task priority scheduling. Built on team-worker agent architecture with artifact contracts and automatic discovery.	TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)

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.

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]

Role Router

Coordinator-only. Workers spawned as team-worker agents.

Role Registry

Role	Spec	Task Prefix	Type	Inner Loop	Injection
coordinator	roles/coordinator/role.md	(none)	orchestrator	-	Always
analyst	role-specs/analyst.md	RESEARCH-*	pipeline	false	Always
writer	role-specs/writer.md	DRAFT-*	pipeline	true	Always
planner	role-specs/planner.md	PLAN-*	pipeline	true	Always
executor	role-specs/executor.md	IMPL-*	pipeline	true	Always
tester	role-specs/tester.md	TEST-*	pipeline	false	Always
reviewer	role-specs/reviewer.md	REVIEW-* + QUALITY-* + IMPROVE-*	pipeline	false	Always
architect	role-specs/architect.md	ARCH-*	consulting	false	High complexity
fe-developer	role-specs/fe-developer.md	DEV-FE-*	frontend	false	Frontend tasks
fe-qa	role-specs/fe-qa.md	QA-FE-*	frontend	false	Frontend tasks
orchestrator	role-specs/orchestrator.md	ORCH-*	specialist	false	Multi-module
security-expert	role-specs/security-expert.md	SECURITY-*	specialist	false	security keywords
performance-optimizer	role-specs/performance-optimizer.md	PERF-*	specialist	false	performance keywords
data-engineer	role-specs/data-engineer.md	DATA-*	specialist	false	data keywords
devops-engineer	role-specs/devops-engineer.md	DEVOPS-*	specialist	false	devops keywords
ml-engineer	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 can spawn utility members for team-level orchestration:

Utility Member	Purpose	When
explorer	Parallel multi-angle exploration	High complexity analysis
discussant	Aggregate multi-CLI critique	Critical decision points

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

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

---

Coordinator Spawn Template

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: <team-name>,
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-lifecycle-v3/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>
priority: <P0|P1|P2>

Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
})

---

Pipeline Definitions

Spec-only (6 tasks, 3 discuss)

RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> DRAFT-003 -> DRAFT-004 -> QUALITY-001(+D3)

Impl-only (4 tasks)

PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001

Full-lifecycle (10 tasks, v2 compatible)

[Spec pipeline] -> PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 + REVIEW-001

Enhanced Parallel Pipeline (v3 NEW)

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)

Conditional Routing (v3 NEW)

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)

Dynamic Injection Example (v3 NEW)

Task description: "Implement user authentication with OAuth2, add security audit, optimize login performance"

Injected roles:

• security-expert (keyword: security, audit)
• performance-optimizer (keyword: optimize, performance)

Pipeline becomes:

PLAN-001 -> IMPL-001 || SECURITY-001 || PERF-001 -> TEST-001 -> REVIEW-001

Cadence Control

Beat model: Event-driven, 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 (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

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

{
  "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	YAML frontmatter, naming, structure
Quality Gates	specs/quality-gates.md	Per-phase quality gates
Team Config	specs/team-config.json	Role registry, pipeline definitions
Artifact Contract	specs/artifact-contract-spec.md	Artifact manifest schema
Role Library	specs/role-library/	Dynamic role definitions
Product Brief Template	templates/product-brief.md	DRAFT-001
Requirements Template	templates/requirements-prd.md	DRAFT-002
Architecture Template	templates/architecture-doc.md	DRAFT-003
Epics Template	templates/epics-template.md	DRAFT-004
Discuss Subagent	subagents/discuss-subagent.md	3-round discuss protocol
Explorer Subagent	subagents/explorer-subagent.md	Shared exploration with cache
Doc Generator Subagent	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