catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-28 09:23:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(workflow): add lightweight interactive planning workflow with in-memory execution and code exploration

Browse Source 
- Introduced `lite-plan` command for intelligent task analysis and planning.
- Implemented dynamic exploration and clarification phases based on task complexity.
- Added support for auto mode and forced exploration flags.
- Defined output artifacts and session structure for planning results.
- Enhanced execution process with context handoff to `lite-execute`.

chore(temp): create temporary memory content and import script

- Added `.temp-memory-content.txt` to store session details and execution plan.
- Implemented `temp-import-memory.cjs` to handle memory import using core-memory command.
- Ensured cleanup of temporary files after execution.
This commit is contained in:
catlog22
2026-02-27 11:43:44 +08:00
parent 07452e57b7
commit 4d755ff9b4
48 changed files with 5659 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
.ccw/workflows/cli-templates/schemas/explore-json-schema.json
View File

@@ -63,6 +63,35 @@
"type": "array",
"items": {"type": "string"},
"description": "Key symbols (functions, classes, types) in this file relevant to the task. Example: ['AuthService', 'login', 'TokenPayload']"
},
"key_code": {
"type": "array",
"items": {
"type": "object",
"required": ["symbol", "description"],
"properties": {
"symbol": {
"type": "string",
"description": "Symbol identifier (function, class, method, type). Example: 'AuthService.login()'"
},
"location": {
"type": "string",
"description": "Line range in file. Example: 'L45-L78'"
},
"description": {
"type": "string",
"minLength": 10,
"description": "What this code does and why it matters. Example: 'JWT token generation with bcrypt verification, returns {token, refreshToken} pair'"
}
},
"additionalProperties": false
},
"description": "Key code constructs with descriptions. Richer complement to key_symbols. Populate for files with relevance >= 0.7."
},
"topic_relation": {
"type": "string",
"minLength": 15,
"description": "How this file relates to the exploration ANGLE/TOPIC. Must reference the angle explicitly. Example: 'Security exploration targets this file because JWT generation lacks token rotation'. Distinct from rationale (WHY selected) - topic_relation explains the CONNECTION to the exploration perspective."
}
},
"additionalProperties": false

15
.claude/agents/cli-explore-agent.md
View File

@@ -123,7 +123,10 @@ RULES: {from prompt, if template specified} | analysis=READ-ONLY
2. Gemini results: Semantic understanding, design intent → `discovery_source: "cli-analysis"`
3. ACE search: Semantic code search → `discovery_source: "ace-search"`
4. Dependency tracing: Import/export graph → `discovery_source: "dependency-trace"`
5. Merge with source attribution and generate rationale for each file
5. Merge with source attribution and generate for each file:
- `rationale`: WHY the file was selected (selection basis)
- `topic_relation`: HOW the file connects to the exploration angle/topic
- `key_code`: Detailed descriptions of key symbols with locations (for relevance >= 0.7)
---
@@ -155,6 +158,12 @@ Every file entry MUST have:
- BAD: "Related to auth" or "Relevant file"
- `role` (required, enum): Structural classification of why it was selected
- `discovery_source` (optional but recommended): How the file was found
- `key_code` (strongly recommended for relevance >= 0.7): Array of {symbol, location?, description}
- GOOD: [{"symbol": "AuthService.login()", "location": "L45-L78", "description": "JWT token generation with bcrypt verification, returns token pair"}]
- BAD: [{"symbol": "login", "description": "login function"}]
- `topic_relation` (strongly recommended for relevance >= 0.7): Connection from exploration angle perspective
- GOOD: "Security exploration targets this file because JWT generation lacks token rotation"
- BAD: "Related to security"
**Step 4: Pre-Output Validation Checklist**
@@ -168,6 +177,8 @@ Before writing ANY JSON output, verify:
- [ ] Data types correct (string, integer, array, object)
- [ ] Every file in relevant_files has: path + relevance + rationale + role
- [ ] Every rationale is specific (>10 chars, not generic)
- [ ] Files with relevance >= 0.7 have key_code with symbol + description (minLength 10)
- [ ] Files with relevance >= 0.7 have topic_relation explaining connection to angle (minLength 15)
---
@@ -216,6 +227,8 @@ Brief summary:
9. **Every file MUST have rationale**: Specific selection basis tied to the topic (not generic)
10. **Every file MUST have role**: Classify as modify_target/dependency/pattern_reference/test_target/type_definition/integration_point/config/context_only
11. **Track discovery source**: Record how each file was found (bash-scan/cli-analysis/ace-search/dependency-trace/manual)
12. **Populate key_code for high-relevance files**: relevance >= 0.7 → key_code array with symbol, location, description
13. **Populate topic_relation for high-relevance files**: relevance >= 0.7 → topic_relation explaining file-to-angle connection
**Bash Tool**:
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution

3
.claude/agents/cli-lite-planning-agent.md
View File

@@ -504,7 +504,7 @@ function parseCLIOutput(cliOutput) {
```javascript
// NOTE: relevant_files items are structured objects:
// {path, relevance, rationale, role, discovery_source?, key_symbols?}
// {path, relevance, rationale, role, discovery_source?, key_symbols?, key_code?, topic_relation?}
function buildEnrichedContext(explorationsContext, explorationAngles) {
const enriched = { relevant_files: [], patterns: [], dependencies: [], integration_points: [], constraints: [] }
@@ -566,6 +566,7 @@ function inferAction(title) {
}
// NOTE: relevant_files items are structured objects with .path property
// New fields: key_code? (array of {symbol, location?, description}), topic_relation? (string)
function inferFile(task, ctx) {
const files = ctx?.relevant_files || []
const getPath = f => typeof f === 'string' ? f : f.path

465
.claude/skills/team-lifecycle-v4/SKILL.md Normal file
View File

@@ -0,0 +1,465 @@
---
name: team-lifecycle-v4
description: Unified team skill for full lifecycle - spec/impl/test. Optimized cadence with inline discuss subagent and shared explore. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team lifecycle".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
# Team Lifecycle v4
Unified team skill: specification -> implementation -> testing -> review. Optimized from v3 with **inline discuss subagent** and **shared explore utility**, halving spec pipeline beats from 12 to 6.
## Key Changes from v3
| Change | Before (v3) | After (v4) | Impact |
|--------|------------|------------|--------|
| Discuss | Standalone role, 6 separate beats | Inline subagent called by produce roles | Spec beats: 12 -> 6 |
| Explorer | Standalone service role | Shared Explore subagent with cache | Eliminates spawn overhead |
| Explore cache | Per-role, no sharing | Centralized `explorations/` with cache-index | Avoids duplicate exploration |
| Worker advance | Always callback coordinator | Fast-advance for simple successors | Fewer coordinator wakes |
## Architecture
```
+---------------------------------------------------+
| Skill(skill="team-lifecycle-v4") |
| args="task description" or args="--role=xxx" |
+-------------------+-------------------------------+
| Role Router
+---- --role present? ----+
| NO | YES
v v
Orchestration Mode Role Dispatch
(auto -> coordinator) (route to role.md)
|
+----+----+-------+-------+-------+-------+
v v v v v v
coordinator analyst writer planner executor tester
^ ^
on-demand by coordinator
+---------+ +--------+
|architect| |reviewer|
+---------+ +--------+
+-------------+ +-----+
|fe-developer | |fe-qa|
+-------------+ +-----+
Subagents (callable by any role, not team members):
[discuss-subagent] - multi-perspective critique
[explore-subagent] - codebase exploration with cache
```
## Role Router
### Input Parsing
Parse `$ARGUMENTS` to extract `--role`. If absent -> Orchestration Mode (auto route to coordinator).
### Role Registry
| Role | File | Task Prefix | Type | Compact |
|------|------|-------------|------|---------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | compact must re-read |
| analyst | [roles/analyst/role.md](roles/analyst/role.md) | RESEARCH-* | pipeline | compact must re-read |
| writer | [roles/writer/role.md](roles/writer/role.md) | DRAFT-* | pipeline | compact must re-read |
| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | pipeline | compact must re-read |
| executor | [roles/executor/role.md](roles/executor/role.md) | IMPL-* | pipeline | compact must re-read |
| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | pipeline | compact must re-read |
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-* + QUALITY-* | pipeline | compact must re-read |
| architect | [roles/architect/role.md](roles/architect/role.md) | ARCH-* | consulting (on-demand) | compact must re-read |
| fe-developer | [roles/fe-developer/role.md](roles/fe-developer/role.md) | DEV-FE-* | frontend pipeline | compact must re-read |
| fe-qa | [roles/fe-qa/role.md](roles/fe-qa/role.md) | QA-FE-* | frontend pipeline | compact must re-read |
> **COMPACT PROTECTION**: Role files are execution documents. After context compression, role instructions become summaries only -- **MUST immediately `Read` the role.md to reload before continuing**. Never execute any Phase based on summaries.
### Subagent Registry
| Subagent | Spec | Callable By | Purpose |
|----------|------|-------------|---------|
| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | analyst, writer, reviewer | Multi-perspective critique |
| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | analyst, planner, any role | Codebase exploration with cache |
### Dispatch
1. Extract `--role` from arguments
2. If no `--role` -> route to coordinator (Orchestration Mode)
3. Look up role in registry -> Read the role file -> Execute its phases
### Orchestration Mode
When invoked without `--role`, coordinator auto-starts. User just provides task description.
**Invocation**: `Skill(skill="team-lifecycle-v4", args="task description")`
**Lifecycle**:
```
User provides task description
-> coordinator Phase 1-3: requirement clarification -> TeamCreate -> create task chain
-> coordinator Phase 4: spawn first batch workers (background) -> STOP
-> Worker executes -> SendMessage callback -> coordinator advances next step
-> Loop until pipeline complete -> Phase 5 report
```
**User Commands** (wake paused coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no advancement |
| `resume` / `continue` | Check worker states, advance next step |
---
## Shared Infrastructure
The following templates apply to all worker roles. Each role.md only needs to write **Phase 2-4** role-specific logic.
### Worker Phase 1: Task Discovery (all workers shared)
Each worker on startup executes the same task discovery flow:
1. Call `TaskList()` to get all tasks
2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty
3. No tasks -> idle wait
4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress
**Resume Artifact Check** (prevent duplicate output after resume):
- Check if this task's output artifacts already exist
- Artifacts complete -> skip to Phase 5 report completion
- Artifacts incomplete or missing -> normal Phase 2-4 execution
### Worker Phase 5: Report + Fast-Advance (all workers shared)
Task completion with optional fast-advance to skip coordinator round-trip:
1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
- Params: operation="log", team=<team-name>, from=<role>, to="coordinator", type=<message-type>, summary="[<role>] <summary>", ref=<artifact-path>
- **CLI fallback**: When MCP unavailable -> `ccw team log --team <team> --from <role> --to coordinator --type <type> --summary "[<role>] ..." --json`
2. **TaskUpdate**: Mark task completed
3. **Fast-Advance Check**:
- Call `TaskList()`, find pending tasks whose blockedBy are ALL completed
- If exactly 1 ready task AND its owner matches a simple successor pattern -> **spawn it directly** (skip coordinator)
- Otherwise -> **SendMessage** to coordinator for orchestration
4. **Loop**: Back to Phase 1 to check for next task
**Fast-Advance Rules**:
| Condition | Action |
|-----------|--------|
| 1 ready task, simple linear successor | Spawn directly via Task(run_in_background: true) |
| Multiple ready tasks (parallel window) | SendMessage to coordinator (needs orchestration) |
| No ready tasks + others running | SendMessage to coordinator (status update) |
| No ready tasks + nothing running | SendMessage to coordinator (pipeline may be complete) |
| Checkpoint task (e.g., spec->impl transition) | SendMessage to coordinator (needs user confirmation) |
### Inline Discuss Protocol (produce roles: analyst, writer, reviewer)
After completing their primary output, produce roles call the discuss subagent inline:
```
Task({
subagent_type: "cli-discuss-agent",
run_in_background: false,
description: "Discuss <round-id>",
prompt: <see subagents/discuss-subagent.md for prompt template>
})
```
**Discussion round mapping** (which role runs which discuss round):
| Role | After Task | Discuss Round | Perspectives |
|------|-----------|---------------|-------------|
| analyst | RESEARCH-001 | DISCUSS-001 | product, risk, coverage |
| writer | DRAFT-001 | DISCUSS-002 | product, technical, quality, coverage |
| writer | DRAFT-002 | DISCUSS-003 | quality, product, coverage |
| writer | DRAFT-003 | DISCUSS-004 | technical, risk |
| writer | DRAFT-004 | DISCUSS-005 | product, technical, quality, coverage |
| reviewer | QUALITY-001 | DISCUSS-006 | all 5 |
The discuss subagent writes its record to `discussions/` and returns the verdict. The calling role includes the discuss result in its Phase 5 report.
### Shared Explore Utility
Any role needing codebase context calls the explore subagent:
```
Task({
subagent_type: "Explore",
run_in_background: false,
description: "Explore <angle>",
prompt: <see subagents/explore-subagent.md for prompt template>
})
```
**Cache**: Results stored in `explorations/` with `cache-index.json`. Before exploring, always check cache first. See [subagents/explore-subagent.md](subagents/explore-subagent.md).
### Wisdom Accumulation (all roles)
Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at session init.
**Directory**:
```
<session-folder>/wisdom/
+-- learnings.md # Patterns and insights
+-- decisions.md # Architecture and design decisions
+-- conventions.md # Codebase conventions
+-- issues.md # Known risks and issues
```
**Worker load** (Phase 2): Extract `Session: <path>` from task description, read wisdom files.
**Worker contribute** (Phase 4/5): Write discoveries to corresponding wisdom files.
### Role Isolation Rules
| Allowed | Prohibited |
|---------|-----------|
| Process own prefix tasks | Process other role's prefix tasks |
| SendMessage to coordinator | Directly communicate with other workers |
| Use tools declared in Toolbox | Create tasks for other roles |
| Call discuss/explore subagents | Modify resources outside own scope |
| Fast-advance simple successors | Spawn parallel worker batches |
Coordinator additionally prohibited: directly write/modify code, call implementation subagents, directly execute analysis/test/review.
---
## Pipeline Definitions
### Spec-only (6 tasks, was 12 in v3)
```
RESEARCH-001(+D1) -> DRAFT-001(+D2) -> DRAFT-002(+D3) -> DRAFT-003(+D4) -> DRAFT-004(+D5) -> QUALITY-001(+D6)
```
Each task includes inline discuss. `(+DN)` = inline discuss round N.
### Impl-only / Backend (4 tasks)
```
PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001
```
### Full-lifecycle (10 tasks, was 16 in v3)
```
[Spec pipeline] -> PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 + REVIEW-001
```
### Frontend Pipelines
```
FE-only: PLAN-001 -> DEV-FE-001 -> QA-FE-001
(GC loop: QA-FE verdict=NEEDS_FIX -> DEV-FE-002 -> QA-FE-002, max 2 rounds)
Fullstack: PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001
Full + FE: [Spec pipeline] -> PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001
```
### Cadence Control
**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
```
Beat Cycle (single beat)
======================================================================
Event Coordinator Workers
----------------------------------------------------------------------
callback/resume --> +- handleCallback -+
| mark completed |
| check pipeline |
+- handleSpawnNext -+
| find ready tasks |
| spawn workers ---+--> [Worker A] Phase 1-5
| (parallel OK) --+--> [Worker B] Phase 1-5
+- STOP (idle) -----+ |
|
callback <-----------------------------------------+
(next beat) SendMessage + TaskUpdate(completed)
======================================================================
Fast-Advance (skips coordinator for simple linear successors)
======================================================================
[Worker A] Phase 5 complete
+- 1 ready task? simple successor? --> spawn Worker B directly
+- complex case? --> SendMessage to coordinator
======================================================================
```
**Pipeline beat view (v4 optimized)**:
```
Spec-only (6 beats, was 12 in v3)
-------------------------------------------------------
Beat 1 2 3 4 5 6
| | | | | |
R1+D1 --> W1+D2 --> W2+D3 --> W3+D4 --> W4+D5 --> Q1+D6
^ ^
pipeline sign-off
start pause
R=RESEARCH W=DRAFT(writer) Q=QUALITY D=DISCUSS(inline)
Impl-only (3 beats, with parallel window)
-------------------------------------------------------
Beat 1 2 3
| | +----+----+
PLAN --> IMPL --> TEST || REVIEW <-- parallel window
+----+----+
pipeline
done
Full-lifecycle (9 beats, was 15 in v3)
-------------------------------------------------------
Beat 1-6: [Spec pipeline as above]
|
Beat 6 (Q1+D6 done): PAUSE CHECKPOINT -- user confirms then resume
|
Beat 7 8 9
PLAN --> IMPL --> TEST || REVIEW
Fullstack (with dual parallel windows)
-------------------------------------------------------
Beat 1 2 3 4
| +----+----+ +----+----+ |
PLAN --> IMPL || DEV-FE --> TEST || QA-FE --> REVIEW
^ ^ ^
parallel 1 parallel 2 sync barrier
```
**Checkpoints**:
| Trigger | Position | Behavior |
|---------|----------|----------|
| Spec->Impl transition | QUALITY-001 completed | Pause, wait for user `resume` |
| GC loop max | QA-FE max 2 rounds | Stop iteration, report current state |
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
**Stall detection** (coordinator `handleCheck`):
| Check | Condition | Resolution |
|-------|-----------|-----------|
| Worker unresponsive | in_progress task with no callback | Report waiting tasks, suggest `resume` |
| Pipeline deadlock | no ready + no running + has pending | Check blockedBy chain, report blockage |
| GC loop exceeded | DEV-FE / QA-FE iteration > max_rounds | Terminate loop, output latest QA report |
### Task Metadata Registry
| Task ID | Role | Phase | Dependencies | Description | Inline Discuss |
|---------|------|-------|-------------|-------------|---------------|
| RESEARCH-001 | analyst | spec | (none) | Seed analysis and context gathering | DISCUSS-001 |
| DRAFT-001 | writer | spec | RESEARCH-001 | Generate Product Brief | DISCUSS-002 |
| DRAFT-002 | writer | spec | DRAFT-001 | Generate Requirements/PRD | DISCUSS-003 |
| DRAFT-003 | writer | spec | DRAFT-002 | Generate Architecture Document | DISCUSS-004 |
| DRAFT-004 | writer | spec | DRAFT-003 | Generate Epics & Stories | DISCUSS-005 |
| QUALITY-001 | reviewer | spec | DRAFT-004 | 5-dimension spec quality + sign-off | DISCUSS-006 |
| PLAN-001 | planner | impl | (none or QUALITY-001) | Multi-angle exploration and planning | - |
| IMPL-001 | executor | impl | PLAN-001 | Code implementation | - |
| TEST-001 | tester | impl | IMPL-001 | Test-fix cycles | - |
| REVIEW-001 | reviewer | impl | IMPL-001 | 4-dimension code review | - |
| DEV-FE-001 | fe-developer | impl | PLAN-001 | Frontend implementation | - |
| QA-FE-001 | fe-qa | impl | DEV-FE-001 | 5-dimension frontend QA | - |
## Coordinator Spawn Template
When coordinator spawns workers, use background mode (Spawn-and-Stop):
```
Task({
subagent_type: "general-purpose",
description: "Spawn <role> worker",
team_name: <team-name>,
name: "<role>",
run_in_background: true,
prompt: `You are team "<team-name>" <ROLE>.
## Primary Instruction
All your work MUST be executed by calling Skill to get role definition:
Skill(skill="team-lifecycle-v4", args="--role=<role>")
Current requirement: <task-description>
Session: <session-folder>
## Role Guidelines
- Only process <PREFIX>-* tasks, do not execute other role work
- All output prefixed with [<role>] tag
- Only communicate with coordinator
- Do not use TaskCreate to create tasks for other roles
- Before each SendMessage, call mcp__ccw-tools__team_msg to log
- After task completion, check for fast-advance opportunity (see SKILL.md Phase 5)
## Workflow
1. Call Skill -> get role definition and execution logic
2. Follow role.md 5-Phase flow
3. team_msg + SendMessage results to coordinator
4. TaskUpdate completed -> check next task or fast-advance`
})
```
## Session Directory
```
.workflow/.team/TLS-<slug>-<date>/
+-- team-session.json # Session state
+-- spec/ # Spec artifacts
| +-- spec-config.json
| +-- discovery-context.json
| +-- product-brief.md
| +-- requirements/
| +-- architecture/
| +-- epics/
| +-- readiness-report.md
| +-- spec-summary.md
+-- discussions/ # Discussion records (written by discuss subagent)
+-- plan/ # Plan artifacts
| +-- plan.json
| +-- .task/TASK-*.json
+-- explorations/ # Shared explore cache
| +-- cache-index.json # { angle+keywords_hash -> file_path }
| +-- explore-<angle>.json
+-- architecture/ # Architect assessments + design-tokens.json
+-- analysis/ # Analyst design-intelligence.json (UI mode)
+-- qa/ # QA audit reports
+-- wisdom/ # Cross-task knowledge
| +-- learnings.md
| +-- decisions.md
| +-- conventions.md
| +-- issues.md
+-- .msg/ # Team message bus logs (messages.jsonl)
+-- shared-memory.json # Cross-role state
```
## Session Resume
Coordinator supports `--resume` / `--continue` for interrupted sessions:
1. Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions
2. Multiple matches -> AskUserQuestion for selection
3. Audit TaskList -> reconcile session state <-> task status
4. Reset in_progress -> pending (interrupted tasks)
5. Rebuild team and spawn needed workers only
6. Create missing tasks with correct blockedBy
7. Kick first executable task -> Phase 4 coordination loop
## Shared Spec Resources
| Resource | Path | Usage |
|----------|------|-------|
| Document Standards | [specs/document-standards.md](specs/document-standards.md) | YAML frontmatter, naming, structure |
| Quality Gates | [specs/quality-gates.md](specs/quality-gates.md) | Per-phase quality gates |
| Product Brief Template | [templates/product-brief.md](templates/product-brief.md) | DRAFT-001 |
| Requirements Template | [templates/requirements-prd.md](templates/requirements-prd.md) | DRAFT-002 |
| Architecture Template | [templates/architecture-doc.md](templates/architecture-doc.md) | DRAFT-003 |
| Epics Template | [templates/epics-template.md](templates/epics-template.md) | DRAFT-004 |
| Discuss Subagent | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | Inline discuss protocol |
| Explore Subagent | [subagents/explore-subagent.md](subagents/explore-subagent.md) | Shared exploration utility |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown --role value | Error with available role list |
| Missing --role arg | Orchestration Mode -> coordinator |
| Role file not found | Error with expected path |
| Command file not found | Fallback to inline execution |
| Discuss subagent fails | Role proceeds without discuss, logs warning |
| Explore cache corrupt | Clear cache, re-explore |
| Fast-advance spawns wrong task | Coordinator reconciles on next callback |

159
.claude/skills/team-lifecycle-v4/roles/analyst/role.md Normal file
View File

@@ -0,0 +1,159 @@
# Role: analyst
Seed analysis, codebase exploration (via shared explore subagent), and multi-dimensional context gathering. Includes inline discuss (DISCUSS-001) after research output.
## Identity
- **Name**: `analyst` | **Prefix**: `RESEARCH-*` | **Tag**: `[analyst]`
- **Responsibility**: Seed Analysis -> Codebase Exploration -> Context Packaging -> **Inline Discuss** -> Report
## Boundaries
### MUST
- Only process RESEARCH-* tasks
- Communicate only with coordinator
- Generate discovery-context.json and spec-config.json
- Support file reference input (@ prefix or .md/.txt extension)
- Call discuss subagent for DISCUSS-001 after output
- Use shared explore subagent for codebase exploration (cache-aware)
### MUST NOT
- Create tasks for other roles
- Directly contact other workers
- Modify spec documents (only create discovery artifacts)
- Skip seed analysis step
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| research_ready | -> coordinator | Research + discuss complete |
| research_progress | -> coordinator | Long research progress update |
| error | -> coordinator | Unrecoverable error |
## Toolbox
| Tool | Purpose |
|------|---------|
| ccw cli --tool gemini --mode analysis | Seed analysis |
| Explore subagent | Codebase exploration (shared cache) |
| discuss subagent | Inline DISCUSS-001 critique |
---
## Phase 2: Seed Analysis
**Objective**: Extract structured seed information from the topic/idea.
**Workflow**:
1. Extract session folder from task description (`Session: <path>`)
2. Parse topic from task description (first non-metadata line)
3. If topic starts with `@` or ends with `.md`/`.txt` -> Read the referenced file as topic content
4. Run Gemini CLI seed analysis:
```
Bash({
command: `ccw cli -p "PURPOSE: Analyze topic and extract structured seed information.
TASK: * Extract problem statement * Identify target users * Determine domain context
* List constraints and assumptions * Identify 3-5 exploration dimensions * Assess complexity
TOPIC: <topic-content>
MODE: analysis
EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment" --tool gemini --mode analysis`,
run_in_background: true
})
```
5. Wait for CLI result, parse seed analysis JSON
**Success**: Seed analysis parsed with problem statement, dimensions, complexity.
---
## Phase 3: Codebase Exploration (conditional)
**Objective**: Gather codebase context if an existing project is detected.
| Condition | Action |
|-----------|--------|
| package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore codebase |
| No project files | Skip -> codebase context = null |
**When project detected** (uses shared explore subagent):
1. Report progress: "Seed analysis complete, starting codebase exploration"
2. Call explore subagent with `angle: general`, `keywords: <from seed analysis>`
```
Task({
subagent_type: "Explore",
run_in_background: false,
description: "Explore general context",
prompt: "Explore codebase for: <topic>
Focus angle: general
Keywords: <seed analysis keywords>
Session folder: <session-folder>
..."
})
```
3. Use exploration results to build codebase context: tech_stack, architecture_patterns, conventions, integration_points
---
## Phase 4: Context Packaging + Inline Discuss
**Objective**: Generate spec-config.json and discovery-context.json, then run DISCUSS-001.
### 4a: Context Packaging
**spec-config.json** -> `<session-folder>/spec/spec-config.json`:
- session_id, topic, status="research_complete", complexity, depth, focus_areas, mode="interactive"
**discovery-context.json** -> `<session-folder>/spec/discovery-context.json`:
- session_id, phase=1, seed_analysis (all fields), codebase_context (or null), recommendations
**design-intelligence.json** -> `<session-folder>/analysis/design-intelligence.json` (UI mode only):
- Produced when frontend keywords detected in seed_analysis
- Fields: industry, style_direction, ux_patterns, color_strategy, typography, component_patterns
- Consumed by architect (for design-tokens.json) and fe-developer
### 4b: Inline Discuss (DISCUSS-001)
After packaging, call discuss subagent:
```
Task({
subagent_type: "cli-discuss-agent",
run_in_background: false,
description: "Discuss DISCUSS-001",
prompt: `## Multi-Perspective Critique: DISCUSS-001
### Input
- Artifact: <session-folder>/spec/discovery-context.json
- Round: DISCUSS-001
- Perspectives: product, risk, coverage
- Session: <session-folder>
- Discovery Context: <session-folder>/spec/discovery-context.json
<rest of discuss subagent prompt from subagents/discuss-subagent.md>`
})
```
**Discuss result handling**:
- `consensus_reached` -> include in report, proceed normally
- `consensus_blocked` -> flag in SendMessage, coordinator decides next step
**Report**: complexity, codebase presence, problem statement, exploration dimensions, discuss verdict, output paths.
**Success**: Both JSON files created; discuss record written; design-intelligence.json created if UI mode.
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Gemini CLI failure | Fallback to direct Claude analysis |
| Codebase detection failed | Continue as new project |
| Topic too vague | Report with clarification questions |
| Explore subagent fails | Continue without codebase context |
| Discuss subagent fails | Proceed without discuss, log warning in report |

193
.claude/skills/team-lifecycle-v4/roles/architect/commands/assess.md Normal file
View File

@@ -0,0 +1,193 @@
# Command: assess
## Purpose
Multi-mode architecture assessment. Auto-detects consultation mode from task subject prefix, runs mode-specific analysis, and produces a verdict with concerns and recommendations.
## Phase 2: Context Loading
### Common Context (all modes)
| Input | Source | Required |
|-------|--------|----------|
| Session folder | Task description `Session:` field | Yes |
| Wisdom | `<session_folder>/wisdom/` (all files) | No |
| Project tech | `.workflow/project-tech.json` | No |
| Explorations | `<session_folder>/explorations/` | No |
### Mode-Specific Context
| Mode | Task Pattern | Additional Context |
|------|-------------|-------------------|
| spec-review | ARCH-SPEC-* | `spec/architecture/_index.md`, `spec/architecture/ADR-*.md` |
| plan-review | ARCH-PLAN-* | `plan/plan.json`, `plan/.task/TASK-*.json` |
| code-review | ARCH-CODE-* | `git diff --name-only`, changed file contents |
| consult | ARCH-CONSULT-* | Question extracted from task description |
| feasibility | ARCH-FEASIBILITY-* | Proposal from task description, codebase search results |
## Phase 3: Mode-Specific Assessment
### Mode: spec-review
Review architecture documents for technical soundness across 4 dimensions.
**Assessment dimensions**:
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Consistency | 25% | ADR decisions align with each other and with architecture index |
| Scalability | 25% | Design supports growth, no single-point bottlenecks |
| Security | 25% | Auth model, data protection, API security addressed |
| Tech fitness | 25% | Technology choices match project-tech.json and problem domain |
**Checks**:
- Read architecture index and all ADR files
- Cross-reference ADR decisions for contradictions
- Verify tech choices align with project-tech.json
- Score each dimension 0-100
---
### Mode: plan-review
Review implementation plan for architectural soundness.
**Checks**:
| Check | What | Severity if Failed |
|-------|------|-------------------|
| Dependency cycles | Build task graph, detect cycles via DFS | High |
| Task granularity | Flag tasks touching >8 files | Medium |
| Convention compliance | Verify plan follows wisdom/conventions.md | Medium |
| Architecture alignment | Verify plan doesn't contradict wisdom/decisions.md | High |
**Dependency cycle detection flow**:
1. Parse all TASK-*.json files -> extract id and depends_on
2. Build directed graph
3. DFS traversal -> flag any node visited twice in same stack
4. Report cycle path if found
---
### Mode: code-review
Assess architectural impact of code changes.
**Checks**:
| Check | Method | Severity if Found |
|-------|--------|-------------------|
| Layer violations | Detect upward imports (deeper layer importing shallower) | High |
| New dependencies | Parse package.json diff for added deps | Medium |
| Module boundary changes | Flag index.ts/index.js modifications | Medium |
| Architectural impact | Score based on file count and boundary changes | Info |
**Impact scoring**:
| Condition | Impact Level |
|-----------|-------------|
| Changed files > 10 | High |
| index.ts/index.js or package.json modified | Medium |
| All other cases | Low |
**Detection example** (find changed files):
```bash
Bash(command="git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached")
```
---
### Mode: consult
Answer architecture decision questions. Route by question complexity.
**Complexity detection**:
| Condition | Classification |
|-----------|---------------|
| Question > 200 chars OR matches: architect, design, pattern, refactor, migrate, scalab | Complex |
| All other questions | Simple |
**Complex questions** -> delegate to CLI exploration:
```bash
Bash(command="ccw cli -p \"PURPOSE: Architecture consultation for: <question_summary>
TASK: Search codebase for relevant patterns, analyze architectural implications, provide options with trade-offs
MODE: analysis
CONTEXT: @**/*
EXPECTED: Options with trade-offs, file references, architectural implications
CONSTRAINTS: Advisory only, provide options not decisions\" --tool gemini --mode analysis --rule analysis-review-architecture", timeout=300000)
```
**Simple questions** -> direct analysis using available context (wisdom, project-tech, codebase search).
---
### Mode: feasibility
Evaluate technical feasibility of a proposal.
**Assessment areas**:
| Area | Method | Output |
|------|--------|--------|
| Tech stack compatibility | Compare proposal needs against project-tech.json | Compatible / Requires additions |
| Codebase readiness | Search for integration points using Grep/Glob | Touch-point count |
| Effort estimation | Based on touch-point count (see table below) | Low / Medium / High |
| Risk assessment | Based on effort + tech compatibility | Risks + mitigations |
**Effort estimation**:
| Touch Points | Effort | Implication |
|-------------|--------|-------------|
| <= 5 | Low | Straightforward implementation |
| 6 - 20 | Medium | Moderate refactoring needed |
| > 20 | High | Significant refactoring, consider phasing |
**Verdict for feasibility**:
| Condition | Verdict |
|-----------|---------|
| Low/medium effort, compatible stack | FEASIBLE |
| High touch-points OR new tech required | RISKY |
| Fundamental incompatibility or unreasonable effort | INFEASIBLE |
---
### Verdict Routing (all modes except feasibility)
| Verdict | Criteria |
|---------|----------|
| BLOCK | >= 2 high-severity concerns |
| CONCERN | >= 1 high-severity OR >= 3 medium-severity concerns |
| APPROVE | All other cases |
## Phase 4: Validation
### Output Format
Write assessment to `<session_folder>/architecture/arch-<slug>.json`.
**Report content sent to coordinator**:
| Field | Description |
|-------|-------------|
| mode | Consultation mode used |
| verdict | APPROVE / CONCERN / BLOCK (or FEASIBLE / RISKY / INFEASIBLE) |
| concern_count | Number of concerns by severity |
| recommendations | Actionable suggestions with trade-offs |
| output_path | Path to full assessment file |
**Wisdom contribution**: Append significant decisions to `<session_folder>/wisdom/decisions.md`.
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Architecture docs not found | Assess from available context, note limitation in report |
| Plan file missing | Report to coordinator via arch_concern |
| Git diff fails (no commits) | Use staged changes or skip code-review mode |
| CLI exploration timeout | Provide partial assessment, flag as incomplete |
| Exploration results unparseable | Fall back to direct analysis without exploration |
| Insufficient context | Request explorer assistance via coordinator |

103
.claude/skills/team-lifecycle-v4/roles/architect/role.md Normal file
View File

@@ -0,0 +1,103 @@
# Role: architect
Architecture consultant. Advice on decisions, feasibility, design patterns.
## Identity
- **Name**: `architect` | **Prefix**: `ARCH-*` | **Tag**: `[architect]`
- **Type**: Consulting (on-demand, advisory only)
- **Responsibility**: Context loading → Mode detection → Analysis → Report
## Boundaries
### MUST
- Only process ARCH-* tasks
- Auto-detect mode from task subject prefix
- Provide options with trade-offs (not final decisions)
### MUST NOT
- Modify source code
- Make final decisions (advisory only)
- Execute implementation or testing
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| arch_ready | → coordinator | Assessment complete |
| arch_concern | → coordinator | Significant risk found |
| error | → coordinator | Analysis failure |
## Toolbox
| Tool | Purpose |
|------|---------|
| commands/assess.md | Multi-mode assessment |
| cli-explore-agent | Deep architecture exploration |
| ccw cli --tool gemini --mode analysis | Architecture analysis |
---
## Consultation Modes
| Task Pattern | Mode | Focus |
|-------------|------|-------|
| ARCH-SPEC-* | spec-review | Review architecture docs |
| ARCH-PLAN-* | plan-review | Review plan soundness |
| ARCH-CODE-* | code-review | Assess code change impact |
| ARCH-CONSULT-* | consult | Answer architecture questions |
| ARCH-FEASIBILITY-* | feasibility | Technical feasibility |
---
## Phase 2: Context Loading
**Common**: session folder, wisdom, project-tech.json, explorations
**Mode-specific**:
| Mode | Additional Context |
|------|-------------------|
| spec-review | architecture/_index.md, ADR-*.md |
| plan-review | plan/plan.json |
| code-review | git diff, changed files |
| consult | Question from task description |
| feasibility | Requirements + codebase |
---
## Phase 3: Assessment
Delegate to `commands/assess.md`. Output: mode, verdict (APPROVE/CONCERN/BLOCK), dimensions[], concerns[], recommendations[].
For complex questions → Gemini CLI with architecture review rule.
---
## Phase 4: Report
Output to `<session-folder>/architecture/arch-<slug>.json`. Contribute decisions to wisdom/decisions.md.
**Frontend project outputs** (when frontend tech stack detected in shared-memory or discovery-context):
- `<session-folder>/architecture/design-tokens.json` — color, spacing, typography, shadow tokens
- `<session-folder>/architecture/component-specs/*.md` — per-component design spec
**Report**: mode, verdict, concern count, recommendations, output path(s).
---
## Coordinator Integration
| Timing | Task |
|--------|------|
| After DRAFT-003 | ARCH-SPEC-001: 架构文档评审 |
| After PLAN-001 | ARCH-PLAN-001: 计划架构审查 |
| On-demand | ARCH-CONSULT-001: 架构咨询 |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Docs not found | Assess from available context |
| CLI timeout | Partial assessment |
| Insufficient context | Request explorer via coordinator |

139
.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md Normal file
View File

@@ -0,0 +1,139 @@
# Command: dispatch
## Purpose
Create task chains based on execution mode. v4 optimized: spec pipeline reduced from 12 to 6 tasks by inlining discuss rounds into produce roles.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Mode | Phase 1 requirements (spec-only, impl-only, etc.) | Yes |
| Session folder | `<session-folder>` from Phase 2 | Yes |
| Scope | User requirements description | Yes |
| Spec file | User-provided path (impl-only mode only) | Conditional |
## Phase 3: Task Chain Creation
### Mode-to-Pipeline Routing
| Mode | Tasks | Pipeline | First Task |
|------|-------|----------|------------|
| spec-only | 6 | Spec pipeline | RESEARCH-001 |
| impl-only | 4 | Impl pipeline | PLAN-001 |
| fe-only | 3 | FE pipeline | PLAN-001 |
| fullstack | 6 | Fullstack pipeline | PLAN-001 |
| full-lifecycle | 10 | Spec + Impl | RESEARCH-001 |
| full-lifecycle-fe | 12 | Spec + Fullstack | RESEARCH-001 |
---
### Spec Pipeline (6 tasks, was 12 in v3)
Used by: spec-only, full-lifecycle, full-lifecycle-fe
| # | Subject | Owner | BlockedBy | Description | Inline Discuss |
|---|---------|-------|-----------|-------------|---------------|
| 1 | RESEARCH-001 | analyst | (none) | Seed analysis and context gathering | DISCUSS-001 |
| 2 | DRAFT-001 | writer | RESEARCH-001 | Generate Product Brief | DISCUSS-002 |
| 3 | DRAFT-002 | writer | DRAFT-001 | Generate Requirements/PRD | DISCUSS-003 |
| 4 | DRAFT-003 | writer | DRAFT-002 | Generate Architecture Document | DISCUSS-004 |
| 5 | DRAFT-004 | writer | DRAFT-003 | Generate Epics & Stories | DISCUSS-005 |
| 6 | QUALITY-001 | reviewer | DRAFT-004 | 5-dimension spec quality + sign-off | DISCUSS-006 |
**Key change from v3**: No separate DISCUSS-* tasks. Each produce role calls the discuss subagent inline after completing its primary output.
### Impl Pipeline (4 tasks)
Used by: impl-only, full-lifecycle (PLAN-001 blockedBy QUALITY-001)
| # | Subject | Owner | BlockedBy | Description |
|---|---------|-------|-----------|-------------|
| 1 | PLAN-001 | planner | (none) | Multi-angle exploration and planning |
| 2 | IMPL-001 | executor | PLAN-001 | Code implementation |
| 3 | TEST-001 | tester | IMPL-001 | Test-fix cycles |
| 4 | REVIEW-001 | reviewer | IMPL-001 | 4-dimension code review |
### FE Pipeline (3 tasks)
Used by: fe-only
| # | Subject | Owner | BlockedBy | Description |
|---|---------|-------|-----------|-------------|
| 1 | PLAN-001 | planner | (none) | Planning (frontend focus) |
| 2 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation |
| 3 | QA-FE-001 | fe-qa | DEV-FE-001 | 5-dimension frontend QA |
GC loop (max 2 rounds): QA-FE verdict=NEEDS_FIX -> create DEV-FE-002 + QA-FE-002 dynamically.
### Fullstack Pipeline (6 tasks)
Used by: fullstack, full-lifecycle-fe (PLAN-001 blockedBy QUALITY-001)
| # | Subject | Owner | BlockedBy | Description |
|---|---------|-------|-----------|-------------|
| 1 | PLAN-001 | planner | (none) | Fullstack planning |
| 2 | IMPL-001 | executor | PLAN-001 | Backend implementation |
| 3 | DEV-FE-001 | fe-developer | PLAN-001 | Frontend implementation |
| 4 | TEST-001 | tester | IMPL-001 | Backend test-fix cycles |
| 5 | QA-FE-001 | fe-qa | DEV-FE-001 | Frontend QA |
| 6 | REVIEW-001 | reviewer | TEST-001, QA-FE-001 | Full code review |
### Composite Modes
| Mode | Construction | PLAN-001 BlockedBy |
|------|-------------|-------------------|
| full-lifecycle | Spec (6) + Impl (4) | QUALITY-001 |
| full-lifecycle-fe | Spec (6) + Fullstack (6) | QUALITY-001 |
---
### Impl-Only Pre-check
Before creating impl-only tasks, verify specification exists:
```
Spec exists?
+- YES -> read spec path -> proceed with task creation
+- NO -> error: "impl-only requires existing spec, use spec-only or full-lifecycle"
```
### Task Description Template
Every task description includes session, scope, and inline discuss metadata:
```
TaskCreate({
subject: "<TASK-ID>",
owner: "<role>",
description: "<task description from pipeline table>\nSession: <session-folder>\nScope: <scope>\nInlineDiscuss: <DISCUSS-NNN or none>",
blockedBy: [<dependency-list>],
status: "pending"
})
```
### Execution Method
| Method | Behavior |
|--------|----------|
| sequential | One task active at a time; next activated after predecessor completes |
| parallel | Tasks with all deps met run concurrently (e.g., TEST-001 + REVIEW-001) |
## Phase 4: Validation
| Check | Criteria |
|-------|----------|
| Task count | Matches mode total from routing table |
| Dependencies | Every blockedBy references an existing task subject |
| Owner assignment | Each task owner matches SKILL.md Role Registry prefix |
| Session reference | Every task description contains `Session: <session-folder>` |
| Inline discuss | Spec tasks have InlineDiscuss field matching round config |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown mode | Reject with supported mode list |
| Missing spec for impl-only | Error, suggest spec-only or full-lifecycle |
| TaskCreate fails | Log error, report to user |
| Duplicate task subject | Skip creation, log warning |

191
.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md Normal file
View File

@@ -0,0 +1,191 @@
# Command: monitor
## Purpose
Event-driven pipeline coordination with Spawn-and-Stop pattern. v4 enhanced with worker fast-advance awareness. Three wake-up sources: worker callbacks (auto-advance), user `check` (status report), user `resume` (manual advance).
## Constants
| Constant | Value | Description |
|----------|-------|-------------|
| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` |
| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS |
| FAST_ADVANCE_AWARE | true | Workers may skip coordinator for simple linear successors |
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Session file | `<session-folder>/team-session.json` | Yes |
| Task list | `TaskList()` | Yes |
| Active workers | session.active_workers[] | Yes |
| Pipeline mode | session.mode | Yes |
## Phase 3: Handler Routing
### Wake-up Source Detection
Parse `$ARGUMENTS` to determine handler:
| Priority | Condition | Handler |
|----------|-----------|---------|
| 1 | Message contains `[<role-name>]` from known worker role | handleCallback |
| 2 | Contains "check" or "status" | handleCheck |
| 3 | Contains "resume", "continue", or "next" | handleResume |
| 4 | None of the above (initial spawn after dispatch) | handleSpawnNext |
Known worker roles: analyst, writer, planner, executor, tester, reviewer, architect, fe-developer, fe-qa.
> **Note**: `discussant` and `explorer` are no longer worker roles in v4. They are subagents called inline by produce roles.
---
### Handler: handleCallback
Worker completed a task. Verify completion, update state, auto-advance.
```
Receive callback from [<role>]
+- Find matching active worker by role
+- Task status = completed?
| +- YES -> remove from active_workers -> update session
| | +- Handle checkpoints (see below)
| | +- -> handleSpawnNext
| +- NO -> progress message, do not advance -> STOP
+- No matching worker found
+- Scan all active workers for completed tasks
+- Found completed -> process each -> handleSpawnNext
+- None completed -> STOP
```
**Fast-advance note**: A worker may have already spawned its successor via fast-advance. When processing a callback:
1. Check if the expected next task is already `in_progress` (fast-advanced)
2. If yes -> skip spawning that task, update active_workers to include the fast-advanced worker
3. If no -> normal handleSpawnNext
---
### Handler: handleCheck
Read-only status report. No pipeline advancement.
**Output format**:
```
[coordinator] Pipeline Status (v4)
[coordinator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)
[coordinator] Execution Graph:
Spec Phase: (if applicable)
[<icon> RESEARCH-001(+D1)] -> [<icon> DRAFT-001(+D2)] -> [<icon> DRAFT-002(+D3)]
-> [<icon> DRAFT-003(+D4)] -> [<icon> DRAFT-004(+D5)] -> [<icon> QUALITY-001(+D6)]
Impl Phase: (if applicable)
[<icon> PLAN-001]
+- BE: [<icon> IMPL-001] -> [<icon> TEST-001] -> [<icon> REVIEW-001]
+- FE: [<icon> DEV-FE-001] -> [<icon> QA-FE-001]
done=completed >>>=running o=pending .=not created
[coordinator] Active Workers:
> <subject> (<role>) - running <elapsed>
[coordinator] Ready to spawn: <subjects>
[coordinator] Commands: 'resume' to advance | 'check' to refresh
```
**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=.
Then STOP.
---
### Handler: handleResume
Check active worker completion, process results, advance pipeline.
```
Load active_workers from session
+- No active workers -> handleSpawnNext
+- Has active workers -> check each:
+- status = completed -> mark done, log
+- status = in_progress -> still running, log
+- other status -> worker failure -> reset to pending
After processing:
+- Some completed -> handleSpawnNext
+- All still running -> report status -> STOP
+- All failed -> handleSpawnNext (retry)
```
---
### Handler: handleSpawnNext
Find all ready tasks, spawn workers in background, update session, STOP.
```
Collect task states from TaskList()
+- completedSubjects: status = completed
+- inProgressSubjects: status = in_progress
+- readySubjects: pending + all blockedBy in completedSubjects
Ready tasks found?
+- NONE + work in progress -> report waiting -> STOP
+- NONE + nothing in progress -> PIPELINE_COMPLETE -> Phase 5
+- HAS ready tasks -> for each:
+- TaskUpdate -> in_progress
+- team_msg log -> task_unblocked
+- Spawn worker (see tool call below)
+- Add to session.active_workers
Update session file -> output summary -> STOP
```
**Spawn worker tool call** (one per ready task):
```bash
Task({
subagent_type: "general-purpose",
description: "Spawn <role> worker for <subject>",
team_name: <team-name>,
name: "<role>",
run_in_background: true,
prompt: "<worker prompt from SKILL.md Coordinator Spawn Template>"
})
```
---
### Checkpoints
| Completed Task | Mode Condition | Action |
|---------------|----------------|--------|
| QUALITY-001 | full-lifecycle or full-lifecycle-fe | Output "SPEC PHASE COMPLETE" checkpoint, pause for user review before impl |
---
### Worker Failure Handling
When a worker has unexpected status (not completed, not in_progress):
1. Reset task -> pending via TaskUpdate
2. Log via team_msg (type: error)
3. Report to user: task reset, will retry on next resume
## Phase 4: Validation
| Check | Criteria |
|-------|----------|
| Session state consistent | active_workers matches TaskList in_progress tasks |
| No orphaned tasks | Every in_progress task has an active_worker entry |
| Pipeline completeness | All expected tasks exist per mode |
| Completion detection | readySubjects=0 + inProgressSubjects=0 -> PIPELINE_COMPLETE |
| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Session file not found | Error, suggest re-initialization |
| Worker callback from unknown role | Log info, scan for other completions |
| All workers still running on resume | Report status, suggest check later |
| Pipeline stall (no ready, no running) | Check for missing tasks, report to user |
| Fast-advance conflict | Coordinator reconciles, no duplicate spawns |

176
.claude/skills/team-lifecycle-v4/roles/coordinator/role.md Normal file
View File

@@ -0,0 +1,176 @@
# Coordinator Role
Orchestrate the team-lifecycle workflow: team creation, task dispatching, progress monitoring, session state. Optimized for v4 reduced pipeline with inline discuss and shared explore.
## Identity
- **Name**: `coordinator` | **Tag**: `[coordinator]`
- **Responsibility**: Parse requirements -> Create team -> Dispatch tasks -> Monitor progress -> Report results
## Boundaries
### MUST
- Parse user requirements and clarify ambiguous inputs via AskUserQuestion
- Create team and spawn worker subagents in background
- Dispatch tasks with proper dependency chains (see SKILL.md Task Metadata Registry)
- Monitor progress via worker callbacks and route messages
- Maintain session state persistence (team-session.json)
### MUST NOT
- Execute spec/impl/research work directly (delegate to workers)
- Modify task outputs (workers own their deliverables)
- Call implementation subagents (code-developer, etc.) directly
- Skip dependency validation when creating task chains
---
## Entry Router
When coordinator is invoked, first detect the invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains `[role-name]` tag from a known worker role | -> handleCallback: auto-advance pipeline |
| Status check | Arguments contain "check" or "status" | -> handleCheck: output execution graph, no advancement |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume: check worker states, advance pipeline |
| New session | None of the above | -> Phase 0 (Session Resume Check) |
For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP.
---
## Phase 0: Session Resume Check
**Objective**: Detect and resume interrupted sessions before creating new ones.
**Workflow**:
1. Scan `.workflow/.team/TLS-*/team-session.json` for sessions with status "active" or "paused"
2. No sessions found -> proceed to Phase 1
3. Single session found -> resume it (-> Session Reconciliation)
4. Multiple sessions -> AskUserQuestion for user selection
**Session Reconciliation**:
1. Audit TaskList -> get real status of all tasks
2. Reconcile: session.completed_tasks <-> TaskList status (bidirectional sync)
3. Reset any in_progress tasks -> pending (they were interrupted)
4. Determine remaining pipeline from reconciled state
5. Rebuild team if disbanded (TeamCreate + spawn needed workers only)
6. Create missing tasks with correct blockedBy dependencies
7. Verify dependency chain integrity
8. Update session file with reconciled state
9. Kick first executable task's worker -> Phase 4
---
## Phase 1: Requirement Clarification
**Objective**: Parse user input and gather execution parameters.
**Workflow**:
1. **Parse arguments** for explicit settings: mode, scope, focus areas, depth
2. **Ask for missing parameters** via AskUserQuestion:
- Mode: spec-only / impl-only / full-lifecycle / fe-only / fullstack / full-lifecycle-fe
- Scope: project description
- Execution method: sequential / parallel
3. **Frontend auto-detection** (for impl-only and full-lifecycle modes):
| Signal | Detection | Pipeline Upgrade |
|--------|----------|-----------------|
| FE keywords (component, page, UI, React, Vue, CSS...) | Keyword match in description | impl-only -> fe-only or fullstack |
| BE keywords also present (API, database, server...) | Both FE + BE keywords | impl-only -> fullstack |
| FE framework in package.json | grep react/vue/svelte/next | full-lifecycle -> full-lifecycle-fe |
4. **Store requirements**: mode, scope, focus, depth, executionMethod
**Success**: All parameters captured, mode finalized.
---
## Phase 2: Create Team + Initialize Session
**Objective**: Initialize team, session file, and wisdom directory.
**Workflow**:
1. Generate session ID: `TLS-<slug>-<date>`
2. Create session folder: `.workflow/.team/<session-id>/`
3. Call TeamCreate with team name
4. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
5. Initialize explorations directory with empty cache-index.json
6. Write team-session.json with: session_id, mode, scope, status="active", tasks_total, tasks_completed=0
**Task counts by mode (v4)**:
| Mode | Tasks | v3 Tasks | Savings |
|------|-------|----------|---------|
| spec-only | 6 | 12 | -6 (discuss inlined) |
| impl-only | 4 | 4 | 0 |
| fe-only | 3 | 3 | 0 |
| fullstack | 6 | 6 | 0 |
| full-lifecycle | 10 | 16 | -6 (discuss inlined) |
| full-lifecycle-fe | 12 | 18 | -6 (discuss inlined) |
**Success**: Team created, session file written, wisdom and explorations initialized.
---
## Phase 3: Create Task Chain
**Objective**: Dispatch tasks based on mode with proper dependencies.
Delegate to `commands/dispatch.md` which creates the full task chain:
1. Reads SKILL.md Task Metadata Registry for task definitions
2. Creates tasks via TaskCreate with correct blockedBy
3. Assigns owner based on role mapping
4. Includes `Session: <session-folder>` in every task description
5. Marks inline discuss round in task description (e.g., `InlineDiscuss: DISCUSS-002`)
---
## Phase 4: Spawn-and-Stop
**Objective**: Spawn first batch of ready workers in background, then STOP.
**Design**: Spawn-and-Stop + Callback pattern, with worker fast-advance.
- Spawn workers with `Task(run_in_background: true)` -> immediately return
- Worker completes -> may fast-advance to next task OR SendMessage callback -> auto-advance
- User can use "check" / "resume" to manually advance
- Coordinator does one operation per invocation, then STOPS
**Workflow**:
1. Load `commands/monitor.md`
2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
3. For each ready task -> spawn worker (see SKILL.md Spawn Template)
4. Output status summary
5. STOP
**Pipeline advancement** driven by three wake sources:
- Worker callback (automatic) -> Entry Router -> handleCallback
- User "check" -> handleCheck (status only)
- User "resume" -> handleResume (advance)
---
## Phase 5: Report + Next Steps
**Objective**: Completion report and follow-up options.
**Workflow**:
1. Load session state -> count completed tasks, duration
2. List deliverables with output paths
3. Update session status -> "completed"
4. Offer next steps: exit / view artifacts / extend tasks / generate lite-plan / create Issue
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Task timeout | Log, mark failed, ask user to retry or skip |
| Worker crash | Respawn worker, reassign task |
| Dependency cycle | Detect, report to user, halt |
| Invalid mode | Reject with error, ask to clarify |
| Session corruption | Attempt recovery, fallback to manual reconciliation |

166
.claude/skills/team-lifecycle-v4/roles/executor/commands/implement.md Normal file
View File

@@ -0,0 +1,166 @@
# Command: implement
## Purpose
Multi-backend code implementation: route tasks to appropriate execution backend (direct edit, subagent, or CLI), build focused prompts, execute with retry and fallback.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Plan | `<session-folder>/plan/plan.json` | Yes |
| Task files | `<session-folder>/plan/.task/TASK-*.json` | Yes |
| Backend | Task metadata / plan default / auto-select | Yes |
| Working directory | task.metadata.working_dir or project root | No |
| Wisdom | `<session-folder>/wisdom/` | No |
## Phase 3: Implementation
### Backend Selection
Priority order (first match wins):
| Priority | Source | Method |
|----------|--------|--------|
| 1 | Task metadata | `task.metadata.executor` field |
| 2 | Plan default | "Execution Backend:" line in plan.json |
| 3 | Auto-select | See auto-select table below |
**Auto-select routing**:
| Condition | Backend |
|-----------|---------|
| Description < 200 chars AND no refactor/architecture keywords AND single target file | agent (direct edit) |
| Description < 200 chars AND simple scope | agent (subagent) |
| Complex scope OR architecture keywords | codex |
| Analysis-heavy OR multi-module integration | gemini |
### Execution Paths
```
Backend selected
├─ agent (direct edit)
│ └─ Read target file → Edit directly → no subagent overhead
├─ agent (subagent)
│ └─ Task({ subagent_type: "code-developer", run_in_background: false })
├─ codex (CLI)
│ └─ Bash(command="ccw cli ... --tool codex --mode write", run_in_background=true)
└─ gemini (CLI)
└─ Bash(command="ccw cli ... --tool gemini --mode write", run_in_background=true)
```
### Path 1: Direct Edit (agent, simple task)
```bash
Read(file_path="<target-file>")
Edit(file_path="<target-file>", old_string="<old>", new_string="<new>")
```
### Path 2: Subagent (agent, moderate task)
```
Task({
subagent_type: "code-developer",
run_in_background: false,
description: "Implement <task-id>",
prompt: "<execution-prompt>"
})
```
### Path 3: CLI Backend (codex or gemini)
```bash
Bash(command="ccw cli -p '<execution-prompt>' --tool <codex|gemini> --mode write --cd <working-dir>", run_in_background=true)
```
### Execution Prompt Template
All backends receive the same structured prompt:
```
# Implementation Task: <task-id>
## Task Description
<task-description>
## Acceptance Criteria
1. <criterion>
## Context from Plan
<architecture-section>
<technical-stack-section>
<task-context-section>
## Files to Modify
<target-files or "Auto-detect based on task">
## Constraints
- Follow existing code style and patterns
- Preserve backward compatibility
- Add appropriate error handling
- Include inline comments for complex logic
```
### Batch Execution
When multiple IMPL tasks exist, execute in dependency order:
```
Topological sort by task.depends_on
├─ Batch 1: Tasks with no dependencies → execute
├─ Batch 2: Tasks depending on batch 1 → execute
└─ Batch N: Continue until all tasks complete
Progress update per batch (when > 1 batch):
→ team_msg: "Processing batch <N>/<total>: <task-id>"
```
### Retry and Fallback
**Retry** (max 3 attempts per task):
```
Attempt 1 → failure
├─ team_msg: "Retry 1/3 after error: <message>"
└─ Attempt 2 → failure
├─ team_msg: "Retry 2/3 after error: <message>"
└─ Attempt 3 → failure → fallback
```
**Fallback** (when primary backend fails after retries):
| Primary Backend | Fallback |
|----------------|----------|
| codex | agent (subagent) |
| gemini | agent (subagent) |
| agent (subagent) | Report failure to coordinator |
| agent (direct edit) | agent (subagent) |
## Phase 4: Validation
### Self-Validation Steps
| Step | Method | Pass Criteria |
|------|--------|--------------|
| Syntax check | `Bash(command="tsc --noEmit", timeout=30000)` | Exit code 0 |
| Acceptance match | Check criteria keywords vs modified files | All criteria addressed |
| Test detection | Search for .test.ts/.spec.ts matching modified files | Tests identified |
| File changes | `Bash(command="git diff --name-only HEAD")` | At least 1 file modified |
### Result Routing
| Outcome | Message Type | Content |
|---------|-------------|---------|
| All tasks pass validation | impl_complete | Task ID, files modified, backend used |
| Batch progress | impl_progress | Batch index, total batches, current task |
| Validation failure after retries | error | Task ID, error details, retry count |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Syntax errors after implementation | Retry with error context (max 3) |
| Backend unavailable | Fallback to agent |
| Missing dependencies | Request from coordinator |
| All retries + fallback exhausted | Report failure with full error log |

103
.claude/skills/team-lifecycle-v4/roles/executor/role.md Normal file
View File

@@ -0,0 +1,103 @@
# Role: executor
Code implementation following approved plans. Multi-backend execution with self-validation.
## Identity
- **Name**: `executor` | **Prefix**: `IMPL-*` | **Tag**: `[executor]`
- **Responsibility**: Load plan → Route to backend → Implement → Self-validate → Report
## Boundaries
### MUST
- Only process IMPL-* tasks
- Follow approved plan exactly
- Use declared execution backends
- Self-validate all implementations
### MUST NOT
- Create tasks
- Contact other workers directly
- Modify plan files
- Skip self-validation
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| impl_complete | → coordinator | Implementation success |
| impl_progress | → coordinator | Batch progress |
| error | → coordinator | Implementation failure |
## Toolbox
| Tool | Purpose |
|------|---------|
| commands/implement.md | Multi-backend implementation |
| code-developer agent | Simple tasks (synchronous) |
| ccw cli --tool codex --mode write | Complex tasks |
| ccw cli --tool gemini --mode write | Alternative backend |
---
## Phase 2: Task & Plan Loading
**Objective**: Load plan and determine execution strategy.
1. Load plan.json and .task/TASK-*.json from `<session-folder>/plan/`
**Backend selection** (priority order):
| Priority | Source | Method |
|----------|--------|--------|
| 1 | Task metadata | task.metadata.executor field |
| 2 | Plan default | "Execution Backend:" in plan |
| 3 | Auto-select | Simple (< 200 chars, no refactor) → agent; Complex → codex |
**Code review selection**:
| Priority | Source | Method |
|----------|--------|--------|
| 1 | Task metadata | task.metadata.code_review field |
| 2 | Plan default | "Code Review:" in plan |
| 3 | Auto-select | Critical keywords (auth, security, payment) → enabled |
---
## Phase 3: Code Implementation
**Objective**: Execute implementation across batches.
**Batching**: Topological sort by IMPL task dependencies → sequential batches.
Delegate to `commands/implement.md` for prompt building and backend routing:
| Backend | Invocation | Use Case |
|---------|-----------|----------|
| agent | Task({ subagent_type: "code-developer", run_in_background: false }) | Simple, direct edits |
| codex | ccw cli --tool codex --mode write (background) | Complex, architecture |
| gemini | ccw cli --tool gemini --mode write (background) | Analysis-heavy |
---
## Phase 4: Self-Validation
| Step | Method | Pass Criteria |
|------|--------|--------------|
| Syntax check | `tsc --noEmit` (30s) | Exit code 0 |
| Acceptance criteria | Match criteria keywords vs implementation | All addressed |
| Test detection | Find .test.ts/.spec.ts for modified files | Tests identified |
| Code review (optional) | gemini analysis or codex review | No blocking issues |
**Report**: task ID, status, files modified, validation results, backend used.
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Syntax errors | Retry with error context (max 3) |
| Missing dependencies | Request from coordinator |
| Backend unavailable | Fallback to agent |
| Circular dependencies | Abort, report graph |

111
.claude/skills/team-lifecycle-v4/roles/fe-developer/role.md Normal file
View File

@@ -0,0 +1,111 @@
# Role: fe-developer
Frontend development. Consumes plan/architecture output, implements components, pages, styles.
## Identity
- **Name**: `fe-developer` | **Prefix**: `DEV-FE-*` | **Tag**: `[fe-developer]`
- **Type**: Frontend pipeline worker
- **Responsibility**: Context loading → Design token consumption → Component implementation → Report
## Boundaries
### MUST
- Only process DEV-FE-* tasks
- Follow existing design tokens and component specs (if available)
- Generate accessible frontend code (semantic HTML, ARIA, keyboard nav)
- Follow project's frontend tech stack
### MUST NOT
- Modify backend code or API interfaces
- Contact other workers directly
- Introduce new frontend dependencies without architecture review
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| dev_fe_complete | → coordinator | Implementation done |
| dev_fe_progress | → coordinator | Long task progress |
| error | → coordinator | Implementation failure |
## Toolbox
| Tool | Purpose |
|------|---------|
| code-developer agent | Component implementation |
| ccw cli --tool gemini --mode write | Complex frontend generation |
---
## Phase 2: Context Loading
**Inputs to load**:
- Plan: `<session-folder>/plan/plan.json`
- Design tokens: `<session-folder>/architecture/design-tokens.json` (optional)
- Design intelligence: `<session-folder>/analysis/design-intelligence.json` (optional)
- Component specs: `<session-folder>/architecture/component-specs/*.md` (optional)
- Shared memory, wisdom
**Tech stack detection**:
| Signal | Framework | Styling |
|--------|-----------|---------|
| react/react-dom in deps | react | - |
| vue in deps | vue | - |
| next in deps | nextjs | - |
| tailwindcss in deps | - | tailwind |
| @shadcn/ui in deps | - | shadcn |
---
## Phase 3: Frontend Implementation
**Step 1**: Generate design token CSS (if tokens available)
- Convert design-tokens.json → CSS custom properties (`:root { --color-*, --space-*, --text-* }`)
- Include dark mode overrides via `@media (prefers-color-scheme: dark)`
- Write to `src/styles/tokens.css`
**Step 2**: Implement components
| Task Size | Strategy |
|-----------|----------|
| Simple (≤ 3 files, single component) | code-developer agent (synchronous) |
| Complex (system, multi-component) | ccw cli --tool gemini --mode write (background) |
**Coding standards** (include in agent/CLI prompt):
- Use design token CSS variables, never hardcode colors/spacing
- Interactive elements: cursor: pointer
- Transitions: 150-300ms
- Text contrast: minimum 4.5:1
- Include focus-visible styles
- Support prefers-reduced-motion
- Responsive: mobile-first
- No emoji as functional icons
---
## Phase 4: Self-Validation
| Check | What |
|-------|------|
| hardcoded-color | No #hex outside tokens.css |
| cursor-pointer | Interactive elements have cursor: pointer |
| focus-styles | Interactive elements have focus styles |
| responsive | Has responsive breakpoints |
| reduced-motion | Animations respect prefers-reduced-motion |
| emoji-icon | No emoji as functional icons |
Contribute to wisdom/conventions.md. Update shared-memory.json with component inventory.
**Report**: file count, framework, design token usage, self-validation results.
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Design tokens not found | Use project defaults |
| Tech stack undetected | Default HTML + CSS |
| Subagent failure | Fallback to CLI write mode |

152
.claude/skills/team-lifecycle-v4/roles/fe-qa/commands/pre-delivery-checklist.md Normal file
View File

@@ -0,0 +1,152 @@
# Command: pre-delivery-checklist
## Purpose
CSS-level pre-delivery checks for frontend files. Validates accessibility, interaction, design compliance, and layout patterns before final delivery.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Changed frontend files | git diff --name-only (filtered to .tsx, .jsx, .css, .scss) | Yes |
| File contents | Read each changed file | Yes |
| Design tokens path | `src/styles/tokens.css` or equivalent | No |
| Session folder | Task description `Session:` field | Yes |
## Phase 3: Checklist Execution
### Category 1: Accessibility (6 items)
| # | Check | Pattern to Detect | Severity |
|---|-------|--------------------|----------|
| 1 | Images have alt text | `<img` without `alt=` | CRITICAL |
| 2 | Form inputs have labels | `<input` without `<label` or `aria-label` | HIGH |
| 3 | Focus states visible | Interactive elements without `:focus` styles | HIGH |
| 4 | Color contrast 4.5:1 | Light text on light background patterns | HIGH |
| 5 | prefers-reduced-motion | Animations without `@media (prefers-reduced-motion)` | MEDIUM |
| 6 | Heading hierarchy | Skipped heading levels (h1 followed by h3) | MEDIUM |
**Do / Don't**:
| # | Do | Don't |
|---|-----|-------|
| 1 | Always provide descriptive alt text | Leave alt empty without `role="presentation"` |
| 2 | Associate every input with a label | Use placeholder as sole label |
| 3 | Add `focus-visible` outline | Remove default focus ring without replacement |
| 4 | Ensure 4.5:1 minimum contrast ratio | Use low-contrast decorative text for content |
| 5 | Wrap in `@media (prefers-reduced-motion: no-preference)` | Force animations on all users |
| 6 | Use sequential heading levels | Skip levels for visual sizing |
---
### Category 2: Interaction (4 items)
| # | Check | Pattern to Detect | Severity |
|---|-------|--------------------|----------|
| 7 | cursor-pointer on clickable | Buttons/links without `cursor: pointer` | MEDIUM |
| 8 | Transitions 150-300ms | Duration outside 150-300ms range | LOW |
| 9 | Loading states | Async operations without loading indicator | MEDIUM |
| 10 | Error states | Async operations without error handling UI | HIGH |
**Do / Don't**:
| # | Do | Don't |
|---|-----|-------|
| 7 | Add `cursor: pointer` to all clickable elements | Leave default cursor on buttons |
| 8 | Use 150-300ms for micro-interactions | Use >500ms or <100ms transitions |
| 9 | Show skeleton/spinner during fetch | Leave blank screen while loading |
| 10 | Show user-friendly error message | Silently fail or show raw error |
---
### Category 3: Design Compliance (4 items)
| # | Check | Pattern to Detect | Severity |
|---|-------|--------------------|----------|
| 11 | No hardcoded colors | Hex values (`#XXXXXX`) outside tokens file | HIGH |
| 12 | No hardcoded spacing | Raw `px` values for margin/padding | MEDIUM |
| 13 | No emoji as icons | Unicode emoji (U+1F300-1F9FF) in UI code | HIGH |
| 14 | Dark mode support | No `prefers-color-scheme` or `.dark` class | MEDIUM |
**Do / Don't**:
| # | Do | Don't |
|---|-----|-------|
| 11 | Use `var(--color-*)` design tokens | Hardcode `#hex` values |
| 12 | Use `var(--space-*)` spacing tokens | Hardcode pixel values |
| 13 | Use proper SVG/icon library | Use emoji for functional icons |
| 14 | Support light/dark themes | Design for light mode only |
---
### Category 4: Layout (2 items)
| # | Check | Pattern to Detect | Severity |
|---|-------|--------------------|----------|
| 15 | Responsive breakpoints | No `md:`/`lg:`/`@media` queries | MEDIUM |
| 16 | No horizontal scroll | Fixed widths greater than viewport | HIGH |
**Do / Don't**:
| # | Do | Don't |
|---|-----|-------|
| 15 | Mobile-first responsive design | Desktop-only layout |
| 16 | Use relative/fluid widths | Set fixed pixel widths on containers |
---
### Check Execution Strategy
| Check Scope | Applies To | Method |
|-------------|-----------|--------|
| Per-file checks | Items 1-4, 7-8, 10-13, 16 | Run against each changed file individually |
| Global checks | Items 5-6, 9, 14-15 | Run against concatenated content of all files |
**Detection example** (check for hardcoded colors):
```bash
Grep(pattern="#[0-9a-fA-F]{6}", path="<file_path>", output_mode="content", "-n"=true)
```
**Detection example** (check for missing alt text):
```bash
Grep(pattern="<img\\s(?![^>]*alt=)", path="<file_path>", output_mode="content", "-n"=true)
```
## Phase 4: Validation
### Pass/Fail Criteria
| Condition | Result |
|-----------|--------|
| Zero CRITICAL + zero HIGH failures | PASS |
| Zero CRITICAL, some HIGH | CONDITIONAL (list fixes needed) |
| Any CRITICAL failure | FAIL |
### Output Format
```
## Pre-Delivery Checklist Results
- Total checks: <n>
- Passed: <n> / <total>
- Failed: <n>
### Failed Items
- [CRITICAL] #1 Images have alt text -- <file_path>
- [HIGH] #11 No hardcoded colors -- <file_path>:<line>
- [MEDIUM] #7 cursor-pointer on clickable -- <file_path>
### Recommendations
(Do/Don't guidance for each failed item)
```
## Error Handling
| Scenario | Resolution |
|----------|------------|
| No frontend files to check | Report empty checklist, all checks N/A |
| File read error | Skip file, note in report |
| Regex match error | Skip check, note in report |
| Design tokens file not found | Skip items 11-12, adjust total |

113
.claude/skills/team-lifecycle-v4/roles/fe-qa/role.md Normal file
View File

@@ -0,0 +1,113 @@
# Role: fe-qa
Frontend quality assurance. 5-dimension review + Generator-Critic loop.
## Identity
- **Name**: `fe-qa` | **Prefix**: `QA-FE-*` | **Tag**: `[fe-qa]`
- **Type**: Frontend pipeline worker
- **Responsibility**: Context loading → 5-dimension review → GC feedback → Report
## Boundaries
### MUST
- Only process QA-FE-* tasks
- Execute 5-dimension review
- Support Generator-Critic loop (max 2 rounds)
- Provide actionable fix suggestions (Do/Don't format)
### MUST NOT
- Modify source code directly (review only)
- Contact other workers directly
- Mark pass when score below threshold
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| qa_fe_passed | → coordinator | All dimensions pass |
| qa_fe_result | → coordinator | Review complete (may have issues) |
| fix_required | → coordinator | Critical issues found |
## Toolbox
| Tool | Purpose |
|------|---------|
| commands/pre-delivery-checklist.md | CSS-level delivery checks |
| ccw cli --tool gemini --mode analysis | Frontend code review |
| ccw cli --tool codex --mode review | Git-aware code review |
---
## Review Dimensions
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Code Quality | 25% | TypeScript types, component structure, error handling |
| Accessibility | 25% | Semantic HTML, ARIA, keyboard nav, contrast, focus-visible |
| Design Compliance | 20% | Token usage, no hardcoded colors, no emoji icons |
| UX Best Practices | 15% | Loading/error/empty states, cursor-pointer, responsive |
| Pre-Delivery | 15% | No console.log, dark mode, i18n readiness |
---
## Phase 2: Context Loading
**Inputs**: design tokens, design intelligence, shared memory, previous QA results (for GC round tracking), changed frontend files via git diff.
Determine GC round from previous QA results count. Max 2 rounds.
---
## Phase 3: 5-Dimension Review
For each changed frontend file, check against all 5 dimensions. Score each dimension 0-10, deducting for issues found.
**Scoring deductions**:
| Severity | Deduction |
|----------|-----------|
| High | -2 to -3 |
| Medium | -1 to -1.5 |
| Low | -0.5 |
**Overall score** = weighted sum of dimension scores.
**Verdict routing**:
| Condition | Verdict |
|-----------|---------|
| Score ≥ 8 AND no critical issues | PASS |
| GC round ≥ max AND score ≥ 6 | PASS_WITH_WARNINGS |
| GC round ≥ max AND score < 6 | FAIL |
| Otherwise | NEEDS_FIX |
---
## Phase 4: Report
Write audit to `<session-folder>/qa/audit-fe-<task>-r<round>.json`. Update wisdom and shared memory.
**Report**: round, verdict, overall score, dimension scores, critical issues with Do/Don't format, action required (if NEEDS_FIX).
---
## Generator-Critic Loop
Orchestrated by coordinator:
```
Round 1: DEV-FE-001 → QA-FE-001
if NEEDS_FIX → coordinator creates DEV-FE-002 + QA-FE-002
Round 2: DEV-FE-002 → QA-FE-002
if still NEEDS_FIX → PASS_WITH_WARNINGS or FAIL (max 2)
```
**Convergence**: score ≥ 8 AND critical_count = 0
## Error Handling
| Scenario | Resolution |
|----------|------------|
| No changed files | Report empty, score N/A |
| Design tokens not found | Skip design compliance, adjust weights |
| Max GC rounds exceeded | Force verdict |

172
.claude/skills/team-lifecycle-v4/roles/planner/commands/explore.md Normal file
View File

@@ -0,0 +1,172 @@
# Command: explore
## Purpose
Complexity-driven codebase exploration using shared explore subagent with centralized cache. v4 optimized: checks cache before exploring, avoids duplicate work across roles.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Task description | PLAN-* task subject/description | Yes |
| Session folder | Task description `Session:` field | Yes |
| Spec context | `<session-folder>/spec/` (if exists) | No |
| Plan directory | `<session-folder>/plan/` | Yes (create if missing) |
| Project tech | `.workflow/project-tech.json` | No |
| Cache index | `<session-folder>/explorations/cache-index.json` | No (create if missing) |
## Phase 3: Exploration
### Complexity Assessment
Score the task description against keyword indicators:
| Indicator | Keywords | Score |
|-----------|----------|-------|
| Structural change | refactor, architect, restructure, modular | +2 |
| Multi-scope | multiple, across, cross-cutting | +2 |
| Integration | integrate, api, database | +1 |
| Non-functional | security, performance, auth | +1 |
**Complexity routing**:
| Score | Level | Strategy | Angle Count |
|-------|-------|----------|-------------|
| 0-1 | Low | ACE semantic search only | 1 |
| 2-3 | Medium | Explore subagent per angle | 2-3 |
| 4+ | High | Explore subagent per angle | 3-5 |
### Angle Presets
Select preset by dominant keyword match, then take first N angles per complexity:
| Preset | Trigger Keywords | Angles (priority order) |
|--------|-----------------|------------------------|
| architecture | refactor, architect, restructure, modular | architecture, dependencies, modularity, integration-points |
| security | security, auth, permission, access | security, auth-patterns, dataflow, validation |
| performance | performance, slow, optimize, cache | performance, bottlenecks, caching, data-access |
| bugfix | fix, bug, error, issue, broken | error-handling, dataflow, state-management, edge-cases |
| feature | (default) | patterns, integration-points, testing, dependencies |
### Cache-First Strategy (v4 new)
Before launching any exploration, check the shared cache:
```
1. Read <session-folder>/explorations/cache-index.json
2. For each selected angle:
a. If angle exists in cache -> SKIP (reuse cached result)
b. If angle not in cache -> explore via subagent
3. Only explore uncached angles
```
This avoids duplicating work done by analyst's `general` exploration or any prior role.
### Low Complexity: Direct Search
```bash
mcp__ace-tool__search_context(project_root_path="<project-root>", query="<task-description>")
```
Transform results into exploration JSON and write to `<session-folder>/explorations/explore-general.json`.
Update cache-index.json.
**ACE failure fallback**:
```bash
Bash(command="rg -l '<keywords>' --type ts", timeout=30000)
```
### Medium/High Complexity: Explore Subagent per Angle
For each uncached angle, call the shared explore subagent:
```
Task({
subagent_type: "Explore",
run_in_background: false,
description: "Explore: <angle>",
prompt: "Explore codebase for: <task-description>
Focus angle: <angle>
Keywords: <relevant-keywords>
Session folder: <session-folder>
## Cache Check
1. Read <session-folder>/explorations/cache-index.json (if exists)
2. Look for entry with matching angle
3. If found AND file exists -> read cached result, return summary
4. If not found -> proceed to exploration
## Exploration Focus
<angle-focus-from-table-below>
## Output
Write JSON to: <session-folder>/explorations/explore-<angle>.json
Update cache-index.json with new entry
Each file in relevant_files MUST have: rationale (>10 chars), role, discovery_source, key_symbols"
})
```
### Angle Focus Guide
| Angle | Focus Points |
|-------|-------------|
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs |
| dependencies | Import chains, external libraries, circular dependencies, shared utilities |
| modularity | Module interfaces, separation of concerns, extraction opportunities |
| integration-points | API endpoints, data flow between modules, event systems, service integrations |
| security | Auth/authz logic, input validation, sensitive data handling, middleware |
| auth-patterns | Auth flows (login/refresh), session management, token validation, permissions |
| dataflow | Data transformations, state propagation, validation points, mutation paths |
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity |
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging |
| patterns | Code conventions, design patterns, naming conventions, best practices |
| testing | Test files, coverage gaps, test patterns (unit/integration/e2e), mocking |
### Explorations Manifest
After all explorations complete (both cached and new), write manifest to `<session-folder>/plan/explorations-manifest.json`:
```json
{
"task_description": "<description>",
"complexity": "<Low|Medium|High>",
"exploration_count": "<N>",
"cached_count": "<M>",
"explorations": [
{ "angle": "<angle>", "file": "../explorations/explore-<angle>.json", "source": "cached|new" }
]
}
```
## Phase 4: Validation
### Output Files
```
<session-folder>/explorations/ (shared cache)
+- cache-index.json (updated)
+- explore-<angle>.json (per angle)
<session-folder>/plan/
+- explorations-manifest.json (summary referencing shared cache)
```
### Success Criteria
| Check | Criteria | Required |
|-------|----------|----------|
| At least 1 exploration | Non-empty exploration file exists | Yes |
| Manifest written | explorations-manifest.json exists | Yes |
| File roles assigned | Every relevant_file has role + rationale | Yes |
| Cache updated | cache-index.json reflects all explorations | Yes |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Single exploration agent fails | Skip angle, remove from manifest, continue |
| All explorations fail | Proceed to plan generation with task description only |
| ACE search fails (Low) | Fallback to ripgrep keyword search |
| Schema file not found | Use inline schema from Output section |
| Cache index corrupt | Reset cache-index.json to empty, re-explore all |

127
.claude/skills/team-lifecycle-v4/roles/planner/role.md Normal file
View File

@@ -0,0 +1,127 @@
# Role: planner
Multi-angle code exploration (via shared explore subagent with cache) and structured implementation planning.
## Identity
- **Name**: `planner` | **Prefix**: `PLAN-*` | **Tag**: `[planner]`
- **Responsibility**: Complexity assessment -> Code exploration (shared cache) -> Plan generation -> Approval
## Boundaries
### MUST
- Only process PLAN-* tasks
- Assess complexity before planning
- Use shared explore subagent for codebase exploration (cache-aware)
- Generate plan.json + .task/TASK-*.json
- Load spec context in full-lifecycle mode
- Submit plan for coordinator approval
### MUST NOT
- Create tasks for other roles
- Implement code
- Modify spec documents
- Skip complexity assessment
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| plan_ready | -> coordinator | Plan complete |
| plan_revision | -> coordinator | Plan revised per feedback |
| error | -> coordinator | Exploration or planning failure |
## Toolbox
| Tool | Purpose |
|------|---------|
| commands/explore.md | Complexity-driven exploration via shared explore subagent |
| Explore subagent | Per-angle exploration (shared cache) |
| cli-lite-planning-agent | Plan generation |
---
## Phase 1.5: Load Spec Context (Full-Lifecycle)
If `<session-folder>/spec/` exists -> load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise -> impl-only mode.
**Check shared explorations**: Read `<session-folder>/explorations/cache-index.json` to see if analyst already cached useful explorations. Reuse rather than re-explore.
---
## Phase 2: Multi-Angle Exploration
**Objective**: Explore codebase to inform planning.
**Complexity routing**:
| Complexity | Criteria | Strategy |
|------------|----------|----------|
| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only |
| Medium | 200-500 chars or moderate scope | 2-3 angle explore subagent |
| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle explore subagent |
Delegate to `commands/explore.md` for angle selection and execution.
**Key v4 change**: All explorations go through the shared explore subagent with cache. Before launching an exploration for an angle, check cache-index.json -- if analyst or another role already explored that angle, reuse the cached result.
---
## Phase 3: Plan Generation
**Objective**: Generate structured implementation plan.
| Complexity | Strategy |
|------------|----------|
| Low | Direct planning -> single TASK-001 with plan.json |
| Medium/High | cli-lite-planning-agent with exploration results |
**Agent call** (Medium/High):
```
Task({
subagent_type: "cli-lite-planning-agent",
run_in_background: false,
description: "Generate implementation plan",
prompt: "Generate plan.
Output: <plan-dir>/plan.json + <plan-dir>/.task/TASK-*.json
Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
Task: <task-description>
Explorations: <explorations-manifest>
Complexity: <complexity>
Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, depends_on"
})
```
**Spec context** (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition.
---
## Phase 4: Submit for Approval
1. Read plan.json and TASK-*.json
2. Report to coordinator: complexity, task count, task list, approach, plan location
3. Wait for response: approved -> complete; revision -> update and resubmit
**Session files**:
```
<session-folder>/plan/
+-- exploration-<angle>.json (per angle, from shared cache)
+-- explorations-manifest.json (summary)
+-- plan.json
+-- .task/TASK-*.json
```
Note: exploration files may be symlinked or referenced from `<session-folder>/explorations/` (shared cache location).
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Exploration agent failure | Plan from description only |
| Planning agent failure | Fallback to direct planning |
| Plan rejected 3+ times | Notify coordinator, suggest alternative |
| Schema not found | Use basic structure |
| Cache index corrupt | Clear cache, re-explore all angles |

163
.claude/skills/team-lifecycle-v4/roles/reviewer/commands/code-review.md Normal file
View File

@@ -0,0 +1,163 @@
# Command: code-review
## Purpose
4-dimension code review analyzing quality, security, architecture, and requirements compliance. Produces a verdict (BLOCK/CONDITIONAL/APPROVE) with categorized findings.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Plan file | `<session_folder>/plan/plan.json` | Yes |
| Git diff | `git diff HEAD~1` or `git diff --cached` | Yes |
| Modified files | From git diff --name-only | Yes |
| Test results | Tester output (if available) | No |
| Wisdom | `<session_folder>/wisdom/` | No |
## Phase 3: 4-Dimension Review
### Dimension Overview
| Dimension | Focus | Weight |
|-----------|-------|--------|
| Quality | Code correctness, type safety, clean code | Equal |
| Security | Vulnerability patterns, secret exposure | Equal |
| Architecture | Module structure, coupling, file size | Equal |
| Requirements | Acceptance criteria coverage, completeness | Equal |
---
### Dimension 1: Quality
Scan each modified file for quality anti-patterns.
| Severity | Pattern | What to Detect |
|----------|---------|----------------|
| Critical | Empty catch blocks | `catch(e) {}` with no handling |
| High | @ts-ignore without justification | Suppression comment < 10 chars explanation |
| High | `any` type in public APIs | `any` outside comments and generic definitions |
| High | console.log in production | `console.(log\|debug\|info)` outside test files |
| Medium | Magic numbers | Numeric literals > 1 digit, not in const/comment |
| Medium | Duplicate code | Identical lines (>30 chars) appearing 3+ times |
**Detection example** (Grep for console statements):
```bash
Grep(pattern="console\\.(log|debug|info)", path="<file_path>", output_mode="content", "-n"=true)
```
---
### Dimension 2: Security
Scan for vulnerability patterns across all modified files.
| Severity | Pattern | What to Detect |
|----------|---------|----------------|
| Critical | Hardcoded secrets | `api_key=`, `password=`, `secret=`, `token=` with string values (20+ chars) |
| Critical | SQL injection | String concatenation in `query()`/`execute()` calls |
| High | eval/exec usage | `eval()`, `new Function()`, `setTimeout(string)` |
| High | XSS vectors | `innerHTML`, `dangerouslySetInnerHTML` |
| Medium | Insecure random | `Math.random()` in security context (token/key/password/session) |
| Low | Missing input validation | Functions with parameters but no validation in first 5 lines |
---
### Dimension 3: Architecture
Assess structural health of modified files.
| Severity | Pattern | What to Detect |
|----------|---------|----------------|
| Critical | Circular dependencies | File A imports B, B imports A |
| High | Excessive parent imports | Import traverses >2 parent directories (`../../../`) |
| Medium | Large files | Files exceeding 500 lines |
| Medium | Tight coupling | >5 imports from same base module |
| Medium | Long functions | Functions exceeding 50 lines |
| Medium | Module boundary changes | Modifications to index.ts/index.js files |
**Detection example** (check for deep parent imports):
```bash
Grep(pattern="from\\s+['\"](\\.\\./){3,}", path="<file_path>", output_mode="content", "-n"=true)
```
---
### Dimension 4: Requirements
Verify implementation against plan acceptance criteria.
| Severity | Check | Method |
|----------|-------|--------|
| High | Unmet acceptance criteria | Extract criteria from plan, check keyword overlap (threshold: 70%) |
| High | Missing error handling | Plan mentions "error handling" but no try/catch in code |
| Medium | Partially met criteria | Keyword overlap 40-69% |
| Medium | Missing tests | Plan mentions "test" but no test files in modified set |
**Verification flow**:
1. Read plan file → extract acceptance criteria section
2. For each criterion → extract keywords (4+ char meaningful words)
3. Search modified files for keyword matches
4. Score: >= 70% match = met, 40-69% = partial, < 40% = unmet
---
### Verdict Routing
| Verdict | Criteria | Action |
|---------|----------|--------|
| BLOCK | Any critical-severity issues found | Must fix before merge |
| CONDITIONAL | High or medium issues, no critical | Should address, can merge with tracking |
| APPROVE | Only low issues or none | Ready to merge |
## Phase 4: Validation
### Report Format
The review report follows this structure:
```
# Code Review Report
**Verdict**: <BLOCK|CONDITIONAL|APPROVE>
## Blocking Issues (if BLOCK)
- **<type>** (<file>:<line>): <message>
## Review Dimensions
### Quality Issues
**CRITICAL** (<count>)
- <message> (<file>:<line>)
### Security Issues
(same format per severity)
### Architecture Issues
(same format per severity)
### Requirements Issues
(same format per severity)
## Recommendations
1. <actionable recommendation>
```
### Summary Counts
| Field | Description |
|-------|-------------|
| Total issues | Sum across all dimensions and severities |
| Critical count | Must be 0 for APPROVE |
| Blocking issues | Listed explicitly in report header |
| Dimensions covered | Must be 4/4 |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Plan file not found | Skip requirements dimension, note in report |
| Git diff empty | Report no changes to review |
| File read fails | Skip file, note in report |
| No modified files | Report empty review |

202
.claude/skills/team-lifecycle-v4/roles/reviewer/commands/spec-quality.md Normal file
View File

@@ -0,0 +1,202 @@
# Command: spec-quality
## Purpose
5-dimension spec quality check with weighted scoring, quality gate determination, and readiness report generation.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Spec documents | `<session_folder>/spec/` (all .md files) | Yes |
| Original requirements | Product brief objectives section | Yes |
| Quality gate config | specs/quality-gates.md | No |
| Session folder | Task description `Session:` field | Yes |
**Spec document phases** (matched by filename/directory):
| Phase | Expected Path | Required |
|-------|--------------|---------|
| product-brief | spec/product-brief.md | Yes |
| prd | spec/requirements/*.md | Yes |
| architecture | spec/architecture/_index.md + ADR-*.md | Yes |
| user-stories | spec/epics/*.md | Yes |
| implementation-plan | plan/plan.json | No (impl-only/full-lifecycle) |
| test-strategy | spec/test-strategy.md | No (optional, not generated by pipeline) |
## Phase 3: 5-Dimension Scoring
### Dimension Weights
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Completeness | 25% | All required sections present with substance |
| Consistency | 20% | Terminology, format, references, naming |
| Traceability | 25% | Goals -> Reqs -> Components -> Stories chain |
| Depth | 20% | AC testable, ADRs justified, stories estimable |
| Coverage | 10% | Original requirements mapped to spec |
---
### Dimension 1: Completeness (25%)
Check each spec document for required sections.
**Required sections by phase**:
| Phase | Required Sections |
|-------|------------------|
| product-brief | Vision Statement, Problem Statement, Target Audience, Success Metrics, Constraints |
| prd | Goals, Requirements, User Stories, Acceptance Criteria, Non-Functional Requirements |
| architecture | System Overview, Component Design, Data Models, API Specifications, Technology Stack |
| user-stories | Story List, Acceptance Criteria, Priority, Estimation |
| implementation-plan | Task Breakdown, Dependencies, Timeline, Resource Allocation |
> **Note**: `test-strategy` is optional — skip scoring if `spec/test-strategy.md` is absent. Do not penalize completeness score for missing optional phases.
**Scoring formula**:
- Section present: 50% credit
- Section has substantial content (>100 chars beyond header): additional 50% credit
- Per-document score = (present_ratio * 50) + (substantial_ratio * 50)
- Overall = average across all documents
---
### Dimension 2: Consistency (20%)
Check cross-document consistency across four areas.
| Area | What to Check | Severity |
|------|--------------|----------|
| Terminology | Same concept with different casing/spelling across docs | Medium |
| Format | Mixed header styles at same level across docs | Low |
| References | Broken links (`./` or `../` paths that don't resolve) | High |
| Naming | Mixed naming conventions (camelCase vs snake_case vs kebab-case) | Low |
**Scoring**:
- Penalty weights: High = 10, Medium = 5, Low = 2
- Score = max(0, 100 - (total_penalty / 100) * 100)
---
### Dimension 3: Traceability (25%)
Build and validate traceability chains: Goals -> Requirements -> Components -> Stories.
**Chain building flow**:
1. Extract goals from product-brief (pattern: `- Goal: <text>`)
2. Extract requirements from PRD (pattern: `- REQ-NNN: <text>`)
3. Extract components from architecture (pattern: `- Component: <text>`)
4. Extract stories from user-stories (pattern: `- US-NNN: <text>`)
5. Link by keyword overlap (threshold: 30% keyword match)
**Chain completeness**: A chain is complete when a goal links to at least one requirement, one component, and one story.
**Scoring**: (complete chains / total chains) * 100
**Weak link identification**: For each incomplete chain, report which link is missing (no requirements, no components, or no stories).
---
### Dimension 4: Depth (20%)
Assess the analytical depth of spec content across four sub-dimensions.
| Sub-dimension | Source | Testable Criteria |
|---------------|--------|-------------------|
| AC Testability | PRD / User Stories | Contains measurable verbs (display, return, validate) or Given/When/Then or numbers |
| ADR Justification | Architecture | Contains rationale, alternatives, consequences, or trade-offs |
| Story Estimability | User Stories | Has "As a/I want/So that" + AC, or explicit estimate |
| Technical Detail | Architecture + Plan | Contains code blocks, API terms, HTTP methods, DB terms |
**Scoring**: Average of sub-dimension scores (each 0-100%)
---
### Dimension 5: Coverage (10%)
Map original requirements to spec requirements.
**Flow**:
1. Extract original requirements from product-brief objectives section
2. Extract spec requirements from all documents (pattern: `- REQ-NNN:` or `- Requirement:` or `- Feature:`)
3. For each original requirement, check keyword overlap with any spec requirement (threshold: 40%)
4. Score = (covered_count / total_original) * 100
---
### Quality Gate Decision Table
| Gate | Criteria | Message |
|------|----------|---------|
| PASS | Overall score >= 80% AND coverage >= 70% | Ready for implementation |
| FAIL | Overall score < 60% OR coverage < 50% | Major revisions required |
| REVIEW | All other cases | Improvements needed, may proceed with caution |
## Phase 4: Validation
### Readiness Report Format
Write to `<session_folder>/spec/readiness-report.md`:
```
# Specification Readiness Report
**Generated**: <timestamp>
**Overall Score**: <score>%
**Quality Gate**: <PASS|REVIEW|FAIL> - <message>
**Recommended Action**: <action>
## Dimension Scores
| Dimension | Score | Weight | Weighted Score |
|-----------|-------|--------|----------------|
| Completeness | <n>% | 25% | <n>% |
| Consistency | <n>% | 20% | <n>% |
| Traceability | <n>% | 25% | <n>% |
| Depth | <n>% | 20% | <n>% |
| Coverage | <n>% | 10% | <n>% |
## Completeness Analysis
(per-phase breakdown: sections present/expected, missing sections)
## Consistency Analysis
(issues by area: terminology, format, references, naming)
## Traceability Analysis
(complete chains / total, weak links)
## Depth Analysis
(per sub-dimension scores)
## Requirement Coverage
(covered / total, uncovered requirements list)
```
### Spec Summary Format
Write to `<session_folder>/spec/spec-summary.md`:
```
# Specification Summary
**Overall Quality Score**: <score>%
**Quality Gate**: <gate>
## Documents Reviewed
(per document: phase, path, size, section list)
## Key Findings
### Strengths (dimensions scoring >= 80%)
### Areas for Improvement (dimensions scoring < 70%)
### Recommendations
```
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Spec folder empty | FAIL gate, report no documents found |
| Missing phase document | Score 0 for that phase in completeness, note in report |
| No original requirements found | Score coverage at 100% (nothing to cover) |
| Broken references | Flag in consistency, do not fail entire review |

133
.claude/skills/team-lifecycle-v4/roles/reviewer/role.md Normal file
View File

@@ -0,0 +1,133 @@
# Role: reviewer
Dual-mode review: code review (REVIEW-*) and spec quality validation (QUALITY-*). QUALITY tasks include inline discuss (DISCUSS-006) for final sign-off.
## Identity
- **Name**: `reviewer` | **Prefix**: `REVIEW-*` + `QUALITY-*` | **Tag**: `[reviewer]`
- **Responsibility**: Branch by Prefix -> Review/Score -> **Inline Discuss (QUALITY only)** -> Report
## Boundaries
### MUST
- Process REVIEW-* and QUALITY-* tasks
- Generate readiness-report.md for QUALITY tasks
- Cover all required dimensions per mode
- Call discuss subagent for DISCUSS-006 after QUALITY-001
### MUST NOT
- Create tasks
- Modify source code
- Skip quality dimensions
- Approve without verification
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| review_result | -> coordinator | Code review complete |
| quality_result | -> coordinator | Spec quality + discuss complete |
| fix_required | -> coordinator | Critical issues found |
## Toolbox
| Tool | Purpose |
|------|---------|
| commands/code-review.md | 4-dimension code review |
| commands/spec-quality.md | 5-dimension spec quality |
| discuss subagent | Inline DISCUSS-006 (QUALITY tasks only) |
---
## Mode Detection
| Task Prefix | Mode | Dimensions | Inline Discuss |
|-------------|------|-----------|---------------|
| REVIEW-* | Code Review | quality, security, architecture, requirements | None |
| QUALITY-* | Spec Quality | completeness, consistency, traceability, depth, coverage | DISCUSS-006 |
---
## Code Review (REVIEW-*)
**Inputs**: Plan file, git diff, modified files, test results (if available)
**4 dimensions** (delegate to commands/code-review.md):
| Dimension | Critical Issues |
|-----------|----------------|
| Quality | Empty catch, any in public APIs, @ts-ignore, console.log |
| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML |
| Architecture | Circular deps, parent imports >2 levels, files >500 lines |
| Requirements | Missing core functionality, incomplete acceptance criteria |
**Verdict**:
| Verdict | Criteria |
|---------|----------|
| BLOCK | Critical issues present |
| CONDITIONAL | High/medium only |
| APPROVE | Low or none |
---
## Spec Quality (QUALITY-*)
**Inputs**: All spec docs in session folder, quality gate config
**5 dimensions** (delegate to commands/spec-quality.md):
| Dimension | Weight | Focus |
|-----------|--------|-------|
| Completeness | 25% | All sections present with substance |
| Consistency | 20% | Terminology, format, references |
| Traceability | 25% | Goals -> Reqs -> Arch -> Stories chain |
| Depth | 20% | AC testable, ADRs justified, stories estimable |
| Coverage | 10% | Original requirements mapped |
**Quality gate**:
| Gate | Criteria |
|------|----------|
| PASS | Score >= 80% AND coverage >= 70% |
| REVIEW | Score 60-79% OR coverage 50-69% |
| FAIL | Score < 60% OR coverage < 50% |
**Artifacts**: readiness-report.md + spec-summary.md
### Inline Discuss (DISCUSS-006) -- QUALITY tasks only
After generating readiness-report.md, call discuss subagent for final sign-off:
```
Task({
subagent_type: "cli-discuss-agent",
run_in_background: false,
description: "Discuss DISCUSS-006",
prompt: `## Multi-Perspective Critique: DISCUSS-006
### Input
- Artifact: <session-folder>/spec/readiness-report.md
- Round: DISCUSS-006
- Perspectives: product, technical, quality, risk, coverage
- Session: <session-folder>
- Discovery Context: <session-folder>/spec/discovery-context.json
<rest of discuss subagent prompt from subagents/discuss-subagent.md>`
})
```
**Discuss result handling**:
- `consensus_reached` -> include in quality report as final endorsement
- `consensus_blocked` -> flag in SendMessage, report specific divergences
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Missing context | Request from coordinator |
| Invalid mode | Abort with error |
| Analysis failure | Retry, then fallback template |
| Discuss subagent fails | Proceed without final discuss, log warning |

152
.claude/skills/team-lifecycle-v4/roles/tester/commands/validate.md Normal file
View File

@@ -0,0 +1,152 @@
# Command: validate
## Purpose
Test-fix cycle with strategy engine: detect framework, run tests, classify failures, select fix strategy, iterate until pass rate target is met or max iterations exhausted.
## Constants
| Constant | Value | Description |
|----------|-------|-------------|
| MAX_ITERATIONS | 10 | Maximum test-fix cycle attempts |
| PASS_RATE_TARGET | 95% | Minimum pass rate to succeed |
| AFFECTED_TESTS_FIRST | true | Run affected tests before full suite |
## Phase 2: Context Loading
Load from task description and executor output:
| Input | Source | Required |
|-------|--------|----------|
| Framework | Auto-detected (see below) | Yes |
| Modified files | Executor task output / git diff | Yes |
| Affected tests | Derived from modified files | No |
| Session folder | Task description `Session:` field | Yes |
| Wisdom | `<session_folder>/wisdom/` | No |
**Framework detection** (priority order):
| Priority | Method | Check |
|----------|--------|-------|
| 1 | package.json devDependencies | vitest, jest, mocha, pytest |
| 2 | package.json scripts.test | Command contains framework name |
| 3 | Config file existence | vitest.config.*, jest.config.*, pytest.ini |
**Affected test discovery** from modified files:
- For each modified file `<name>.<ext>`, search:
`<name>.test.ts`, `<name>.spec.ts`, `tests/<name>.test.ts`, `__tests__/<name>.test.ts`
## Phase 3: Test-Fix Cycle
### Test Command Table
| Framework | Affected Tests | Full Suite |
|-----------|---------------|------------|
| vitest | `vitest run <files> --reporter=verbose` | `vitest run --reporter=verbose` |
| jest | `jest <files> --no-coverage --verbose` | `jest --no-coverage --verbose` |
| mocha | `mocha <files> --reporter spec` | `mocha --reporter spec` |
| pytest | `pytest <files> -v --tb=short` | `pytest -v --tb=short` |
### Iteration Flow
```
Iteration 1
├─ Run affected tests (or full suite if none)
├─ Parse results → pass rate
├─ Pass rate >= 95%?
│ ├─ YES + affected-only → run full suite to confirm
│ │ ├─ Full suite passes → SUCCESS
│ │ └─ Full suite fails → continue with full results
│ └─ YES + full suite → SUCCESS
└─ NO → classify failures → select strategy → apply fixes
Iteration 2..10
├─ Re-run tests
├─ Track best pass rate across iterations
├─ Pass rate >= 95% → SUCCESS
├─ No failures to fix → STOP (anomaly)
└─ Failures remain → classify → select strategy → apply fixes
After iteration 10
└─ FAIL: max iterations reached, report best pass rate
```
**Progress update**: When iteration > 5, send progress to coordinator with current pass rate and iteration count.
### Strategy Selection Matrix
| Condition | Strategy | Behavior |
|-----------|----------|----------|
| Iteration <= 3 OR pass rate >= 80% | Conservative | Fix one failure at a time, highest severity first |
| Critical failures exist AND count < 5 | Surgical | Identify common error pattern, fix all matching occurrences |
| Pass rate < 50% OR iteration > 7 | Aggressive | Fix all critical + high failures in batch |
| Default (no other match) | Conservative | Safe fallback |
### Failure Classification Table
| Severity | Error Patterns |
|----------|---------------|
| Critical | SyntaxError, cannot find module, is not defined |
| High | Assertion mismatch (expected/received), toBe/toEqual failures |
| Medium | Timeout, async errors |
| Low | Warnings, deprecation notices |
### Fix Approach by Error Type
| Error Type | Pattern | Fix Approach |
|------------|---------|-------------|
| missing_import | "Cannot find module '<module>'" | Add import statement, resolve relative path from modified files |
| undefined_variable | "<name> is not defined" | Check source for renamed/moved exports, update reference |
| assertion_mismatch | "Expected: X, Received: Y" | Read test file at failure line, update expected value if behavior change is intentional |
| timeout | "Timeout" | Increase timeout or add async/await |
| syntax_error | "SyntaxError" | Read source at error line, fix syntax |
### Tool Call Example
Run tests with framework-appropriate command:
```bash
Bash(command="vitest run src/utils/__tests__/parser.test.ts --reporter=verbose", timeout=120000)
```
Read test file to analyze failure:
```bash
Read(file_path="<test_file_path>")
```
Apply fix via Edit:
```bash
Edit(file_path="<file>", old_string="<old>", new_string="<new>")
```
## Phase 4: Validation
### Success Criteria
| Check | Criteria | Required |
|-------|----------|----------|
| Pass rate | >= 95% | Yes |
| Full suite run | At least one full suite pass | Yes |
| No critical failures | Zero critical-severity failures remaining | Yes |
| Best pass rate tracked | Reported in final result | Yes |
### Result Routing
| Outcome | Message Type | Content |
|---------|-------------|---------|
| Pass rate >= target | test_result | Success, iterations count, full suite confirmed |
| Max iterations, pass rate < target | fix_required | Best pass rate, remaining failures, iteration count |
| No tests found | error | Framework detected but no test files |
| Framework not detected | error | Detection methods exhausted |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Framework not detected | Report error to coordinator, list detection attempts |
| No test files found | Report to coordinator, suggest manual test path |
| Test command fails (exit code != 0/1) | Check stderr for environment issues, retry once |
| Fix application fails | Skip fix, try next iteration with different strategy |
| Infinite loop (same failures repeat) | Abort after 3 identical result sets |

108
.claude/skills/team-lifecycle-v4/roles/tester/role.md Normal file
View File

@@ -0,0 +1,108 @@
# Role: tester
Adaptive test execution with fix cycles and quality gates.
## Identity
- **Name**: `tester` | **Prefix**: `TEST-*` | **Tag**: `[tester]`
- **Responsibility**: Detect Framework → Run Tests → Fix Cycle → Report
## Boundaries
### MUST
- Only process TEST-* tasks
- Detect test framework before running
- Run affected tests before full suite
- Use strategy engine for fix cycles
### MUST NOT
- Create tasks
- Contact other workers directly
- Modify production code beyond test fixes
- Skip framework detection
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| test_result | → coordinator | Tests pass or final result |
| fix_required | → coordinator | Failures after max iterations |
| error | → coordinator | Framework not detected |
## Toolbox
| Tool | Purpose |
|------|---------|
| commands/validate.md | Test-fix cycle with strategy engine |
---
## Phase 2: Framework Detection & Test Discovery
**Framework detection** (priority order):
| Priority | Method | Frameworks |
|----------|--------|-----------|
| 1 | package.json devDependencies | vitest, jest, mocha, pytest |
| 2 | package.json scripts.test | vitest, jest, mocha, pytest |
| 3 | Config files | vitest.config.*, jest.config.*, pytest.ini |
**Affected test discovery** from executor's modified files:
- Search variants: `<name>.test.ts`, `<name>.spec.ts`, `tests/<name>.test.ts`, `__tests__/<name>.test.ts`
---
## Phase 3: Test Execution & Fix Cycle
**Config**: MAX_ITERATIONS=10, PASS_RATE_TARGET=95%, AFFECTED_TESTS_FIRST=true
Delegate to `commands/validate.md`:
1. Run affected tests → parse results
2. Pass rate met → run full suite
3. Failures → select strategy → fix → re-run → repeat
**Strategy selection**:
| Condition | Strategy | Behavior |
|-----------|----------|----------|
| Iteration ≤ 3 or pass ≥ 80% | Conservative | Fix one critical failure at a time |
| Critical failures < 5 | Surgical | Fix specific pattern everywhere |
| Pass < 50% or iteration > 7 | Aggressive | Fix all failures in batch |
**Test commands**:
| Framework | Affected | Full Suite |
|-----------|---------|------------|
| vitest | `vitest run <files>` | `vitest run` |
| jest | `jest <files> --no-coverage` | `jest --no-coverage` |
| pytest | `pytest <files> -v` | `pytest -v` |
---
## Phase 4: Result Analysis
**Failure classification**:
| Severity | Patterns |
|----------|----------|
| Critical | SyntaxError, cannot find module, undefined |
| High | Assertion failures, toBe/toEqual |
| Medium | Timeout, async errors |
| Low | Warnings, deprecations |
**Report routing**:
| Condition | Type |
|-----------|------|
| Pass rate ≥ target | test_result (success) |
| Pass rate < target after max iterations | fix_required |
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Framework not detected | Prompt user |
| No tests found | Report to coordinator |
| Infinite fix loop | Abort after MAX_ITERATIONS |

187
.claude/skills/team-lifecycle-v4/roles/writer/commands/generate-doc.md Normal file
View File

@@ -0,0 +1,187 @@
# Command: generate-doc
## Purpose
Multi-CLI document generation for 4 document types. Each uses parallel or staged CLI analysis, then synthesizes into templated documents.
## Phase 2: Context Loading
| Input | Source | Required |
|-------|--------|----------|
| Document standards | `../../specs/document-standards.md` | Yes |
| Template | From routing table below | Yes |
| Spec config | `<session-folder>/spec/spec-config.json` | Yes |
| Discovery context | `<session-folder>/spec/discovery-context.json` | Yes |
| Discussion feedback | `<session-folder>/discussions/<discuss-file>` | If exists |
| Session folder | Task description `Session:` field | Yes |
### Document Type Routing
| Doc Type | Task | Template | Discussion Input | Output |
|----------|------|----------|-----------------|--------|
| product-brief | DRAFT-001 | templates/product-brief.md | discuss-001-scope.md | spec/product-brief.md |
| requirements | DRAFT-002 | templates/requirements-prd.md | discuss-002-brief.md | spec/requirements/_index.md |
| architecture | DRAFT-003 | templates/architecture-doc.md | discuss-003-requirements.md | spec/architecture/_index.md |
| epics | DRAFT-004 | templates/epics-template.md | discuss-004-architecture.md | spec/epics/_index.md |
### Progressive Dependencies
Each doc type requires all prior docs: discovery-context → product-brief → requirements/_index → architecture/_index.
## Phase 3: Document Generation
### Shared Context Block
Built from spec-config and discovery-context for all CLI prompts:
```
SEED: <topic>
PROBLEM: <problem_statement>
TARGET USERS: <target_users>
DOMAIN: <domain>
CONSTRAINTS: <constraints>
FOCUS AREAS: <focus_areas>
CODEBASE CONTEXT: <existing_patterns, tech_stack> (if discovery-context exists)
```
---
### DRAFT-001: Product Brief
**Strategy**: 3-way parallel CLI analysis, then synthesize.
| Perspective | CLI Tool | Focus |
|-------------|----------|-------|
| Product | gemini | Vision, market fit, success metrics, scope |
| Technical | codex | Feasibility, constraints, integration complexity |
| User | claude | Personas, journey maps, pain points, UX |
**CLI call template** (one per perspective, all `run_in_background: true`):
```bash
Bash(command="ccw cli -p \"PURPOSE: <perspective> analysis for specification.\n<shared-context>\nTASK: <perspective-specific tasks>\nMODE: analysis\nEXPECTED: <structured output>\nCONSTRAINTS: <perspective scope>\" --tool <tool> --mode analysis", run_in_background=true)
```
**Synthesis flow** (after all 3 return):
```
3 CLI outputs received
├─ Identify convergent themes (2+ perspectives agree)
├─ Identify conflicts (e.g., product wants X, technical says infeasible)
├─ Extract unique insights per perspective
├─ Integrate discussion feedback (if exists)
└─ Fill template → Write to spec/product-brief.md
```
**Template sections**: Vision, Problem Statement, Target Users, Goals, Scope, Success Criteria, Assumptions.
---
### DRAFT-002: Requirements/PRD
**Strategy**: Single CLI expansion, then structure into individual requirement files.
| Step | Tool | Action |
|------|------|--------|
| 1 | gemini | Generate functional (REQ-NNN) and non-functional (NFR-type-NNN) requirements |
| 2 | (local) | Integrate discussion feedback |
| 3 | (local) | Write individual files + _index.md |
**CLI prompt focus**: For each product-brief goal, generate 3-7 functional requirements with user stories, acceptance criteria, and MoSCoW priority. Generate NFR categories: performance, security, scalability, usability.
**Output structure**:
```
spec/requirements/
├─ _index.md (summary table + MoSCoW breakdown)
├─ REQ-001-<slug>.md (individual functional requirement)
├─ REQ-002-<slug>.md
├─ NFR-perf-001-<slug>.md (non-functional)
└─ NFR-sec-001-<slug>.md
```
Each requirement file has: YAML frontmatter (id, title, priority, status, traces), description, user story, acceptance criteria.
---
### DRAFT-003: Architecture
**Strategy**: 2-stage CLI (design + critical review).
| Stage | Tool | Purpose |
|-------|------|---------|
| 1 | gemini | Architecture design: style, components, tech stack, ADRs, data model, security |
| 2 | codex | Critical review: challenge ADRs, identify bottlenecks, rate quality 1-5 |
Stage 2 runs after stage 1 completes (sequential dependency).
**After both complete**:
1. Integrate discussion feedback
2. Map codebase integration points (from discovery-context.relevant_files)
3. Write individual ADR files + _index.md
**Output structure**:
```
spec/architecture/
├─ _index.md (overview, component diagram, tech stack, data model, API, security)
├─ ADR-001-<slug>.md (individual decision record)
└─ ADR-002-<slug>.md
```
Each ADR file has: YAML frontmatter (id, title, status, traces), context, decision, alternatives with pros/cons, consequences, review feedback.
---
### DRAFT-004: Epics & Stories
**Strategy**: Single CLI decomposition, then structure into individual epic files.
| Step | Tool | Action |
|------|------|--------|
| 1 | gemini | Decompose requirements into 3-7 Epics with Stories, dependency map, MVP subset |
| 2 | (local) | Integrate discussion feedback |
| 3 | (local) | Write individual EPIC files + _index.md |
**CLI prompt focus**: Group requirements by domain, generate EPIC-NNN with STORY-EPIC-NNN children, define MVP subset, create Mermaid dependency diagram, recommend execution order.
**Output structure**:
```
spec/epics/
├─ _index.md (overview table, dependency map, execution order, MVP scope)
├─ EPIC-001-<slug>.md (individual epic with stories)
└─ EPIC-002-<slug>.md
```
Each epic file has: YAML frontmatter (id, title, priority, mvp, size, requirements, architecture, dependencies), stories with user stories and acceptance criteria.
All generated documents include YAML frontmatter: session_id, phase, document_type, status=draft, generated_at, version, dependencies.
## Phase 4: Validation
| Check | What to Verify |
|-------|---------------|
| has_frontmatter | Document starts with valid YAML frontmatter |
| sections_complete | All template sections present in output |
| cross_references | session_id matches spec-config |
| discussion_integrated | Feedback reflected (if feedback exists) |
| files_written | All expected files exist (individual + _index.md) |
### Result Routing
| Outcome | Message Type | Content |
|---------|-------------|---------|
| All checks pass | draft_ready | Doc type, output path, summary |
| Validation issues | draft_ready (with warnings) | Doc type, output path, issues list |
| Critical failure | error | Missing template, CLI failure |
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Prior doc not found | Notify coordinator, request prerequisite task completion |
| Template not found | Error, report missing template path |
| CLI tool fails | Retry with fallback tool (gemini → codex → claude) |
| Discussion contradicts prior docs | Note conflict in document, flag for next discussion round |
| Partial CLI output | Use available data, note gaps in document |

135
.claude/skills/team-lifecycle-v4/roles/writer/role.md Normal file
View File

@@ -0,0 +1,135 @@
# Role: writer
Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation. Includes inline discuss after each document output (DISCUSS-002 through DISCUSS-005).
## Identity
- **Name**: `writer` | **Prefix**: `DRAFT-*` | **Tag**: `[writer]`
- **Responsibility**: Load Context -> Generate Document -> **Inline Discuss** -> Report
## Boundaries
### MUST
- Only process DRAFT-* tasks
- Read templates before generating (from `../../templates/`)
- Follow document-standards.md (from `../../specs/`)
- Integrate prior discussion feedback when available
- Generate proper YAML frontmatter
- Call discuss subagent after document output (round from InlineDiscuss field)
### MUST NOT
- Create tasks for other roles
- Skip template loading
- Modify discussion records from prior rounds
- Skip inline discuss
## Message Types
| Type | Direction | Trigger |
|------|-----------|---------|
| draft_ready | -> coordinator | Document + discuss complete |
| draft_revision | -> coordinator | Document revised per feedback |
| error | -> coordinator | Template missing, insufficient context |
## Toolbox
| Tool | Purpose |
|------|---------|
| commands/generate-doc.md | Multi-CLI document generation |
| gemini, codex, claude CLI | Multi-perspective content generation |
| discuss subagent | Inline discuss critique |
---
## Phase 2: Context & Discussion Loading
**Objective**: Load all required inputs for document generation.
**Document type routing**:
| Task Subject Contains | Doc Type | Template | Prior Discussion Input |
|----------------------|----------|----------|----------------------|
| Product Brief | product-brief | templates/product-brief.md | discussions/DISCUSS-001-discussion.md |
| Requirements / PRD | requirements | templates/requirements-prd.md | discussions/DISCUSS-002-discussion.md |
| Architecture | architecture | templates/architecture-doc.md | discussions/DISCUSS-003-discussion.md |
| Epics | epics | templates/epics-template.md | discussions/DISCUSS-004-discussion.md |
**Inline discuss mapping**:
| Doc Type | Inline Discuss Round | Perspectives |
|----------|---------------------|-------------|
| product-brief | DISCUSS-002 | product, technical, quality, coverage |
| requirements | DISCUSS-003 | quality, product, coverage |
| architecture | DISCUSS-004 | technical, risk |
| epics | DISCUSS-005 | product, technical, quality, coverage |
**Progressive dependency loading**:
| Doc Type | Requires |
|----------|----------|
| product-brief | discovery-context.json |
| requirements | + product-brief.md |
| architecture | + requirements/_index.md |
| epics | + architecture/_index.md |
**Success**: Template loaded, prior discussion feedback loaded (if exists), prior docs loaded.
---
## Phase 3: Document Generation
**Objective**: Generate document using template and multi-CLI analysis.
Delegate to `commands/generate-doc.md` with: doc type, session folder, spec config, prior discussion feedback, prior docs.
---
## Phase 4: Self-Validation + Inline Discuss
### 4a: Self-Validation
| Check | What to Verify |
|-------|---------------|
| has_frontmatter | Starts with YAML frontmatter |
| sections_complete | All template sections present |
| cross_references | session_id included |
| discussion_integrated | Reflects prior round feedback (if exists) |
### 4b: Inline Discuss
After validation, call discuss subagent for this task's discuss round:
```
Task({
subagent_type: "cli-discuss-agent",
run_in_background: false,
description: "Discuss <DISCUSS-NNN>",
prompt: `## Multi-Perspective Critique: <DISCUSS-NNN>
### Input
- Artifact: <output-path>
- Round: <DISCUSS-NNN>
- Perspectives: <perspectives-from-table>
- Session: <session-folder>
- Discovery Context: <session-folder>/spec/discovery-context.json
<rest of discuss subagent prompt from subagents/discuss-subagent.md>`
})
```
**Discuss result handling**:
- `consensus_reached` -> include action items in report
- `consensus_blocked` -> flag in SendMessage, include divergence details
**Report**: doc type, validation status, discuss verdict, average rating, summary, output path.
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Prior doc not found | Notify coordinator, request prerequisite |
| CLI failure | Retry with fallback tool |
| Discussion contradicts prior docs | Note conflict, flag for coordinator |
| Discuss subagent fails | Proceed without discuss, log warning in report |

192
.claude/skills/team-lifecycle-v4/specs/document-standards.md Normal file
View File

@@ -0,0 +1,192 @@
# Document Standards
Defines format conventions, YAML frontmatter schema, naming rules, and content structure for all spec-generator outputs.
## When to Use
| Phase | Usage | Section |
|-------|-------|---------|
| All Phases | Frontmatter format | YAML Frontmatter Schema |
| All Phases | File naming | Naming Conventions |
| Phase 2-5 | Document structure | Content Structure |
| Phase 6 | Validation reference | All sections |
---
## YAML Frontmatter Schema
Every generated document MUST begin with YAML frontmatter:
```yaml
---
session_id: SPEC-{slug}-{YYYY-MM-DD}
phase: {1-6}
document_type: {product-brief|requirements|architecture|epics|readiness-report|spec-summary}
status: draft|review|complete
generated_at: {ISO8601 timestamp}
stepsCompleted: []
version: 1
dependencies:
- {list of input documents used}
---
```
### Field Definitions
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `session_id` | string | Yes | Session identifier matching spec-config.json |
| `phase` | number | Yes | Phase number that generated this document (1-6) |
| `document_type` | string | Yes | One of: product-brief, requirements, architecture, epics, readiness-report, spec-summary |
| `status` | enum | Yes | draft (initial), review (user reviewed), complete (finalized) |
| `generated_at` | string | Yes | ISO8601 timestamp of generation |
| `stepsCompleted` | array | Yes | List of step IDs completed during generation |
| `version` | number | Yes | Document version, incremented on re-generation |
| `dependencies` | array | No | List of input files this document depends on |
### Status Transitions
```
draft -> review -> complete
| ^
+-------------------+ (direct promotion in auto mode)
```
- **draft**: Initial generation, not yet user-reviewed
- **review**: User has reviewed and provided feedback
- **complete**: Finalized, ready for downstream consumption
In auto mode (`-y`), documents are promoted directly from `draft` to `complete`.
---
## Naming Conventions
### Session ID Format
```
SPEC-{slug}-{YYYY-MM-DD}
```
- **slug**: Lowercase, alphanumeric + Chinese characters, hyphens as separators, max 40 chars
- **date**: UTC+8 date in YYYY-MM-DD format
Examples:
- `SPEC-task-management-system-2026-02-11`
- `SPEC-user-auth-oauth-2026-02-11`
### Output Files
| File | Phase | Description |
|------|-------|-------------|
| `spec-config.json` | 1 | Session configuration and state |
| `discovery-context.json` | 1 | Codebase exploration results (optional) |
| `product-brief.md` | 2 | Product brief document |
| `requirements.md` | 3 | PRD document |
| `architecture.md` | 4 | Architecture decisions document |
| `epics.md` | 5 | Epic/Story breakdown document |
| `readiness-report.md` | 6 | Quality validation report |
| `spec-summary.md` | 6 | One-page executive summary |
### Output Directory
```
.workflow/.spec/{session-id}/
```
---
## Content Structure
### Heading Hierarchy
- `#` (H1): Document title only (one per document)
- `##` (H2): Major sections
- `###` (H3): Subsections
- `####` (H4): Detail items (use sparingly)
Maximum depth: 4 levels. Prefer flat structures.
### Section Ordering
Every document follows this general pattern:
1. **YAML Frontmatter** (mandatory)
2. **Title** (H1)
3. **Executive Summary** (2-3 sentences)
4. **Core Content Sections** (H2, document-specific)
5. **Open Questions / Risks** (if applicable)
6. **References / Traceability** (links to upstream/downstream docs)
### Formatting Rules
| Element | Format | Example |
|---------|--------|---------|
| Requirements | `REQ-{NNN}` prefix | REQ-001: User login |
| Acceptance criteria | Checkbox list | `- [ ] User can log in with email` |
| Architecture decisions | `ADR-{NNN}` prefix | ADR-001: Use PostgreSQL |
| Epics | `EPIC-{NNN}` prefix | EPIC-001: Authentication |
| Stories | `STORY-{EPIC}-{NNN}` prefix | STORY-001-001: Login form |
| Priority tags | MoSCoW labels | `[Must]`, `[Should]`, `[Could]`, `[Won't]` |
| Mermaid diagrams | Fenced code blocks | ````mermaid ... ``` `` |
| Code examples | Language-tagged blocks | ````typescript ... ``` `` |
### Cross-Reference Format
Use relative references between documents:
```markdown
See [Product Brief](product-brief.md#section-name) for details.
Derived from [REQ-001](requirements.md#req-001).
```
### Language
- Document body: Follow user's input language (Chinese or English)
- Technical identifiers: Always English (REQ-001, ADR-001, EPIC-001)
- YAML frontmatter keys: Always English
---
## spec-config.json Schema
```json
{
"session_id": "string (required)",
"seed_input": "string (required) - original user input",
"input_type": "text|file (required)",
"timestamp": "ISO8601 (required)",
"mode": "interactive|auto (required)",
"complexity": "simple|moderate|complex (required)",
"depth": "light|standard|comprehensive (required)",
"focus_areas": ["string array"],
"seed_analysis": {
"problem_statement": "string",
"target_users": ["string array"],
"domain": "string",
"constraints": ["string array"],
"dimensions": ["string array - 3-5 exploration dimensions"]
},
"has_codebase": "boolean",
"phasesCompleted": [
{
"phase": "number (1-6)",
"name": "string (phase name)",
"output_file": "string (primary output file)",
"completed_at": "ISO8601"
}
]
}
```
---
## Validation Checklist
- [ ] Every document starts with valid YAML frontmatter
- [ ] `session_id` matches across all documents in a session
- [ ] `status` field reflects current document state
- [ ] All cross-references resolve to valid targets
- [ ] Heading hierarchy is correct (no skipped levels)
- [ ] Technical identifiers use correct prefixes
- [ ] Output files are in the correct directory

207
.claude/skills/team-lifecycle-v4/specs/quality-gates.md Normal file
View File

@@ -0,0 +1,207 @@
# Quality Gates
Per-phase quality gate criteria and scoring dimensions for spec-generator outputs.
## When to Use
| Phase | Usage | Section |
|-------|-------|---------|
| Phase 2-5 | Post-generation self-check | Per-Phase Gates |
| Phase 6 | Cross-document validation | Cross-Document Validation |
| Phase 6 | Final scoring | Scoring Dimensions |
---
## Quality Thresholds
| Gate | Score | Action |
|------|-------|--------|
| **Pass** | >= 80% | Continue to next phase |
| **Review** | 60-79% | Log warnings, continue with caveats |
| **Fail** | < 60% | Must address issues before continuing |
In auto mode (`-y`), Review-level issues are logged but do not block progress.
---
## Scoring Dimensions
### 1. Completeness (25%)
All required sections present with substantive content.
| Score | Criteria |
|-------|----------|
| 100% | All template sections filled with detailed content |
| 75% | All sections present, some lack detail |
| 50% | Major sections present but minor sections missing |
| 25% | Multiple major sections missing or empty |
| 0% | Document is a skeleton only |
### 2. Consistency (25%)
Terminology, formatting, and references are uniform across documents.
| Score | Criteria |
|-------|----------|
| 100% | All terms consistent, all references valid, formatting uniform |
| 75% | Minor terminology variations, all references valid |
| 50% | Some inconsistent terms, 1-2 broken references |
| 25% | Frequent inconsistencies, multiple broken references |
| 0% | Documents contradict each other |
### 3. Traceability (25%)
Requirements, architecture decisions, and stories trace back to goals.
| Score | Criteria |
|-------|----------|
| 100% | Every story traces to a requirement, every requirement traces to a goal |
| 75% | Most items traceable, few orphans |
| 50% | Partial traceability, some disconnected items |
| 25% | Weak traceability, many orphan items |
| 0% | No traceability between documents |
### 4. Depth (25%)
Content provides sufficient detail for execution teams.
| Score | Criteria |
|-------|----------|
| 100% | Acceptance criteria specific and testable, architecture decisions justified, stories estimable |
| 75% | Most items detailed enough, few vague areas |
| 50% | Mix of detailed and vague content |
| 25% | Mostly high-level, lacking actionable detail |
| 0% | Too abstract for execution |
---
## Per-Phase Quality Gates
### Phase 1: Discovery
| Check | Criteria | Severity |
|-------|----------|----------|
| Session ID valid | Matches `SPEC-{slug}-{date}` format | Error |
| Problem statement exists | Non-empty, >= 20 characters | Error |
| Target users identified | >= 1 user group | Error |
| Dimensions generated | 3-5 exploration dimensions | Warning |
| Constraints listed | >= 0 (can be empty with justification) | Info |
### Phase 2: Product Brief
| Check | Criteria | Severity |
|-------|----------|----------|
| Vision statement | Clear, 1-3 sentences | Error |
| Problem statement | Specific and measurable | Error |
| Target users | >= 1 persona with needs described | Error |
| Goals defined | >= 2 measurable goals | Error |
| Success metrics | >= 2 quantifiable metrics | Warning |
| Scope boundaries | In-scope and out-of-scope listed | Warning |
| Multi-perspective | >= 2 CLI perspectives synthesized | Info |
### Phase 3: Requirements (PRD)
| Check | Criteria | Severity |
|-------|----------|----------|
| Functional requirements | >= 3 with REQ-NNN IDs | Error |
| Acceptance criteria | Every requirement has >= 1 criterion | Error |
| MoSCoW priority | Every requirement tagged | Error |
| Non-functional requirements | >= 1 (performance, security, etc.) | Warning |
| User stories | >= 1 per Must-have requirement | Warning |
| Traceability | Requirements trace to product brief goals | Warning |
### Phase 4: Architecture
| Check | Criteria | Severity |
|-------|----------|----------|
| Component diagram | Present (Mermaid or ASCII) | Error |
| Tech stack specified | Languages, frameworks, key libraries | Error |
| ADR present | >= 1 Architecture Decision Record | Error |
| ADR has alternatives | Each ADR lists >= 2 options considered | Warning |
| Integration points | External systems/APIs identified | Warning |
| Data model | Key entities and relationships described | Warning |
| Codebase mapping | Mapped to existing code (if has_codebase) | Info |
### Phase 5: Epics & Stories
| Check | Criteria | Severity |
|-------|----------|----------|
| Epics defined | 3-7 epics with EPIC-NNN IDs | Error |
| MVP subset | >= 1 epic tagged as MVP | Error |
| Stories per epic | 2-5 stories per epic | Error |
| Story format | "As a...I want...So that..." pattern | Warning |
| Dependency map | Cross-epic dependencies documented | Warning |
| Estimation hints | Relative sizing (S/M/L/XL) per story | Info |
| Traceability | Stories trace to requirements | Warning |
### Phase 6: Readiness Check
| Check | Criteria | Severity |
|-------|----------|----------|
| All documents exist | product-brief, requirements, architecture, epics | Error |
| Frontmatter valid | All YAML frontmatter parseable and correct | Error |
| Cross-references valid | All document links resolve | Error |
| Overall score >= 60% | Weighted average across 4 dimensions | Error |
| No unresolved Errors | All Error-severity issues addressed | Error |
| Summary generated | spec-summary.md created | Warning |
---
## Cross-Document Validation
Checks performed during Phase 6 across all documents:
### Completeness Matrix
```
Product Brief goals -> Requirements (each goal has >= 1 requirement)
Requirements -> Architecture (each Must requirement has design coverage)
Requirements -> Epics (each Must requirement appears in >= 1 story)
Architecture ADRs -> Epics (tech choices reflected in implementation stories)
```
### Consistency Checks
| Check | Documents | Rule |
|-------|-----------|------|
| Terminology | All | Same term used consistently (no synonyms for same concept) |
| User personas | Brief + PRD + Epics | Same user names/roles throughout |
| Scope | Brief + PRD | PRD scope does not exceed brief scope |
| Tech stack | Architecture + Epics | Stories reference correct technologies |
### Traceability Matrix Format
```markdown
| Goal | Requirements | Architecture | Epics |
|------|-------------|--------------|-------|
| G-001: ... | REQ-001, REQ-002 | ADR-001 | EPIC-001 |
| G-002: ... | REQ-003 | ADR-002 | EPIC-002, EPIC-003 |
```
---
## Issue Classification
### Error (Must Fix)
- Missing required document or section
- Broken cross-references
- Contradictory information between documents
- Empty acceptance criteria on Must-have requirements
- No MVP subset defined in epics
### Warning (Should Fix)
- Vague acceptance criteria
- Missing non-functional requirements
- No success metrics defined
- Incomplete traceability
- Missing architecture review notes
### Info (Nice to Have)
- Could add more detailed personas
- Consider additional ADR alternatives
- Story estimation hints missing
- Mermaid diagrams could be more detailed

169
.claude/skills/team-lifecycle-v4/specs/team-config.json Normal file
View File

@@ -0,0 +1,169 @@
{
"team_name": "team-lifecycle",
"team_display_name": "Team Lifecycle v4",
"description": "Optimized team skill: inline discuss subagent + shared explore cache, spec beats halved",
"version": "4.0.0",
"architecture": "folder-based + subagents",
"role_structure": "roles/{name}/role.md + roles/{name}/commands/*.md",
"subagent_structure": "subagents/{name}-subagent.md",
"roles": {
"coordinator": {
"task_prefix": null,
"responsibility": "Pipeline orchestration, requirement clarification, task chain creation, message dispatch",
"message_types": ["plan_approved", "plan_revision", "task_unblocked", "fix_required", "error", "shutdown"]
},
"analyst": {
"task_prefix": "RESEARCH",
"responsibility": "Seed analysis, codebase exploration, multi-dimensional context gathering + inline discuss",
"inline_discuss": "DISCUSS-001",
"message_types": ["research_ready", "research_progress", "error"]
},
"writer": {
"task_prefix": "DRAFT",
"responsibility": "Product Brief / PRD / Architecture / Epics document generation + inline discuss",
"inline_discuss": ["DISCUSS-002", "DISCUSS-003", "DISCUSS-004", "DISCUSS-005"],
"message_types": ["draft_ready", "draft_revision", "error"]
},
"planner": {
"task_prefix": "PLAN",
"responsibility": "Multi-angle code exploration (via shared explore), structured implementation planning",
"message_types": ["plan_ready", "plan_revision", "error"]
},
"executor": {
"task_prefix": "IMPL",
"responsibility": "Code implementation following approved plans",
"message_types": ["impl_complete", "impl_progress", "error"]
},
"tester": {
"task_prefix": "TEST",
"responsibility": "Adaptive test-fix cycles, progressive testing, quality gates",
"message_types": ["test_result", "fix_required", "error"]
},
"reviewer": {
"task_prefix": "REVIEW",
"additional_prefixes": ["QUALITY"],
"responsibility": "Code review (REVIEW-*) + Spec quality validation (QUALITY-*) + inline discuss for sign-off",
"inline_discuss": "DISCUSS-006",
"message_types": ["review_result", "quality_result", "fix_required", "error"]
},
"architect": {
"task_prefix": "ARCH",
"responsibility": "Architecture assessment, tech feasibility, design pattern review. Consulting role -- on-demand by coordinator",
"role_type": "consulting",
"consultation_modes": ["spec-review", "plan-review", "code-review", "consult", "feasibility"],
"message_types": ["arch_ready", "arch_concern", "arch_progress", "error"]
},
"fe-developer": {
"task_prefix": "DEV-FE",
"responsibility": "Frontend component/page implementation, design token consumption, responsive UI",
"role_type": "frontend-pipeline",
"message_types": ["dev_fe_complete", "dev_fe_progress", "error"]
},
"fe-qa": {
"task_prefix": "QA-FE",
"responsibility": "5-dimension frontend review (quality, a11y, design compliance, UX, pre-delivery), GC loop",
"role_type": "frontend-pipeline",
"message_types": ["qa_fe_passed", "qa_fe_result", "fix_required", "error"]
}
},
"subagents": {
"discuss": {
"spec": "subagents/discuss-subagent.md",
"type": "cli-discuss-agent",
"callable_by": ["analyst", "writer", "reviewer"],
"purpose": "Multi-perspective critique with CLI tools, consensus synthesis"
},
"explore": {
"spec": "subagents/explore-subagent.md",
"type": "Explore",
"callable_by": ["analyst", "planner", "any"],
"purpose": "Codebase exploration with centralized cache"
}
},
"pipelines": {
"spec-only": {
"description": "Specification pipeline: research+discuss -> draft+discuss x4 -> quality+discuss",
"task_chain": [
"RESEARCH-001",
"DRAFT-001", "DRAFT-002", "DRAFT-003", "DRAFT-004",
"QUALITY-001"
],
"beats": 6,
"v3_beats": 12,
"optimization": "Discuss rounds inlined into produce roles"
},
"impl-only": {
"description": "Implementation pipeline: plan -> implement -> test + review",
"task_chain": ["PLAN-001", "IMPL-001", "TEST-001", "REVIEW-001"],
"beats": 3
},
"full-lifecycle": {
"description": "Full lifecycle: spec pipeline -> implementation pipeline",
"task_chain": "spec-only + impl-only (PLAN-001 blockedBy QUALITY-001)",
"beats": 9,
"v3_beats": 15,
"optimization": "6 fewer spec beats + QUALITY-001 is last spec task"
},
"fe-only": {
"description": "Frontend-only pipeline: plan -> frontend dev -> frontend QA",
"task_chain": ["PLAN-001", "DEV-FE-001", "QA-FE-001"],
"gc_loop": { "max_rounds": 2, "convergence": "score >= 8 && critical === 0" }
},
"fullstack": {
"description": "Fullstack pipeline: plan -> backend + frontend parallel -> test + QA",
"task_chain": ["PLAN-001", "IMPL-001||DEV-FE-001", "TEST-001||QA-FE-001", "REVIEW-001"],
"sync_points": ["REVIEW-001"]
},
"full-lifecycle-fe": {
"description": "Full lifecycle with frontend: spec -> plan -> backend + frontend -> test + QA",
"task_chain": "spec-only + fullstack (PLAN-001 blockedBy QUALITY-001)"
}
},
"frontend_detection": {
"keywords": ["component", "page", "UI", "frontend", "CSS", "HTML", "React", "Vue", "Tailwind", "Svelte", "Next.js", "Nuxt", "shadcn", "design system"],
"file_patterns": ["*.tsx", "*.jsx", "*.vue", "*.svelte", "*.css", "*.scss", "*.html"],
"routing_rules": {
"frontend_only": "All tasks match frontend keywords, no backend/API mentions",
"fullstack": "Mix of frontend and backend tasks",
"backend_only": "No frontend keywords detected (default impl-only)"
}
},
"ui_ux_pro_max": {
"skill_name": "ui-ux-pro-max",
"invocation": "Skill(skill=\"ui-ux-pro-max\", args=\"...\")",
"domains": ["product", "style", "typography", "color", "landing", "chart", "ux", "web"],
"stacks": ["html-tailwind", "react", "nextjs", "vue", "svelte", "shadcn", "swiftui", "react-native", "flutter"],
"design_intelligence_chain": ["analyst -> design-intelligence.json", "architect -> design-tokens.json", "fe-developer -> tokens.css", "fe-qa -> anti-pattern audit"]
},
"shared_memory": {
"file": "shared-memory.json",
"schema": {
"design_intelligence": "From analyst via ui-ux-pro-max",
"design_token_registry": "From architect, consumed by fe-developer/fe-qa",
"component_inventory": "From fe-developer, list of implemented components",
"style_decisions": "Accumulated design decisions",
"qa_history": "From fe-qa, audit trail",
"industry_context": "Industry + strictness config",
"exploration_cache": "From explore subagent, shared by all roles"
}
},
"session_dirs": {
"base": ".workflow/.team/TLS-{slug}-{YYYY-MM-DD}/",
"spec": "spec/",
"discussions": "discussions/",
"plan": "plan/",
"explorations": "explorations/",
"architecture": "architecture/",
"analysis": "analysis/",
"qa": "qa/",
"wisdom": "wisdom/",
"messages": ".msg/"
}
}

134
.claude/skills/team-lifecycle-v4/subagents/discuss-subagent.md Normal file
View File

@@ -0,0 +1,134 @@
# Discuss Subagent
Lightweight multi-perspective critique engine. Called inline by produce roles (analyst, writer, reviewer) instead of as a separate team member. Eliminates spawn overhead while preserving multi-CLI analysis quality.
## Design Rationale
In v3, `discussant` was a full team role requiring: agent spawn -> Skill load -> Phase 1 task discovery -> Phase 2-4 work -> Phase 5 report + callback. For what is essentially "run CLI analyses + synthesize", the framework overhead exceeded actual work time.
In v4, discuss is a **subagent call** from within the producing role, reducing each discuss round from ~60-90s overhead to ~5s overhead.
## Invocation
Called by produce roles after artifact creation:
```
Task({
subagent_type: "cli-discuss-agent",
run_in_background: false,
description: "Discuss <round-id>",
prompt: `## Multi-Perspective Critique: <round-id>
### Input
- Artifact: <artifact-path>
- Round: <round-id>
- Perspectives: <perspective-list>
- Session: <session-folder>
- Discovery Context: <session-folder>/spec/discovery-context.json (for coverage perspective)
### Perspective Routing
| Perspective | CLI Tool | Role | Focus Areas |
|-------------|----------|------|-------------|
| Product | gemini | Product Manager | Market fit, user value, business viability |
| Technical | codex | Tech Lead | Feasibility, tech debt, performance, security |
| Quality | claude | QA Lead | Completeness, testability, consistency |
| Risk | gemini | Risk Analyst | Risk identification, dependencies, failure modes |
| Coverage | gemini | Requirements Analyst | Requirement completeness vs discovery-context |
### Execution Steps
1. Read artifact from <artifact-path>
2. For each perspective, launch CLI analysis in background:
Bash(command="ccw cli -p 'PURPOSE: Analyze from <role> perspective for <round-id>
TASK: <focus-areas>
MODE: analysis
CONTEXT: Artifact content below
EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5)
CONSTRAINTS: Output valid JSON only
Artifact:
<artifact-content>' --tool <cli-tool> --mode analysis", run_in_background=true)
3. Wait for all CLI results
4. Divergence detection:
- Coverage gap: missing_requirements non-empty -> High severity
- High risk: risk_level is high or critical -> High severity
- Low rating: any perspective rating <= 2 -> Medium severity
- Rating spread: max - min >= 3 -> Medium severity
5. Consensus determination:
- No high-severity divergences AND average rating >= 3.0 -> consensus_reached
- Otherwise -> consensus_blocked
6. Synthesize:
- Convergent themes (agreed by 2+ perspectives)
- Divergent views (conflicting assessments)
- Coverage gaps
- Action items from suggestions
7. Write discussion record to: <session-folder>/discussions/<round-id>-discussion.md
### Discussion Record Format
# Discussion Record: <round-id>
**Artifact**: <artifact-path>
**Perspectives**: <list>
**Consensus**: reached / blocked
**Average Rating**: <avg>/5
## Convergent Themes
- <theme>
## Divergent Views
- **<topic>** (<severity>): <description>
## Action Items
1. <item>
## Ratings
| Perspective | Rating |
|-------------|--------|
| <name> | <n>/5 |
### Return Value
Return a summary string with:
- Verdict: consensus_reached or consensus_blocked
- Average rating
- Key action items (top 3)
- Discussion record path
### Error Handling
- Single CLI fails -> fallback to direct Claude analysis for that perspective
- All CLI fail -> generate basic discussion from direct artifact reading
- Artifact not found -> return error immediately`
})
```
## Round Configuration
| Round | Artifact | Perspectives | Calling Role |
|-------|----------|-------------|-------------|
| DISCUSS-001 | spec/discovery-context.json | product, risk, coverage | analyst |
| DISCUSS-002 | spec/product-brief.md | product, technical, quality, coverage | writer |
| DISCUSS-003 | spec/requirements/_index.md | quality, product, coverage | writer |
| DISCUSS-004 | spec/architecture/_index.md | technical, risk | writer |
| DISCUSS-005 | spec/epics/_index.md | product, technical, quality, coverage | writer |
| DISCUSS-006 | spec/readiness-report.md | all 5 | reviewer |
## Integration with Calling Role
The calling role is responsible for:
1. **Before calling**: Complete primary artifact output
2. **Calling**: Invoke discuss subagent with correct round config
3. **After calling**:
- Include discuss verdict in Phase 5 report
- If `consensus_blocked` with high-severity divergences -> flag in SendMessage to coordinator
- Discussion record is written by the subagent, no further action needed
## Comparison with v3
| Aspect | v3 (discussant role) | v4 (discuss subagent) |
|--------|---------------------|----------------------|
| Spawn | Full general-purpose agent | Inline subagent call |
| Skill load | Reads SKILL.md + role.md | None (prompt contains all logic) |
| Task discovery | TaskList + TaskGet + TaskUpdate | None (called with context) |
| Report overhead | team_msg + SendMessage + TaskUpdate | Return value to caller |
| Total overhead | ~25-45s framework | ~5s call overhead |
| Pipeline beat | 1 beat per discuss round | 0 additional beats |

172
.claude/skills/team-lifecycle-v4/subagents/explore-subagent.md Normal file
View File

@@ -0,0 +1,172 @@
# Explore Subagent
Shared codebase exploration utility with centralized caching. Callable by any role needing code context. Replaces v3's standalone explorer role.
## Design Rationale
In v3, exploration happened in 3 separate places:
- `analyst` Phase 3: ACE semantic search for architecture patterns
- `planner` Phase 2: multi-angle cli-explore-agent
- `explorer` role: standalone service with full spawn cycle
Results were scattered across different directories and never shared. In v4, all exploration routes through this subagent with a **unified cache** in `explorations/`.
## Invocation
```
Task({
subagent_type: "Explore",
run_in_background: false,
description: "Explore <angle>",
prompt: `Explore codebase for: <query>
Focus angle: <angle>
Keywords: <keyword-list>
Session folder: <session-folder>
## Cache Check
1. Read <session-folder>/explorations/cache-index.json (if exists)
2. Look for entry with matching angle
3. If found AND file exists -> read cached result, return summary
4. If not found -> proceed to exploration
## Exploration
<angle-specific-focus-from-table-below>
## Output
Write JSON to: <session-folder>/explorations/explore-<angle>.json
Update cache-index.json with new entry
## Output Schema
{
"angle": "<angle>",
"query": "<query>",
"relevant_files": [
{ "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] }
],
"patterns": [],
"dependencies": [],
"external_refs": [],
"_metadata": { "created_by": "<calling-role>", "timestamp": "...", "cache_key": "..." }
}
Return summary: file count, pattern count, top 5 files, output path`
})
```
## Cache Mechanism
### Cache Index Schema
`<session-folder>/explorations/cache-index.json`:
```json
{
"entries": [
{
"angle": "architecture",
"keywords": ["auth", "middleware"],
"file": "explore-architecture.json",
"created_by": "analyst",
"created_at": "2026-02-27T10:00:00Z",
"file_count": 15
}
]
}
```
### Cache Lookup Rules
| Condition | Action |
|-----------|--------|
| Exact angle match exists | Return cached result |
| No match | Execute exploration, cache result |
| Cache file missing but index has entry | Remove stale entry, re-explore |
### Cache Invalidation
Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache.
## Angle Focus Guide
| Angle | Focus Points | Typical Caller |
|-------|-------------|----------------|
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | analyst, planner |
| dependencies | Import chains, external libraries, circular dependencies, shared utilities | planner |
| modularity | Module interfaces, separation of concerns, extraction opportunities | planner |
| integration-points | API endpoints, data flow between modules, event systems | analyst, planner |
| security | Auth/authz logic, input validation, sensitive data handling, middleware | planner |
| auth-patterns | Auth flows, session management, token validation, permissions | planner |
| dataflow | Data transformations, state propagation, validation points | planner |
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | planner |
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | planner |
| patterns | Code conventions, design patterns, naming conventions, best practices | analyst, planner |
| testing | Test files, coverage gaps, test patterns, mocking strategies | planner |
| general | Broad semantic search for topic-related code | analyst |
## Exploration Strategies
### Low Complexity (direct search)
For simple queries, use ACE semantic search:
```
mcp__ace-tool__search_context(project_root_path="<project-root>", query="<query>")
```
ACE failure fallback: `rg -l '<keywords>' --type ts`
### Medium/High Complexity (multi-angle)
For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles (see planner's `commands/explore.md`).
## Search Tool Priority
| Tool | Priority | Use Case |
|------|----------|----------|
| mcp__ace-tool__search_context | P0 | Semantic search |
| Grep / Glob | P1 | Pattern matching |
| cli-explore-agent | Deep | Multi-angle exploration |
| WebSearch | P3 | External docs |
## Integration with Roles
### analyst (RESEARCH-001)
```
# After seed analysis, explore codebase context
Task({
subagent_type: "Explore",
description: "Explore general context",
prompt: "Explore codebase for: <topic>\nFocus angle: general\n..."
})
# Result feeds into discovery-context.json
```
### planner (PLAN-001)
```
# Multi-angle exploration before plan generation
for angle in selected_angles:
Task({
subagent_type: "Explore",
description: "Explore <angle>",
prompt: "Explore codebase for: <task>\nFocus angle: <angle>\n..."
})
# Explorations manifest built from cache-index.json
```
### Any role needing context
Any role can call explore subagent when needing codebase context for better decisions.
## Comparison with v3
| Aspect | v3 (explorer role) | v4 (explore subagent) |
|--------|-------------------|----------------------|
| Identity | Full team member | Utility subagent |
| Task creation | Coordinator creates EXPLORE-* tasks | No tasks, direct call |
| Spawn overhead | Full agent lifecycle | Subagent call (~5s) |
| Result sharing | Isolated in explorations/ | Shared cache with index |
| Caller | Only via coordinator dispatch | Any role directly |
| Duplication | analyst + planner + explorer all explore | Single cached path |

254
.claude/skills/team-lifecycle-v4/templates/architecture-doc.md Normal file
View File

@@ -0,0 +1,254 @@
# Architecture Document Template (Directory Structure)
Template for generating architecture decision documents as a directory of individual ADR files in Phase 4.
## Usage Context
| Phase | Usage |
|-------|-------|
| Phase 4 (Architecture) | Generate `architecture/` directory from requirements analysis |
| Output Location | `{workDir}/architecture/` |
## Output Structure
```
{workDir}/architecture/
├── _index.md # Overview, components, tech stack, data model, security
├── ADR-001-{slug}.md # Individual Architecture Decision Record
├── ADR-002-{slug}.md
└── ...
```
---
## Template: _index.md
```markdown
---
session_id: {session_id}
phase: 4
document_type: architecture-index
status: draft
generated_at: {timestamp}
version: 1
dependencies:
- ../spec-config.json
- ../product-brief.md
- ../requirements/_index.md
---
# Architecture: {product_name}
{executive_summary - high-level architecture approach and key decisions}
## System Overview
### Architecture Style
{description of chosen architecture style: microservices, monolith, serverless, etc.}
### System Context Diagram
```mermaid
C4Context
title System Context Diagram
Person(user, "User", "Primary user")
System(system, "{product_name}", "Core system")
System_Ext(ext1, "{external_system}", "{description}")
Rel(user, system, "Uses")
Rel(system, ext1, "Integrates with")
```
## Component Architecture
### Component Diagram
```mermaid
graph TD
subgraph "{product_name}"
A[Component A] --> B[Component B]
B --> C[Component C]
A --> D[Component D]
end
B --> E[External Service]
```
### Component Descriptions
| Component | Responsibility | Technology | Dependencies |
|-----------|---------------|------------|--------------|
| {component_name} | {what it does} | {tech stack} | {depends on} |
## Technology Stack
### Core Technologies
| Layer | Technology | Version | Rationale |
|-------|-----------|---------|-----------|
| Frontend | {technology} | {version} | {why chosen} |
| Backend | {technology} | {version} | {why chosen} |
| Database | {technology} | {version} | {why chosen} |
| Infrastructure | {technology} | {version} | {why chosen} |
### Key Libraries & Frameworks
| Library | Purpose | License |
|---------|---------|---------|
| {library_name} | {purpose} | {license} |
## Architecture Decision Records
| ADR | Title | Status | Key Choice |
|-----|-------|--------|------------|
| [ADR-001](ADR-001-{slug}.md) | {title} | Accepted | {one-line summary} |
| [ADR-002](ADR-002-{slug}.md) | {title} | Accepted | {one-line summary} |
| [ADR-003](ADR-003-{slug}.md) | {title} | Proposed | {one-line summary} |
## Data Architecture
### Data Model
```mermaid
erDiagram
ENTITY_A ||--o{ ENTITY_B : "has many"
ENTITY_A {
string id PK
string name
datetime created_at
}
ENTITY_B {
string id PK
string entity_a_id FK
string value
}
```
### Data Storage Strategy
| Data Type | Storage | Retention | Backup |
|-----------|---------|-----------|--------|
| {type} | {storage solution} | {retention policy} | {backup strategy} |
## API Design
### API Overview
| Endpoint | Method | Purpose | Auth |
|----------|--------|---------|------|
| {/api/resource} | {GET/POST/etc} | {purpose} | {auth type} |
## Security Architecture
### Security Controls
| Control | Implementation | Requirement |
|---------|---------------|-------------|
| Authentication | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
| Authorization | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
| Data Protection | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
## Infrastructure & Deployment
### Deployment Architecture
{description of deployment model: containers, serverless, VMs, etc.}
### Environment Strategy
| Environment | Purpose | Configuration |
|-------------|---------|---------------|
| Development | Local development | {config} |
| Staging | Pre-production testing | {config} |
| Production | Live system | {config} |
## Codebase Integration
{if has_codebase is true:}
### Existing Code Mapping
| New Component | Existing Module | Integration Type | Notes |
|--------------|----------------|------------------|-------|
| {component} | {existing module path} | Extend/Replace/New | {notes} |
### Migration Notes
{any migration considerations for existing code}
## Quality Attributes
| Attribute | Target | Measurement | ADR Reference |
|-----------|--------|-------------|---------------|
| Performance | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
| Scalability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
| Reliability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
## Risks & Mitigations
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| {risk} | High/Medium/Low | High/Medium/Low | {mitigation approach} |
## Open Questions
- [ ] {architectural question 1}
- [ ] {architectural question 2}
## References
- Derived from: [Requirements](../requirements/_index.md), [Product Brief](../product-brief.md)
- Next: [Epics & Stories](../epics/_index.md)
```
---
## Template: ADR-NNN-{slug}.md (Individual Architecture Decision Record)
```markdown
---
id: ADR-{NNN}
status: Accepted
traces_to: [{REQ-NNN}, {NFR-X-NNN}]
date: {timestamp}
---
# ADR-{NNN}: {decision_title}
## Context
{what is the situation that motivates this decision}
## Decision
{what is the chosen approach}
## Alternatives Considered
| Option | Pros | Cons |
|--------|------|------|
| {option_1 - chosen} | {pros} | {cons} |
| {option_2} | {pros} | {cons} |
| {option_3} | {pros} | {cons} |
## Consequences
- **Positive**: {positive outcomes}
- **Negative**: {tradeoffs accepted}
- **Risks**: {risks to monitor}
## Traces
- **Requirements**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md), [NFR-X-{NNN}](../requirements/NFR-X-{NNN}-{slug}.md)
- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)
```
---
## Variable Descriptions
| Variable | Source | Description |
|----------|--------|-------------|
| `{session_id}` | spec-config.json | Session identifier |
| `{timestamp}` | Runtime | ISO8601 generation timestamp |
| `{product_name}` | product-brief.md | Product/feature name |
| `{NNN}` | Auto-increment | ADR/requirement number |
| `{slug}` | Auto-generated | Kebab-case from decision title |
| `{has_codebase}` | spec-config.json | Whether existing codebase exists |

196
.claude/skills/team-lifecycle-v4/templates/epics-template.md Normal file
View File

@@ -0,0 +1,196 @@
# Epics & Stories Template (Directory Structure)
Template for generating epic/story breakdown as a directory of individual Epic files in Phase 5.
## Usage Context
| Phase | Usage |
|-------|-------|
| Phase 5 (Epics & Stories) | Generate `epics/` directory from requirements decomposition |
| Output Location | `{workDir}/epics/` |
## Output Structure
```
{workDir}/epics/
├── _index.md # Overview table + dependency map + MVP scope + execution order
├── EPIC-001-{slug}.md # Individual Epic with its Stories
├── EPIC-002-{slug}.md
└── ...
```
---
## Template: _index.md
```markdown
---
session_id: {session_id}
phase: 5
document_type: epics-index
status: draft
generated_at: {timestamp}
version: 1
dependencies:
- ../spec-config.json
- ../product-brief.md
- ../requirements/_index.md
- ../architecture/_index.md
---
# Epics & Stories: {product_name}
{executive_summary - overview of epic structure and MVP scope}
## Epic Overview
| Epic ID | Title | Priority | MVP | Stories | Est. Size |
|---------|-------|----------|-----|---------|-----------|
| [EPIC-001](EPIC-001-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} |
| [EPIC-002](EPIC-002-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} |
| [EPIC-003](EPIC-003-{slug}.md) | {title} | Should | No | {n} | {S/M/L/XL} |
## Dependency Map
```mermaid
graph LR
EPIC-001 --> EPIC-002
EPIC-001 --> EPIC-003
EPIC-002 --> EPIC-004
EPIC-003 --> EPIC-005
```
### Dependency Notes
{explanation of why these dependencies exist and suggested execution order}
### Recommended Execution Order
1. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - foundational}
2. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - depends on #1}
3. ...
## MVP Scope
### MVP Epics
{list of epics included in MVP with justification, linking to each}
### MVP Definition of Done
- [ ] {MVP completion criterion 1}
- [ ] {MVP completion criterion 2}
- [ ] {MVP completion criterion 3}
## Traceability Matrix
| Requirement | Epic | Stories | Architecture |
|-------------|------|---------|--------------|
| [REQ-001](../requirements/REQ-001-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-001, STORY-001-002 | [ADR-001](../architecture/ADR-001-{slug}.md) |
| [REQ-002](../requirements/REQ-002-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-003 | Component B |
| [REQ-003](../requirements/REQ-003-{slug}.md) | [EPIC-002](EPIC-002-{slug}.md) | STORY-002-001 | [ADR-002](../architecture/ADR-002-{slug}.md) |
## Estimation Summary
| Size | Meaning | Count |
|------|---------|-------|
| S | Small - well-understood, minimal risk | {n} |
| M | Medium - some complexity, moderate risk | {n} |
| L | Large - significant complexity, should consider splitting | {n} |
| XL | Extra Large - high complexity, must split before implementation | {n} |
## Risks & Considerations
| Risk | Affected Epics | Mitigation |
|------|---------------|------------|
| {risk description} | [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) | {mitigation} |
## Open Questions
- [ ] {question about scope or implementation 1}
- [ ] {question about scope or implementation 2}
## References
- Derived from: [Requirements](../requirements/_index.md), [Architecture](../architecture/_index.md)
- Handoff to: execution workflows (lite-plan, plan, req-plan)
```
---
## Template: EPIC-NNN-{slug}.md (Individual Epic)
```markdown
---
id: EPIC-{NNN}
priority: {Must|Should|Could}
mvp: {true|false}
size: {S|M|L|XL}
requirements: [REQ-{NNN}]
architecture: [ADR-{NNN}]
dependencies: [EPIC-{NNN}]
status: draft
---
# EPIC-{NNN}: {epic_title}
**Priority**: {Must|Should|Could}
**MVP**: {Yes|No}
**Estimated Size**: {S|M|L|XL}
## Description
{detailed epic description}
## Requirements
- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title}
- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title}
## Architecture
- [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md): {title}
- Component: {component_name}
## Dependencies
- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (blocking): {reason}
- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (soft): {reason}
## Stories
### STORY-{EPIC}-001: {story_title}
**User Story**: As a {persona}, I want to {action} so that {benefit}.
**Acceptance Criteria**:
- [ ] {criterion 1}
- [ ] {criterion 2}
- [ ] {criterion 3}
**Size**: {S|M|L|XL}
**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md)
---
### STORY-{EPIC}-002: {story_title}
**User Story**: As a {persona}, I want to {action} so that {benefit}.
**Acceptance Criteria**:
- [ ] {criterion 1}
- [ ] {criterion 2}
**Size**: {S|M|L|XL}
**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md)
```
---
## Variable Descriptions
| Variable | Source | Description |
|----------|--------|-------------|
| `{session_id}` | spec-config.json | Session identifier |
| `{timestamp}` | Runtime | ISO8601 generation timestamp |
| `{product_name}` | product-brief.md | Product/feature name |
| `{EPIC}` | Auto-increment | Epic number (3 digits) |
| `{NNN}` | Auto-increment | Story/requirement number |
| `{slug}` | Auto-generated | Kebab-case from epic/story title |
| `{S\|M\|L\|XL}` | CLI analysis | Relative size estimate |

133
.claude/skills/team-lifecycle-v4/templates/product-brief.md Normal file
View File

@@ -0,0 +1,133 @@
# Product Brief Template
Template for generating product brief documents in Phase 2.
## Usage Context
| Phase | Usage |
|-------|-------|
| Phase 2 (Product Brief) | Generate product-brief.md from multi-CLI analysis |
| Output Location | `{workDir}/product-brief.md` |
---
## Template
```markdown
---
session_id: {session_id}
phase: 2
document_type: product-brief
status: draft
generated_at: {timestamp}
stepsCompleted: []
version: 1
dependencies:
- spec-config.json
---
# Product Brief: {product_name}
{executive_summary - 2-3 sentences capturing the essence of the product/feature}
## Vision
{vision_statement - clear, aspirational 1-3 sentence statement of what success looks like}
## Problem Statement
### Current Situation
{description of the current state and pain points}
### Impact
{quantified impact of the problem - who is affected, how much, how often}
## Target Users
{for each user persona:}
### {Persona Name}
- **Role**: {user's role/context}
- **Needs**: {primary needs related to this product}
- **Pain Points**: {current frustrations}
- **Success Criteria**: {what success looks like for this user}
## Goals & Success Metrics
| Goal ID | Goal | Success Metric | Target |
|---------|------|----------------|--------|
| G-001 | {goal description} | {measurable metric} | {specific target} |
| G-002 | {goal description} | {measurable metric} | {specific target} |
## Scope
### In Scope
- {feature/capability 1}
- {feature/capability 2}
- {feature/capability 3}
### Out of Scope
- {explicitly excluded item 1}
- {explicitly excluded item 2}
### Assumptions
- {key assumption 1}
- {key assumption 2}
## Competitive Landscape
| Aspect | Current State | Proposed Solution | Advantage |
|--------|--------------|-------------------|-----------|
| {aspect} | {how it's done now} | {our approach} | {differentiator} |
## Constraints & Dependencies
### Technical Constraints
- {constraint 1}
- {constraint 2}
### Business Constraints
- {constraint 1}
### Dependencies
- {external dependency 1}
- {external dependency 2}
## Multi-Perspective Synthesis
### Product Perspective
{summary of product/market analysis findings}
### Technical Perspective
{summary of technical feasibility and constraints}
### User Perspective
{summary of user journey and UX considerations}
### Convergent Themes
{themes where all perspectives agree}
### Conflicting Views
{areas where perspectives differ, with notes on resolution approach}
## Open Questions
- [ ] {unresolved question 1}
- [ ] {unresolved question 2}
## References
- Derived from: [spec-config.json](spec-config.json)
- Next: [Requirements PRD](requirements.md)
```
## Variable Descriptions
| Variable | Source | Description |
|----------|--------|-------------|
| `{session_id}` | spec-config.json | Session identifier |
| `{timestamp}` | Runtime | ISO8601 generation timestamp |
| `{product_name}` | Seed analysis | Product/feature name |
| `{executive_summary}` | CLI synthesis | 2-3 sentence summary |
| `{vision_statement}` | CLI product perspective | Aspirational vision |
| All `{...}` fields | CLI analysis outputs | Filled from multi-perspective analysis |

224
.claude/skills/team-lifecycle-v4/templates/requirements-prd.md Normal file
View File

@@ -0,0 +1,224 @@
# Requirements PRD Template (Directory Structure)
Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3.
## Usage Context
| Phase | Usage |
|-------|-------|
| Phase 3 (Requirements) | Generate `requirements/` directory from product brief expansion |
| Output Location | `{workDir}/requirements/` |
## Output Structure
```
{workDir}/requirements/
├── _index.md # Summary + MoSCoW table + traceability matrix + links
├── REQ-001-{slug}.md # Individual functional requirement
├── REQ-002-{slug}.md
├── NFR-P-001-{slug}.md # Non-functional: Performance
├── NFR-S-001-{slug}.md # Non-functional: Security
├── NFR-SC-001-{slug}.md # Non-functional: Scalability
├── NFR-U-001-{slug}.md # Non-functional: Usability
└── ...
```
---
## Template: _index.md
```markdown
---
session_id: {session_id}
phase: 3
document_type: requirements-index
status: draft
generated_at: {timestamp}
version: 1
dependencies:
- ../spec-config.json
- ../product-brief.md
---
# Requirements: {product_name}
{executive_summary - brief overview of what this PRD covers and key decisions}
## Requirement Summary
| Priority | Count | Coverage |
|----------|-------|----------|
| Must Have | {n} | {description of must-have scope} |
| Should Have | {n} | {description of should-have scope} |
| Could Have | {n} | {description of could-have scope} |
| Won't Have | {n} | {description of explicitly excluded} |
## Functional Requirements
| ID | Title | Priority | Traces To |
|----|-------|----------|-----------|
| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) |
## Non-Functional Requirements
### Performance
| ID | Title | Target |
|----|-------|--------|
| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} |
### Security
| ID | Title | Standard |
|----|-------|----------|
| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} |
### Scalability
| ID | Title | Target |
|----|-------|--------|
| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} |
### Usability
| ID | Title | Target |
|----|-------|--------|
| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} |
## Data Requirements
### Data Entities
| Entity | Description | Key Attributes |
|--------|-------------|----------------|
| {entity_name} | {description} | {attr1, attr2, attr3} |
### Data Flows
{description of key data flows, optionally with Mermaid diagram}
## Integration Requirements
| System | Direction | Protocol | Data Format | Notes |
|--------|-----------|----------|-------------|-------|
| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} |
## Constraints & Assumptions
### Constraints
- {technical or business constraint 1}
- {technical or business constraint 2}
### Assumptions
- {assumption 1 - must be validated}
- {assumption 2 - must be validated}
## Priority Rationale
{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries}
## Traceability Matrix
| Goal | Requirements |
|------|-------------|
| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) |
| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) |
## Open Questions
- [ ] {unresolved question 1}
- [ ] {unresolved question 2}
## References
- Derived from: [Product Brief](../product-brief.md)
- Next: [Architecture](../architecture/_index.md)
```
---
## Template: REQ-NNN-{slug}.md (Individual Functional Requirement)
```markdown
---
id: REQ-{NNN}
type: functional
priority: {Must|Should|Could|Won't}
traces_to: [G-{NNN}]
status: draft
---
# REQ-{NNN}: {requirement_title}
**Priority**: {Must|Should|Could|Won't}
## Description
{detailed requirement description}
## User Story
As a {persona}, I want to {action} so that {benefit}.
## Acceptance Criteria
- [ ] {specific, testable criterion 1}
- [ ] {specific, testable criterion 2}
- [ ] {specific, testable criterion 3}
## Traces
- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)
```
---
## Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement)
```markdown
---
id: NFR-{type}-{NNN}
type: non-functional
category: {Performance|Security|Scalability|Usability}
priority: {Must|Should|Could}
status: draft
---
# NFR-{type}-{NNN}: {requirement_title}
**Category**: {Performance|Security|Scalability|Usability}
**Priority**: {Must|Should|Could}
## Requirement
{detailed requirement description}
## Metric & Target
| Metric | Target | Measurement Method |
|--------|--------|--------------------|
| {metric} | {target value} | {how measured} |
## Traces
- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
```
---
## Variable Descriptions
| Variable | Source | Description |
|----------|--------|-------------|
| `{session_id}` | spec-config.json | Session identifier |
| `{timestamp}` | Runtime | ISO8601 generation timestamp |
| `{product_name}` | product-brief.md | Product/feature name |
| `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) |
| `{slug}` | Auto-generated | Kebab-case from requirement title |
| `{type}` | Category | P (Performance), S (Security), SC (Scalability), U (Usability) |
| `{Must\|Should\|Could\|Won't}` | User input / auto | MoSCoW priority tag |

2
.claude/skills/workflow-lite-plan/phases/01-lite-plan.md
View File

@@ -255,6 +255,8 @@ cli-explore-agent autonomously handles: project structure discovery, schema load
- [ ] Constraints are project-specific to ${angle}
- [ ] JSON output follows schema exactly
- [ ] clarification_needs includes options + recommended
- [ ] Files with relevance >= 0.7 have key_code array describing key symbols
- [ ] Files with relevance >= 0.7 have topic_relation explaining connection to ${angle}
## Execution
**Write**: \`${sessionFolder}/exploration-${angle}.json\`

105
.temp-memory-content.txt Normal file
View File

@@ -0,0 +1,105 @@
## Session ID
(none)
## Project Root
D:\Claude_dms3
## Objective
为 CCW spec 系统添加独立的 category 分类字段，实现 workflow stage 标记与 keywords 的分离，支持按阶段过滤加载 spec 文档。
## Execution Plan
### Source: inferred
<details>
<summary>Full Execution Plan (Click to expand)</summary>
1. 分析当前 spec 系统实现
2. 设计 category 分类方案 (general | exploration | planning | execution)
3. 后端实现：
- spec-index-builder.ts: 添加 category 字段到 SpecIndexEntry
- spec-init.ts: 更新 seed documents 使用 category
- spec-loader.ts: 支持 category 过滤
- commands/spec.ts: 添加 --category 选项
- cli.ts: 注册 --category 选项
4. 前端实现：
- api.ts: 添加 category 类型
- SpecCard.tsx: 显示 category badge
- SpecsSettingsPage.tsx: 添加 category 过滤 UI
5. 测试所有 ccw spec 命令
</details>
## Working Files (Modified)
- D:\Claude_dms3\ccw\src\tools\spec-index-builder.ts (role: core types + parsing)
- D:\Claude_dms3\ccw\src\tools\spec-init.ts (role: seed documents)
- D:\Claude_dms3\ccw\src\tools\spec-loader.ts (role: loading + filtering)
- D:\Claude_dms3\ccw\src\commands\spec.ts (role: CLI command handler)
- D:\Claude_dms3\ccw\src\cli.ts (role: CLI registration)
- D:\Claude_dms3\ccw\frontend\src\lib\api.ts (role: frontend types)
- D:\Claude_dms3\ccw\frontend\src\components\specs\SpecCard.tsx (role: UI display)
- D:\Claude_dms3\ccw\frontend\src\components\specs\index.ts (role: exports)
- D:\Claude_dms3\ccw\frontend\src\pages\SpecsSettingsPage.tsx (role: filtering UI)
## Reference Files (Read-Only)
- D:\Claude_dms3\ccw\src\core\routes\spec-routes.ts (role: API routes)
- D:\Claude_dms3\ccw\frontend\src\hooks\useSystemSettings.ts (role: hooks)
## Last Action
成功测试所有 ccw spec 命令：
- ccw spec help ✅
- ccw spec init ✅
- ccw spec rebuild ✅
- ccw spec list ✅
- ccw spec status ✅
- ccw spec load --category general ✅ (仅加载 general 分类)
- ccw spec load --category planning ✅ (仅加载 planning 分类)
发现并修复 CLI 启动问题：cli.ts 中 run() 函数未被调用，已添加 run(process.argv) 调用。
## Decisions
- 添加 category 为独立字段而非混入 keywords: 清晰的职责分离，keywords 用于主题匹配，category 用于 workflow stage 过滤
- 使用 general 作为默认值: 适用于所有阶段的通用规范
- 前端显示 category badge: 提供可视化分类指示
- SpecIndexEntry 增加 contentLength 字段: 由用户系统优化添加，避免重复读取文件
## Constraints
- 保持向后兼容：category 为可选字段，默认 general
- 不修改现有 spec 文档的 keywords 语义
## Dependencies
(none)
## Known Issues
- 前端构建存在预存 TypeScript 错误（IssuePanel.tsx, IssueManagerPage.tsx），与本功能无关
- esbuild 打包需要正确配置 --packages=external 以避免动态 require 问题
## Changes Made
- spec-index-builder.ts: 添加 SpecCategory 类型、VALID_CATEGORIES、isValidCategory()、buildEntry() 解析 category
- spec-init.ts: SpecFrontmatter 添加 category，SEED_DOCS 使用独立 category 字段
- spec-loader.ts: SpecLoadOptions 添加 category，filterSpecs() 支持 category 过滤
- spec.ts: SpecOptions 添加 category，loadAction() 传递 category 到 loadSpecs
- cli.ts: 添加 --category 选项，修复 run() 未调用问题
- api.ts: SpecEntry 添加 category 类型
- SpecCard.tsx: 添加 SpecCategory 类型、categoryConfig 配置、显示 category badge
- SpecsSettingsPage.tsx: 添加 CategoryFilter 状态、categoryCounts 计算、category 过滤按钮
## Pending
(none - 功能实现完成并测试通过)
## Notes
**Category 设计思路**：
- general: 适用于所有阶段（如编码规范）
- exploration: 代码探索、分析、调试
- planning: 任务规划、需求分析
- execution: 实现、测试、部署
系统级加载示例：ccw spec load --category exploration
**索引验证**：
{
"title": "Architecture Constraints",
"category": "planning",
"keywords": ["architecture", "module", "layer", "pattern"]
}
keywords 不再包含 exploration/planning/execution 标记。

BIN
assets/wechat-group-qr.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 166 KiB

BIN
assets/wechat-group-qr.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 226 KiB

7
ccw/frontend/src/components/mcp/CcwToolsMcpCard.tsx
View File

@@ -324,9 +324,16 @@ export function CcwToolsMcpCard({
{/* Tool Checkboxes */}
<div className="space-y-2">
<div className="flex items-center justify-between">
<p className="text-xs font-medium text-muted-foreground uppercase">
{formatMessage({ id: 'mcp.ccw.tools.label' })}
</p>
{!isInstalled && (
<p className="text-xs text-amber-600 dark:text-amber-500">
{formatMessage({ id: 'mcp.ccw.tools.hint' })}
</p>
)}
</div>
<div className="grid grid-cols-2 gap-2">
{CCW_MCP_TOOLS.map((tool) => {
const isEnabled = enabledTools.includes(tool.name);

11
ccw/frontend/src/components/specs/GlobalSettingsTab.tsx
View File

@@ -181,9 +181,10 @@ export function GlobalSettingsTab() {
updateMutation.mutate({ personalSpecDefaults: newDefaults });
};
// Calculate totals
// Calculate totals - Only include specs and personal dimensions
const dimensions = stats?.dimensions || {};
const dimensionEntries = Object.entries(dimensions) as [
const dimensionEntries = Object.entries(dimensions)
.filter(([dim]) => dim === 'specs' || dim === 'personal') as [
keyof typeof dimensions,
SpecDimensionStats
][];
@@ -304,8 +305,10 @@ export function GlobalSettingsTab() {
</div>
) : (
<>
<div className="grid grid-cols-2 md:grid-cols-4 gap-4">
{dimensionEntries.map(([dim, data]) => (
<div className="grid grid-cols-2 gap-4">
{dimensionEntries
.filter(([entry]) => entry[0] === 'specs' || entry[1] === 'personal')
.map(([dim, data]) => (
<div
key={dim}
className="text-center p-4 rounded-lg bg-muted/50 hover:bg-muted transition-colors"

83
ccw/frontend/src/components/specs/InjectionControlTab.tsx
View File

@@ -43,6 +43,8 @@ import {
Folder,
ChevronDown,
ChevronRight,
Layers,
Filter,
} from 'lucide-react';
import { useInstallRecommendedHooks } from '@/hooks/useSystemSettings';
import type { InjectionPreviewFile, InjectionPreviewResponse } from '@/lib/api';
@@ -83,6 +85,19 @@ export interface InjectionControlTabProps {
className?: string;
}
// ========== Category Configuration ==========
type SpecCategory = 'general' | 'exploration' | 'planning' | 'execution';
const SPEC_CATEGORIES: SpecCategory[] = ['general', 'exploration', 'planning', 'execution'];
const CATEGORY_CONFIG: Record<SpecCategory, { color: string; bgColor: string }> = {
general: { color: 'text-gray-600', bgColor: 'bg-gray-100 dark:bg-gray-800' },
exploration: { color: 'text-blue-600', bgColor: 'bg-blue-100 dark:bg-blue-900/30' },
planning: { color: 'text-purple-600', bgColor: 'bg-purple-100 dark:bg-purple-900/30' },
execution: { color: 'text-green-600', bgColor: 'bg-green-100 dark:bg-green-900/30' },
};
// ========== Recommended Hooks Configuration ==========
const RECOMMENDED_HOOKS = [
@@ -184,6 +199,7 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) {
// State for injection preview
const [previewMode, setPreviewMode] = useState<'required' | 'all'>('required');
const [categoryFilter, setCategoryFilter] = useState<SpecCategory | 'all'>('all');
const [previewData, setPreviewData] = useState<InjectionPreviewResponse | null>(null);
const [previewLoading, setPreviewLoading] = useState(false);
const [expandedDimensions, setExpandedDimensions] = useState<Record<string, boolean>>({
@@ -358,17 +374,36 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) {
}
}, [installedHookIds, installHooksMutation, formatMessage]);
// Group files by dimension
// Group files by dimension and filter by category
const filesByDimension = useMemo(() => {
if (!previewData) return {};
const grouped: Record<string, InjectionPreviewFile[]> = {};
for (const file of previewData.files) {
// Apply category filter
if (categoryFilter !== 'all' && file.category !== categoryFilter) {
continue;
}
if (!grouped[file.dimension]) {
grouped[file.dimension] = [];
}
grouped[file.dimension].push(file);
}
return grouped;
}, [previewData, categoryFilter]);
// Calculate category statistics
const categoryStats = useMemo(() => {
if (!previewData) {
return { general: 0, exploration: 0, planning: 0, execution: 0 };
}
const stats: Record<SpecCategory, number> = { general: 0, exploration: 0, planning: 0, execution: 0 };
for (const file of previewData.files) {
const cat = (file.category as SpecCategory) || 'general';
if (stats[cat] !== undefined) {
stats[cat]++;
}
}
return stats;
}, [previewData]);
// Calculate progress and status
@@ -641,7 +676,37 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) {
)}
</CardDescription>
</CardHeader>
<CardContent>
<CardContent className="space-y-4">
{/* Category Filter */}
<div className="flex items-center gap-2 flex-wrap">
<Filter className="h-4 w-4 text-muted-foreground" />
<span className="text-sm text-muted-foreground">
{formatMessage({ id: 'specs.filterByCategory', defaultMessage: 'Category:' })}
</span>
<div className="flex gap-2 flex-wrap">
<Button
variant={categoryFilter === 'all' ? 'default' : 'outline'}
size="sm"
onClick={() => setCategoryFilter('all')}
>
{formatMessage({ id: 'specs.category.all', defaultMessage: 'All' })}
</Button>
{SPEC_CATEGORIES.map(cat => (
<Button
key={cat}
variant={categoryFilter === cat ? 'default' : 'outline'}
size="sm"
onClick={() => setCategoryFilter(cat)}
className="gap-1"
>
<Layers className="h-3 w-3" />
{formatMessage({ id: `specs.category.${cat}`, defaultMessage: cat })} ({categoryStats[cat]})
</Button>
))}
</div>
</div>
{/* Files List */}
{previewLoading ? (
<div className="flex items-center justify-center py-8">
<Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
@@ -669,12 +734,15 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) {
</Badge>
</div>
<span className="text-sm text-muted-foreground">
{formatNumber(files.reduce((sum, f) => sum + f.contentLength, 0))} {formatMessage({ id: 'specs.injection.characters', defaultMessage: 'chars' })}
{formatNumber(files.reduce((sum, f) => sum + f.contentLength, 0))} {formatMessage({ id: 'specs.injection.characters', defaultMessage: 'characters' })}
</span>
</button>
{expandedDimensions[dim] && (
<div className="border-t">
{files.map((file) => (
{files.map((file) => {
const fileCategory = (file.category as SpecCategory) || 'general';
const categoryStyle = CATEGORY_CONFIG[fileCategory] || CATEGORY_CONFIG.general;
return (
<div
key={file.file}
className="flex items-center justify-between p-3 border-b last:border-b-0 hover:bg-muted/30"
@@ -691,6 +759,10 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) {
</div>
</div>
<div className="flex items-center gap-2">
<Badge variant="outline" className={cn('text-xs gap-1', categoryStyle.bgColor, categoryStyle.color)}>
<Layers className="h-3 w-3" />
{formatMessage({ id: `specs.category.${fileCategory}`, defaultMessage: fileCategory })}
</Badge>
<Badge variant="outline" className="text-xs">
{formatMessage({ id: `specs.priority.${file.priority}`, defaultMessage: file.priority })}
</Badge>
@@ -707,7 +779,8 @@ export function InjectionControlTab({ className }: InjectionControlTabProps) {
</Button>
</div>
</div>
))}
);
})}
</div>
)}
</div>

11
ccw/frontend/src/components/terminal-dashboard/IssuePanel.tsx
View File

@@ -73,11 +73,14 @@ function PriorityBadge({ priority }: { priority: Issue['priority'] }) {
function StatusDot({ status }: { status: Issue['status'] }) {
const colorMap: Record<Issue['status'], string> = {
open: 'text-info',
in_progress: 'text-warning',
resolved: 'text-success',
closed: 'text-muted-foreground',
registered: 'text-info',
planning: 'text-blue-500',
planned: 'text-blue-600',
queued: 'text-yellow-500',
executing: 'text-warning',
completed: 'text-success',
failed: 'text-destructive',
paused: 'text-muted-foreground',
};
return <CircleDot className={cn('w-3 h-3 shrink-0', colorMap[status] ?? 'text-muted-foreground')} />;
}

1
ccw/frontend/src/locales/en/mcp-manager.json
View File

@@ -112,6 +112,7 @@
},
"tools": {
"label": "Available Tools",
"hint": "Install CCW MCP first to select tools",
"core": "Core",
"write_file": {
"name": "write_file",

1
ccw/frontend/src/locales/zh/mcp-manager.json
View File

@@ -112,6 +112,7 @@
},
"tools": {
"label": "可用工具",
"hint": "请先安装 CCW MCP 后再选择工具",
"core": "核心",
"write_file": {
"name": "write_file",

60
ccw/frontend/src/pages/IssueManagerPage.tsx
View File

@@ -138,7 +138,7 @@ function EditIssueDialog({ open, onOpenChange, issue, onSubmit, isUpdating }: Ed
const [title, setTitle] = useState('');
const [context, setContext] = useState('');
const [priority, setPriority] = useState<Issue['priority']>('medium');
const [status, setStatus] = useState<Issue['status']>('open');
const [status, setStatus] = useState<Issue['status']>('registered');
// Reset form when dialog opens or issue changes
useEffect(() => {
@@ -146,12 +146,12 @@ function EditIssueDialog({ open, onOpenChange, issue, onSubmit, isUpdating }: Ed
setTitle(issue.title ?? '');
setContext(issue.context ?? '');
setPriority(issue.priority ?? 'medium');
setStatus(issue.status ?? 'open');
setStatus(issue.status ?? 'registered');
} else if (!open) {
setTitle('');
setContext('');
setPriority('medium');
setStatus('open');
setStatus('registered');
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [open, issue?.id]);
@@ -217,10 +217,11 @@ function EditIssueDialog({ open, onOpenChange, issue, onSubmit, isUpdating }: Ed
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="open">{formatMessage({ id: 'issues.status.open' })}</SelectItem>
<SelectItem value="in_progress">{formatMessage({ id: 'issues.status.inProgress' })}</SelectItem>
<SelectItem value="resolved">{formatMessage({ id: 'issues.status.resolved' })}</SelectItem>
<SelectItem value="closed">{formatMessage({ id: 'issues.status.closed' })}</SelectItem>
<SelectItem value="registered">{formatMessage({ id: 'issues.status.registered', defaultMessage: 'Registered' })}</SelectItem>
<SelectItem value="planning">{formatMessage({ id: 'issues.status.planning', defaultMessage: 'Planning' })}</SelectItem>
<SelectItem value="planned">{formatMessage({ id: 'issues.status.planned', defaultMessage: 'Planned' })}</SelectItem>
<SelectItem value="queued">{formatMessage({ id: 'issues.status.queued', defaultMessage: 'Queued' })}</SelectItem>
<SelectItem value="executing">{formatMessage({ id: 'issues.status.executing', defaultMessage: 'Executing' })}</SelectItem>
<SelectItem value="completed">{formatMessage({ id: 'issues.status.completed' })}</SelectItem>
</SelectContent>
</Select>
@@ -341,11 +342,14 @@ export function IssueManagerPage() {
// Filter counts
const statusCounts = useMemo(() => ({
all: issues.length,
open: issuesByStatus.open?.length || 0,
in_progress: issuesByStatus.in_progress?.length || 0,
resolved: issuesByStatus.resolved?.length || 0,
closed: issuesByStatus.closed?.length || 0,
registered: issuesByStatus.registered?.length || 0,
planning: issuesByStatus.planning?.length || 0,
planned: issuesByStatus.planned?.length || 0,
queued: issuesByStatus.queued?.length || 0,
executing: issuesByStatus.executing?.length || 0,
completed: issuesByStatus.completed?.length || 0,
failed: issuesByStatus.failed?.length || 0,
paused: issuesByStatus.paused?.length || 0,
}), [issues, issuesByStatus]);
const handleCreateIssue = async (data: { title: string; context?: string; priority?: Issue['priority'] }) => {
@@ -440,9 +444,9 @@ export function IssueManagerPage() {
<Card className="p-4">
<div className="flex items-center gap-2">
<Clock className="w-5 h-5 text-warning" />
<span className="text-2xl font-bold">{issuesByStatus.in_progress?.length || 0}</span>
<span className="text-2xl font-bold">{issuesByStatus.executing?.length || 0}</span>
</div>
<p className="text-sm text-muted-foreground mt-1">{formatMessage({ id: 'issues.status.inProgress' })}</p>
<p className="text-sm text-muted-foreground mt-1">{formatMessage({ id: 'issues.status.executing', defaultMessage: 'Executing' })}</p>
</Card>
<Card className="p-4">
<div className="flex items-center gap-2">
@@ -454,9 +458,9 @@ export function IssueManagerPage() {
<Card className="p-4">
<div className="flex items-center gap-2">
<CheckCircle className="w-5 h-5 text-success" />
<span className="text-2xl font-bold">{issuesByStatus.resolved?.length || 0}</span>
<span className="text-2xl font-bold">{issuesByStatus.completed?.length || 0}</span>
</div>
<p className="text-sm text-muted-foreground mt-1">{formatMessage({ id: 'issues.status.resolved' })}</p>
<p className="text-sm text-muted-foreground mt-1">{formatMessage({ id: 'issues.status.completed' })}</p>
</Card>
</div>
@@ -478,10 +482,12 @@ export function IssueManagerPage() {
</SelectTrigger>
<SelectContent>
<SelectItem value="all">{formatMessage({ id: 'issues.filters.all' })}</SelectItem>
<SelectItem value="open">{formatMessage({ id: 'issues.status.open' })}</SelectItem>
<SelectItem value="in_progress">{formatMessage({ id: 'issues.status.inProgress' })}</SelectItem>
<SelectItem value="resolved">{formatMessage({ id: 'issues.status.resolved' })}</SelectItem>
<SelectItem value="closed">{formatMessage({ id: 'issues.status.closed' })}</SelectItem>
<SelectItem value="registered">{formatMessage({ id: 'issues.status.registered', defaultMessage: 'Registered' })}</SelectItem>
<SelectItem value="planning">{formatMessage({ id: 'issues.status.planning', defaultMessage: 'Planning' })}</SelectItem>
<SelectItem value="planned">{formatMessage({ id: 'issues.status.planned', defaultMessage: 'Planned' })}</SelectItem>
<SelectItem value="queued">{formatMessage({ id: 'issues.status.queued', defaultMessage: 'Queued' })}</SelectItem>
<SelectItem value="executing">{formatMessage({ id: 'issues.status.executing', defaultMessage: 'Executing' })}</SelectItem>
<SelectItem value="completed">{formatMessage({ id: 'issues.status.completed' })}</SelectItem>
</SelectContent>
</Select>
<Select value={priorityFilter} onValueChange={(v) => setPriorityFilter(v as PriorityFilter)}>
@@ -509,20 +515,20 @@ export function IssueManagerPage() {
{formatMessage({ id: 'issues.filters.all' })} ({statusCounts.all})
</Button>
<Button
variant={statusFilter === 'open' ? 'default' : 'outline'}
variant={statusFilter === 'registered' ? 'default' : 'outline'}
size="sm"
onClick={() => setStatusFilter('open')}
onClick={() => setStatusFilter('registered')}
>
<Badge variant="info" className="mr-2">{statusCounts.open}</Badge>
{formatMessage({ id: 'issues.status.open' })}
<Badge variant="info" className="mr-2">{statusCounts.registered}</Badge>
{formatMessage({ id: 'issues.status.registered', defaultMessage: 'Registered' })}
</Button>
<Button
variant={statusFilter === 'in_progress' ? 'default' : 'outline'}
variant={statusFilter === 'executing' ? 'default' : 'outline'}
size="sm"
onClick={() => setStatusFilter('in_progress')}
onClick={() => setStatusFilter('executing')}
>
<Badge variant="warning" className="mr-2">{statusCounts.in_progress}</Badge>
{formatMessage({ id: 'issues.status.inProgress' })}
<Badge variant="warning" className="mr-2">{statusCounts.executing}</Badge>
{formatMessage({ id: 'issues.status.executing', defaultMessage: 'Executing' })}
</Button>
<Button
variant={priorityFilter === 'critical' ? 'destructive' : 'outline'}

8
ccw/frontend/src/pages/SpecsSettingsPage.tsx
View File

@@ -260,10 +260,12 @@ export function SpecsSettingsPage() {
</div>
</div>
{/* Stats Summary */}
{/* Stats Summary - Only show specs and personal dimensions */}
{statsData?.dimensions && (
<div className="grid grid-cols-2 md:grid-cols-4 gap-4">
{Object.entries(statsData.dimensions).map(([dim, data]) => (
<div className="grid grid-cols-2 gap-4">
{Object.entries(statsData.dimensions)
.filter(([dim]) => dim === 'specs' || dim === 'personal')
.map(([dim, data]) => (
<Card key={dim}>
<CardContent className="pt-4">
<div className="text-sm text-muted-foreground">

59
ccw/src/commands/serve.ts
View File

@@ -3,6 +3,10 @@ import { launchBrowser } from '../utils/browser-launcher.js';
import { validatePath } from '../utils/path-resolver.js';
import { startReactFrontend, stopReactFrontend } from '../utils/react-frontend.js';
import chalk from 'chalk';
import { exec } from 'child_process';
import { promisify } from 'util';
const execAsync = promisify(exec);
interface ServeOptions {
port?: number;
@@ -11,6 +15,36 @@ interface ServeOptions {
browser?: boolean;
}
/**
* Check if a port is in use
* @param port - Port number to check
* @returns Promise<boolean> - true if port is in use
*/
async function isPortInUse(port: number): Promise<boolean> {
try {
const { stdout } = await execAsync(`netstat -ano | findstr :${port}`);
const lines = stdout.trim().split(/\r?\n/).filter(Boolean);
for (const line of lines) {
const parts = line.trim().split(/\s+/);
if (parts.length < 4) continue;
const proto = parts[0]?.toUpperCase();
const localAddress = parts[1] || '';
const state = parts[3]?.toUpperCase();
// Check if this is a TCP connection in LISTENING state on our port
if (proto === 'TCP' && localAddress.endsWith(`:${port}`) && state === 'LISTENING') {
return true;
}
}
return false;
} catch {
// If netstat fails or no matches found, assume port is free
return false;
}
}
/**
* Serve command handler - starts dashboard server with live path switching
* @param {Object} options - Command options
@@ -33,13 +67,36 @@ export async function serveCommand(options: ServeOptions): Promise<void> {
initialPath = pathValidation.path;
}
const startupId = Math.random().toString(36).substring(7);
console.log(chalk.blue.bold('\n CCW Dashboard Server\n'));
console.log(chalk.gray(` Startup ID: ${startupId}`));
console.log(chalk.gray(` Initial project: ${initialPath}`));
console.log(chalk.gray(` Host: ${host}`));
console.log(chalk.gray(` Port: ${port}\n`));
// Start React frontend
// Calculate React frontend port
const reactPort = port + 1;
// Check if ports are already in use
const mainPortInUse = await isPortInUse(port);
const reactPortInUse = await isPortInUse(reactPort);
if (mainPortInUse) {
console.error(chalk.red(`\n Error: Port ${port} is already in use.`));
console.error(chalk.yellow(` Another CCW server may be running.`));
console.error(chalk.gray(` Try stopping it first: ccw stop`));
console.error(chalk.gray(` Or use a different port: ccw serve --port ${port + 2}\n`));
process.exit(1);
}
if (reactPortInUse) {
console.error(chalk.red(`\n Error: Port ${reactPort} (React frontend) is already in use.`));
console.error(chalk.yellow(` Another process may be using this port.`));
console.error(chalk.gray(` Try using a different port: ccw serve --port ${port + 2}\n`));
process.exit(1);
}
// Start React frontend
try {
await startReactFrontend(reactPort);
} catch (error) {

9
ccw/src/commands/stop.ts
View File

@@ -32,7 +32,8 @@ async function findProcessOnPort(port: number): Promise<string | null> {
if (proto !== 'TCP') continue;
if (!localAddress.endsWith(`:${port}`)) continue;
if (!/^\d+$/.test(pidCandidate)) continue;
// Reject PID 0 (System Idle Process) and non-numeric PIDs
if (!/^[1-9]\d*$/.test(pidCandidate)) continue;
return pidCandidate; // PID is the last column
}
@@ -43,7 +44,8 @@ async function findProcessOnPort(port: number): Promise<string | null> {
}
async function getProcessCommandLine(pid: string): Promise<string | null> {
if (!/^\d+$/.test(pid)) return null;
// Reject PID 0 (System Idle Process) and non-numeric PIDs
if (!/^[1-9]\d*$/.test(pid)) return null;
try {
const probeCommand =
@@ -78,7 +80,8 @@ function isLikelyViteCommandLine(commandLine: string, port: number): boolean {
* @returns {Promise<boolean>} Success status
*/
async function killProcess(pid: string): Promise<boolean> {
if (!/^\d+$/.test(pid)) return false;
// Reject PID 0 (System Idle Process) and non-numeric PIDs
if (!/^[1-9]\d*$/.test(pid)) return false;
try {
// Prefer taskkill to terminate the entire process tree on Windows (npm/cmd wrappers can orphan children).

140
temp-import-memory.cjs Normal file
View File

@@ -0,0 +1,140 @@
// Using the bundled core-memory command
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');
async function main() {
const memoryText = `## Session ID
(none)
## Project Root
D:\\Claude_dms3
## Objective
为 CCW spec 系统添加独立的 category 分类字段，实现 workflow stage 标记与 keywords 的分离，支持按阶段过滤加载 spec 文档。
## Execution Plan
### Source: inferred
<details>
<summary>Full Execution Plan (Click to expand)</summary>
1. 分析当前 spec 系统实现
2. 设计 category 分类方案 (general | exploration | planning | execution)
3. 后端实现：
- spec-index-builder.ts: 添加 category 字段到 SpecIndexEntry
- spec-init.ts: 更新 seed documents 使用 category
- spec-loader.ts: 支持 category 过滤
- commands/spec.ts: 添加 --category 选项
- cli.ts: 注册 --category 选项
4. 前端实现：
- api.ts: 添加 category 类型
- SpecCard.tsx: 显示 category badge
- SpecsSettingsPage.tsx: 添加 category 过滤 UI
5. 测试所有 ccw spec 命令
</details>
## Working Files (Modified)
- D:\\Claude_dms3\\ccw\\src\\tools\\spec-index-builder.ts (role: core types + parsing)
- D:\\Claude_dms3\\ccw\\src\\tools\\spec-init.ts (role: seed documents)
- D:\\Claude_dms3\\ccw\\src\\tools\\spec-loader.ts (role: loading + filtering)
- D:\\Claude_dms3\\ccw\\src\\commands\\spec.ts (role: CLI command handler)
- D:\\Claude_dms3\\ccw\\src\\cli.ts (role: CLI registration)
- D:\\Claude_dms3\\ccw\\frontend\\src\\lib\\api.ts (role: frontend types)
- D:\\Claude_dms3\\ccw\\frontend\\src\\components\\specs\\SpecCard.tsx (role: UI display)
- D:\\Claude_dms3\\ccw\\frontend\\src\\components\\specs\\index.ts (role: exports)
- D:\\Claude_dms3\\ccw\\frontend\\src\\pages\\SpecsSettingsPage.tsx (role: filtering UI)
## Reference Files (Read-Only)
- D:\\Claude_dms3\\ccw\\src\\core\\routes\\spec-routes.ts (role: API routes)
- D:\\Claude_dms3\\ccw\\frontend\\src\\hooks\\useSystemSettings.ts (role: hooks)
## Last Action
成功测试所有 ccw spec 命令：
- ccw spec help ✅
- ccw spec init ✅
- ccw spec rebuild ✅
- ccw spec list ✅
- ccw spec status ✅
- ccw spec load --category general ✅ (仅加载 general 分类)
- ccw spec load --category planning ✅ (仅加载 planning 分类)
发现并修复 CLI 启动问题：cli.ts 中 run() 函数未被调用，已添加 run(process.argv) 调用。
## Decisions
- 添加 category 为独立字段而非混入 keywords: 清晰的职责分离，keywords 用于主题匹配，category 用于 workflow stage 过滤
- 使用 general 作为默认值: 适用于所有阶段的通用规范
- 前端显示 category badge: 提供可视化分类指示
- SpecIndexEntry 增加 contentLength 字段: 由用户系统优化添加，避免重复读取文件
## Constraints
- 保持向后兼容：category 为可选字段，默认 general
- 不修改现有 spec 文档的 keywords 语义
## Dependencies
(none)
## Known Issues
- 前端构建存在预存 TypeScript 错误（IssuePanel.tsx, IssueManagerPage.tsx），与本功能无关
- esbuild 打包需要正确配置 --packages=external 以避免动态 require 问题
## Changes Made
- spec-index-builder.ts: 添加 SpecCategory 类型、VALID_CATEGORIES、isValidCategory()、buildEntry() 解析 category
- spec-init.ts: SpecFrontmatter 添加 category，SEED_DOCS 使用独立 category 字段
- spec-loader.ts: SpecLoadOptions 添加 category，filterSpecs() 支持 category 过滤
- spec.ts: SpecOptions 添加 category，loadAction() 传递 category 到 loadSpecs
- cli.ts: 添加 --category 选项，修复 run() 未调用问题
- api.ts: SpecEntry 添加 category 类型
- SpecCard.tsx: 添加 SpecCategory 类型、categoryConfig 配置、显示 category badge
- SpecsSettingsPage.tsx: 添加 CategoryFilter 状态、categoryCounts 计算、category 过滤按钮
## Pending
(none - 功能实现完成并测试通过)
## Notes
**Category 设计思路**：
- general: 适用于所有阶段（如编码规范）
- exploration: 代码探索、分析、调试
- planning: 任务规划、需求分析
- execution: 实现、测试、部署
系统级加载示例：ccw spec load --category exploration
**索引验证**：
{
"title": "Architecture Constraints",
"category": "planning",
"keywords": ["architecture", "module", "layer", "pattern"]
}
keywords 不再包含 exploration/planning/execution 标记。`;
// Write memory text to temp file
const tempFile = path.join(__dirname, '.temp-memory-import.txt');
fs.writeFileSync(tempFile, memoryText.trim(), 'utf8');
try {
// Change to project directory and run ccw core-memory import with the text from file
process.chdir('D:\\Claude_dms3');
const textContent = fs.readFileSync(tempFile, 'utf8');
// Escape for command line - use base64 to avoid escaping issues
const base64Content = Buffer.from(textContent).toString('base64');
const result = execSync(`node -e "const s=require('fs');const t=Buffer.from('${base64Content}','base64').toString();const{getCoreMemoryStore}=require('./ccw/dist/commands/core-memory.js');const m=getCoreMemoryStore('.').upsertMemory({content:t});console.log(JSON.stringify({operation:'import',id:m.id,message:'Created memory: '+m.id,recovery_id:m.id}))"`, {
cwd: 'D:\\Claude_dms3',
encoding: 'utf8',
maxBuffer: 50 * 1024 * 1024
});
console.log(result);
} finally {
// Cleanup
if (fs.existsSync(tempFile)) {
fs.unlinkSync(tempFile);
}
}
}
main().catch(err => {
console.error(err.message);
process.exit(1);
});