mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: add Discuss and Explore subagents for dynamic critique and code exploration
- Implement Discuss Subagent for multi-perspective critique with dynamic perspectives. - Create Explore Subagent for shared codebase exploration with centralized caching. - Add tests for CcwToolsMcpCard component to ensure enabled tools are preserved on config save. - Introduce SessionPreviewPanel component for previewing and selecting sessions for Memory V2 extraction. - Develop CommandCreateDialog component for creating/importing commands with import and CLI generate modes.
This commit is contained in:
catlog22
432
.claude/skills/team-coordinate/specs/role-template.md
Normal file
432
.claude/skills/team-coordinate/specs/role-template.md
Normal file
@@ -0,0 +1,432 @@
|
||||
# Dynamic Role Template
|
||||
|
||||
Template used by coordinator to generate worker role.md files at runtime. Each generated role is written to `<session>/roles/<role-name>.md`.
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Role: <role_name>
|
||||
|
||||
<role_description>
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `<role_name>` | **Tag**: `[<role_name>]`
|
||||
- **Task Prefix**: `<prefix>-*`
|
||||
- **Responsibility**: <responsibility_type>
|
||||
<if inner_loop>
|
||||
- **Mode**: Inner Loop (handle all `<prefix>-*` tasks in single agent)
|
||||
</if>
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process `<prefix>-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[<role_name>]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within <responsibility_type> responsibility scope
|
||||
- Use fast-advance for simple linear successors (see SKILL.md Phase 5)
|
||||
- Produce MD artifacts in `<session>/artifacts/`
|
||||
<if inner_loop>
|
||||
- Use subagent for heavy work (do not execute CLI/generation in main agent context)
|
||||
- Maintain context_accumulator across tasks within the inner loop
|
||||
- Loop through all `<prefix>-*` tasks before reporting to coordinator
|
||||
</if>
|
||||
|
||||
### MUST NOT
|
||||
- Execute work outside this role's responsibility scope
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Modify files or resources outside this role's scope
|
||||
- Omit `[<role_name>]` identifier in any output
|
||||
- Fast-advance when multiple tasks are ready or at checkpoint boundaries
|
||||
<if inner_loop>
|
||||
- Execute heavy work (CLI calls, large document generation) in main agent (delegate to subagent)
|
||||
- SendMessage to coordinator mid-loop (unless consensus_blocked HIGH or error count >= 3)
|
||||
</if>
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
<tools based on responsibility_type -- see reference sections below>
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Description |
|
||||
|------|-----------|-------------|
|
||||
| `<prefix>_complete` | -> coordinator | Task completed with artifact path |
|
||||
| `<prefix>_error` | -> coordinator | Error encountered |
|
||||
| `capability_gap` | -> coordinator | Work outside role scope discovered |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: <team-name>,
|
||||
from: "<role_name>",
|
||||
to: "coordinator",
|
||||
type: <message-type>,
|
||||
summary: "[<role_name>] <prefix> complete: <task-subject>",
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --team <team-name> --from <role_name> --to coordinator --type <message-type> --summary \"[<role_name>] <prefix> complete\" --ref <artifact-path> --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery
|
||||
|
||||
Standard task discovery flow: TaskList -> filter by prefix `<prefix>-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
### Phase 2: <phase2_name>
|
||||
|
||||
<phase2_content -- generated by coordinator based on responsibility type>
|
||||
|
||||
### Phase 3: <phase3_name>
|
||||
|
||||
<phase3_content -- generated by coordinator based on task specifics>
|
||||
|
||||
### Phase 4: <phase4_name>
|
||||
|
||||
<phase4_content -- generated by coordinator based on responsibility type>
|
||||
|
||||
<if inline_discuss>
|
||||
### Phase 4b: Inline Discuss (optional)
|
||||
|
||||
After primary work, optionally call discuss subagent:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "cli-discuss-agent",
|
||||
run_in_background: false,
|
||||
description: "Discuss <round-id>",
|
||||
prompt: "## Multi-Perspective Critique: <round-id>
|
||||
See subagents/discuss-subagent.md for prompt template.
|
||||
Perspectives: <specified by coordinator when generating this role>"
|
||||
})
|
||||
```
|
||||
|
||||
| Verdict | Severity | Action |
|
||||
|---------|----------|--------|
|
||||
| consensus_reached | - | Include action items in report, proceed to Phase 5 |
|
||||
| consensus_blocked | HIGH | Phase 5 SendMessage includes structured consensus_blocked format. Do NOT self-revise. |
|
||||
| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed normally. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. |
|
||||
</if>
|
||||
|
||||
<if inner_loop>
|
||||
### Phase 5-L: Loop Completion (Inner Loop)
|
||||
|
||||
When more same-prefix tasks remain:
|
||||
|
||||
1. **TaskUpdate**: Mark current task completed
|
||||
2. **team_msg**: Log task completion
|
||||
3. **Accumulate summary**:
|
||||
```
|
||||
context_accumulator.append({
|
||||
task: "<task-id>",
|
||||
artifact: "<output-path>",
|
||||
key_decisions: <from subagent return>,
|
||||
discuss_verdict: <from Phase 4>,
|
||||
summary: <from subagent return>
|
||||
})
|
||||
```
|
||||
4. **Interrupt check**:
|
||||
- consensus_blocked HIGH -> SendMessage -> STOP
|
||||
- Error count >= 3 -> SendMessage -> STOP
|
||||
5. **Loop**: Back to Phase 1
|
||||
|
||||
**Does NOT**: SendMessage to coordinator, Fast-Advance spawn.
|
||||
|
||||
### Phase 5-F: Final Report (Inner Loop)
|
||||
|
||||
When all same-prefix tasks are done:
|
||||
|
||||
1. **TaskUpdate**: Mark last task completed
|
||||
2. **team_msg**: Log completion
|
||||
3. **Summary report**: All tasks summary + discuss results + artifact paths
|
||||
4. **Fast-Advance check**: Check cross-prefix successors
|
||||
5. **SendMessage** or **spawn successor**
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report + Fast-Advance
|
||||
|
||||
<else>
|
||||
### Phase 5: Report + Fast-Advance
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report + Fast-Advance
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[<role_name>]` prefix -> TaskUpdate completed -> Fast-Advance Check -> Loop to Phase 1 for next task.
|
||||
</if>
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No <prefix>-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Context file not found | Notify coordinator, request location |
|
||||
| Subagent fails | Retry once with fallback; still fails -> log error, continue next task |
|
||||
| Fast-advance spawn fails | Fall back to SendMessage to coordinator |
|
||||
<if inner_loop>
|
||||
| Cumulative 3 task failures | SendMessage to coordinator, STOP inner loop |
|
||||
| Agent crash mid-loop | Coordinator detects orphan on resume -> re-spawn -> resume from interrupted task |
|
||||
</if>
|
||||
| Work outside scope discovered | SendMessage capability_gap to coordinator |
|
||||
| Critical issue beyond scope | SendMessage fix_required to coordinator |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2-4 Content by Responsibility Type
|
||||
|
||||
Reference sections for coordinator to fill when generating roles. Select the matching section based on `responsibility_type`.
|
||||
|
||||
### orchestration
|
||||
|
||||
**Phase 2: Context Assessment**
|
||||
|
||||
```
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From TaskGet | Yes |
|
||||
| Shared memory | <session>/shared-memory.json | No |
|
||||
| Prior artifacts | <session>/artifacts/ | No |
|
||||
| Wisdom | <session>/wisdom/ | No |
|
||||
|
||||
Loading steps:
|
||||
1. Extract session path from task description
|
||||
2. Read shared-memory.json for cross-role context
|
||||
3. Read prior artifacts (if any exist from upstream tasks)
|
||||
4. Load wisdom files for accumulated knowledge
|
||||
5. Optionally call explore subagent for codebase context
|
||||
```
|
||||
|
||||
**Phase 3: Subagent Execution**
|
||||
|
||||
```
|
||||
Delegate to appropriate subagent based on task:
|
||||
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
run_in_background: false,
|
||||
description: "<task-type> for <task-id>",
|
||||
prompt: "## Task
|
||||
- <task description>
|
||||
- Session: <session-folder>
|
||||
## Context
|
||||
<prior artifacts + shared memory + explore results>
|
||||
## Expected Output
|
||||
Write artifact to: <session>/artifacts/<artifact-name>.md
|
||||
Return JSON summary: { artifact_path, summary, key_decisions[], warnings[] }"
|
||||
})
|
||||
```
|
||||
|
||||
**Phase 4: Result Aggregation**
|
||||
|
||||
```
|
||||
1. Verify subagent output artifact exists
|
||||
2. Read artifact, validate structure/completeness
|
||||
3. Update shared-memory.json with key findings
|
||||
4. Write insights to wisdom/ files
|
||||
```
|
||||
|
||||
### code-gen (docs)
|
||||
|
||||
**Phase 2: Load Prior Context**
|
||||
|
||||
```
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From TaskGet | Yes |
|
||||
| Prior artifacts | <session>/artifacts/ from upstream tasks | Conditional |
|
||||
| Shared memory | <session>/shared-memory.json | No |
|
||||
| Wisdom | <session>/wisdom/ | No |
|
||||
|
||||
Loading steps:
|
||||
1. Extract session path from task description
|
||||
2. Read upstream artifacts (e.g., research findings for a writer)
|
||||
3. Read shared-memory.json for cross-role context
|
||||
4. Load wisdom for accumulated decisions
|
||||
```
|
||||
|
||||
**Phase 3: Document Generation**
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "universal-executor",
|
||||
run_in_background: false,
|
||||
description: "Generate <doc-type> for <task-id>",
|
||||
prompt: "## Task
|
||||
- Generate: <document type>
|
||||
- Session: <session-folder>
|
||||
## Prior Context
|
||||
<upstream artifacts + shared memory>
|
||||
## Instructions
|
||||
<task-specific writing instructions from coordinator>
|
||||
## Expected Output
|
||||
Write document to: <session>/artifacts/<doc-name>.md
|
||||
Return JSON: { artifact_path, summary, key_decisions[], sections_generated[], warnings[] }"
|
||||
})
|
||||
```
|
||||
|
||||
**Phase 4: Structure Validation**
|
||||
|
||||
```
|
||||
1. Verify document artifact exists
|
||||
2. Check document has expected sections
|
||||
3. Validate no placeholder text remains
|
||||
4. Update shared-memory.json with document metadata
|
||||
```
|
||||
|
||||
### code-gen (code)
|
||||
|
||||
**Phase 2: Load Plan/Specs**
|
||||
|
||||
```
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From TaskGet | Yes |
|
||||
| Plan/design artifacts | <session>/artifacts/ | Conditional |
|
||||
| Shared memory | <session>/shared-memory.json | No |
|
||||
| Wisdom | <session>/wisdom/ | No |
|
||||
|
||||
Loading steps:
|
||||
1. Extract session path from task description
|
||||
2. Read plan/design artifacts from upstream
|
||||
3. Load shared-memory.json for implementation context
|
||||
4. Load wisdom for conventions and patterns
|
||||
```
|
||||
|
||||
**Phase 3: Code Implementation**
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
run_in_background: false,
|
||||
description: "Implement <task-id>",
|
||||
prompt: "## Task
|
||||
- <implementation description>
|
||||
- Session: <session-folder>
|
||||
## Plan/Design Context
|
||||
<upstream artifacts>
|
||||
## Instructions
|
||||
<task-specific implementation instructions>
|
||||
## Expected Output
|
||||
Implement code changes.
|
||||
Write summary to: <session>/artifacts/implementation-summary.md
|
||||
Return JSON: { artifact_path, summary, files_changed[], key_decisions[], warnings[] }"
|
||||
})
|
||||
```
|
||||
|
||||
**Phase 4: Syntax Validation**
|
||||
|
||||
```
|
||||
1. Run syntax check (tsc --noEmit or equivalent)
|
||||
2. Verify all planned files exist
|
||||
3. Check no broken imports
|
||||
4. If validation fails -> attempt auto-fix (max 2 attempts)
|
||||
5. Write implementation summary to artifacts/
|
||||
```
|
||||
|
||||
### read-only
|
||||
|
||||
**Phase 2: Target Loading**
|
||||
|
||||
```
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From TaskGet | Yes |
|
||||
| Target artifacts/files | From task description or upstream | Yes |
|
||||
| Shared memory | <session>/shared-memory.json | No |
|
||||
|
||||
Loading steps:
|
||||
1. Extract session path and target files from task description
|
||||
2. Read target artifacts or source files for analysis
|
||||
3. Load shared-memory.json for context
|
||||
```
|
||||
|
||||
**Phase 3: Multi-Dimension Analysis**
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
run_in_background: false,
|
||||
description: "Analyze <target> for <task-id>",
|
||||
prompt: "## Task
|
||||
- Analyze: <target description>
|
||||
- Dimensions: <analysis dimensions from coordinator>
|
||||
- Session: <session-folder>
|
||||
## Target Content
|
||||
<artifact content or file content>
|
||||
## Expected Output
|
||||
Write report to: <session>/artifacts/analysis-report.md
|
||||
Return JSON: { artifact_path, summary, findings[], severity_counts: {critical, high, medium, low} }"
|
||||
})
|
||||
```
|
||||
|
||||
**Phase 4: Severity Classification**
|
||||
|
||||
```
|
||||
1. Verify analysis report exists
|
||||
2. Classify findings by severity (Critical/High/Medium/Low)
|
||||
3. Update shared-memory.json with key findings
|
||||
4. Write issues to wisdom/issues.md
|
||||
```
|
||||
|
||||
### validation
|
||||
|
||||
**Phase 2: Environment Detection**
|
||||
|
||||
```
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From TaskGet | Yes |
|
||||
| Implementation artifacts | Upstream code changes | Yes |
|
||||
|
||||
Loading steps:
|
||||
1. Detect test framework from project files
|
||||
2. Get changed files from implementation
|
||||
3. Identify test command and coverage tool
|
||||
```
|
||||
|
||||
**Phase 3: Test-Fix Cycle**
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "test-fix-agent",
|
||||
run_in_background: false,
|
||||
description: "Test-fix for <task-id>",
|
||||
prompt: "## Task
|
||||
- Run tests and fix failures
|
||||
- Session: <session-folder>
|
||||
- Max iterations: 5
|
||||
## Changed Files
|
||||
<from upstream implementation>
|
||||
## Expected Output
|
||||
Write report to: <session>/artifacts/test-report.md
|
||||
Return JSON: { artifact_path, pass_rate, coverage, iterations_used, remaining_failures[] }"
|
||||
})
|
||||
```
|
||||
|
||||
**Phase 4: Result Analysis**
|
||||
|
||||
```
|
||||
1. Check pass rate >= 95%
|
||||
2. Check coverage meets threshold
|
||||
3. Generate test report with pass/fail counts
|
||||
4. Update shared-memory.json with test results
|
||||
```
|
||||
Reference in New Issue
Block a user