catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-07 16:41:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add Role Analysis Reviewer Agent and validation template

Browse Source 
- 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
2026-03-05 19:58:10 +08:00
parent bc7a556985
commit 3fd55ebd4b
55 changed files with 4262 additions and 1138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

619
.claude/skills/team-lifecycle-v3/specs/domain-model.md Normal file
View 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)