mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-06 16:31:12 +08:00
Add document standards, quality gates, and templates for team lifecycle phases
- Introduced `document-standards.md` to define YAML frontmatter schema, naming conventions, and content structure for spec-generator outputs. - Created `quality-gates.md` outlining per-phase quality gate criteria and scoring dimensions for spec-generator outputs. - Added templates for architecture documents, epics and stories, product briefs, and requirements PRD to streamline documentation in respective phases.
This commit is contained in:
catlog22
@@ -27,9 +27,9 @@ Universal team coordination skill: analyze task -> generate role-specs -> dispat
|
||||
[team-worker agents, each loaded with a dynamic role-spec]
|
||||
(roles generated at runtime from task analysis)
|
||||
|
||||
Subagents (callable by any worker, not team members):
|
||||
[discuss-subagent] - multi-perspective critique (dynamic perspectives)
|
||||
[explore-subagent] - codebase exploration with cache
|
||||
CLI Tools (callable by any worker):
|
||||
ccw cli --mode analysis - analysis and exploration
|
||||
ccw cli --mode write - code generation and modification
|
||||
```
|
||||
|
||||
## Role Router
|
||||
@@ -49,12 +49,14 @@ Only coordinator is statically registered. All other roles are dynamic, stored a
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | built-in orchestrator |
|
||||
| (dynamic) | `<session>/role-specs/<role-name>.md` | runtime-generated role-spec |
|
||||
|
||||
### Subagent Registry
|
||||
### CLI Tool Usage
|
||||
|
||||
| Subagent | Spec | Callable By | Purpose |
|
||||
|----------|------|-------------|---------|
|
||||
| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | any role | Multi-perspective critique (dynamic perspectives) |
|
||||
| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | any role | Codebase exploration with cache |
|
||||
Workers can use CLI tools for analysis and code operations:
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| ccw cli --mode analysis | Analysis, exploration, pattern discovery |
|
||||
| ccw cli --mode write | Code generation, modification, refactoring |
|
||||
|
||||
### Dispatch
|
||||
|
||||
@@ -259,7 +261,7 @@ Coordinator supports `resume` / `continue` for interrupted sessions:
|
||||
| Unknown command | Error with available command list |
|
||||
| Dynamic role-spec not found | Error, coordinator may need to regenerate |
|
||||
| Command file not found | Fallback to inline execution |
|
||||
| Discuss subagent fails | Worker proceeds without discuss, logs warning |
|
||||
| CLI tool fails | Worker proceeds with direct implementation, logs warning |
|
||||
| Explore cache corrupt | Clear cache, re-explore |
|
||||
| Fast-advance spawns wrong task | Coordinator reconciles on next callback |
|
||||
| capability_gap reported | Coordinator generates new role-spec via handleAdapt |
|
||||
|
||||
@@ -117,7 +117,7 @@ For each role, determine frontmatter and generation hints:
|
||||
|-------|------------|
|
||||
| `prefix` | From capability prefix (e.g., RESEARCH, DRAFT, IMPL) |
|
||||
| `inner_loop` | `true` if role has 2+ serial same-prefix tasks |
|
||||
| `subagents` | Suggested, not mandatory — coordinator may adjust based on task needs |
|
||||
| `CLI tools` | Suggested, not mandatory — coordinator may adjust based on task needs |
|
||||
| `pattern_hint` | Reference pattern name from role-spec-template (research/document/code/analysis/validation) — guides coordinator's Phase 2-4 composition, NOT a rigid template selector |
|
||||
| `output_type` | `artifact` (new files in session/artifacts/) / `codebase` (modify existing project files) / `mixed` (both) — determines verification strategy in Behavioral Traits |
|
||||
| `message_types.success` | `<prefix>_complete` |
|
||||
@@ -177,7 +177,7 @@ Write `<session-folder>/task-analysis.json`:
|
||||
"task_count": 1,
|
||||
"inner_loop": false,
|
||||
"role_spec_metadata": {
|
||||
"subagents": ["explore"],
|
||||
"CLI tools": ["explore"],
|
||||
"pattern_hint": "research",
|
||||
"output_type": "artifact",
|
||||
"message_types": {
|
||||
|
||||
@@ -25,7 +25,7 @@ Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec gener
|
||||
- **Read source code or perform codebase exploration** (delegate to worker roles)
|
||||
- Execute task work directly (delegate to workers)
|
||||
- Modify task output artifacts (workers own their deliverables)
|
||||
- Call implementation subagents (code-developer, etc.) directly
|
||||
- Call implementation agents (code-developer, etc.) directly
|
||||
- Skip dependency validation when creating task chains
|
||||
- Generate more than 5 worker roles (merge if exceeded)
|
||||
- Override consensus_blocked HIGH without user confirmation
|
||||
|
||||
@@ -11,7 +11,7 @@ Template used by coordinator to generate lightweight worker role-spec files at r
|
||||
role: <role_name>
|
||||
prefix: <PREFIX>
|
||||
inner_loop: <true|false>
|
||||
subagents: [<subagent-names>]
|
||||
CLI tools: [<CLI tool-names>]
|
||||
message_types:
|
||||
success: <prefix>_complete
|
||||
error: error
|
||||
@@ -45,7 +45,7 @@ message_types:
|
||||
| `role` | Yes | Role name matching session registry |
|
||||
| `prefix` | Yes | Task prefix to filter (e.g., RESEARCH, DRAFT, IMPL) |
|
||||
| `inner_loop` | Yes | Whether team-worker loops through same-prefix tasks |
|
||||
| `subagents` | No | Array of subagent types this role may call |
|
||||
| `CLI tools` | No | Array of CLI tool types this role may call |
|
||||
| `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") |
|
||||
@@ -61,13 +61,13 @@ message_types:
|
||||
| ~80 lines target | Lightweight, domain-focused |
|
||||
| No pseudocode | Decision tables + text + tool calls only |
|
||||
| `<placeholder>` notation | Use angle brackets for variable substitution |
|
||||
| Reference subagents by name | team-worker resolves invocation from its delegation templates |
|
||||
| Reference CLI tools by name | team-worker resolves invocation from its delegation templates |
|
||||
|
||||
## 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.
|
||||
|
||||
**Design principle**: Constrain behavioral characteristics (accuracy, feedback, quality gates), NOT specific actions (which tool, which subagent, which path). Tasks are diverse — the coordinator composes task-specific Phase 2-3 instructions, while these traits ensure execution quality regardless of task type.
|
||||
**Design principle**: Constrain behavioral characteristics (accuracy, feedback, quality gates), NOT specific actions (which tool, which CLI tool, which path). Tasks are diverse — the coordinator composes task-specific Phase 2-3 instructions, while these traits ensure execution quality regardless of task type.
|
||||
|
||||
### Accuracy — outputs must be verifiable
|
||||
|
||||
@@ -95,7 +95,7 @@ Phase 4 must produce a verification summary with these fields:
|
||||
|
||||
### Error Protocol
|
||||
|
||||
- Primary approach fails → try alternative (different subagent / different tool)
|
||||
- Primary approach fails → try alternative (different CLI tool / different tool)
|
||||
- 2 retries exhausted → escalate to coordinator with failure details
|
||||
- NEVER: skip verification and report completed
|
||||
|
||||
@@ -108,7 +108,7 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a
|
||||
### Research / Exploration
|
||||
|
||||
- Phase 2: Define exploration scope + load prior knowledge from shared state and wisdom
|
||||
- Phase 3: Explore via subagents, direct tool calls, or codebase search — approach chosen by agent
|
||||
- Phase 3: Explore via CLI tools, direct tool calls, or codebase search — approach chosen by agent
|
||||
- Phase 4: Verify findings documented (Behavioral Traits) + update shared state
|
||||
|
||||
### Document / Content
|
||||
@@ -120,7 +120,7 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a
|
||||
### Code Implementation
|
||||
|
||||
- Phase 2: Load design/spec artifacts from upstream
|
||||
- Phase 3: Implement code changes — subagent choice and approach determined by task complexity
|
||||
- Phase 3: Implement code changes — CLI tool choice and approach determined by task complexity
|
||||
- Phase 4: Syntax check + file verification (Behavioral Traits) + update shared state
|
||||
|
||||
### Analysis / Audit
|
||||
|
||||
@@ -1,132 +0,0 @@
|
||||
# Discuss Subagent
|
||||
|
||||
Lightweight multi-perspective critique engine. Called inline by any role needing peer review. Perspectives are dynamic -- specified by the calling role, not pre-defined.
|
||||
|
||||
## Design
|
||||
|
||||
Unlike team-lifecycle-v4's fixed perspective definitions (product, technical, quality, risk, coverage), team-coordinate uses **dynamic perspectives** passed in the prompt. The calling role decides what viewpoints matter for its artifact.
|
||||
|
||||
## Invocation
|
||||
|
||||
Called by roles after artifact creation:
|
||||
|
||||
```javascript
|
||||
// Multi-perspective critique using CLI tools
|
||||
// The coordinator reads the artifact and launches parallel CLI analyses for each perspective
|
||||
Bash({
|
||||
command: `ccw cli -p "## Multi-Perspective Critique: <round-id>
|
||||
|
||||
### Input
|
||||
- Artifact: <artifact-path>
|
||||
- Round: <round-id>
|
||||
- Session: <session-folder>
|
||||
|
||||
### Perspectives
|
||||
<Dynamic perspective list -- each entry defines: name, cli_tool, role_label, focus_areas>
|
||||
|
||||
Example:
|
||||
| Perspective | CLI Tool | Role | Focus Areas |
|
||||
|-------------|----------|------|-------------|
|
||||
| Feasibility | gemini | Engineer | Implementation complexity, technical risks, resource needs |
|
||||
| Clarity | codex | Editor | Readability, logical flow, completeness of explanation |
|
||||
| Accuracy | gemini | Domain Expert | Factual correctness, source reliability, claim verification |
|
||||
|
||||
### Execution Steps
|
||||
1. Read artifact from <artifact-path>
|
||||
2. For each perspective, launch CLI analysis in background:
|
||||
Bash(command="ccw cli -p 'PURPOSE: Analyze from <role> perspective for <round-id>
|
||||
TASK: <focus-areas>
|
||||
MODE: analysis
|
||||
CONTEXT: Artifact content below
|
||||
EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5)
|
||||
CONSTRAINTS: Output valid JSON only
|
||||
|
||||
Artifact:
|
||||
<artifact-content>' --tool <cli-tool> --mode analysis", run_in_background=true)
|
||||
3. Wait for all CLI results
|
||||
4. Divergence detection:
|
||||
- High severity: any rating <= 2, critical issue identified
|
||||
- Medium severity: rating spread (max - min) >= 3, or single perspective rated <= 2 with others >= 3
|
||||
- Low severity: minor suggestions only, all ratings >= 3
|
||||
5. Consensus determination:
|
||||
- No high-severity divergences AND average rating >= 3.0 -> consensus_reached
|
||||
- Otherwise -> consensus_blocked
|
||||
6. Synthesize:
|
||||
- Convergent themes (agreed by 2+ perspectives)
|
||||
- Divergent views (conflicting assessments)
|
||||
- Action items from suggestions
|
||||
7. Write discussion record to: <session-folder>/discussions/<round-id>-discussion.md
|
||||
|
||||
### Discussion Record Format
|
||||
# Discussion Record: <round-id>
|
||||
|
||||
**Artifact**: <artifact-path>
|
||||
**Perspectives**: <list>
|
||||
**Consensus**: reached / blocked
|
||||
**Average Rating**: <avg>/5
|
||||
|
||||
## Convergent Themes
|
||||
- <theme>
|
||||
|
||||
## Divergent Views
|
||||
- **<topic>** (<severity>): <description>
|
||||
|
||||
## Action Items
|
||||
1. <item>
|
||||
|
||||
## Ratings
|
||||
| Perspective | Rating |
|
||||
|-------------|--------|
|
||||
| <name> | <n>/5 |
|
||||
|
||||
### Return Value
|
||||
|
||||
**When consensus_reached**:
|
||||
Return a summary string with:
|
||||
- Verdict: consensus_reached
|
||||
- Average rating
|
||||
- Key action items (top 3)
|
||||
- Discussion record path
|
||||
|
||||
**When consensus_blocked**:
|
||||
Return a structured summary with:
|
||||
- Verdict: consensus_blocked
|
||||
- Severity: HIGH | MEDIUM | LOW
|
||||
- Average rating
|
||||
- Divergence summary: top 3 divergent points with perspective attribution
|
||||
- Action items: prioritized list of required changes
|
||||
- Recommendation: revise | proceed-with-caution | escalate
|
||||
- Discussion record path
|
||||
|
||||
### Error Handling
|
||||
- Single CLI fails -> fallback to direct Claude analysis for that perspective
|
||||
- All CLI fail -> generate basic discussion from direct artifact reading
|
||||
- Artifact not found -> return error immediately`
|
||||
})
|
||||
```
|
||||
|
||||
## Integration with Calling Role
|
||||
|
||||
The calling role is responsible for:
|
||||
|
||||
1. **Before calling**: Complete primary artifact output
|
||||
2. **Calling**: Invoke discuss subagent with appropriate dynamic perspectives
|
||||
3. **After calling**:
|
||||
|
||||
| Verdict | Severity | Role Action |
|
||||
|---------|----------|-------------|
|
||||
| consensus_reached | - | Include action items in Phase 5 report, proceed normally |
|
||||
| consensus_blocked | HIGH | Include divergence details in Phase 5 SendMessage. Do NOT self-revise -- coordinator decides. |
|
||||
| consensus_blocked | MEDIUM | Include warning in Phase 5 SendMessage. Proceed normally. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. |
|
||||
|
||||
**SendMessage format for consensus_blocked (HIGH or MEDIUM)**:
|
||||
|
||||
```
|
||||
[<role>] <task-id> complete. Discuss <round-id>: consensus_blocked (severity=<severity>)
|
||||
Divergences: <top-3-divergent-points>
|
||||
Action items: <prioritized-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Artifact: <artifact-path>
|
||||
Discussion: <discussion-record-path>
|
||||
```
|
||||
@@ -1,120 +0,0 @@
|
||||
# Explore Subagent
|
||||
|
||||
Shared codebase exploration utility with centralized caching. Callable by any role needing code context.
|
||||
|
||||
## Invocation
|
||||
|
||||
```
|
||||
Agent({
|
||||
subagent_type: "Explore",
|
||||
run_in_background: false,
|
||||
description: "Explore <angle>",
|
||||
prompt: `Explore codebase for: <query>
|
||||
|
||||
Focus angle: <angle>
|
||||
Keywords: <keyword-list>
|
||||
Session folder: <session-folder>
|
||||
|
||||
## Cache Check
|
||||
1. Read <session-folder>/explorations/cache-index.json (if exists)
|
||||
2. Look for entry with matching angle
|
||||
3. If found AND file exists -> read cached result, return summary
|
||||
4. If not found -> proceed to exploration
|
||||
|
||||
## Exploration
|
||||
<angle-specific-focus-from-table-below>
|
||||
|
||||
## Output
|
||||
Write JSON to: <session-folder>/explorations/explore-<angle>.json
|
||||
Update cache-index.json with new entry
|
||||
|
||||
## Output Schema
|
||||
{
|
||||
"angle": "<angle>",
|
||||
"query": "<query>",
|
||||
"relevant_files": [
|
||||
{ "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] }
|
||||
],
|
||||
"patterns": [],
|
||||
"dependencies": [],
|
||||
"external_refs": [],
|
||||
"_metadata": { "created_by": "<calling-role>", "timestamp": "...", "cache_key": "..." }
|
||||
}
|
||||
|
||||
Return summary: file count, pattern count, top 5 files, output path`
|
||||
})
|
||||
```
|
||||
|
||||
## Cache Mechanism
|
||||
|
||||
### Cache Index Schema
|
||||
|
||||
`<session-folder>/explorations/cache-index.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"entries": [
|
||||
{
|
||||
"angle": "architecture",
|
||||
"keywords": ["auth", "middleware"],
|
||||
"file": "explore-architecture.json",
|
||||
"created_by": "analyst",
|
||||
"created_at": "2026-02-27T10:00:00Z",
|
||||
"file_count": 15
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Cache Lookup Rules
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Exact angle match exists | Return cached result |
|
||||
| No match | Execute exploration, cache result |
|
||||
| Cache file missing but index has entry | Remove stale entry, re-explore |
|
||||
|
||||
### Cache Invalidation
|
||||
|
||||
Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache.
|
||||
|
||||
## Angle Focus Guide
|
||||
|
||||
| Angle | Focus Points | Typical Caller |
|
||||
|-------|-------------|----------------|
|
||||
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | any |
|
||||
| dependencies | Import chains, external libraries, circular dependencies, shared utilities | any |
|
||||
| modularity | Module interfaces, separation of concerns, extraction opportunities | any |
|
||||
| integration-points | API endpoints, data flow between modules, event systems | any |
|
||||
| security | Auth/authz logic, input validation, sensitive data handling, middleware | any |
|
||||
| dataflow | Data transformations, state propagation, validation points | any |
|
||||
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | any |
|
||||
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | any |
|
||||
| patterns | Code conventions, design patterns, naming conventions, best practices | any |
|
||||
| testing | Test files, coverage gaps, test patterns, mocking strategies | any |
|
||||
| general | Broad semantic search for topic-related code | any |
|
||||
|
||||
## Exploration Strategies
|
||||
|
||||
### Low Complexity (direct search)
|
||||
|
||||
For simple queries, use ACE semantic search:
|
||||
|
||||
```
|
||||
mcp__ace-tool__search_context(project_root_path="<project-root>", query="<query>")
|
||||
```
|
||||
|
||||
ACE failure fallback: `rg -l '<keywords>' --type ts`
|
||||
|
||||
### Medium/High Complexity (multi-angle)
|
||||
|
||||
For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles.
|
||||
|
||||
## Search Tool Priority
|
||||
|
||||
| Tool | Priority | Use Case |
|
||||
|------|----------|----------|
|
||||
| mcp__ace-tool__search_context | P0 | Semantic search |
|
||||
| Grep / Glob | P1 | Pattern matching |
|
||||
| cli-explore-agent | Deep | Multi-angle exploration |
|
||||
| WebSearch | P3 | External docs |
|
||||
Reference in New Issue
Block a user