From cbd1813ea79c65f6ee27ade4499fc5cb702fc5dd Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 9 Mar 2026 23:20:17 +0800 Subject: [PATCH] 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. --- .claude/skills/team-coordinate/SKILL.md | 26 ++++ .../coordinator/commands/analyze-task.md | 14 +++ .../roles/coordinator/commands/dispatch.md | 14 +++ .../roles/coordinator/commands/monitor.md | 16 +++ .../team-coordinate/roles/coordinator/role.md | 42 +++++++ .../specs/knowledge-transfer.md | 111 +++++++++++++++++ .../skills/team-coordinate/specs/pipelines.md | 14 +++ .../team-coordinate/specs/quality-gates.md | 112 ++++++++++++++++++ .../specs/role-spec-template.md | 86 +++++++------- 9 files changed, 395 insertions(+), 40 deletions(-) create mode 100644 .claude/skills/team-coordinate/specs/knowledge-transfer.md create mode 100644 .claude/skills/team-coordinate/specs/quality-gates.md diff --git a/.claude/skills/team-coordinate/SKILL.md b/.claude/skills/team-coordinate/SKILL.md index fbfd9b1e..b03e5085 100644 --- 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--/` | +| Worker agent | `team-worker` | +| Message bus | `mcp__ccw-tools__team_msg(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 [feedback]` | Revise specific task with optional feedback | +| `feedback ` | 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 ``` diff --git a/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md b/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md index 2b76fc6f..78b12d47 100644 --- 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**: `/task-analysis.json` + ## Phase 2: Context Loading | Input | Source | Required | diff --git a/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md b/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md index 03829307..8d384fa2 100644 --- 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 | diff --git a/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md b/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md index 7df6b2d9..8ebbb534 100644 --- 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 | diff --git a/.claude/skills/team-coordinate/roles/coordinator/role.md b/.claude/skills/team-coordinate/roles/coordinator/role.md index be246302..2fcb1fdb 100644 --- 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=)` + +--- + ## 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 diff --git a/.claude/skills/team-coordinate/specs/knowledge-transfer.md b/.claude/skills/team-coordinate/specs/knowledge-transfer.md new file mode 100644 index 00000000..105c0bab --- /dev/null +++ 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 `/artifacts/.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=)` | Key findings, decisions, metadata (small, structured data) | +| **Wisdom** | Cross-task | Append to `/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 | `/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=)` | Yes | +| 3 | Read artifact files from upstream state's `ref` paths | Yes | +| 4 | Read `/wisdom/*.md` if exists | Yes | +| 5 | Check `/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 `/artifacts/-.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": "", + "ref": "/artifacts/", + "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=, from=, type="state_update", data={ + "": { "key_findings": [...], "scope": "..." } +}) +``` + +**Read state**: +``` +team_msg(operation="get_state", 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 `/explorations/cache-index.json` | +| 2 | If angle already explored, read cached result from `explore-.json` | +| 3 | If not cached, perform exploration | +| 4 | Write result to `/explorations/explore-.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 diff --git a/.claude/skills/team-coordinate/specs/pipelines.md b/.claude/skills/team-coordinate/specs/pipelines.md index 2b91cd49..5a75bfc7 100644 --- 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). diff --git a/.claude/skills/team-coordinate/specs/quality-gates.md b/.claude/skills/team-coordinate/specs/quality-gates.md new file mode 100644 index 00000000..e59e4520 --- /dev/null +++ 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 `/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 `/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 `/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 | diff --git a/.claude/skills/team-coordinate/specs/role-spec-template.md b/.claude/skills/team-coordinate/specs/role-spec-template.md index ff271f9d..8aad3b11 100644 --- 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: | `` 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: [] | Prefix: -* +Responsibility: +``` + +### 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 `/artifacts/.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=)` | Key findings, decisions, metadata (small, structured data) | -| **Wisdom** | Cross-task | Append to `/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 | `/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: -3. Read cross-role state via `team_msg(operation="get_state", 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=, from=, type="state_update", data={ "": { ... } })` -- **Read state**: `team_msg(operation="get_state", 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 |