feat(team-coordinate): align with team-skill-designer and team-lifecycle-v4 standards

Add quality-gates.md and knowledge-transfer.md specs. Update SKILL.md with Shared Constants, Specs Reference, and new user commands. Enhance coordinator role.md with frontmatter, Message Types, Message Bus Protocol, and Toolbox. Add When to Use + Strategy sections to all command files. Update role-spec-template with Identity/Boundaries blocks and validation checklist.
2026-03-10 17:11:04 +08:00 · 2026-03-09 23:20:17 +08:00
parent b2fc2f60f1
commit cbd1813ea7
9 changed files with 395 additions and 40 deletions
--- a/.claude/skills/team-coordinate/SKILL.md
+++ b/.claude/skills/team-coordinate/SKILL.md
@@ -32,6 +32,18 @@ Universal team coordination skill: analyze task -> generate role-specs -> dispat
    ccw cli --mode write     - code generation and modification
 ```

+## Shared Constants
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `TC` |
+| Session path | `.workflow/.team/TC-<slug>-<date>/` |
+| Worker agent | `team-worker` |
+| Message bus | `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)` |
+| CLI analysis | `ccw cli --mode analysis` |
+| CLI write | `ccw cli --mode write` |
+| Max roles | 5 |
+
 ## Role Router

 This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
@@ -85,6 +97,9 @@ User provides task description
 |---------|--------|
 | `check` / `status` | Output execution status graph, no advancement |
 | `resume` / `continue` | Check worker states, advance next step |
+| `revise <TASK-ID> [feedback]` | Revise specific task with optional feedback |
+| `feedback <text>` | Inject feedback into active pipeline |
+| `improve [dimension]` | Auto-improve weakest quality dimension |

 ---

@@ -150,6 +165,17 @@ AskUserQuestion({

 ---

+## Specs Reference
+
+| Spec | Purpose |
+|------|---------|
+| [specs/pipelines.md](specs/pipelines.md) | Dynamic pipeline model, task naming, dependency graph |
+| [specs/role-spec-template.md](specs/role-spec-template.md) | Template for dynamic role-spec generation |
+| [specs/quality-gates.md](specs/quality-gates.md) | Quality thresholds and scoring dimensions |
+| [specs/knowledge-transfer.md](specs/knowledge-transfer.md) | Context transfer protocols between roles |
+
+---
+
 ## Session Directory

 ```
--- a/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md
+++ b/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md
@@ -16,6 +16,20 @@ Parse user task description -> detect required capabilities -> build dependency

 If task context requires codebase knowledge, set `needs_research: true`. Phase 2 will spawn researcher worker.

+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| New task | Coordinator Phase 1 receives task description |
+| Re-analysis | User provides revised requirements |
+| Adapt | handleAdapt extends analysis for new capability |
+
+## Strategy
+
+- **Delegation**: Inline execution (coordinator processes directly)
+- **Mode**: Text-level analysis only (no codebase reading)
+- **Output**: `<session>/task-analysis.json`
+
 ## Phase 2: Context Loading

 | Input | Source | Required |
--- a/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md
+++ b/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md
@@ -4,6 +4,20 @@

 Create task chains from dynamic dependency graphs. Builds pipelines from the task-analysis.json produced by Phase 1. Workers are spawned as team-worker agents with role-spec paths.

+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| After analysis | Phase 1 complete, task-analysis.json exists |
+| After adapt | handleAdapt created new roles, needs new tasks |
+| Re-dispatch | Pipeline restructuring (rare) |
+
+## Strategy
+
+- **Delegation**: Inline execution (coordinator processes directly)
+- **Inputs**: task-analysis.json + team-session.json
+- **Output**: TaskCreate calls with dependency chains
+
 ## Phase 2: Context Loading

 | Input | Source | Required |
--- a/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md
+++ b/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md
@@ -4,6 +4,22 @@

 Event-driven pipeline coordination with Spawn-and-Stop pattern. Role names are read from `team-session.json#roles`. Workers are spawned as `team-worker` agents with role-spec paths. Includes `handleComplete` for pipeline completion action and `handleAdapt` for mid-pipeline capability gap handling.

+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| Worker callback | Message contains [role-name] from session roles |
+| User command | "check", "status", "resume", "continue" |
+| Capability gap | Worker reports capability_gap |
+| Pipeline spawn | After dispatch, initial spawn needed |
+| Pipeline complete | All tasks done |
+
+## Strategy
+
+- **Delegation**: Inline execution with handler routing
+- **Beat model**: ONE_STEP_PER_INVOCATION — one handler then STOP
+- **Workers**: Spawned as team-worker via Agent() in background
+
 ## Constants

 | Constant | Value | Description |
--- a/.claude/skills/team-coordinate/roles/coordinator/role.md
+++ b/.claude/skills/team-coordinate/roles/coordinator/role.md
@@ -1,3 +1,7 @@
+---
+role: coordinator
+---
+
 # Coordinator Role

 Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec generation, task dispatching, progress monitoring, session state, and completion action. The sole built-in role -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent.
@@ -33,6 +37,30 @@ Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec gener

 ---

+## Message Types
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| state_update | outbound | Session init, pipeline progress |
+| task_unblocked | outbound | Task ready for execution |
+| fast_advance | inbound | Worker skipped coordinator |
+| capability_gap | inbound | Worker needs new capability |
+| error | inbound | Worker failure |
+| impl_complete | inbound | Worker task done |
+| consensus_blocked | inbound | Discussion verdict conflict |
+
+## Message Bus Protocol
+
+All coordinator state changes MUST be logged to team_msg BEFORE SendMessage:
+
+1. `team_msg(operation="log", ...)` — log the event
+2. `SendMessage(...)` — communicate to worker/user
+3. `TaskUpdate(...)` — update task state
+
+Read state before every handler: `team_msg(operation="get_state", session_id=<session-id>)`
+
+---
+
 ## Command Execution Protocol

 When coordinator needs to execute a command (analyze-task, dispatch, monitor):
@@ -52,6 +80,20 @@ Phase 1 needs task analysis
  -> Continue to Phase 2
 ```

+## Toolbox
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| commands/analyze-task.md | Command | Task analysis and role design |
+| commands/dispatch.md | Command | Task chain creation |
+| commands/monitor.md | Command | Pipeline monitoring and handlers |
+| team-worker | Subagent | Worker spawning |
+| TeamCreate / TeamDelete | System | Team lifecycle |
+| TaskCreate / TaskList / TaskGet / TaskUpdate | System | Task lifecycle |
+| team_msg | System | Message bus operations |
+| SendMessage | System | Inter-agent communication |
+| AskUserQuestion | System | User interaction |
+
 ---

 ## Entry Router
--- a/.claude/skills/team-coordinate/specs/knowledge-transfer.md
+++ b/.claude/skills/team-coordinate/specs/knowledge-transfer.md
@@ -0,0 +1,111 @@
+# Knowledge Transfer Protocols
+
+## 1. Transfer Channels
+
+| Channel | Scope | Mechanism | When to Use |
+|---------|-------|-----------|-------------|
+| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
+| **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
+| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
+| **Context Accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
+| **Exploration Cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
+
+## 2. Context Loading Protocol (Phase 2)
+
+Every role MUST load context in this order before starting work.
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Extract session path from task description | Yes |
+| 2 | `team_msg(operation="get_state", session_id=<session-id>)` | Yes |
+| 3 | Read artifact files from upstream state's `ref` paths | Yes |
+| 4 | Read `<session>/wisdom/*.md` if exists | Yes |
+| 5 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
+| 6 | For inner_loop roles: load context_accumulator from prior tasks | If inner_loop |
+
+**Loading rules**:
+- Never skip step 2 -- state contains key decisions and findings
+- If `ref` path in state does not exist, log warning and continue
+- Wisdom files are append-only -- read all entries, newest last
+
+## 3. Context Publishing Protocol (Phase 4)
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
+| 2 | Send `team_msg(type="state_update")` with payload (see schema below) | Yes |
+| 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
+
+## 4. State Update Schema
+
+Sent via `team_msg(type="state_update")` on task completion.
+
+```json
+{
+  "status": "task_complete",
+  "task_id": "<TASK-NNN>",
+  "ref": "<session>/artifacts/<filename>",
+  "key_findings": [
+    "Finding 1",
+    "Finding 2"
+  ],
+  "decisions": [
+    "Decision with rationale"
+  ],
+  "files_modified": [
+    "path/to/file.ts"
+  ],
+  "verification": "self-validated | peer-reviewed | tested"
+}
+```
+
+**Field rules**:
+- `ref`: Always an artifact path, never inline content
+- `key_findings`: Max 5 items, each under 100 chars
+- `decisions`: Include rationale, not just the choice
+- `files_modified`: Only for implementation tasks
+- `verification`: One of `self-validated`, `peer-reviewed`, `tested`
+
+**Write state** (namespaced by role):
+```
+team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={
+  "<role_name>": { "key_findings": [...], "scope": "..." }
+})
+```
+
+**Read state**:
+```
+team_msg(operation="get_state", session_id=<session-id>)
+// Returns merged state from all state_update messages
+```
+
+## 5. Exploration Cache Protocol
+
+Prevents redundant research across tasks and discussion rounds.
+
+| Step | Action |
+|------|--------|
+| 1 | Read `<session>/explorations/cache-index.json` |
+| 2 | If angle already explored, read cached result from `explore-<angle>.json` |
+| 3 | If not cached, perform exploration |
+| 4 | Write result to `<session>/explorations/explore-<angle>.json` |
+| 5 | Update `cache-index.json` with new entry |
+
+**cache-index.json format**:
+```json
+{
+  "entries": [
+    {
+      "angle": "competitor-analysis",
+      "file": "explore-competitor-analysis.json",
+      "created_by": "RESEARCH-001",
+      "timestamp": "2026-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+**Rules**:
+- Cache key is the exploration `angle` (normalized to kebab-case)
+- Cache entries never expire within a session
+- Any role can read cached explorations; only the creator updates them
--- a/.claude/skills/team-coordinate/specs/pipelines.md
+++ b/.claude/skills/team-coordinate/specs/pipelines.md
@@ -81,3 +81,17 @@ message_types:
 ## Specs Reference

 - [role-spec-template.md](role-spec-template.md) — Template for generating dynamic role-specs
+- [quality-gates.md](quality-gates.md) — Quality thresholds and scoring dimensions
+- [knowledge-transfer.md](knowledge-transfer.md) — Context transfer protocols between roles
+
+## Quality Gate Integration
+
+Dynamic pipelines reference quality thresholds from [specs/quality-gates.md](quality-gates.md).
+
+| Gate Point | Trigger | Criteria Source |
+|------------|---------|----------------|
+| After artifact production | Producer role Phase 4 | Behavioral Traits in role-spec |
+| After validation tasks | Tester/analyst completion | quality-gates.md thresholds |
+| Pipeline completion | All tasks done | Aggregate scoring |
+
+Issue classification: Error (blocks) > Warning (proceed with justification) > Info (log for future).
--- a/.claude/skills/team-coordinate/specs/quality-gates.md
+++ b/.claude/skills/team-coordinate/specs/quality-gates.md
@@ -0,0 +1,112 @@
+# Quality Gates
+
+## 1. Quality Thresholds
+
+| Result | Score | Action |
+|--------|-------|--------|
+| Pass | >= 80% | Report completed |
+| Review | 60-79% | Report completed with warnings |
+| Fail | < 60% | Retry Phase 3 (max 2 retries) |
+
+## 2. Scoring Dimensions
+
+| Dimension | Weight | Criteria |
+|-----------|--------|----------|
+| Completeness | 25% | All required outputs present with substantive content |
+| Consistency | 25% | Terminology, formatting, cross-references are uniform |
+| Accuracy | 25% | Outputs are factually correct and verifiable against sources |
+| Depth | 25% | Sufficient detail for downstream consumers to act on deliverables |
+
+**Score** = weighted average of all dimensions (0-100 per dimension).
+
+## 3. Dynamic Role Quality Checks
+
+Quality checks vary by `output_type` (from task-analysis.json role metadata).
+
+### output_type: artifact
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Artifact exists | File written to `<session>/artifacts/` |
+| Content non-empty | Substantive content, not just headers |
+| Format correct | Expected format (MD, JSON) matches deliverable |
+| Cross-references | All references to upstream artifacts resolve |
+
+### output_type: codebase
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Files modified | Claimed files actually changed (Read to confirm) |
+| Syntax valid | No syntax errors in modified files |
+| No regressions | Existing functionality preserved |
+| Summary artifact | Implementation summary written to artifacts/ |
+
+### output_type: mixed
+
+All checks from both `artifact` and `codebase` apply.
+
+## 4. Verification Protocol
+
+Derived from Behavioral Traits in [role-spec-template.md](role-spec-template.md).
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Verify all claimed files exist via Read | Yes |
+| 2 | Confirm artifact written to `<session>/artifacts/` | Yes |
+| 3 | Check verification summary fields present | Yes |
+| 4 | Score against quality dimensions | Yes |
+| 5 | Apply threshold -> Pass/Review/Fail | Yes |
+
+**On Fail**: Retry Phase 3 (max 2 retries). After 2 retries, report `partial_completion`.
+
+**On Review**: Proceed with warnings logged to `<session>/wisdom/issues.md`.
+
+## 5. Code Review Dimensions
+
+For REVIEW-* or validation tasks during implementation pipelines.
+
+### Quality
+
+| Check | Severity |
+|-------|----------|
+| Empty catch blocks | Error |
+| `as any` type casts | Warning |
+| `@ts-ignore` / `@ts-expect-error` | Warning |
+| `console.log` in production code | Warning |
+| Unused imports/variables | Info |
+
+### Security
+
+| Check | Severity |
+|-------|----------|
+| Hardcoded secrets/credentials | Error |
+| SQL injection vectors | Error |
+| `eval()` or `Function()` usage | Error |
+| `innerHTML` assignment | Warning |
+| Missing input validation | Warning |
+
+### Architecture
+
+| Check | Severity |
+|-------|----------|
+| Circular dependencies | Error |
+| Deep cross-boundary imports (3+ levels) | Warning |
+| Files > 500 lines | Warning |
+| Functions > 50 lines | Info |
+
+### Requirements Coverage
+
+| Check | Severity |
+|-------|----------|
+| Core functionality implemented | Error if missing |
+| Acceptance criteria covered | Error if missing |
+| Edge cases handled | Warning |
+| Error states handled | Warning |
+
+## 6. Issue Classification
+
+| Class | Label | Action |
+|-------|-------|--------|
+| Error | Must fix | Blocks progression, must resolve before proceeding |
+| Warning | Should fix | Should resolve, can proceed with justification |
+| Info | Nice to have | Optional improvement, log for future |
--- a/.claude/skills/team-coordinate/specs/role-spec-template.md
+++ b/.claude/skills/team-coordinate/specs/role-spec-template.md
@@ -46,6 +46,7 @@ message_types:
 | `prefix` | Yes | Task prefix to filter (e.g., RESEARCH, DRAFT, IMPL) |
 | `inner_loop` | Yes | Whether team-worker loops through same-prefix tasks |
 | `CLI tools` | No | Array of CLI tool types this role may call |
+| `output_tag` | Yes | Output tag for all messages, e.g., `[researcher]` |
 | `message_types` | Yes | Message type mapping for team_msg |
 | `message_types.success` | Yes | Type string for successful completion |
 | `message_types.error` | Yes | Type string for errors (usually "error") |
@@ -63,6 +64,29 @@ message_types:
 | `<placeholder>` notation | Use angle brackets for variable substitution |
 | Reference CLI tools by name | team-worker resolves invocation from its delegation templates |

+## Generated Role-Spec Structure
+
+Every generated role-spec MUST include these blocks:
+
+### Identity Block (mandatory — first section of generated spec)
+
+```
+Tag: [<role_name>] | Prefix: <PREFIX>-*
+Responsibility: <one-line from task analysis>
+```
+
+### Boundaries Block (mandatory — after Identity)
+
+```
+### MUST
+- <3-5 rules derived from task analysis>
+
+### MUST NOT
+- Execute work outside assigned prefix
+- Modify artifacts from other roles
+- Skip Phase 4 verification
+```
+
 ## Behavioral Traits

 All dynamically generated role-specs MUST embed these traits into Phase 4. Coordinator copies this section verbatim into every generated role-spec as a Phase 4 appendix.
@@ -93,6 +117,11 @@ Phase 4 must produce a verification summary with these fields:
 - Still fails → report `partial_completion` with details, NOT `completed`
 - Update shared state via `team_msg(operation="log", type="state_update", data={...})` after verification passes

+Quality thresholds from [specs/quality-gates.md](quality-gates.md):
+- Pass >= 80%: report completed
+- Review 60-79%: report completed with warnings
+- Fail < 60%: retry Phase 3 (max 2)
+
 ### Error Protocol

 - Primary approach fails → try alternative (different CLI tool / different tool)
@@ -139,48 +168,25 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a

 ## Knowledge Transfer Protocol

-How context flows between roles. Coordinator MUST reference this when composing Phase 2 of any role-spec.
+Full protocol: [specs/knowledge-transfer.md](knowledge-transfer.md)

-### Transfer Channels
+Generated role-specs Phase 2 MUST declare which upstream sources to load.
+Generated role-specs Phase 4 MUST include state update and artifact publishing.

-| Channel | Scope | Mechanism | When to Use |
-|---------|-------|-----------|-------------|
-| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
-| **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
-| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
-| **context_accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
-| **Exploration cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
+---

-### Phase 2 Context Loading (role-spec must specify)
+## Generated Role-Spec Validation

-Every generated role-spec Phase 2 MUST declare which upstream sources to load:
+Coordinator verifies before writing each role-spec:

-```
-1. Extract session path from task description
-2. Read upstream artifacts: <list which artifacts from which upstream role>
-3. Read cross-role state via `team_msg(operation="get_state", session_id=<session-id>)`
-4. Load wisdom files for accumulated knowledge
-5. For inner_loop roles: load context_accumulator from prior tasks
-6. Check exploration cache before running new explorations
-```
-
-### State Update Convention
-
-Cross-role state is managed via `team_msg` state updates instead of a separate file:
-
- **Write state**: `team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={ "<role_name>": { ... } })`
- **Read state**: `team_msg(operation="get_state", session_id=<session-id>)`
- **Namespaced keys**: Each role writes under its own namespace key in `data`
- **Small data only**: Key findings, decision summaries, metadata. NOT full documents
- **State stored in**: `.msg/meta.json` (auto-managed by team_msg)
- **Example write**:
-  ```
-  team_msg(operation="log", session_id="TC-auth-2026-03-03", from="researcher", type="state_update", data={
-    "researcher": { "key_findings": [...], "scope": "..." }
-  })
-  ```
- **Example read**:
-  ```
-  team_msg(operation="get_state", session_id="TC-auth-2026-03-03")
-  // Returns merged state from all state_update messages
-  ```
+| Check | Criteria |
+|-------|----------|
+| Frontmatter complete | All required fields present (role, prefix, inner_loop, output_tag, message_types, CLI tools) |
+| Identity block | Tag, prefix, responsibility defined |
+| Boundaries | MUST and MUST NOT rules present |
+| Phase 2 | Context loading sources specified |
+| Phase 3 | Execution goal clear, not prescriptive about tools |
+| Phase 4 | Behavioral Traits copied verbatim |
+| Error Handling | Table with 3+ scenarios |
+| Line count | Target ~80 lines (max 120) |
+| No built-in overlap | No Phase 1/5, no message bus code, no consensus handling |