mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
feat: Add comprehensive test generation and evaluation commands
- Introduced `/workflow:test-gen` command to automate test workflow generation based on completed implementation tasks, including detailed lifecycle phases, task decomposition, and agent assignment. - Implemented `/workflow:concept-eval` command for pre-planning evaluation of concepts, assessing feasibility, risks, and optimization recommendations using strategic and technical analysis tools. - Added `/workflow:docs` command for generating hierarchical architecture and API documentation, with structured task creation and session management. - Developed `/workflow:status` command to provide on-demand views of workflow state, supporting multiple formats and validation checks for task integrity and relationships.
This commit is contained in:
catlog22
407
.claude/commands/workflow/tools/concept-eval.md
Normal file
407
.claude/commands/workflow/tools/concept-eval.md
Normal file
@@ -0,0 +1,407 @@
|
||||
---
|
||||
name: concept-eval
|
||||
description: Evaluate concept planning before implementation with intelligent tool analysis
|
||||
usage: /workflow:concept-eval [--tool gemini|codex|both] <input>
|
||||
argument-hint: [--tool gemini|codex|both] "concept description"|file.md|ISS-001
|
||||
examples:
|
||||
- /workflow:concept-eval "Build microservices architecture"
|
||||
- /workflow:concept-eval --tool gemini requirements.md
|
||||
- /workflow:concept-eval --tool both ISS-001
|
||||
allowed-tools: Task(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*)
|
||||
---
|
||||
|
||||
# Workflow Concept Evaluation Command
|
||||
|
||||
## Overview
|
||||
Pre-planning evaluation command that assesses concept feasibility, identifies potential issues, and provides optimization recommendations before formal planning begins. **Works before `/workflow:plan`** to catch conceptual problems early and improve initial design quality.
|
||||
|
||||
## Core Responsibilities
|
||||
- **Concept Analysis**: Evaluate design concepts for architectural soundness
|
||||
- **Feasibility Assessment**: Technical and resource feasibility evaluation
|
||||
- **Risk Identification**: Early identification of potential implementation risks
|
||||
- **Optimization Suggestions**: Generate actionable improvement recommendations
|
||||
- **Context Integration**: Leverage existing codebase patterns and documentation
|
||||
- **Tool Selection**: Use gemini for strategic analysis, codex for technical assessment
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:concept-eval [--tool gemini|codex|both] <input>
|
||||
```
|
||||
|
||||
## Parameters
|
||||
- **--tool**: Specify evaluation tool (default: both)
|
||||
- `gemini`: Strategic and architectural evaluation
|
||||
- `codex`: Technical feasibility and implementation assessment
|
||||
- `both`: Comprehensive dual-perspective analysis
|
||||
- **input**: Concept description, file path, or issue reference
|
||||
|
||||
## Input Detection
|
||||
- **Files**: `.md/.txt/.json/.yaml/.yml` → Reads content and extracts concept requirements
|
||||
- **Issues**: `ISS-*`, `ISSUE-*`, `*-request-*` → Loads issue data and requirement specifications
|
||||
- **Text**: Everything else → Parses natural language concept descriptions
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### Evaluation Process
|
||||
The command performs comprehensive concept evaluation through:
|
||||
|
||||
**0. Context Preparation** ⚠️ FIRST STEP
|
||||
- **MCP Tools Integration**: Use Code Index for codebase exploration, Exa for external context
|
||||
- **Documentation loading**: Automatic context gathering based on concept scope
|
||||
- **Always check**: `CLAUDE.md`, `README.md` - Project context and conventions
|
||||
- **For architecture concepts**: `.workflow/docs/architecture/`, existing system patterns
|
||||
- **For specific modules**: `.workflow/docs/modules/[relevant-module]/` documentation
|
||||
- **For API concepts**: `.workflow/docs/api/` specifications
|
||||
- **Claude Code Memory Integration**: Access conversation history and previous work context
|
||||
- **Session Memory**: Current session analysis and decisions
|
||||
- **Project Memory**: Previous implementations and lessons learned
|
||||
- **Pattern Memory**: Successful approaches and anti-patterns identified
|
||||
- **Context Continuity**: Reference previous concept evaluations and outcomes
|
||||
- **Context-driven selection**: Only load documentation relevant to the concept scope
|
||||
- **Pattern analysis**: Identify existing implementation patterns and conventions
|
||||
|
||||
**1. Input Processing & Context Gathering**
|
||||
- Parse input to extract concept requirements and scope
|
||||
- Automatic tool assignment based on evaluation needs:
|
||||
- **Strategic evaluation** (gemini): Architectural soundness, design patterns, business alignment
|
||||
- **Technical assessment** (codex): Implementation complexity, technical feasibility, resource requirements
|
||||
- **Comprehensive analysis** (both): Combined strategic and technical evaluation
|
||||
- Load relevant project documentation and existing patterns
|
||||
|
||||
**2. Concept Analysis** ⚠️ CRITICAL EVALUATION PHASE
|
||||
- **Conceptual integrity**: Evaluate design coherence and completeness
|
||||
- **Architectural soundness**: Assess alignment with existing system architecture
|
||||
- **Technical feasibility**: Analyze implementation complexity and resource requirements
|
||||
- **Risk assessment**: Identify potential technical and business risks
|
||||
- **Dependency analysis**: Map required dependencies and integration points
|
||||
|
||||
**3. Evaluation Execution**
|
||||
Based on tool selection, execute appropriate analysis:
|
||||
|
||||
**Gemini Strategic Analysis**:
|
||||
```bash
|
||||
~/.claude/scripts/gemini-wrapper -p "
|
||||
PURPOSE: Strategic evaluation of concept design and architecture
|
||||
TASK: Analyze concept for architectural soundness, design patterns, and strategic alignment
|
||||
CONTEXT: @{CLAUDE.md,README.md,.workflow/docs/**/*} Concept requirements and existing patterns | Previous conversation context and Claude Code session memory for continuity and pattern recognition
|
||||
EXPECTED: Strategic assessment with architectural recommendations informed by session history
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/concept-eval.txt) | Focus on strategic soundness and design quality | Reference previous evaluations and lessons learned
|
||||
"
|
||||
```
|
||||
|
||||
**Codex Technical Assessment**:
|
||||
```bash
|
||||
codex --full-auto exec "
|
||||
PURPOSE: Technical feasibility assessment of concept implementation
|
||||
TASK: Evaluate implementation complexity, technical risks, and resource requirements
|
||||
CONTEXT: @{CLAUDE.md,README.md,src/**/*} Concept requirements and existing codebase | Current session work context and previous technical decisions
|
||||
EXPECTED: Technical assessment with implementation recommendations building on session memory
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/concept-eval.txt) | Focus on technical feasibility and implementation complexity | Consider previous technical approaches and outcomes
|
||||
" -s danger-full-access
|
||||
```
|
||||
|
||||
**Combined Analysis** (when --tool both):
|
||||
Execute both analyses in parallel, then synthesize results for comprehensive evaluation.
|
||||
|
||||
**4. Optimization Recommendations**
|
||||
- **Design improvements**: Architectural and design optimization suggestions
|
||||
- **Risk mitigation**: Strategies to address identified risks
|
||||
- **Implementation approach**: Recommended technical approaches and patterns
|
||||
- **Resource optimization**: Efficient resource utilization strategies
|
||||
- **Integration suggestions**: Optimal integration with existing systems
|
||||
|
||||
## Implementation Standards
|
||||
|
||||
### Evaluation Criteria ⚠️ CRITICAL
|
||||
Concept evaluation focuses on these key dimensions:
|
||||
|
||||
**Strategic Evaluation (Gemini)**:
|
||||
1. **Architectural Soundness**: Design coherence and system integration
|
||||
2. **Business Alignment**: Concept alignment with business objectives
|
||||
3. **Scalability Considerations**: Long-term growth and expansion potential
|
||||
4. **Design Patterns**: Appropriate use of established design patterns
|
||||
5. **Risk Assessment**: Strategic and business risk identification
|
||||
|
||||
**Technical Assessment (Codex)**:
|
||||
1. **Implementation Complexity**: Technical difficulty and effort estimation
|
||||
2. **Technical Feasibility**: Availability of required technologies and skills
|
||||
3. **Resource Requirements**: Development time, infrastructure, and team resources
|
||||
4. **Integration Challenges**: Technical integration complexity and risks
|
||||
5. **Performance Implications**: System performance and scalability impact
|
||||
|
||||
### Evaluation Context Loading ⚠️ CRITICAL
|
||||
Context preparation ensures comprehensive evaluation:
|
||||
|
||||
```json
|
||||
// Context loading strategy for concept evaluation
|
||||
"context_preparation": {
|
||||
"required_docs": [
|
||||
"CLAUDE.md",
|
||||
"README.md"
|
||||
],
|
||||
"conditional_docs": {
|
||||
"architecture_concepts": [
|
||||
".workflow/docs/architecture/",
|
||||
"docs/system-design.md"
|
||||
],
|
||||
"api_concepts": [
|
||||
".workflow/docs/api/",
|
||||
"api-documentation.md"
|
||||
],
|
||||
"module_concepts": [
|
||||
".workflow/docs/modules/[relevant-module]/",
|
||||
"src/[module]/**/*.md"
|
||||
]
|
||||
},
|
||||
"pattern_analysis": {
|
||||
"existing_implementations": "src/**/*",
|
||||
"configuration_patterns": "config/",
|
||||
"test_patterns": "test/**/*"
|
||||
},
|
||||
"claude_code_memory": {
|
||||
"session_context": "Current session conversation history and decisions",
|
||||
"project_memory": "Previous implementations and lessons learned across sessions",
|
||||
"pattern_memory": "Successful approaches and anti-patterns identified",
|
||||
"evaluation_history": "Previous concept evaluations and their outcomes",
|
||||
"technical_decisions": "Past technical choices and their rationale",
|
||||
"architectural_evolution": "System architecture changes and migration patterns"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Analysis Output Structure
|
||||
|
||||
**Evaluation Categories**:
|
||||
```markdown
|
||||
## Concept Evaluation Summary
|
||||
|
||||
### ✅ Strengths Identified
|
||||
- [ ] **Design Quality**: Well-defined architectural approach
|
||||
- [ ] **Technical Approach**: Appropriate technology selection
|
||||
- [ ] **Integration**: Good fit with existing systems
|
||||
|
||||
### ⚠️ Areas for Improvement
|
||||
- [ ] **Complexity**: Reduce implementation complexity in module X
|
||||
- [ ] **Dependencies**: Simplify dependency management approach
|
||||
- [ ] **Scalability**: Address potential performance bottlenecks
|
||||
|
||||
### ❌ Critical Issues
|
||||
- [ ] **Architecture**: Conflicts with existing system design
|
||||
- [ ] **Resources**: Insufficient resources for proposed timeline
|
||||
- [ ] **Risk**: High technical risk in component Y
|
||||
|
||||
### 🎯 Optimization Recommendations
|
||||
- [ ] **Alternative Approach**: Consider microservices instead of monolithic design
|
||||
- [ ] **Technology Stack**: Use existing React patterns instead of Vue
|
||||
- [ ] **Implementation Strategy**: Phase implementation to reduce risk
|
||||
```
|
||||
|
||||
## Document Generation & Output
|
||||
|
||||
**Evaluation Workflow**: Input Processing → Context Loading → Analysis Execution → Report Generation → Recommendations
|
||||
|
||||
**Always Created**:
|
||||
- **CONCEPT_EVALUATION.md**: Complete evaluation results and recommendations
|
||||
- **evaluation-session.json**: Evaluation metadata and tool configuration
|
||||
- **OPTIMIZATION_SUGGESTIONS.md**: Actionable improvement recommendations
|
||||
|
||||
**Auto-Created (for comprehensive analysis)**:
|
||||
- **strategic-analysis.md**: Gemini strategic evaluation results
|
||||
- **technical-assessment.md**: Codex technical feasibility analysis
|
||||
- **risk-assessment-matrix.md**: Comprehensive risk evaluation
|
||||
- **implementation-roadmap.md**: Recommended implementation approach
|
||||
|
||||
**Document Structure**:
|
||||
```
|
||||
.workflow/WFS-[topic]/.evaluation/
|
||||
├── evaluation-session.json # Evaluation session metadata
|
||||
├── CONCEPT_EVALUATION.md # Complete evaluation results
|
||||
├── OPTIMIZATION_SUGGESTIONS.md # Actionable recommendations
|
||||
├── strategic-analysis.md # Gemini strategic evaluation
|
||||
├── technical-assessment.md # Codex technical assessment
|
||||
├── risk-assessment-matrix.md # Risk evaluation matrix
|
||||
└── implementation-roadmap.md # Recommended approach
|
||||
```
|
||||
|
||||
### Evaluation Implementation
|
||||
|
||||
**Session-Aware Evaluation**:
|
||||
```bash
|
||||
# Check for existing sessions and context
|
||||
active_sessions=$(find .workflow/ -name ".active-*" 2>/dev/null)
|
||||
if [ -n "$active_sessions" ]; then
|
||||
echo "Found active sessions: $active_sessions"
|
||||
echo "Concept evaluation will consider existing session context"
|
||||
fi
|
||||
|
||||
# Create evaluation session directory
|
||||
evaluation_session="CE-$(date +%Y%m%d_%H%M%S)"
|
||||
mkdir -p ".workflow/.evaluation/$evaluation_session"
|
||||
|
||||
# Store evaluation metadata
|
||||
cat > ".workflow/.evaluation/$evaluation_session/evaluation-session.json" << EOF
|
||||
{
|
||||
"session_id": "$evaluation_session",
|
||||
"timestamp": "$(date -Iseconds)",
|
||||
"concept_input": "$input_description",
|
||||
"tool_selection": "$tool_choice",
|
||||
"context_loaded": [
|
||||
"CLAUDE.md",
|
||||
"README.md"
|
||||
],
|
||||
"evaluation_scope": "$evaluation_scope"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
**Tool Execution Pattern**:
|
||||
```bash
|
||||
# Execute based on tool selection
|
||||
case "$tool_choice" in
|
||||
"gemini")
|
||||
echo "Performing strategic concept evaluation with Gemini..."
|
||||
~/.claude/scripts/gemini-wrapper -p "$gemini_prompt" > ".workflow/.evaluation/$evaluation_session/strategic-analysis.md"
|
||||
;;
|
||||
"codex")
|
||||
echo "Performing technical assessment with Codex..."
|
||||
codex --full-auto exec "$codex_prompt" -s danger-full-access > ".workflow/.evaluation/$evaluation_session/technical-assessment.md"
|
||||
;;
|
||||
"both"|*)
|
||||
echo "Performing comprehensive evaluation with both tools..."
|
||||
~/.claude/scripts/gemini-wrapper -p "$gemini_prompt" > ".workflow/.evaluation/$evaluation_session/strategic-analysis.md" &
|
||||
codex --full-auto exec "$codex_prompt" -s danger-full-access > ".workflow/.evaluation/$evaluation_session/technical-assessment.md" &
|
||||
wait # Wait for both analyses to complete
|
||||
|
||||
# Synthesize results
|
||||
~/.claude/scripts/gemini-wrapper -p "
|
||||
PURPOSE: Synthesize strategic and technical concept evaluations
|
||||
TASK: Combine analyses and generate integrated recommendations
|
||||
CONTEXT: @{.workflow/.evaluation/$evaluation_session/strategic-analysis.md,.workflow/.evaluation/$evaluation_session/technical-assessment.md}
|
||||
EXPECTED: Integrated evaluation with prioritized recommendations
|
||||
RULES: Focus on actionable insights and clear next steps
|
||||
" > ".workflow/.evaluation/$evaluation_session/CONCEPT_EVALUATION.md"
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
## Integration with Workflow Commands
|
||||
|
||||
### Workflow Position
|
||||
**Pre-Planning Phase**: Use before formal planning to optimize concept quality
|
||||
```
|
||||
concept-eval → plan → plan-verify → execute
|
||||
```
|
||||
|
||||
### Usage Scenarios
|
||||
|
||||
**Early Concept Validation**:
|
||||
```bash
|
||||
# Validate initial concept before detailed planning
|
||||
/workflow:concept-eval "Build real-time notification system using WebSockets"
|
||||
```
|
||||
|
||||
**Architecture Review**:
|
||||
```bash
|
||||
# Strategic architecture evaluation
|
||||
/workflow:concept-eval --tool gemini architecture-proposal.md
|
||||
```
|
||||
|
||||
**Technical Feasibility Check**:
|
||||
```bash
|
||||
# Technical implementation assessment
|
||||
/workflow:concept-eval --tool codex "Implement ML-based recommendation engine"
|
||||
```
|
||||
|
||||
**Comprehensive Analysis**:
|
||||
```bash
|
||||
# Full strategic and technical evaluation
|
||||
/workflow:concept-eval --tool both ISS-042
|
||||
```
|
||||
|
||||
### Integration Benefits
|
||||
- **Early Risk Detection**: Identify issues before detailed planning
|
||||
- **Quality Improvement**: Optimize concepts before implementation planning
|
||||
- **Resource Efficiency**: Avoid detailed planning of infeasible concepts
|
||||
- **Decision Support**: Data-driven concept selection and refinement
|
||||
- **Team Alignment**: Clear evaluation criteria and recommendations
|
||||
|
||||
## Error Handling & Edge Cases
|
||||
|
||||
### Input Validation
|
||||
```bash
|
||||
# Validate input format and accessibility
|
||||
if [[ -z "$input" ]]; then
|
||||
echo "Error: Concept input required"
|
||||
echo "Usage: /workflow:concept-eval [--tool gemini|codex|both] <input>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check file accessibility for file inputs
|
||||
if [[ "$input" =~ \.(md|txt|json|yaml|yml)$ ]] && [[ ! -f "$input" ]]; then
|
||||
echo "Error: File not found: $input"
|
||||
echo "Please provide a valid file path or concept description"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Tool Availability
|
||||
```bash
|
||||
# Check tool availability
|
||||
if [[ "$tool_choice" == "gemini" ]] || [[ "$tool_choice" == "both" ]]; then
|
||||
if ! command -v ~/.claude/scripts/gemini-wrapper &> /dev/null; then
|
||||
echo "Warning: Gemini wrapper not available, using codex only"
|
||||
tool_choice="codex"
|
||||
fi
|
||||
fi
|
||||
|
||||
if [[ "$tool_choice" == "codex" ]] || [[ "$tool_choice" == "both" ]]; then
|
||||
if ! command -v codex &> /dev/null; then
|
||||
echo "Warning: Codex not available, using gemini only"
|
||||
tool_choice="gemini"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
### Recovery Strategies
|
||||
```bash
|
||||
# Fallback to manual evaluation if tools fail
|
||||
if [[ "$evaluation_failed" == "true" ]]; then
|
||||
echo "Automated evaluation failed, generating manual evaluation template..."
|
||||
cat > ".workflow/.evaluation/$evaluation_session/manual-evaluation-template.md" << EOF
|
||||
# Manual Concept Evaluation
|
||||
|
||||
## Concept Description
|
||||
$input_description
|
||||
|
||||
## Evaluation Checklist
|
||||
- [ ] **Architectural Soundness**: Does the concept align with existing architecture?
|
||||
- [ ] **Technical Feasibility**: Are required technologies available and mature?
|
||||
- [ ] **Resource Requirements**: Are time and team resources realistic?
|
||||
- [ ] **Integration Complexity**: How complex is integration with existing systems?
|
||||
- [ ] **Risk Assessment**: What are the main technical and business risks?
|
||||
|
||||
## Recommendations
|
||||
[Provide manual evaluation and recommendations]
|
||||
EOF
|
||||
fi
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Evaluation Excellence
|
||||
- **Comprehensive Analysis**: Consider all aspects of concept feasibility
|
||||
- **Context-Rich Assessment**: Leverage full project context and existing patterns
|
||||
- **Actionable Recommendations**: Provide specific, implementable suggestions
|
||||
- **Risk-Aware Evaluation**: Identify and assess potential implementation risks
|
||||
|
||||
### User Experience Excellence
|
||||
- **Clear Results**: Present evaluation results in actionable format
|
||||
- **Focused Recommendations**: Prioritize most critical optimization suggestions
|
||||
- **Integration Guidance**: Provide clear next steps for concept refinement
|
||||
- **Tool Transparency**: Clear indication of which tools were used and why
|
||||
|
||||
### Output Quality
|
||||
- **Structured Reports**: Consistent, well-organized evaluation documentation
|
||||
- **Evidence-Based**: All recommendations backed by analysis and reasoning
|
||||
- **Prioritized Actions**: Clear indication of critical vs. optional improvements
|
||||
- **Implementation Ready**: Evaluation results directly usable for planning phase
|
||||
256
.claude/commands/workflow/tools/docs.md
Normal file
256
.claude/commands/workflow/tools/docs.md
Normal file
@@ -0,0 +1,256 @@
|
||||
---
|
||||
name: docs
|
||||
description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control
|
||||
usage: /workflow:docs <type> [scope]
|
||||
argument-hint: "architecture"|"api"|"all"
|
||||
examples:
|
||||
- /workflow:docs all
|
||||
- /workflow:docs architecture src/modules
|
||||
- /workflow:docs api --scope api/
|
||||
---
|
||||
|
||||
# Workflow Documentation Command
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:docs <type> [scope]
|
||||
```
|
||||
|
||||
## Input Detection
|
||||
- **Document Types**: `architecture`, `api`, `all` → Creates appropriate documentation tasks
|
||||
- **Scope**: Optional module/directory filtering → Focuses documentation generation
|
||||
- **Default**: `all` → Complete documentation suite
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### Planning & Task Creation Process
|
||||
The command performs structured planning and task creation:
|
||||
|
||||
**0. Pre-Planning Architecture Analysis** ⚠️ MANDATORY FIRST STEP
|
||||
- **System Structure Analysis**: MUST run `bash(~/.claude/scripts/get_modules_by_depth.sh)` for dynamic task decomposition
|
||||
- **Module Boundary Identification**: Understand module organization and dependencies
|
||||
- **Architecture Pattern Recognition**: Identify architectural styles and design patterns
|
||||
- **Foundation for documentation**: Use structure analysis to guide task decomposition
|
||||
|
||||
**1. Documentation Planning**
|
||||
- **Type Analysis**: Determine documentation scope (architecture/api/all)
|
||||
- **Module Discovery**: Use architecture analysis results to identify components
|
||||
- **Dynamic Task Decomposition**: Analyze project structure to determine optimal task count and module grouping
|
||||
- **Session Management**: Create or use existing documentation session
|
||||
|
||||
**2. Task Generation**
|
||||
- **Create session**: `.workflow/WFS-docs-[timestamp]/`
|
||||
- **Create active marker**: `.workflow/.active-WFS-docs-[timestamp]` (must match session folder name)
|
||||
- **Generate IMPL_PLAN.md**: Documentation requirements and task breakdown
|
||||
- **Create task.json files**: Individual documentation tasks with flow_control
|
||||
- **Setup TODO_LIST.md**: Progress tracking for documentation generation
|
||||
|
||||
### Session Management ⚠️ CRITICAL
|
||||
- **Check for active sessions**: Look for `.workflow/.active-WFS-docs-*` markers
|
||||
- **Marker naming**: Active marker must exactly match session folder name
|
||||
- **Session creation**: `WFS-docs-[timestamp]` folder with matching `.active-WFS-docs-[timestamp]` marker
|
||||
- **Task execution**: Use `/workflow:execute` to run individual documentation tasks within active session
|
||||
- **Session isolation**: Each documentation session maintains independent context and state
|
||||
|
||||
## Output Structure
|
||||
```
|
||||
.workflow/docs/
|
||||
├── README.md # System navigation
|
||||
├── modules/ # Level 1: Module documentation
|
||||
│ ├── [module-1]/
|
||||
│ │ ├── overview.md
|
||||
│ │ ├── api.md
|
||||
│ │ ├── dependencies.md
|
||||
│ │ └── examples.md
|
||||
│ └── [module-n]/...
|
||||
├── architecture/ # Level 2: System architecture
|
||||
│ ├── system-design.md
|
||||
│ ├── module-map.md
|
||||
│ ├── data-flow.md
|
||||
│ └── tech-stack.md
|
||||
└── api/ # Level 2: Unified API docs
|
||||
├── unified-api.md
|
||||
└── openapi.yaml
|
||||
```
|
||||
|
||||
## Task Decomposition Standards
|
||||
|
||||
### Dynamic Task Planning Rules
|
||||
**Module Grouping**: Max 3 modules per task, max 30 files per task
|
||||
**Task Count**: Calculate based on `total_modules ÷ 3 (rounded up) + base_tasks`
|
||||
**File Limits**: Split tasks when file count exceeds 30 in any module group
|
||||
**Base Tasks**: System overview (1) + Architecture (1) + API consolidation (1)
|
||||
**Module Tasks**: Group related modules by dependency depth and functional similarity
|
||||
|
||||
### Documentation Task Types
|
||||
**IMPL-001**: System Overview Documentation
|
||||
- Project structure analysis
|
||||
- Technology stack documentation
|
||||
- Main navigation creation
|
||||
|
||||
**IMPL-002**: Module Documentation (per module)
|
||||
- Individual module analysis
|
||||
- API surface documentation
|
||||
- Dependencies and relationships
|
||||
- Usage examples
|
||||
|
||||
**IMPL-003**: Architecture Documentation
|
||||
- System design patterns
|
||||
- Module interaction mapping
|
||||
- Data flow documentation
|
||||
- Design principles
|
||||
|
||||
**IMPL-004**: API Documentation
|
||||
- Endpoint discovery and analysis
|
||||
- OpenAPI specification generation
|
||||
- Authentication documentation
|
||||
- Integration examples
|
||||
|
||||
### Task JSON Schema (5-Field Architecture)
|
||||
Each documentation task uses the workflow-architecture.md 5-field schema:
|
||||
- **id**: IMPL-N format
|
||||
- **title**: Documentation task name
|
||||
- **status**: pending|active|completed|blocked
|
||||
- **meta**: { type: "documentation", agent: "@doc-generator" }
|
||||
- **context**: { requirements, focus_paths, acceptance, scope }
|
||||
- **flow_control**: { pre_analysis[], implementation_approach, target_files[] }
|
||||
|
||||
## Document Generation
|
||||
|
||||
### Workflow Process
|
||||
**Input Analysis** → **Session Creation** → **IMPL_PLAN.md** → **.task/IMPL-NNN.json** → **TODO_LIST.md** → **Execute Tasks**
|
||||
|
||||
**Always Created**:
|
||||
- **IMPL_PLAN.md**: Documentation requirements and task breakdown
|
||||
- **Session state**: Task references and documentation paths
|
||||
|
||||
**Auto-Created (based on scope)**:
|
||||
- **TODO_LIST.md**: Progress tracking for documentation tasks
|
||||
- **.task/IMPL-*.json**: Individual documentation tasks with flow_control
|
||||
- **.process/ANALYSIS_RESULTS.md**: Documentation analysis artifacts
|
||||
|
||||
**Document Structure**:
|
||||
```
|
||||
.workflow/
|
||||
├── .active-WFS-docs-20231201-143022 # Active session marker (matches folder name)
|
||||
└── WFS-docs-20231201-143022/ # Documentation session folder
|
||||
├── IMPL_PLAN.md # Main documentation plan
|
||||
├── TODO_LIST.md # Progress tracking
|
||||
├── .process/
|
||||
│ └── ANALYSIS_RESULTS.md # Documentation analysis
|
||||
└── .task/
|
||||
├── IMPL-001.json # System overview task
|
||||
├── IMPL-002.json # Module documentation task
|
||||
├── IMPL-003.json # Architecture documentation task
|
||||
└── IMPL-004.json # API documentation task
|
||||
```
|
||||
|
||||
### Task Flow Control Templates
|
||||
|
||||
**System Overview Task (IMPL-001)**:
|
||||
```json
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "system_architecture_analysis",
|
||||
"action": "Discover system architecture and module hierarchy",
|
||||
"command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
|
||||
"output_to": "system_structure"
|
||||
},
|
||||
{
|
||||
"step": "project_discovery",
|
||||
"action": "Discover project structure and entry points",
|
||||
"command": "bash(find . -type f -name '*.json' -o -name '*.md' -o -name 'package.json' | head -20)",
|
||||
"output_to": "project_structure"
|
||||
},
|
||||
{
|
||||
"step": "analyze_tech_stack",
|
||||
"action": "Analyze technology stack and dependencies using structure analysis",
|
||||
"command": "~/.claude/scripts/gemini-wrapper -p \"Analyze project technology stack and dependencies based on: [system_structure]\"",
|
||||
"output_to": "tech_analysis"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/README.md"]
|
||||
}
|
||||
```
|
||||
|
||||
**Module Documentation Task (IMPL-002)**:
|
||||
```json
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_system_structure",
|
||||
"action": "Load system architecture analysis from previous task",
|
||||
"command": "bash(cat .workflow/WFS-docs-*/IMPL-001-system_structure.output 2>/dev/null || ~/.claude/scripts/get_modules_by_depth.sh)",
|
||||
"output_to": "system_context"
|
||||
},
|
||||
{
|
||||
"step": "module_analysis",
|
||||
"action": "Analyze specific module structure and API within system context",
|
||||
"command": "~/.claude/scripts/gemini-wrapper -p \"Analyze module [MODULE_NAME] structure and exported API within system: [system_context]\"",
|
||||
"output_to": "module_context"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/modules/[MODULE_NAME]/overview.md"]
|
||||
}
|
||||
```
|
||||
|
||||
## Analysis Templates
|
||||
|
||||
### Project Structure Analysis Rules
|
||||
- Identify main modules and purposes
|
||||
- Map directory organization patterns
|
||||
- Extract entry points and configuration files
|
||||
- Recognize architectural styles and design patterns
|
||||
- Analyze module relationships and dependencies
|
||||
- Document technology stack and requirements
|
||||
|
||||
### Module Analysis Rules
|
||||
- Identify module boundaries and entry points
|
||||
- Extract exported functions, classes, interfaces
|
||||
- Document internal organization and structure
|
||||
- Analyze API surfaces with types and parameters
|
||||
- Map dependencies within and between modules
|
||||
- Extract usage patterns and examples
|
||||
|
||||
### API Analysis Rules
|
||||
- Classify endpoint types (REST, GraphQL, WebSocket, RPC)
|
||||
- Extract request/response parameters and schemas
|
||||
- Document authentication and authorization requirements
|
||||
- Generate OpenAPI 3.0 specification structure
|
||||
- Create comprehensive endpoint documentation
|
||||
- Provide usage examples and integration guides
|
||||
|
||||
## Error Handling
|
||||
- **Invalid document type**: Clear error message with valid options
|
||||
- **Module not found**: Skip missing modules with warning
|
||||
- **Analysis failures**: Fall back to file-based analysis
|
||||
- **Permission issues**: Clear guidance on directory access
|
||||
|
||||
## Key Benefits
|
||||
|
||||
### Structured Documentation Process
|
||||
- **Task-based approach**: Documentation broken into manageable, trackable tasks
|
||||
- **Flow control integration**: Systematic analysis ensures completeness
|
||||
- **Progress visibility**: TODO_LIST.md provides clear completion status
|
||||
- **Quality assurance**: Each task has defined acceptance criteria
|
||||
|
||||
### Workflow Integration
|
||||
- **Planning foundation**: Documentation provides context for implementation planning
|
||||
- **Execution consistency**: Same task execution model as implementation
|
||||
- **Context accumulation**: Documentation builds comprehensive project understanding
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Complete Documentation Workflow
|
||||
```bash
|
||||
# Step 1: Create documentation plan and tasks
|
||||
/workflow:docs all
|
||||
|
||||
# Step 2: Execute documentation tasks (after planning)
|
||||
/workflow:execute IMPL-001 # System overview
|
||||
/workflow:execute IMPL-002 # Module documentation
|
||||
/workflow:execute IMPL-003 # Architecture documentation
|
||||
/workflow:execute IMPL-004 # API documentation
|
||||
```
|
||||
The system creates structured documentation tasks with proper session management, task.json files, and integration with the broader workflow system for systematic and trackable documentation generation.
|
||||
258
.claude/commands/workflow/tools/status.md
Normal file
258
.claude/commands/workflow/tools/status.md
Normal file
@@ -0,0 +1,258 @@
|
||||
---
|
||||
name: workflow:status
|
||||
description: Generate on-demand views from JSON task data
|
||||
usage: /workflow:status [task-id] [--format=<format>] [--validate]
|
||||
argument-hint: [optional: task-id, format, validation]
|
||||
examples:
|
||||
- /workflow:status
|
||||
- /workflow:status impl-1
|
||||
- /workflow:status --format=hierarchy
|
||||
- /workflow:status --validate
|
||||
---
|
||||
|
||||
# Workflow Status Command (/workflow:status)
|
||||
|
||||
## Overview
|
||||
Generates on-demand views from JSON task data. No synchronization needed - all views are calculated from the current state of JSON files.
|
||||
|
||||
## Core Principles
|
||||
**Data Source:** @~/.claude/workflows/workflow-architecture.md
|
||||
|
||||
## Key Features
|
||||
|
||||
### Pure View Generation
|
||||
- **No Sync**: Views are generated, not synchronized
|
||||
- **Always Current**: Reads latest JSON data every time
|
||||
- **No Persistence**: Views are temporary, not saved
|
||||
- **Single Source**: All data comes from JSON files only
|
||||
|
||||
### Multiple View Formats
|
||||
- **Overview** (default): Current tasks and status
|
||||
- **Hierarchy**: Task relationships and structure
|
||||
- **Details**: Specific task information
|
||||
|
||||
## Usage
|
||||
|
||||
### Default Overview
|
||||
```bash
|
||||
/workflow:status
|
||||
```
|
||||
|
||||
Generates current workflow overview:
|
||||
```markdown
|
||||
# Workflow Overview
|
||||
**Session**: WFS-user-auth
|
||||
**Phase**: IMPLEMENT
|
||||
**Type**: medium
|
||||
|
||||
## Active Tasks
|
||||
- [⚠️] impl-1: Build authentication module (code-developer)
|
||||
- [⚠️] impl-2: Setup user management (code-developer)
|
||||
|
||||
## Completed Tasks
|
||||
- [✅] impl-0: Project setup
|
||||
|
||||
## Stats
|
||||
- **Total**: 8 tasks
|
||||
- **Completed**: 3
|
||||
- **Active**: 2
|
||||
- **Remaining**: 3
|
||||
```
|
||||
|
||||
### Specific Task View
|
||||
```bash
|
||||
/workflow:status impl-1
|
||||
```
|
||||
|
||||
Shows detailed task information:
|
||||
```markdown
|
||||
# Task: impl-1
|
||||
|
||||
**Title**: Build authentication module
|
||||
**Status**: active
|
||||
**Agent**: @code-developer
|
||||
**Type**: feature
|
||||
|
||||
## Context
|
||||
- **Requirements**: JWT authentication, OAuth2 support
|
||||
- **Scope**: src/auth/*, tests/auth/*
|
||||
- **Acceptance**: Module handles JWT tokens, OAuth2 flow implemented
|
||||
- **Inherited From**: WFS-user-auth
|
||||
|
||||
## Relations
|
||||
- **Parent**: none
|
||||
- **Subtasks**: impl-1.1, impl-1.2
|
||||
- **Dependencies**: impl-0
|
||||
|
||||
## Execution
|
||||
- **Attempts**: 0
|
||||
- **Last Attempt**: never
|
||||
|
||||
## Metadata
|
||||
- **Created**: 2025-09-05T10:30:00Z
|
||||
- **Updated**: 2025-09-05T10:35:00Z
|
||||
```
|
||||
|
||||
### Hierarchy View
|
||||
```bash
|
||||
/workflow:status --format=hierarchy
|
||||
```
|
||||
|
||||
Shows task relationships:
|
||||
```markdown
|
||||
# Task Hierarchy
|
||||
|
||||
## Main Tasks
|
||||
- impl-0: Project setup ✅
|
||||
- impl-1: Build authentication module ⚠️
|
||||
- impl-1.1: Design auth schema
|
||||
- impl-1.2: Implement auth logic
|
||||
- impl-2: Setup user management ⚠️
|
||||
|
||||
## Dependencies
|
||||
- impl-1 → depends on → impl-0
|
||||
- impl-2 → depends on → impl-1
|
||||
```
|
||||
|
||||
## View Generation Process
|
||||
|
||||
### Data Loading
|
||||
```pseudo
|
||||
function generate_workflow_status(task_id, format):
|
||||
// Load all current data
|
||||
session = load_workflow_session()
|
||||
all_tasks = load_all_task_json_files()
|
||||
|
||||
// Filter if specific task requested
|
||||
if task_id:
|
||||
target_task = find_task(all_tasks, task_id)
|
||||
return generate_task_detail_view(target_task)
|
||||
|
||||
// Generate requested format
|
||||
switch format:
|
||||
case 'hierarchy':
|
||||
return generate_hierarchy_view(all_tasks)
|
||||
default:
|
||||
return generate_overview(session, all_tasks)
|
||||
```
|
||||
|
||||
### Real-Time Calculation
|
||||
- **Task Counts**: Calculated from JSON file status fields
|
||||
- **Relationships**: Built from JSON relations fields
|
||||
- **Status**: Read directly from current JSON state
|
||||
|
||||
## Validation Mode
|
||||
|
||||
### Basic Validation
|
||||
```bash
|
||||
/workflow:status --validate
|
||||
```
|
||||
|
||||
Performs integrity checks:
|
||||
```markdown
|
||||
# Validation Results
|
||||
|
||||
## JSON File Validation
|
||||
✅ All task JSON files are valid
|
||||
✅ Session file is valid and readable
|
||||
|
||||
## Relationship Validation
|
||||
✅ All parent-child relationships are valid
|
||||
✅ All dependencies reference existing tasks
|
||||
✅ No circular dependencies detected
|
||||
|
||||
## Hierarchy Validation
|
||||
✅ Task hierarchy within depth limits (max 3 levels)
|
||||
✅ All subtask references are bidirectional
|
||||
|
||||
## Issues Found
|
||||
⚠️ impl-3: No subtasks defined (expected for leaf task)
|
||||
|
||||
**Status**: All systems operational
|
||||
```
|
||||
|
||||
### Validation Checks
|
||||
- **JSON Schema**: All files parse correctly
|
||||
- **References**: All task IDs exist
|
||||
- **Hierarchy**: Parent-child relationships are valid
|
||||
- **Dependencies**: No circular dependencies
|
||||
- **Depth**: Task hierarchy within limits
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Missing Files
|
||||
```bash
|
||||
❌ Session file not found
|
||||
→ Initialize new workflow session? (y/n)
|
||||
|
||||
❌ Task impl-5 not found
|
||||
→ Available tasks: impl-1, impl-2, impl-3, impl-4
|
||||
```
|
||||
|
||||
### Invalid Data
|
||||
```bash
|
||||
❌ Invalid JSON in impl-2.json
|
||||
→ Cannot generate view for impl-2
|
||||
→ Repair file manually or recreate task
|
||||
|
||||
⚠️ Circular dependency detected: impl-1 → impl-2 → impl-1
|
||||
→ Task relationships may be incorrect
|
||||
```
|
||||
|
||||
## Performance Benefits
|
||||
|
||||
### Fast Generation
|
||||
- **No File Writes**: Only reads JSON files
|
||||
- **No Sync Logic**: No complex synchronization
|
||||
- **Instant Results**: Generate views on demand
|
||||
- **No Conflicts**: No state consistency issues
|
||||
|
||||
### Scalability
|
||||
- **Large Task Sets**: Handles hundreds of tasks efficiently
|
||||
- **Complex Hierarchies**: No performance degradation
|
||||
- **Concurrent Access**: Multiple views can be generated simultaneously
|
||||
|
||||
## Integration
|
||||
|
||||
### Workflow Integration
|
||||
- Use after task creation to see current state
|
||||
- Use for debugging task relationships
|
||||
|
||||
### Command Integration
|
||||
```bash
|
||||
# Common workflow
|
||||
/task:create "New feature"
|
||||
/workflow:status # Check current state
|
||||
/task:breakdown impl-1
|
||||
/workflow:status --format=hierarchy # View new structure
|
||||
/task:execute impl-1.1
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Supported Formats
|
||||
- `overview` (default): General workflow status
|
||||
- `hierarchy`: Task relationships
|
||||
- `tasks`: Simple task list
|
||||
- `details`: Comprehensive information
|
||||
|
||||
### Custom Filtering
|
||||
```bash
|
||||
# Show only active tasks
|
||||
/workflow:status --format=tasks --filter=active
|
||||
|
||||
# Show completed tasks only
|
||||
/workflow:status --format=tasks --filter=completed
|
||||
|
||||
# Show tasks for specific agent
|
||||
/workflow:status --format=tasks --agent=@code-developer
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/task:create` - Create tasks (generates JSON data)
|
||||
- `/task:execute` - Execute tasks (updates JSON data)
|
||||
- `/task:breakdown` - Create subtasks (generates more JSON data)
|
||||
- `/workflow:vibe` - Coordinate agents (uses workflow status for coordination)
|
||||
|
||||
This workflow status system provides instant, accurate views of workflow state without any synchronization complexity or performance overhead.
|
||||
Reference in New Issue
Block a user