catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-06 16:31:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add document standards, quality gates, and templates for team lifecycle phases

Browse Source 
- 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
2026-03-04 23:54:20 +08:00
parent fd0c9efa4d
commit bbdd1840de
103 changed files with 1959 additions and 1311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude/skills/team-arch-opt/SKILL.md
View File

@@ -27,7 +27,7 @@ Unified team skill: Analyze codebase architecture, identify structural issues (d
analyzer desig- refact- valid- review-
ner orer ator er
Subagents (callable by workers, not team members):
CLI Tools (callable by workers inline):
[explore] [discuss]
(tw) = team-worker agent
@@ -52,12 +52,12 @@ Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
| validator | [role-specs/validator.md](role-specs/validator.md) | VALIDATE-* | validation | false |
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* / QUALITY-* | read_only_analysis | false |
### Subagent Registry
### CLI Tool Registry
| Subagent | Spec | Callable By | Purpose |
|----------|------|-------------|---------|
| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | analyzer, refactorer | Shared codebase exploration for architecture-critical structures and dependency graphs |
| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | designer, reviewer | Multi-perspective discussion for refactoring approaches and review findings |
| Tool | Spec | Used By | Purpose |
|------|------|---------|---------|
| explore | [cli-tools/explore.md](cli-tools/explore.md) | analyzer, refactorer | Shared codebase exploration for architecture-critical structures and dependency graphs |
| discuss | [cli-tools/discuss.md](cli-tools/discuss.md) | designer, reviewer | Multi-perspective discussion for refactoring approaches and review findings |
### Dispatch
@@ -460,7 +460,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) |
| CLI tool spec not found | Error with expected path (cli-tools/<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 |

4
.claude/skills/team-arch-opt/role-specs/analyzer.md
View File

@@ -1,7 +1,7 @@
---
prefix: ANALYZE
inner_loop: false
subagents: [explore]
cli_tools: [explore]
message_types:
success: analyze_complete
error: error
@@ -31,7 +31,7 @@ Analyze codebase architecture to identify structural issues: dependency cycles,
| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering |
| No detection | Generic | All architecture dimensions |
3. Use `explore` subagent to map module structure, dependency graph, and layer boundaries within target scope
3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope
4. Detect available analysis tools (linters, dependency analyzers, build tools)
## Phase 3: Architecture Analysis

4
.claude/skills/team-arch-opt/role-specs/designer.md
View File

@@ -2,7 +2,7 @@
prefix: DESIGN
inner_loop: false
discuss_rounds: [DISCUSS-REFACTOR]
subagents: [discuss]
cli_tools: [discuss]
message_types:
success: design_complete
error: error
@@ -57,7 +57,7 @@ Prioritize refactorings by impact/effort ratio:
| P2 (Medium) | Medium impact + Low effort (duplication extraction) |
| P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) |
If complexity is High, invoke `discuss` subagent (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.
If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.
Define measurable success criteria per refactoring (target metric improvement or structural change).

4
.claude/skills/team-arch-opt/role-specs/refactorer.md
View File

@@ -2,7 +2,7 @@
prefix: REFACTOR
inner_loop: true
additional_prefixes: [FIX]
subagents: [explore]
cli_tools: [explore]
message_types:
success: refactor_complete
error: error
@@ -47,7 +47,7 @@ Implement architecture refactoring changes following the design plan. For FIX ta
- **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md` -- extract this pipeline's plan
4. For FIX: parse review/validation feedback for specific issues to address
5. Use `explore` subagent to load implementation context for target files
5. Use `explore` CLI tool to load implementation context for target files
6. For inner loop (single mode only): load context_accumulator from prior REFACTOR/FIX tasks
**Meta.json namespace**:

4
.claude/skills/team-arch-opt/role-specs/reviewer.md
View File

@@ -3,7 +3,7 @@ prefix: REVIEW
inner_loop: false
additional_prefixes: [QUALITY]
discuss_rounds: [DISCUSS-REVIEW]
subagents: [discuss]
cli_tools: [discuss]
message_types:
success: review_complete
error: error
@@ -90,7 +90,7 @@ Per-dimension review process:
- Dependency direction follows layer conventions (dependencies flow inward)
- Appropriate abstraction level (not over-engineered, not under-abstracted)
If any Critical findings detected, invoke `discuss` subagent (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
If any Critical findings detected, invoke `discuss` CLI tool (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
## Phase 4: Verdict & Feedback

16
.claude/skills/team-arch-opt/specs/team-config.json
View File

@@ -31,7 +31,7 @@
"inner_loop": false,
"additional_prefixes": [],
"discuss_rounds": [],
"subagents": ["explore"],
"cli_tools": ["explore"],
"message_types": {
"success": "analyze_complete",
"error": "error"
@@ -51,7 +51,7 @@
"inner_loop": false,
"additional_prefixes": [],
"discuss_rounds": ["DISCUSS-REFACTOR"],
"subagents": ["discuss"],
"cli_tools": ["discuss"],
"message_types": {
"success": "design_complete",
"error": "error"
@@ -71,7 +71,7 @@
"inner_loop": true,
"additional_prefixes": ["FIX"],
"discuss_rounds": [],
"subagents": ["explore"],
"cli_tools": ["explore"],
"message_types": {
"success": "refactor_complete",
"error": "error",
@@ -92,7 +92,7 @@
"inner_loop": false,
"additional_prefixes": [],
"discuss_rounds": [],
"subagents": [],
"cli_tools": [],
"message_types": {
"success": "validate_complete",
"error": "error",
@@ -113,7 +113,7 @@
"inner_loop": false,
"additional_prefixes": ["QUALITY"],
"discuss_rounds": ["DISCUSS-REVIEW"],
"subagents": ["discuss"],
"cli_tools": ["discuss"],
"message_types": {
"success": "review_complete",
"error": "error",
@@ -193,10 +193,10 @@
"diagram": "See pipeline-diagram section"
},
"subagents": [
"cli_tools": [
{
"name": "explore",
"agent_type": "cli-explore-agent",
"implementation": "ccw cli with analysis mode",
"callable_by": ["analyzer", "refactorer"],
"purpose": "Shared codebase exploration for architecture-critical structures, dependency graphs, and module boundaries",
"has_cache": true,
@@ -204,7 +204,7 @@
},
{
"name": "discuss",
"agent_type": "cli-discuss-agent",
"implementation": "ccw cli with analysis mode",
"callable_by": ["designer", "reviewer"],
"purpose": "Multi-perspective discussion for refactoring approaches and review findings",
"has_cache": false

123
.claude/skills/team-arch-opt/subagents/discuss-subagent.md
View File

@@ -1,123 +0,0 @@
# Discuss Subagent
Multi-perspective discussion for evaluating refactoring strategies and reviewing code change quality. Used by designer (DISCUSS-REFACTOR) and reviewer (DISCUSS-REVIEW) when complex trade-offs require multi-angle analysis.
## Design Rationale
Complex refactoring decisions (e.g., choosing between dependency inversion vs mediator pattern to break a cycle) and nuanced code review findings (e.g., evaluating whether a temporary coupling increase is acceptable) benefit from structured multi-perspective analysis. This subagent provides that analysis inline without spawning additional team members.
## Invocation
Called by designer, reviewer after their primary analysis when complexity warrants multi-perspective evaluation:
```javascript
// Multi-perspective discussion using CLI tools
Bash({
command: `ccw cli -p "PURPOSE: Conduct multi-perspective discussion on <topic> for architecture optimization
TASK: • Evaluate architecture impact • Assess risks and trade-offs • Consider maintainability • Explore alternatives
MODE: analysis
CONTEXT: @<session-folder>/discussions/<round-id>.md | Memory: <relevant-context-from-calling-role>
EXPECTED: Structured recommendation with consensus verdict (proceed/revise/escalate), confidence level, key trade-offs, recommended approach with rationale, dissenting perspectives
CONSTRAINTS: Focus on <round-id> topic
Round: <round-id>
Topic: <discussion-topic>
Session: <session-folder>
Context:
<relevant-context-from-calling-role>
Perspectives to consider:
- Architecture impact: Will this actually improve the target structural metric?
- Risk assessment: What could break? Dangling references? Behavioral changes? Migration risk?
- Maintainability: Is the refactored code more understandable and maintainable?
- Alternative approaches: Are there simpler or safer ways to achieve the same structural improvement?
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)" --tool gemini --mode analysis`,
run_in_background: false
})
```
**Alternative: Direct multi-perspective analysis**
For simpler discussions, call CLI tool directly without wrapper:
```javascript
Bash({
command: `ccw cli -p "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:
- Architecture impact: Will this actually improve the target structural metric?
- Risk assessment: What could break? Dangling references? Behavioral changes? Migration risk?
- Maintainability: Is the refactored code more understandable and maintainable?
- Alternative approaches: Are there simpler or safer ways to achieve the same structural improvement?
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-REFACTOR | <session>/discussions/DISCUSS-REFACTOR.md | Refactoring strategy trade-offs | designer |
| 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-REFACTOR|DISCUSS-REVIEW>",
"topic": "<discussion-topic>",
"verdict": "<proceed|revise|escalate>",
"confidence": "<high|medium|low>",
"trade_offs": [
{ "dimension": "<architecture|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 |

113
.claude/skills/team-arch-opt/subagents/explore-subagent.md
View File

@@ -1,113 +0,0 @@
# Explore Subagent
Shared codebase exploration for discovering architecture-critical structures, dependency graphs, module boundaries, and layer organization. Results are cached to avoid redundant exploration across analyzer and refactorer roles.
## Design Rationale
Codebase exploration is a read-only operation shared between analyzer (mapping structural issues) and refactorer (understanding implementation context). Caching explorations avoids redundant work when refactorer re-explores structures the analyzer already mapped.
## Invocation
Called by analyzer, refactorer after needing codebase context for architecture analysis or implementation:
```
Agent({
subagent_type: "Explore",
run_in_background: false,
description: "Explore codebase for architecture-critical structures in <target-scope>",
prompt: `Explore the codebase to identify architecture-critical structures.
Target scope: <target-scope>
Session: <session-folder>
Focus: <exploration-focus>
Tasks:
1. Map the module structure, entry points, and layer boundaries within scope
2. Build dependency graph (import/require relationships between modules)
3. Identify architectural patterns (layering, dependency injection, event-driven, plugin architecture)
4. Note any existing abstractions, interfaces, and module boundaries
5. List key files with their roles, layer assignment, and dependency relationships
Output a structured exploration report with:
- Module map (key files, their relationships, and layer assignments)
- Dependency graph (directed edges between modules, cycle indicators)
- Layer structure (identified layers and their boundaries)
- Existing architectural patterns found
- Architecture-relevant configuration (path aliases, barrel exports, module boundaries)`
})
```
## 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 analysis/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>", "layer": "<presentation|domain|data|infra>", "dependency_graph": { "imports": ["<path>"], "imported_by": ["<path>"] } }
],
"dependency_graph": {
"nodes": ["<module-path>"],
"edges": [{ "from": "<path>", "to": "<path>", "type": "<import|re-export|dynamic>" }],
"cycles": [["<path-a>", "<path-b>", "<path-a>"]]
},
"layer_structure": [
{ "layer": "<name>", "modules": ["<path>"], "violations": ["<description>"] }
],
"existing_patterns": [
{ "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 |