mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: Enhance team skill router with command architecture and role isolation rules
- Added command architecture section to skill router template, detailing role organization and command delegation. - Updated role router input parsing to reflect new file structure for roles. - Introduced role isolation rules to enforce strict boundaries on role responsibilities and output tagging. - Enhanced team configuration section to include role-specific guidelines and message bus requirements. feat: Improve terminal dashboard with session status indicators - Integrated terminal status indicators in the session group tree, displaying active, idle, error, paused, and resuming states. - Updated session click handling to focus on existing panes or assign sessions to available panes. feat: Add session lifecycle controls in terminal pane - Implemented restart, pause, and resume functionalities for terminal sessions with loading states. - Enhanced UI buttons for session control with appropriate loading indicators and tooltips. i18n: Update terminal dashboard localization for session controls - Added translations for restart, pause, and resume session actions in English and Chinese. chore: Create role command template for command file generation - Established a comprehensive template for generating command files in roles, including sections for strategy, execution steps, and error handling. - Included pre-built command patterns for common tasks like exploration, analysis, implementation, validation, review, dispatch, and monitoring.
This commit is contained in:
catlog22
@@ -0,0 +1,725 @@
|
||||
# Role Command Template
|
||||
|
||||
Template for generating command files in `roles/{role-name}/commands/{command}.md`.
|
||||
|
||||
## Purpose
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 0 | Read to understand command file structure |
|
||||
| Phase 3 | Apply with role-specific content |
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Command: {{command_name}}
|
||||
|
||||
> {{command_description}}
|
||||
|
||||
## When to Use
|
||||
|
||||
{{when_to_use_description}}
|
||||
|
||||
**Trigger conditions**:
|
||||
{{#each triggers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: {{delegation_mode}}
|
||||
|
||||
{{#if delegation_mode_subagent}}
|
||||
**Subagent Type**: `{{subagent_type}}`
|
||||
**Parallel Count**: {{parallel_count}} (1-4)
|
||||
{{/if}}
|
||||
|
||||
{{#if delegation_mode_cli}}
|
||||
**CLI Tool**: `{{cli_tool}}`
|
||||
**CLI Mode**: `{{cli_mode}}`
|
||||
**Parallel Perspectives**: {{cli_perspectives}}
|
||||
{{/if}}
|
||||
|
||||
{{#if delegation_mode_sequential}}
|
||||
**Agent Type**: `{{agent_type}}`
|
||||
**Delegation Scope**: {{delegation_scope}}
|
||||
{{/if}}
|
||||
|
||||
### Decision Logic
|
||||
|
||||
\`\`\`javascript
|
||||
{{decision_logic}}
|
||||
\`\`\`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Context Preparation
|
||||
|
||||
\`\`\`javascript
|
||||
{{context_preparation_code}}
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Execute Strategy
|
||||
|
||||
\`\`\`javascript
|
||||
{{execution_code}}
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Result Processing
|
||||
|
||||
\`\`\`javascript
|
||||
{{result_processing_code}}
|
||||
\`\`\`
|
||||
|
||||
## Output Format
|
||||
|
||||
\`\`\`
|
||||
{{output_format}}
|
||||
\`\`\`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
{{#each error_handlers}}
|
||||
| {{this.scenario}} | {{this.resolution}} |
|
||||
{{/each}}
|
||||
| Agent/CLI failure | Retry once, then fallback to inline execution |
|
||||
| Timeout (>5 min) | Report partial results, notify coordinator |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7 Pre-built Command Patterns
|
||||
|
||||
### 1. explore.md (Multi-angle Exploration)
|
||||
|
||||
**Delegation Mode**: Subagent Fan-out
|
||||
**Source Pattern**: team-lifecycle planner Phase 2
|
||||
**Maps to**: Orchestration roles
|
||||
|
||||
```markdown
|
||||
# Command: explore
|
||||
|
||||
> Multi-angle codebase exploration using parallel cli-explore-agent instances.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 2 of Orchestration roles
|
||||
- Task requires understanding existing code patterns
|
||||
- Multiple exploration angles needed (architecture, patterns, dependencies)
|
||||
|
||||
**Trigger conditions**:
|
||||
- New feature planning
|
||||
- Codebase unfamiliar to the agent
|
||||
- Cross-module impact analysis
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: Subagent Fan-out
|
||||
**Subagent Type**: `cli-explore-agent`
|
||||
**Parallel Count**: 2-4 (based on complexity)
|
||||
|
||||
### Decision Logic
|
||||
|
||||
\`\`\`javascript
|
||||
const angles = []
|
||||
if (/architect|structure|design/.test(task.description)) angles.push("architecture")
|
||||
if (/pattern|convention|style/.test(task.description)) angles.push("patterns")
|
||||
if (/depend|import|module/.test(task.description)) angles.push("dependencies")
|
||||
if (/test|spec|coverage/.test(task.description)) angles.push("testing")
|
||||
if (angles.length === 0) angles.push("general", "patterns")
|
||||
\`\`\`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Context Preparation
|
||||
|
||||
\`\`\`javascript
|
||||
const taskDescription = task.description
|
||||
const projectRoot = Bash(\`git rev-parse --show-toplevel\`).trim()
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Execute Strategy
|
||||
|
||||
\`\`\`javascript
|
||||
// Launch parallel exploration agents (1 per angle)
|
||||
for (const angle of angles) {
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: \`Explore: \${angle}\`,
|
||||
prompt: \`Explore the codebase from the perspective of \${angle}.
|
||||
Focus on: \${taskDescription}
|
||||
Project root: \${projectRoot}
|
||||
|
||||
Report findings as structured markdown with file references.\`
|
||||
})
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Result Processing
|
||||
|
||||
\`\`\`javascript
|
||||
// Aggregate exploration results
|
||||
const aggregated = {
|
||||
angles_explored: angles,
|
||||
key_findings: [], // merge from all agents
|
||||
relevant_files: [], // deduplicate across agents
|
||||
patterns_found: []
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Output Format
|
||||
|
||||
\`\`\`
|
||||
## Exploration Results
|
||||
|
||||
### Angles Explored: [list]
|
||||
|
||||
### Key Findings
|
||||
- [finding with file:line reference]
|
||||
|
||||
### Relevant Files
|
||||
- [file path with relevance note]
|
||||
|
||||
### Patterns Found
|
||||
- [pattern name: description]
|
||||
\`\`\`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Agent returns no results | Retry with broader search scope |
|
||||
| Agent timeout | Use partial results, note incomplete angles |
|
||||
| Project root not found | Fall back to current directory |
|
||||
```
|
||||
|
||||
### 2. analyze.md (Multi-perspective Analysis)
|
||||
|
||||
**Delegation Mode**: CLI Fan-out
|
||||
**Source Pattern**: analyze-with-file Phase 2
|
||||
**Maps to**: Read-only analysis roles
|
||||
|
||||
```markdown
|
||||
# Command: analyze
|
||||
|
||||
> Multi-perspective code analysis using parallel ccw cli calls.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 3 of Read-only analysis roles
|
||||
- Multiple analysis dimensions needed (security, performance, quality)
|
||||
- Deep analysis beyond inline capability
|
||||
|
||||
**Trigger conditions**:
|
||||
- Code review with specific focus areas
|
||||
- Security/performance audit
|
||||
- Architecture assessment
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: CLI Fan-out
|
||||
**CLI Tool**: `gemini` (primary), `codex` (secondary)
|
||||
**CLI Mode**: `analysis`
|
||||
**Parallel Perspectives**: 2-4
|
||||
|
||||
### Decision Logic
|
||||
|
||||
\`\`\`javascript
|
||||
const perspectives = []
|
||||
if (/security|auth|inject|xss/.test(task.description)) perspectives.push("security")
|
||||
if (/performance|speed|optimize|memory/.test(task.description)) perspectives.push("performance")
|
||||
if (/quality|clean|maintain|debt/.test(task.description)) perspectives.push("code-quality")
|
||||
if (/architect|pattern|structure/.test(task.description)) perspectives.push("architecture")
|
||||
if (perspectives.length === 0) perspectives.push("code-quality", "architecture")
|
||||
\`\`\`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Context Preparation
|
||||
|
||||
\`\`\`javascript
|
||||
const targetFiles = Bash(\`git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached\`)
|
||||
.split('\\n').filter(Boolean)
|
||||
const fileContext = targetFiles.map(f => \`@\${f}\`).join(' ')
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Execute Strategy
|
||||
|
||||
\`\`\`javascript
|
||||
for (const perspective of perspectives) {
|
||||
Bash(\`ccw cli -p "PURPOSE: Analyze code from \${perspective} perspective
|
||||
TASK: Review changes in: \${targetFiles.join(', ')}
|
||||
MODE: analysis
|
||||
CONTEXT: \${fileContext}
|
||||
EXPECTED: Findings with severity, file:line references, remediation
|
||||
CONSTRAINTS: Focus on \${perspective}" --tool gemini --mode analysis\`, { run_in_background: true })
|
||||
}
|
||||
// Wait for all CLI results
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Result Processing
|
||||
|
||||
\`\`\`javascript
|
||||
// Aggregate findings across all perspectives
|
||||
const findings = { critical: [], high: [], medium: [], low: [] }
|
||||
// Merge, deduplicate, prioritize
|
||||
\`\`\`
|
||||
|
||||
## Output Format
|
||||
|
||||
\`\`\`
|
||||
## Analysis Results
|
||||
|
||||
### Perspectives Analyzed: [list]
|
||||
|
||||
### Findings by Severity
|
||||
#### Critical
|
||||
- [finding with file:line]
|
||||
#### High
|
||||
- [finding]
|
||||
...
|
||||
\`\`\`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| CLI tool unavailable | Fall back to secondary tool (codex) |
|
||||
| CLI returns empty | Retry with broader scope |
|
||||
| Too many findings | Prioritize critical/high, summarize medium/low |
|
||||
```
|
||||
|
||||
### 3. implement.md (Code Implementation)
|
||||
|
||||
**Delegation Mode**: Sequential Delegation
|
||||
**Source Pattern**: team-lifecycle executor Phase 3
|
||||
**Maps to**: Code generation roles
|
||||
|
||||
```markdown
|
||||
# Command: implement
|
||||
|
||||
> Code implementation via code-developer subagent delegation with batch routing.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 3 of Code generation roles
|
||||
- Implementation involves >2 files or complex logic
|
||||
- Plan tasks available with file specifications
|
||||
|
||||
**Trigger conditions**:
|
||||
- Plan approved and tasks defined
|
||||
- Multi-file implementation needed
|
||||
- Complex logic requiring specialized agent
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: Sequential Delegation (with batch routing)
|
||||
**Agent Type**: `code-developer`
|
||||
**Delegation Scope**: Per-batch (group related tasks)
|
||||
|
||||
### Decision Logic
|
||||
|
||||
\`\`\`javascript
|
||||
const taskCount = planTasks.length
|
||||
if (taskCount <= 2) {
|
||||
// Direct: inline Edit/Write
|
||||
mode = "direct"
|
||||
} else if (taskCount <= 5) {
|
||||
// Single agent: one code-developer for all
|
||||
mode = "single-agent"
|
||||
} else {
|
||||
// Batch: group by module, one agent per batch
|
||||
mode = "batch-agent"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Context Preparation
|
||||
|
||||
\`\`\`javascript
|
||||
const plan = JSON.parse(Read(planPath))
|
||||
const planTasks = plan.task_ids.map(id =>
|
||||
JSON.parse(Read(\`\${planDir}/.task/\${id}.json\`))
|
||||
)
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Execute Strategy
|
||||
|
||||
\`\`\`javascript
|
||||
if (mode === "direct") {
|
||||
for (const pt of planTasks) {
|
||||
for (const f of (pt.files || [])) {
|
||||
Read(f.path)
|
||||
Edit({ file_path: f.path, old_string: "...", new_string: "..." })
|
||||
}
|
||||
}
|
||||
} else {
|
||||
const batches = mode === "batch-agent"
|
||||
? groupByModule(planTasks)
|
||||
: [planTasks]
|
||||
|
||||
for (const batch of batches) {
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
run_in_background: false,
|
||||
description: \`Implement \${batch.length} tasks\`,
|
||||
prompt: \`## Goal\\n\${plan.summary}\\n\\n## Tasks\\n\${
|
||||
batch.map(t => \`### \${t.title}\\n\${t.description}\`).join('\\n\\n')
|
||||
}\\n\\nComplete each task according to its convergence criteria.\`
|
||||
})
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Result Processing
|
||||
|
||||
\`\`\`javascript
|
||||
const changedFiles = Bash(\`git diff --name-only\`).split('\\n').filter(Boolean)
|
||||
const syntaxClean = !Bash(\`tsc --noEmit 2>&1 || true\`).includes('error TS')
|
||||
\`\`\`
|
||||
|
||||
## Output Format
|
||||
|
||||
\`\`\`
|
||||
## Implementation Results
|
||||
|
||||
### Changed Files: [count]
|
||||
- [file path]
|
||||
|
||||
### Syntax Check: PASS/FAIL
|
||||
### Tasks Completed: [count]/[total]
|
||||
\`\`\`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Plan file not found | Notify coordinator, request plan path |
|
||||
| Agent fails on task | Retry once, then mark task as blocked |
|
||||
| Syntax errors after impl | Attempt auto-fix, report if unresolved |
|
||||
```
|
||||
|
||||
### 4. validate.md (Test-Fix Cycle)
|
||||
|
||||
**Delegation Mode**: Sequential Delegation
|
||||
**Source Pattern**: team-lifecycle tester
|
||||
**Maps to**: Validation roles
|
||||
|
||||
```markdown
|
||||
# Command: validate
|
||||
|
||||
> Iterative test-fix cycle with max iteration control.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 3 of Validation roles
|
||||
- After implementation, before review
|
||||
- Automated test suite available
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: Sequential Delegation
|
||||
**Agent Type**: `code-developer` (for fix iterations)
|
||||
**Max Iterations**: 5
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Context Preparation
|
||||
|
||||
\`\`\`javascript
|
||||
const testCommand = detectTestCommand() // npm test, pytest, etc.
|
||||
const changedFiles = Bash(\`git diff --name-only\`).split('\\n').filter(Boolean)
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Execute Strategy
|
||||
|
||||
\`\`\`javascript
|
||||
let iteration = 0
|
||||
const MAX_ITERATIONS = 5
|
||||
let lastResult = null
|
||||
|
||||
while (iteration < MAX_ITERATIONS) {
|
||||
lastResult = Bash(\`\${testCommand} 2>&1 || true\`)
|
||||
const passed = !lastResult.includes('FAIL') && !lastResult.includes('Error')
|
||||
|
||||
if (passed) break
|
||||
|
||||
// Delegate fix to code-developer
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
run_in_background: false,
|
||||
description: \`Fix test failures (iteration \${iteration + 1})\`,
|
||||
prompt: \`Test failures:\\n\${lastResult}\\n\\nFix the failing tests. Changed files: \${changedFiles.join(', ')}\`
|
||||
})
|
||||
|
||||
iteration++
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Result Processing
|
||||
|
||||
\`\`\`javascript
|
||||
const result = {
|
||||
iterations: iteration,
|
||||
passed: iteration < MAX_ITERATIONS,
|
||||
lastOutput: lastResult
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No test command found | Notify coordinator |
|
||||
| Max iterations exceeded | Report failures, suggest manual intervention |
|
||||
| Test environment broken | Report environment issue |
|
||||
```
|
||||
|
||||
### 5. review.md (Multi-dimensional Review)
|
||||
|
||||
**Delegation Mode**: CLI Fan-out
|
||||
**Source Pattern**: team-lifecycle reviewer
|
||||
**Maps to**: Read-only analysis roles
|
||||
|
||||
```markdown
|
||||
# Command: review
|
||||
|
||||
> 4-dimensional code review with optional codex review integration.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 3 of Read-only analysis roles (reviewer type)
|
||||
- After implementation and testing
|
||||
- Quality gate before delivery
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: CLI Fan-out
|
||||
**CLI Tool**: `gemini` + optional `codex` (review mode)
|
||||
**Dimensions**: correctness, completeness, maintainability, requirement-fit
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 2: Execute Strategy
|
||||
|
||||
\`\`\`javascript
|
||||
// Dimension 1-3: Parallel CLI analysis
|
||||
const dimensions = ["correctness", "completeness", "maintainability"]
|
||||
for (const dim of dimensions) {
|
||||
Bash(\`ccw cli -p "PURPOSE: Review code for \${dim}
|
||||
TASK: Evaluate changes against \${dim} criteria
|
||||
MODE: analysis
|
||||
CONTEXT: @\${changedFiles.join(' @')}
|
||||
EXPECTED: Findings with severity and file:line references" --tool gemini --mode analysis\`, { run_in_background: true })
|
||||
}
|
||||
|
||||
// Dimension 4: Optional codex review
|
||||
Bash(\`ccw cli --tool codex --mode review --uncommitted\`, { run_in_background: true })
|
||||
\`\`\`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Codex unavailable | Skip dimension 4, report 3-dimension review |
|
||||
| No changed files | Review full scope of plan files |
|
||||
```
|
||||
|
||||
### 6. dispatch.md (Task Distribution)
|
||||
|
||||
**Delegation Mode**: N/A (Coordinator-only)
|
||||
**Source Pattern**: auto-parallel + CP-3
|
||||
**Maps to**: Coordinator role
|
||||
|
||||
```markdown
|
||||
# Command: dispatch
|
||||
|
||||
> Task chain creation with dependency management for coordinator.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 3 of Coordinator role
|
||||
- After requirement clarification
|
||||
- When creating and assigning tasks to teammates
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: Direct (no delegation - coordinator acts directly)
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Context Preparation
|
||||
|
||||
\`\`\`javascript
|
||||
const config = TEAM_CONFIG
|
||||
const pipeline = config.pipeline
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Execute Strategy
|
||||
|
||||
\`\`\`javascript
|
||||
const taskIds = {}
|
||||
|
||||
for (const stage of pipeline.stages) {
|
||||
const blockedByIds = stage.blockedBy.map(dep => taskIds[dep]).filter(Boolean)
|
||||
|
||||
TaskCreate({
|
||||
subject: \`\${stage.name}-001: \${stage.role} work\`,
|
||||
description: taskDescription,
|
||||
activeForm: \`\${stage.name} 进行中\`
|
||||
})
|
||||
|
||||
// Record task ID
|
||||
taskIds[stage.name] = newTaskId
|
||||
|
||||
// Set owner and dependencies
|
||||
TaskUpdate({
|
||||
taskId: newTaskId,
|
||||
owner: stage.role,
|
||||
addBlockedBy: blockedByIds
|
||||
})
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Result Processing
|
||||
|
||||
\`\`\`javascript
|
||||
// Verify task chain created correctly
|
||||
const allTasks = TaskList()
|
||||
const chainValid = pipeline.stages.every(s => taskIds[s.name])
|
||||
\`\`\`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Task creation fails | Retry, then report to user |
|
||||
| Dependency cycle detected | Flatten dependencies, warn |
|
||||
| Role not spawned yet | Queue task, spawn role first |
|
||||
```
|
||||
|
||||
### 7. monitor.md (Progress Monitoring)
|
||||
|
||||
**Delegation Mode**: N/A (Coordinator-only)
|
||||
**Source Pattern**: coordinate.md Phase 4
|
||||
**Maps to**: Coordinator role
|
||||
|
||||
```markdown
|
||||
# Command: monitor
|
||||
|
||||
> Message bus polling and coordination loop for coordinator.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 4 of Coordinator role
|
||||
- After task dispatch
|
||||
- Continuous monitoring until all tasks complete
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: Direct (coordinator polls and routes)
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Context Preparation
|
||||
|
||||
\`\`\`javascript
|
||||
const routingTable = {}
|
||||
for (const role of config.worker_roles) {
|
||||
const resultType = role.message_types.find(mt =>
|
||||
!mt.type.includes('error') && !mt.type.includes('progress')
|
||||
)
|
||||
routingTable[resultType?.type || \`\${role.name}_complete\`] = {
|
||||
role: role.name,
|
||||
action: "Mark task completed, check downstream dependencies"
|
||||
}
|
||||
}
|
||||
routingTable["error"] = { role: "*", action: "Assess severity, retry or escalate" }
|
||||
routingTable["fix_required"] = { role: "*", action: "Create fix task for executor" }
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Execute Strategy
|
||||
|
||||
\`\`\`javascript
|
||||
// Coordination loop
|
||||
let allComplete = false
|
||||
while (!allComplete) {
|
||||
// Poll message bus
|
||||
const messages = mcp__ccw-tools__team_msg({
|
||||
operation: "list",
|
||||
team: teamName,
|
||||
last: 10
|
||||
})
|
||||
|
||||
// Route each message
|
||||
for (const msg of messages) {
|
||||
const handler = routingTable[msg.type]
|
||||
if (handler) {
|
||||
// Execute handler action
|
||||
}
|
||||
}
|
||||
|
||||
// Check completion
|
||||
const tasks = TaskList()
|
||||
allComplete = tasks.filter(t =>
|
||||
t.owner !== 'coordinator' && t.status !== 'completed'
|
||||
).length === 0
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Message bus unavailable | Fall back to TaskList polling |
|
||||
| Teammate unresponsive | Send follow-up, 2x → respawn |
|
||||
| Deadlock detected | Identify cycle, break with manual unblock |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variable Reference
|
||||
|
||||
| Variable | Source | Description |
|
||||
|----------|--------|-------------|
|
||||
| `{{command_name}}` | Command identifier | e.g., "explore", "analyze" |
|
||||
| `{{command_description}}` | One-line description | What this command does |
|
||||
| `{{delegation_mode}}` | Mode selection | "Subagent Fan-out", "CLI Fan-out", "Sequential Delegation", "Direct" |
|
||||
| `{{when_to_use_description}}` | Usage context | When to invoke this command |
|
||||
| `{{triggers}}` | Trigger conditions | List of conditions |
|
||||
| `{{decision_logic}}` | Strategy selection code | JavaScript decision code |
|
||||
| `{{context_preparation_code}}` | Context setup | JavaScript setup code |
|
||||
| `{{execution_code}}` | Core execution | JavaScript execution code |
|
||||
| `{{result_processing_code}}` | Result aggregation | JavaScript result code |
|
||||
| `{{output_format}}` | Expected output structure | Markdown format spec |
|
||||
| `{{error_handlers}}` | Error handling entries | Array of {scenario, resolution} |
|
||||
|
||||
## Self-Containment Rules
|
||||
|
||||
1. **No cross-command references**: Each command.md must be executable independently
|
||||
2. **Include all imports**: List all required context (files, configs) in Step 1
|
||||
3. **Complete error handling**: Every command handles its own failures
|
||||
4. **Explicit output format**: Define what the command produces
|
||||
5. **Strategy declaration**: State delegation mode and decision logic upfront
|
||||
@@ -1,6 +1,6 @@
|
||||
# Role File Template
|
||||
|
||||
Template for generating per-role execution detail files in `roles/{role-name}.md`.
|
||||
Template for generating per-role execution detail files in `roles/{role-name}/role.md`.
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -24,6 +24,24 @@ Template for generating per-role execution detail files in `roles/{role-name}.md
|
||||
- **Task Prefix**: `{{task_prefix}}-*`
|
||||
- **Responsibility**: {{responsibility_type}}
|
||||
- **Communication**: SendMessage to coordinator only
|
||||
- **Output Tag**: `[{{role_name}}]`
|
||||
|
||||
## Role Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- 仅处理 `{{task_prefix}}-*` 前缀的任务
|
||||
- 所有输出（SendMessage、team_msg、日志）必须带 `[{{role_name}}]` 标识
|
||||
- 仅通过 SendMessage 与 coordinator 通信
|
||||
- 严格在 {{responsibility_type}} 职责范围内工作
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- ❌ 执行其他角色职责范围内的工作
|
||||
- ❌ 直接与其他 worker 角色通信（必须经过 coordinator）
|
||||
- ❌ 为其他角色创建任务（TaskCreate 是 coordinator 专属）
|
||||
- ❌ 修改不属于本角色职责的文件或资源
|
||||
- ❌ 在输出中省略 `[{{role_name}}]` 标识
|
||||
|
||||
## Message Types
|
||||
|
||||
@@ -33,6 +51,36 @@ Template for generating per-role execution detail files in `roles/{role-name}.md
|
||||
| `{{this.type}}` | {{../role_name}} → coordinator | {{this.trigger}} | {{this.description}} |
|
||||
{{/each}}
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | File | Phase | Description |
|
||||
|---------|------|-------|-------------|
|
||||
{{#each commands}}
|
||||
| `{{this.name}}` | [commands/{{this.name}}.md](commands/{{this.name}}.md) | Phase {{this.phase}} | {{this.description}} |
|
||||
{{/each}}
|
||||
|
||||
{{#if has_no_commands}}
|
||||
> No command files — all phases execute inline.
|
||||
{{/if}}
|
||||
|
||||
### Subagent Capabilities
|
||||
|
||||
| Agent Type | Used By | Purpose |
|
||||
|------------|---------|---------|
|
||||
{{#each subagents}}
|
||||
| `{{this.type}}` | {{this.used_by}} | {{this.purpose}} |
|
||||
{{/each}}
|
||||
|
||||
### CLI Capabilities
|
||||
|
||||
| CLI Tool | Mode | Used By | Purpose |
|
||||
|----------|------|---------|---------|
|
||||
{{#each cli_tools}}
|
||||
| `{{this.tool}}` | {{this.mode}} | {{this.used_by}} | {{this.purpose}} |
|
||||
{{/each}}
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
@@ -54,33 +102,75 @@ TaskUpdate({ taskId: task.id, status: 'in_progress' })
|
||||
|
||||
### Phase 2: {{phase2_name}}
|
||||
|
||||
{{#if phase2_command}}
|
||||
\`\`\`javascript
|
||||
// Delegate to command file
|
||||
try {
|
||||
const commandContent = Read("commands/{{phase2_command}}.md")
|
||||
// Execute strategy defined in command file
|
||||
} catch {
|
||||
// Fallback: inline execution
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Command**: [commands/{{phase2_command}}.md](commands/{{phase2_command}}.md)
|
||||
{{else}}
|
||||
{{phase2_content}}
|
||||
{{/if}}
|
||||
|
||||
### Phase 3: {{phase3_name}}
|
||||
|
||||
{{#if phase3_command}}
|
||||
\`\`\`javascript
|
||||
// Delegate to command file
|
||||
try {
|
||||
const commandContent = Read("commands/{{phase3_command}}.md")
|
||||
// Execute strategy defined in command file
|
||||
} catch {
|
||||
// Fallback: inline execution
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Command**: [commands/{{phase3_command}}.md](commands/{{phase3_command}}.md)
|
||||
{{else}}
|
||||
{{phase3_content}}
|
||||
{{/if}}
|
||||
|
||||
### Phase 4: {{phase4_name}}
|
||||
|
||||
{{#if phase4_command}}
|
||||
\`\`\`javascript
|
||||
// Delegate to command file
|
||||
try {
|
||||
const commandContent = Read("commands/{{phase4_command}}.md")
|
||||
// Execute strategy defined in command file
|
||||
} catch {
|
||||
// Fallback: inline execution
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Command**: [commands/{{phase4_command}}.md](commands/{{phase4_command}}.md)
|
||||
{{else}}
|
||||
{{phase4_content}}
|
||||
{{/if}}
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
\`\`\`javascript
|
||||
// Log message before SendMessage
|
||||
// Log message before SendMessage — 所有输出必须带 [{{role_name}}] 标识
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: teamName,
|
||||
from: "{{role_name}}",
|
||||
to: "coordinator",
|
||||
type: "{{primary_message_type}}",
|
||||
summary: \`{{task_prefix}} complete: \${task.subject}\`
|
||||
summary: \`[{{role_name}}] {{task_prefix}} complete: \${task.subject}\`
|
||||
})
|
||||
|
||||
SendMessage({
|
||||
type: "message",
|
||||
recipient: "coordinator",
|
||||
content: \`## {{display_name}} Results
|
||||
content: \`## [{{role_name}}] {{display_name}} Results
|
||||
|
||||
**Task**: \${task.subject}
|
||||
**Status**: \${resultStatus}
|
||||
@@ -90,7 +180,7 @@ SendMessage({
|
||||
|
||||
### Details
|
||||
\${resultDetails}\`,
|
||||
summary: \`{{task_prefix}} complete\`
|
||||
summary: \`[{{role_name}}] {{task_prefix}} complete\`
|
||||
})
|
||||
|
||||
// Mark task completed
|
||||
@@ -115,6 +205,9 @@ if (nextTasks.length > 0) {
|
||||
|----------|------------|
|
||||
| No {{task_prefix}}-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Context/Plan file not found | Notify coordinator, request location |
|
||||
{{#if has_commands}}
|
||||
| Command file not found | Fall back to inline execution |
|
||||
{{/if}}
|
||||
{{#if adaptive_routing}}
|
||||
| Sub-agent failure | Retry once, then fallback to direct execution |
|
||||
{{/if}}
|
||||
@@ -270,6 +363,26 @@ Team coordinator. Orchestrates the pipeline: requirement clarification → task
|
||||
- **Task Prefix**: N/A (coordinator creates tasks, doesn't receive them)
|
||||
- **Responsibility**: Orchestration
|
||||
- **Communication**: SendMessage to all teammates
|
||||
- **Output Tag**: `[coordinator]`
|
||||
|
||||
## Role Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- 所有输出（SendMessage、team_msg、日志）必须带 `[coordinator]` 标识
|
||||
- 仅负责需求澄清、任务创建/分发、进度监控、结果汇报
|
||||
- 通过 TaskCreate 创建任务并分配给 worker 角色
|
||||
- 通过消息总线监控 worker 进度并路由消息
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- ❌ **直接执行任何业务任务**（代码编写、分析、测试、审查等）
|
||||
- ❌ 直接调用 code-developer、cli-explore-agent 等实现类 subagent
|
||||
- ❌ 直接修改源代码或生成产物文件
|
||||
- ❌ 绕过 worker 角色自行完成应委派的工作
|
||||
- ❌ 在输出中省略 `[coordinator]` 标识
|
||||
|
||||
> **核心原则**: coordinator 是指挥者，不是执行者。所有实际工作必须通过 TaskCreate 委派给 worker 角色。
|
||||
|
||||
## Execution
|
||||
|
||||
@@ -331,3 +444,11 @@ Summarize results. AskUserQuestion for next requirement or shutdown.
|
||||
| `{{message_types}}` | config.message_types | Array of message types |
|
||||
| `{{primary_message_type}}` | config.message_types[0].type | Primary type |
|
||||
| `{{adaptive_routing}}` | config.adaptive_routing | Boolean |
|
||||
| `{{commands}}` | config.commands | Array of command definitions |
|
||||
| `{{has_commands}}` | config.commands.length > 0 | Boolean: has extracted commands |
|
||||
| `{{has_no_commands}}` | config.commands.length === 0 | Boolean: all phases inline |
|
||||
| `{{subagents}}` | config.subagents | Array of subagent capabilities |
|
||||
| `{{cli_tools}}` | config.cli_tools | Array of CLI tool capabilities |
|
||||
| `{{phase2_command}}` | config.phase2_command | Command name for Phase 2 (if extracted) |
|
||||
| `{{phase3_command}}` | config.phase3_command | Command name for Phase 3 (if extracted) |
|
||||
| `{{phase4_command}}` | config.phase4_command | Command name for Phase 4 (if extracted) |
|
||||
|
||||
@@ -40,6 +40,24 @@ Unified team skill. All team members invoke this skill with `--role=xxx` to rout
|
||||
└──────────┘ └──────────┘ └──────────┘ └──────────┘
|
||||
\`\`\`
|
||||
|
||||
## Command Architecture
|
||||
|
||||
Each role is organized as a folder with a `role.md` orchestrator and optional `commands/` for delegation:
|
||||
|
||||
\`\`\`
|
||||
roles/
|
||||
{{#each roles}}
|
||||
├── {{this.name}}/
|
||||
│ ├── role.md # Orchestrator (Phase 1/5 inline, Phase 2-4 delegate)
|
||||
│ └── commands/ # Optional: extracted command files
|
||||
│ └── *.md # Self-contained command modules
|
||||
{{/each}}
|
||||
\`\`\`
|
||||
|
||||
**Design principle**: role.md keeps Phase 1 (Task Discovery) and Phase 5 (Report) inline. Phases 2-4 either stay inline (simple logic) or delegate to `commands/*.md` via `Read("commands/xxx.md")` when they involve subagent delegation, CLI fan-out, or complex strategies.
|
||||
|
||||
**Command files** are self-contained: each includes Strategy, Execution Steps, and Error Handling. Any subagent can `Read()` a command file and execute it independently.
|
||||
|
||||
## Role Router
|
||||
|
||||
### Input Parsing
|
||||
@@ -65,7 +83,7 @@ const teamName = "{{team_name}}"
|
||||
\`\`\`javascript
|
||||
const VALID_ROLES = {
|
||||
{{#each roles}}
|
||||
"{{this.name}}": { file: "roles/{{this.name}}.md", prefix: "{{this.task_prefix}}" },
|
||||
"{{this.name}}": { file: "roles/{{this.name}}/role.md", prefix: "{{this.task_prefix}}" },
|
||||
{{/each}}
|
||||
}
|
||||
|
||||
@@ -83,11 +101,51 @@ Read(VALID_ROLES[role].file)
|
||||
| Role | Task Prefix | Responsibility | Role File |
|
||||
|------|-------------|----------------|-----------|
|
||||
{{#each roles}}
|
||||
| `{{this.name}}` | {{this.task_prefix}}-* | {{this.responsibility}} | [roles/{{this.name}}.md](roles/{{this.name}}.md) |
|
||||
| `{{this.name}}` | {{this.task_prefix}}-* | {{this.responsibility}} | [roles/{{this.name}}/role.md](roles/{{this.name}}/role.md) |
|
||||
{{/each}}
|
||||
|
||||
## Shared Infrastructure
|
||||
|
||||
### Role Isolation Rules
|
||||
|
||||
**核心原则**: 每个角色仅能执行自己职责范围内的工作。
|
||||
|
||||
#### Output Tagging（强制）
|
||||
|
||||
所有角色的输出必须带 `[role_name]` 标识前缀：
|
||||
|
||||
\`\`\`javascript
|
||||
// SendMessage — content 和 summary 都必须带标识
|
||||
SendMessage({
|
||||
content: \`## [\\${role}] ...\`,
|
||||
summary: \`[\\${role}] ...\`
|
||||
})
|
||||
|
||||
// team_msg — summary 必须带标识
|
||||
mcp__ccw-tools__team_msg({
|
||||
summary: \`[\\${role}] ...\`
|
||||
})
|
||||
\`\`\`
|
||||
|
||||
#### Coordinator 隔离
|
||||
|
||||
| 允许 | 禁止 |
|
||||
|------|------|
|
||||
| 需求澄清 (AskUserQuestion) | ❌ 直接编写/修改代码 |
|
||||
| 创建任务链 (TaskCreate) | ❌ 调用实现类 subagent (code-developer 等) |
|
||||
| 分发任务给 worker | ❌ 直接执行分析/测试/审查 |
|
||||
| 监控进度 (消息总线) | ❌ 绕过 worker 自行完成任务 |
|
||||
| 汇报结果给用户 | ❌ 修改源代码或产物文件 |
|
||||
|
||||
#### Worker 隔离
|
||||
|
||||
| 允许 | 禁止 |
|
||||
|------|------|
|
||||
| 处理自己前缀的任务 | ❌ 处理其他角色前缀的任务 |
|
||||
| SendMessage 给 coordinator | ❌ 直接与其他 worker 通信 |
|
||||
| 使用 Toolbox 中声明的工具 | ❌ 为其他角色创建任务 (TaskCreate) |
|
||||
| 委派给 commands/ 中的命令 | ❌ 修改不属于本职责的资源 |
|
||||
|
||||
### Team Configuration
|
||||
|
||||
\`\`\`javascript
|
||||
@@ -149,9 +207,9 @@ TaskUpdate({ taskId: task.id, status: 'in_progress' })
|
||||
|
||||
// Phase 2-4: Role-specific (see roles/{role}.md)
|
||||
|
||||
// Phase 5: Report + Loop
|
||||
mcp__ccw-tools__team_msg({ operation: "log", team: "{{team_name}}", from: role, to: "coordinator", type: "...", summary: "..." })
|
||||
SendMessage({ type: "message", recipient: "coordinator", content: "...", summary: "..." })
|
||||
// Phase 5: Report + Loop — 所有输出必须带 [role] 标识
|
||||
mcp__ccw-tools__team_msg({ operation: "log", team: "{{team_name}}", from: role, to: "coordinator", type: "...", summary: \`[\${role}] ...\` })
|
||||
SendMessage({ type: "message", recipient: "coordinator", content: \`## [\${role}] ...\`, summary: \`[\${role}] ...\` })
|
||||
TaskUpdate({ taskId: task.id, status: 'completed' })
|
||||
// Check for next task → back to Phase 1
|
||||
\`\`\`
|
||||
@@ -182,13 +240,19 @@ Task({
|
||||
当前需求: \${taskDescription}
|
||||
约束: \${constraints}
|
||||
|
||||
## 角色准则（强制）
|
||||
- 你只能处理 {{this.task_prefix}}-* 前缀的任务，不得执行其他角色的工作
|
||||
- 所有输出（SendMessage、team_msg）必须带 [{{this.name}}] 标识前缀
|
||||
- 仅与 coordinator 通信，不得直接联系其他 worker
|
||||
- 不得使用 TaskCreate 为其他角色创建任务
|
||||
|
||||
## 消息总线（必须）
|
||||
每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。
|
||||
|
||||
工作流程:
|
||||
1. TaskList → 找到 {{this.task_prefix}}-* 任务
|
||||
2. Skill(skill="team-{{../team_name}}", args="--role={{this.name}}") 执行
|
||||
3. team_msg log + SendMessage 结果给 coordinator
|
||||
3. team_msg log + SendMessage 结果给 coordinator（带 [{{this.name}}] 标识）
|
||||
4. TaskUpdate completed → 检查下一个任务\`
|
||||
})
|
||||
{{/each}}
|
||||
@@ -200,7 +264,8 @@ Task({
|
||||
|----------|------------|
|
||||
| Unknown --role value | Error with available role list |
|
||||
| Missing --role arg | Error with usage hint |
|
||||
| Role file not found | Error with expected path |
|
||||
| Role file not found | Error with expected path (roles/{name}/role.md) |
|
||||
| Command file not found | Fall back to inline execution in role.md |
|
||||
| Task prefix conflict | Log warning, proceed |
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user