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,6 @@ Unified team skill: Profile application performance, identify bottlenecks, desig
|
||||
profiler strate- optim- bench- review-
|
||||
gist izer marker er
|
||||
|
||||
Subagents (callable by workers, not team members):
|
||||
[explore] [discuss]
|
||||
|
||||
(tw) = team-worker agent
|
||||
```
|
||||
|
||||
@@ -52,13 +49,6 @@ Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
|
||||
| benchmarker | [role-specs/benchmarker.md](role-specs/benchmarker.md) | BENCH-* | validation | false |
|
||||
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* / QUALITY-* | read_only_analysis | false |
|
||||
|
||||
### Subagent Registry
|
||||
|
||||
| Subagent | Spec | Callable By | Purpose |
|
||||
|----------|------|-------------|---------|
|
||||
| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | profiler, optimizer | Shared codebase exploration for performance-critical code paths |
|
||||
| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | strategist, reviewer | Multi-perspective discussion for optimization approaches and review findings |
|
||||
|
||||
### Dispatch
|
||||
|
||||
Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
|
||||
@@ -459,7 +449,7 @@ Coordinator supports `--resume` / `--continue` for interrupted sessions:
|
||||
|----------|------------|
|
||||
| Role spec file not found | Error with expected path (role-specs/<name>.md) |
|
||||
| Command file not found | Fallback to inline execution in coordinator role.md |
|
||||
| Subagent spec not found | Error with expected path (subagents/<name>-subagent.md) |
|
||||
| Role file not found | Error with expected path (role-specs/<name>.md) |
|
||||
| Fast-advance orphan detected | Coordinator resets task to pending on next check |
|
||||
| consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline |
|
||||
| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md |
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
prefix: IMPL
|
||||
inner_loop: true
|
||||
additional_prefixes: [FIX]
|
||||
subagents: [explore]
|
||||
delegates_to: []
|
||||
message_types:
|
||||
success: impl_complete
|
||||
error: error
|
||||
@@ -47,7 +47,7 @@ Implement optimization changes following the strategy plan. For FIX tasks, apply
|
||||
- **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md` -- extract this pipeline's plan
|
||||
|
||||
4. For FIX: parse review/benchmark feedback for specific issues to address
|
||||
5. Use `explore` subagent to load implementation context for target files
|
||||
5. Use ACE search or CLI tools to load implementation context for target files
|
||||
6. For inner loop (single mode only): load context_accumulator from prior IMPL/FIX tasks
|
||||
|
||||
**Shared-memory namespace**:
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
prefix: PROFILE
|
||||
inner_loop: false
|
||||
subagents: [explore]
|
||||
delegates_to: []
|
||||
message_types:
|
||||
success: profile_complete
|
||||
error: error
|
||||
@@ -31,7 +31,7 @@ Profile application performance to identify CPU, memory, I/O, network, and rende
|
||||
| CLI entry / bin/ directory | CLI Tool | Startup time, throughput, memory peak |
|
||||
| No detection | Generic | All profiling dimensions |
|
||||
|
||||
3. Use `explore` subagent to map performance-critical code paths within target scope
|
||||
3. Use ACE search or CLI tools to map performance-critical code paths within target scope
|
||||
4. Detect available profiling tools (test runners, benchmark harnesses, linting tools)
|
||||
|
||||
## Phase 3: Performance Profiling
|
||||
|
||||
@@ -3,7 +3,7 @@ prefix: REVIEW
|
||||
inner_loop: false
|
||||
additional_prefixes: [QUALITY]
|
||||
discuss_rounds: [DISCUSS-REVIEW]
|
||||
subagents: [discuss]
|
||||
delegates_to: []
|
||||
message_types:
|
||||
success: review_complete
|
||||
error: error
|
||||
@@ -65,7 +65,7 @@ Per-dimension review process:
|
||||
- Record findings with severity (Critical / High / Medium / Low)
|
||||
- Include specific file:line references and suggested fixes
|
||||
|
||||
If any Critical findings detected, invoke `discuss` subagent (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
|
||||
If any Critical findings detected, use CLI tools for multi-perspective validation (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
|
||||
|
||||
## Phase 4: Verdict & Feedback
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
prefix: STRATEGY
|
||||
inner_loop: false
|
||||
discuss_rounds: [DISCUSS-OPT]
|
||||
subagents: [discuss]
|
||||
delegates_to: []
|
||||
message_types:
|
||||
success: strategy_complete
|
||||
error: error
|
||||
@@ -55,7 +55,7 @@ Prioritize optimizations by impact/effort ratio:
|
||||
| P2 (Medium) | Medium impact + Low effort |
|
||||
| P3 (Low) | Low impact or High effort -- defer |
|
||||
|
||||
If complexity is High, invoke `discuss` subagent (DISCUSS-OPT round) to evaluate trade-offs between competing strategies before finalizing the plan.
|
||||
If complexity is High, use CLI tools for multi-perspective analysis (DISCUSS-OPT round) to evaluate trade-offs between competing strategies before finalizing the plan.
|
||||
|
||||
Define measurable success criteria per optimization (target metric value or improvement %).
|
||||
|
||||
|
||||
@@ -1,89 +0,0 @@
|
||||
# Discuss Subagent
|
||||
|
||||
Multi-perspective discussion for evaluating optimization strategies and reviewing code change quality. Used by strategist (DISCUSS-OPT) and reviewer (DISCUSS-REVIEW) when complex trade-offs require multi-angle analysis.
|
||||
|
||||
## Design Rationale
|
||||
|
||||
Complex optimization decisions (e.g., choosing between algorithmic change vs caching layer) and nuanced code review findings (e.g., evaluating whether a side effect is acceptable) benefit from structured multi-perspective analysis. This subagent provides that analysis inline without spawning additional team members.
|
||||
|
||||
## Invocation
|
||||
|
||||
Called by strategist, reviewer after their primary analysis when complexity warrants multi-perspective evaluation:
|
||||
|
||||
```
|
||||
Agent({
|
||||
subagent_type: "cli-discuss-agent",
|
||||
run_in_background: false,
|
||||
description: "Discuss <round-id>: <topic> for performance optimization",
|
||||
prompt: `Conduct a multi-perspective discussion on the following topic.
|
||||
|
||||
Round: <round-id>
|
||||
Topic: <discussion-topic>
|
||||
Session: <session-folder>
|
||||
|
||||
Context:
|
||||
<relevant-context-from-calling-role>
|
||||
|
||||
Perspectives to consider:
|
||||
- Performance impact: Will this actually improve the target metric?
|
||||
- Risk assessment: What could go wrong? Side effects? Regressions?
|
||||
- Maintainability: Is the optimized code still understandable and maintainable?
|
||||
- Alternative approaches: Are there simpler or safer ways to achieve the same goal?
|
||||
|
||||
Evaluate trade-offs and provide a structured recommendation with:
|
||||
- Consensus verdict: proceed / revise / escalate
|
||||
- Confidence level: high / medium / low
|
||||
- Key trade-offs identified
|
||||
- Recommended approach with rationale
|
||||
- Dissenting perspectives (if any)`
|
||||
})
|
||||
```
|
||||
|
||||
## Round Configuration
|
||||
|
||||
| Round | Artifact | Parameters | Calling Role |
|
||||
|-------|----------|------------|-------------|
|
||||
| DISCUSS-OPT | <session>/discussions/DISCUSS-OPT.md | Optimization strategy trade-offs | strategist |
|
||||
| DISCUSS-REVIEW | <session>/discussions/DISCUSS-REVIEW.md | Code review finding validation | reviewer |
|
||||
|
||||
## Integration with Calling Role
|
||||
|
||||
The calling role is responsible for:
|
||||
|
||||
1. **Before calling**: Complete primary analysis, identify the specific trade-off or finding needing discussion
|
||||
2. **Calling**: Invoke subagent with round ID, topic, and relevant context
|
||||
3. **After calling**:
|
||||
|
||||
| Result | Action |
|
||||
|--------|--------|
|
||||
| consensus_reached (proceed) | Incorporate recommendation into output, continue |
|
||||
| consensus_reached (revise) | Adjust findings/strategy based on discussion insights |
|
||||
| consensus_blocked (HIGH) | Report to coordinator via message with severity |
|
||||
| consensus_blocked (MEDIUM) | Include in output with recommendation for revision |
|
||||
| consensus_blocked (LOW) | Note in output, proceed with original assessment |
|
||||
|
||||
## Output Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"round_id": "<DISCUSS-OPT|DISCUSS-REVIEW>",
|
||||
"topic": "<discussion-topic>",
|
||||
"verdict": "<proceed|revise|escalate>",
|
||||
"confidence": "<high|medium|low>",
|
||||
"trade_offs": [
|
||||
{ "dimension": "<performance|risk|maintainability>", "pro": "<benefit>", "con": "<cost>" }
|
||||
],
|
||||
"recommendation": "<recommended-approach>",
|
||||
"rationale": "<reasoning>",
|
||||
"dissenting_views": ["<alternative-perspective>"]
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Single perspective analysis fails | Continue with partial perspectives |
|
||||
| All analyses fail | Return basic recommendation from calling role's primary analysis |
|
||||
| Artifact not found | Return error immediately |
|
||||
| Discussion inconclusive | Return "revise" verdict with low confidence |
|
||||
@@ -1,108 +0,0 @@
|
||||
# Explore Subagent
|
||||
|
||||
Shared codebase exploration for discovering performance-critical code paths, module structures, and optimization opportunities. Results are cached to avoid redundant exploration across profiler and optimizer roles.
|
||||
|
||||
## Design Rationale
|
||||
|
||||
Codebase exploration is a read-only operation shared between profiler (mapping bottlenecks) and optimizer (understanding implementation context). Caching explorations avoids redundant work when optimizer re-explores paths the profiler already mapped.
|
||||
|
||||
## Invocation
|
||||
|
||||
Called by profiler, optimizer after needing codebase context for performance analysis or implementation:
|
||||
|
||||
```
|
||||
Agent({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: "Explore codebase for performance-critical paths in <target-scope>",
|
||||
prompt: `Explore the codebase to identify performance-critical code paths.
|
||||
|
||||
Target scope: <target-scope>
|
||||
Session: <session-folder>
|
||||
Focus: <exploration-focus>
|
||||
|
||||
Tasks:
|
||||
1. Map the module structure and entry points within scope
|
||||
2. Identify hot code paths (frequently called functions, critical loops)
|
||||
3. Find performance-relevant patterns (caching, lazy loading, async, pooling)
|
||||
4. Note any existing performance optimizations or benchmark harnesses
|
||||
5. List key files with their roles in the performance-critical path
|
||||
|
||||
Output a structured exploration report with:
|
||||
- Module map (key files and their relationships)
|
||||
- Hot path analysis (call chains, loop nests, recursive patterns)
|
||||
- Existing optimization patterns found
|
||||
- Performance-relevant configuration (caching, pooling, batching settings)
|
||||
- Recommended investigation targets for profiling`
|
||||
})
|
||||
```
|
||||
|
||||
## Cache Mechanism
|
||||
|
||||
### Cache Index Schema
|
||||
|
||||
`<session-folder>/explorations/cache-index.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"entries": [
|
||||
{
|
||||
"key": "<scope-hash>",
|
||||
"scope": "<target-scope>",
|
||||
"focus": "<exploration-focus>",
|
||||
"timestamp": "<ISO-8601>",
|
||||
"result_file": "<hash>.md"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Cache Lookup Rules
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Exact scope+focus match exists | Return cached result from <hash>.md |
|
||||
| No match | Execute subagent, cache result to <hash>.md, update index |
|
||||
| Cache file missing but index has entry | Remove stale entry, re-execute |
|
||||
| Cache older than current session | Use cached (explorations are stable within session) |
|
||||
|
||||
## Integration with Calling Role
|
||||
|
||||
The calling role is responsible for:
|
||||
|
||||
1. **Before calling**: Determine target scope and exploration focus
|
||||
2. **Calling**: Check cache first, invoke subagent only on cache miss
|
||||
3. **After calling**:
|
||||
|
||||
| Result | Action |
|
||||
|--------|--------|
|
||||
| Exploration successful | Use findings to inform profiling/implementation |
|
||||
| Exploration partial | Use available findings, note gaps |
|
||||
| Exploration failed | Proceed without exploration context, use direct file reading |
|
||||
|
||||
## Output Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"scope": "<target-scope>",
|
||||
"module_map": [
|
||||
{ "file": "<path>", "role": "<description>", "hot_path": true }
|
||||
],
|
||||
"hot_paths": [
|
||||
{ "chain": "<call-chain>", "frequency": "<high|medium|low>", "files": ["<path>"] }
|
||||
],
|
||||
"existing_optimizations": [
|
||||
{ "type": "<pattern>", "location": "<file:line>", "description": "<what>" }
|
||||
],
|
||||
"investigation_targets": ["<file-or-pattern>"]
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Single exploration angle fails | Continue with partial results |
|
||||
| All exploration fails | Return basic result from direct file listing |
|
||||
| Target scope not found | Return error immediately |
|
||||
| Cache corrupt | Clear cache-index.json, re-execute |
|
||||
Reference in New Issue
Block a user