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

Initial release: Claude Code Workflow (CCW) v2.0

Browse Source 
🚀 Revolutionary AI-powered development workflow orchestration system

## 🔥 Core Innovations
- **Document-State Separation**: Markdown for planning, JSON for execution state
- **Progressive Complexity Management**: Level 0-2 adaptive workflow depth
- **5-Agent Orchestration**: Specialized AI agents with context preservation
- **Session-First Architecture**: Auto-discovery and state inheritance

## 🏗️ Key Features
- Intelligent workflow orchestration (Simple/Medium/Complex patterns)
- Real-time document-state synchronization with conflict resolution
- Hierarchical task management with 3-level JSON structure
- Gemini CLI integration with 12+ specialized templates
- Comprehensive file output generation for all workflow commands

## 📦 Installation
Remote one-liner installation:
```
iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-CCW/main/install-remote.ps1)
```

## 🎯 System Architecture
4-layer intelligent development architecture:
1. Command Layer - Smart routing and version management
2. Agent Layer - 5 specialized development agents
3. Workflow Layer - Gemini templates and task orchestration
4. Memory Layer - Distributed documentation and auto-sync

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-09-07 17:39:54 +08:00
commit 445ac823ba
87 changed files with 19076 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
.claude/commands/enhance-prompt.md Normal file
View File

@@ -0,0 +1,202 @@
---
name: enhance-prompt
description: Dynamic prompt enhancement for complex requirements - Structured enhancement of user prompts before agent execution
usage: /enhance-prompt <user_input>
argument-hint: [--gemini] "user input to enhance"
examples:
- /enhance-prompt "add user profile editing"
- /enhance-prompt "fix login button"
- /enhance-prompt "clean up the payment code"
---
### 🚀 **Command Overview: `/enhance-prompt`**
- **Type**: Prompt Engineering Command
- **Purpose**: To systematically enhance raw user prompts, translating them into clear, context-rich, and actionable specifications before agent execution.
- **Key Feature**: Dynamically integrates with Gemini for deep, codebase-aware analysis.
### 📥 **Command Parameters**
- `<user_input>`: **(Required)** The raw text prompt from the user that needs enhancement.
- `--gemini`: **(Optional)** An explicit flag to force the full Gemini collaboration flow, ensuring codebase analysis is performed even for simple prompts.
### 🔄 **Core Enhancement Protocol**
This is the standard pipeline every prompt goes through for structured enhancement.
`Step 1: Intent Translation` **->** `Step 2: Context Extraction` **->** `Step 3: Key Points Identification` **->** `Step 4: Optional Gemini Consultation`
### 🧠 **Gemini Collaboration Logic**
This logic determines when to invoke Gemini for deeper, codebase-aware insights.
```pseudo
FUNCTION decide_enhancement_path(user_prompt, options):
// Set of keywords that indicate high complexity or architectural changes.
critical_keywords = ["refactor", "migrate", "redesign", "auth", "payment", "security"]
// Conditions for triggering Gemini analysis.
use_gemini = FALSE
IF options.gemini_flag is TRUE:
use_gemini = TRUE
ELSE IF prompt_affects_multiple_modules(user_prompt, threshold=3):
use_gemini = TRUE
ELSE IF any_keyword_in_prompt(critical_keywords, user_prompt):
use_gemini = TRUE
// Execute the appropriate enhancement flow.
enhanced_prompt = run_standard_enhancement(user_prompt) // Steps 1-3
IF use_gemini is TRUE:
// This action corresponds to calling the Gemini CLI tool programmatically.
// e.g., `gemini --all-files -p "..."` based on the derived context.
gemini_insights = execute_tool("gemini", enhanced_prompt) // Calls the Gemini CLI
enhanced_prompt.append(gemini_insights)
RETURN enhanced_prompt
END FUNCTION
```
### 📚 **Enhancement Rules**
- **Ambiguity Resolution**: Generic terms are translated into specific technical intents.
- `"fix"` → Identify the specific bug and preserve existing functionality.
- `"improve"` → Enhance performance or readability while maintaining compatibility.
- `"add"` → Implement a new feature and integrate it with existing code.
- `"refactor"` → Restructure code to improve quality while preserving external behavior.
- **Implicit Context Inference**: Missing technical context is automatically inferred.
```bash
# User: "add login"
# Inferred Context:
# - Authentication system implementation
# - Frontend login form + backend validation
# - Session management considerations
# - Security best practices (e.g., password handling)
```
- **Technical Translation**: Business goals are converted into technical specifications.
```bash
# User: "make it faster"
# Translated Intent:
# - Identify performance bottlenecks
# - Define target metrics/benchmarks
# - Profile before optimizing
# - Document performance gains and trade-offs
```
### 🗺️ **Enhancement Translation Matrix**
| User Says | → Translate To | Key Context | Focus Areas |
| ------------------ | ----------------------- | ----------------------- | --------------------------- |
| "make it work" | Fix functionality | Debug implementation | Root cause → fix → test |
| "add [feature]" | Implement capability | Integration points | Core function + edge cases |
| "improve [area]" | Optimize/enhance | Current limits | Measurable improvements |
| "fix [bug]" | Resolve issue | Bug symptoms | Root cause + prevention |
| "refactor [code]" | Restructure quality | Structure pain points | Maintain behavior |
| "update [component]" | Modernize | Version compatibility | Migration path |
### ⚡ **Automatic Invocation Triggers**
The `/enhance-prompt` command is designed to run automatically when the system detects:
- Ambiguous user language (e.g., "fix", "improve", "clean up").
- Tasks impacting multiple modules or components (>3).
- Requests for system architecture changes.
- Modifications to critical systems (auth, payment, security).
- Complex refactoring requests.
### 🛠️ **Gemini Integration Protocol (Internal)**
**Core Principles**: @~/.claude/workflows/core-principles.md
This section details how the system programmatically interacts with the Gemini CLI.
- **Primary Tool**: All Gemini analysis is performed via direct calls to the `gemini` command-line tool (e.g., `gemini --all-files -p "..."`).
- **Central Guidelines**: All CLI usage patterns, syntax, and context detection rules are defined in the central guidelines document:
- **Specialized Templates**: For specific analysis types, the system references dedicated templates:
- **Pattern/Architecture**: `gemini-core-templates.md`
- **Security**: `gemini-core-templates.md` (for vulnerability scanning)
- **Documentation**: `gemini-dms-templates.md`
### 📝 **Enhancement Examples**
This card contains the original, unmodified examples to demonstrate the command's output.
#### Example 1: Feature Request (with Gemini Integration)
```bash
# User Input: "add user profile editing"
# Standard Enhancement:
TRANSLATED_INTENT: Implement user profile editing feature
DOMAIN_CONTEXT: User management system
ACTION_TYPE: Create new feature
COMPLEXITY: Medium (multi-component)
# Gemini Analysis Added:
GEMINI_PATTERN_ANALYSIS: FormValidator used in AccountSettings, PreferencesEditor
GEMINI_ARCHITECTURE: UserService → ProfileRepository → UserModel pattern
# Final Enhanced Structure:
ENRICHED_CONTEXT:
- Frontend: Profile form using FormValidator pattern
- Backend: API endpoints following UserService pattern
- Database: User model via ProfileRepository
- Auth: Permission checks using AuthGuard pattern
KEY_POINTS:
- Data validation using existing FormValidator
- Image upload via SecureUploadService
- Field permissions with AuthGuard middleware
ATTENTION_AREAS:
- Security: Use SecureUploadService for file handling
- Performance: Lazy loading patterns (ProfileImage.tsx)
```
#### Example 2: Bug Fix
```bash
# User Input: "login button doesn't work"
# Enhanced Structure:
TRANSLATED_INTENT: Debug and fix non-functional login button
DOMAIN_CONTEXT: Authentication UI
ACTION_TYPE: Fix bug
COMPLEXITY: Simple (single component)
KEY_POINTS:
- Identify root cause (event/state/API)
- Preserve existing auth flow
- Add error handling if missing
ATTENTION_AREAS:
- Don't break existing functionality
- Test edge cases and user states
```
#### Example 3: Refactoring Request
```bash
# User Input: "clean up the payment code"
# Enhanced Structure:
TRANSLATED_INTENT: Refactor payment module for maintainability
DOMAIN_CONTEXT: Payment processing system
ACTION_TYPE: Refactor
COMPLEXITY: Complex (critical system)
KEY_POINTS:
- Maintain exact functionality
- Improve code organization
- Extract reusable components
ATTENTION_AREAS:
- Critical: No behavior changes
- Security: Maintain PCI compliance
- Testing: Comprehensive coverage
```
### ✨ **Key Benefits**
1. **Clarity**: Ambiguous requests become clear specifications.
2. **Completeness**: Implicit requirements become explicit.
3. **Context**: Missing context is automatically inferred.
4. **Codebase Awareness**: Gemini provides actual patterns from the project.
5. **Quality**: Attention areas prevent common mistakes.
6. **Efficiency**: Agents receive structured, actionable input.
7. **Smart Flow Control**: Seamless integration with workflows.

199
.claude/commands/gemini-chat.md Normal file
View File

@@ -0,0 +1,199 @@
---
name: gemini-chat
description: Single-execution Gemini CLI interaction command with dynamic template selection for codebase analysis
usage: /gemini-chat <inquiry> [--all-files] [--compress] [--save-session]
argument-hint: "your question or analysis request" [optional: all-files, compression, session saving]
examples:
- /gemini-chat "analyze the authentication flow"
- /gemini-chat "how can I optimize this React component performance?" --all-files
- /gemini-chat "review security vulnerabilities in @{src/auth/*.js}" --compress
- /gemini-chat "comprehensive code quality assessment" --all-files --save-session
allowed-tools: Bash(gemini:*), Bash(~/.claude/scripts/gemini-chat-executor.sh:*)
model: sonnet
---
### 🚀 **Command Overview: `/gemini-chat`**
- **Type**: Gemini CLI Execution Wrapper
- **Purpose**: To provide direct interaction with the `gemini` CLI, enhanced with intelligent, dynamic prompt template selection for codebase analysis.
- **Core Tools**:
- `Bash(gemini:*)`: Executes the external Gemini CLI tool.
- `Bash(~/.claude/scripts/gemini-chat-executor.sh:*)`: Manages all template discovery and selection logic.
### 📥 **Parameters & Usage**
- **`<inquiry>` (Required)**: Your primary question or analysis request.
- **`--all-files` (Optional)**: Includes the entire codebase in the analysis context.
- **`--compress` (Optional)**: Applies context compression for large prompts.
- **`--save-session` (Optional)**: Saves the full interaction to current workflow session directory.
- **File References**: Explicitly specify files or patterns within the inquiry using `@{path/to/file}`.
### 🔄 **Core Execution Workflow**
⚠️ **IMPORTANT**: Template selection is **AUTOMATIC** based on input analysis and is the **FIRST STEP** in command execution.
`Parse Input & Intent` **->** `Auto-Select Template` **->** `Load Selected Template` **->** `Determine Context Needs` **->** `Assemble Context` **->** `Construct Prompt` **->** `Execute Gemini CLI` **->** `(Optional) Save Session`
### 🧠 **Template Selection Logic**
⚠️ **CRITICAL**: Templates are selected **AUTOMATICALLY** by analyzing user input. The command execution calls script methods to discover and select the best template.
**Script Methods Available:**
- `~/.claude/scripts/gemini-chat-executor.sh list` - Lists all available templates
- `~/.claude/scripts/gemini-chat-executor.sh load "template_name"` - Loads a specific template
```pseudo
FUNCTION automatic_template_selection(user_inquiry):
// STEP 1: Command execution calls list method to discover templates
available_templates = call_script_method("list")
// STEP 2: Analyze user input to determine best template match
analyzed_intent = analyze_input_keywords_and_context(user_inquiry)
best_template = match_template_to_intent(analyzed_intent, available_templates)
// STEP 3: Command execution calls load method with selected template
IF best_template is FOUND:
template_content = call_script_method("load", best_template.name)
log_info("Auto-selected template: " + best_template.name)
ELSE:
// Fallback to default template if no clear match
template_content = call_script_method("load", "default")
log_warning("No clear template match, using default template")
RETURN template_content
END FUNCTION
```
**Automatic Selection Flow:**
1. **Command starts** → Calls `list` method to discover available templates
2. **Input analysis** → Analyzes user inquiry for keywords, intent, and context
3. **Template matching** → Automatically selects best template based on analysis
4. **Template loading** → Command calls `load` method with selected template name
5. **Continue execution** → Process the inquiry with loaded template
### 📚 **Context Assembly Priority**
Context is gathered based on a clear hierarchy of sources.
1. **Template Requirements**: The primary driver. The selected template defines a default set of required file patterns.
2. **User-Explicit Files**: Files specified by the user (e.g., `@{src/auth/*.js}`) override or add to the template's requirements.
3. **Command-Level Flags**: The `--all-files` flag overrides all other file specifications to scope the context to the entire project.
### 📝 **Structured Prompt Format**
The final prompt sent to the `gemini` CLI is assembled in three distinct parts.
```
=== SYSTEM PROMPT ===
[Content from the selected template file is placed here]
=== CONTEXT ===
@{CLAUDE.md,**/*CLAUDE.md} [Project guidelines, always included]
@{target_files} [File context gathered based on the assembly priority]
=== USER INPUT ===
[The original user inquiry text]
```
### ⚙️ **Gemini CLI Execution Logic**
This describes how the external `gemini` binary is invoked with the constructed prompt.
```pseudo
FUNCTION execute_gemini_cli(structured_prompt, flags):
// Retrieves the path from the user's execution environment.
current_directory = get_current_working_directory()
IF flags contain "--all-files":
// For --all-files, it may be necessary to navigate to the correct directory first.
navigate_to_project_root(current_directory)
// Executes the gemini tool using the --all-files flag.
result = execute_tool("Bash(gemini:*)", "--all-files", "-p", structured_prompt)
ELSE:
// Default execution relies on @{file_patterns} resolved by the Gemini CLI.
// The prompt already contains the necessary @{...} references.
result = execute_tool("Bash(gemini:*)", "-p", structured_prompt)
IF result is 'FAILED' AND flags contain "--all-files":
// Implements the fallback strategy if --all-files fails.
log_warning("`--all-files` failed. Falling back to pattern-based context.")
prompt_with_fallback = add_file_patterns_to_prompt(structured_prompt)
result = execute_tool("Bash(gemini:*)", "-p", prompt_with_fallback)
RETURN result
END FUNCTION
```
### 💾 **Session Persistence**
⚠️ **CRITICAL**: Before saving, MUST check for existing active session to avoid creating duplicate sessions.
- **Trigger**: Activated by the `--save-session` flag.
- **Action**: Saves the complete interaction, including the template used, context, and Gemini's output.
- **Session Check**: Query `.workflow/session_status.jsonl` to identify current active session.
- **Location Strategy**:
- **IF active session exists**: Save to existing `.workflow/WFS-[topic-slug]/.chat/` directory
- **IF no active session**: Create new session directory following WFS naming convention
**File Structure**: @~/.claude/workflows/file-structure-standards.md
- **File Format**: `chat-YYYYMMDD-HHMMSS.md` with timestamp for unique identification.
- **Structure**: Integrates with session management system using WFS-[topic-slug] format for consistency.
- **Coordination**: Session files coordinate with workflow-session.json and maintain document-state separation.
### 🔗 **Chat Session Integration**
**Session Detection Workflow:**
```pseudo
FUNCTION determine_save_location():
// STEP 1: Check for existing active session
active_sessions = query_session_registry(".workflow/session_status.jsonl")
IF active_sessions.count > 0:
// Use existing active session directory
session_dir = active_sessions[0].session_path + "/.chat/"
ensure_directory_exists(session_dir)
RETURN session_dir
ELSE:
// No active session - create new one only if necessary
new_session_slug = generate_topic_slug(user_inquiry)
session_dir = ".workflow/WFS-" + new_session_slug + "/.chat/"
create_session_structure(session_dir)
RETURN session_dir
END FUNCTION
```
**Storage Structure:**
```
.workflow/WFS-[topic-slug]/.chat/
├── chat-20240307-143022.md # Individual chat sessions
├── chat-20240307-151445.md # Timestamped for chronological order
└── analysis-security.md # Named analysis sessions
```
**Session Template:**
```markdown
# Chat Session: [Timestamp] - [Topic]
## Query
[Original user inquiry]
## Template Used
[Auto-selected template name and rationale]
## Context
[Files and patterns included in analysis]
## Gemini Response
[Complete response from Gemini CLI]
## Key Insights
- [Important findings]
- [Architectural insights]
- [Implementation recommendations]
## Integration Links
- [🔙 Workflow Session](../workflow-session.json)
- [📋 Implementation Plan](../IMPL_PLAN.md)
- [📝 Task Definitions](../.task/)
```

257
.claude/commands/gemini-execute.md Normal file
View File

@@ -0,0 +1,257 @@
---
name: gemini-execute
description: Intelligent context inference executor with auto-approval capabilities, supporting user descriptions and task ID execution modes
usage: /gemini-execute <description|task-id> [--yolo] [--debug] [--save-session]
argument-hint: "implementation description or task-id" [auto-approve, debug, session saving]
examples:
- /gemini-execute "implement user authentication system" --yolo
- /gemini-execute "optimize React component performance @{custom/path}" --yolo
- /gemini-execute IMPL-001 --yolo
- /gemini-execute "fix API performance issues" --debug --save-session
allowed-tools: Bash(gemini:*)
model: sonnet
---
### 🚀 Command Overview: /gemini-execute
- **Type**: Intelligent Context Inference Executor.
- **Purpose**: Infers context files to automatically execute implementation tasks using the Gemini CLI.
- **Key Feature**: `--yolo` flag for non-interactive, auto-approved execution within workflows.
- **Core Tool**: `Bash(gemini:*)`.
### ⚙️ Execution Modes
- **Direct User Description Mode**:
- **Input**: A natural language description of the task (e.g., `"implement user authentication system"`).
- **Process**: Analyzes keywords in the description to intelligently infer and collect relevant context files before execution.
- **Task ID Mode**:
- **Input**: A specific task identifier (e.g., `IMPL-001`).
- **Process**: Parses the corresponding `.task/impl-*.json` file to determine scope, type, and related files for execution.
### 📥 Command Parameters
- `--yolo`: Enables non-interactive auto-approval mode. Automatically accepts all inferred operations.
- `--debug`: Outputs detailed logs of the inference process and execution steps.
- `--save-session`: Saves the entire execution session to the `.workflow/WFS-[topic-slug]/.chat/` directory.
### 🔄 High-Level Execution Flow
- **Description Input**: `Keyword Extraction` -> `Pattern Mapping` -> `Context Collection` -> `Gemini Execution`
- **Task ID Input**: `Task Parsing` -> `Type & Scope Analysis` -> `Reference Integration` -> `Gemini Execution`
### 🧠 Intelligent Inference Logic
This logic determines which files are collected as context before calling the Gemini CLI.
```pseudo
FUNCTION infer_context(input, user_description):
collected_files = ["@{CLAUDE.md,**/*CLAUDE.md}"] // Base context
// Check for and process user-specified file overrides first
IF user_description contains "@{...}":
user_patterns = extract_patterns_from_string(user_description)
collected_files += user_patterns
// Determine execution mode based on input format
IF input matches pattern 'IMPL-*': // Task ID Mode
task_data = read_json_file(".task/" + input + ".json")
IF task_data is not found:
RAISE_ERROR("Task ID not found")
RETURN
// Infer patterns based on task type (e.g., "feature", "bugfix")
type_patterns = get_patterns_for_task_type(task_data.type)
collected_files += type_patterns
collected_files += task_data.brainstorming_refs
ELSE: // User Description Mode
keywords = extract_tech_keywords(user_description)
// Map keywords to file patterns (e.g., "React" -> "src/components/**/*.{jsx,tsx}")
inferred_patterns = map_keywords_to_file_patterns(keywords)
collected_files += inferred_patterns
// The final collected files are used to construct the Gemini command
// This corresponds to calling the allowed tool `Bash(gemini:*)`
run_gemini_cli(collected_files, user_description)
END FUNCTION
```
### 🖐️ User Override Logic
Users can override or supplement the automatic inference.
```pseudo
FUNCTION calculate_final_patterns(description):
inferred_patterns = get_inferred_patterns(description) // e.g., **/*auth*
user_patterns = extract_user_patterns(description) // e.g., @{custom/auth/helpers.js}
// The final context is the union of inferred and user-specified patterns
final_patterns = inferred_patterns + user_patterns
RETURN final_patterns
END FUNCTION
```
### 🛠️ Gemini CLI Integration (Templated)
The following templates are used to call the `gemini` command via the `Bash` tool.
```bash
# User Description Mode
gemini --all-files -p "@{intelligently_inferred_file_patterns} @{CLAUDE.md,**/*CLAUDE.md}
Implementation Task: [user_description]
Based on intelligently inferred context, please provide:
- Specific implementation code
- File modification locations (file:line)
- Test cases
- Integration guidance"
# Task ID Mode
gemini --all-files -p "@{task_related_files} @{brainstorming_refs} @{CLAUDE.md,**/*CLAUDE.md}
Task Execution: [task_title] (ID: [task-id])
Task Description: [extracted_from_json]
Task Type: [feature/bugfix/refactor/etc]
Please execute implementation based on task definition:
- Follow task acceptance criteria
- Based on brainstorming analysis results
- Provide specific code and tests"
```
### 🔗 Workflow System Integration Logic
The command integrates deeply with the workflow system, especially with `--yolo`.
```pseudo
FUNCTION execute_with_workflow(task, flags):
IF "--yolo" in flags:
// With --yolo, all confirmation steps are automatically approved.
confirm_inferred_files = TRUE
confirm_gemini_execution = TRUE
confirm_file_modifications = TRUE
ELSE:
// Standard mode requires user confirmation at each critical step.
confirm_inferred_files = request_user_confirmation("Approve inferred files?")
// ... and so on for other steps.
IF all_confirmations_are_true:
execute_gemini_task(task)
// Actions performed after successful execution
generate_task_summary_doc()
update_workflow_status_files() // Updates WFS & workflow-session.json
END FUNCTION
```
### 📄 Task Summary Template (Templated)
This template is automatically filled and generated after execution.
```markdown
# Task Summary: [Task-ID/Generated-ID] [Task Name/Description]
## Execution Content
- **Intelligently Inferred Files**: [inferred_file_patterns]
- **Gemini Analysis Results**: [key_findings]
- **Implemented Features**: [specific_implementation_content]
- **Modified Files**: [file:line references]
## Issues Resolved
- [list_of_resolved_problems]
## Links
- [🔙 Back to Task List](../TODO_LIST.md#[Task-ID])
- [📋 Implementation Plan](../IMPL_PLAN.md#[Task-ID])
```
### 🛡️ Error Handling Protocols
- **Keyword Inference Failure**: `Use generic pattern 'src/**/*'` -> `Prompt user for manual specification`.
- **Task ID Not Found**: `Display error message` -> `List available tasks`.
- **File Pattern No Matches**: `Expand search scope` -> `Log debug info`.
- **Gemini CLI Failure**: `Attempt fallback mode (e.g., --all-files -> @{patterns})` -> `Simplify context & retry`.
### ⚡ Performance Optimizations
- **Caching**: Caches frequently used keyword-to-pattern mapping results.
- **Pattern Optimization**: Avoids overly broad file patterns like `**/*` where possible.
- **Progressive Inference**: Tries precise patterns (`src/api/auth`) before broader ones (`**/*auth*`).
- **Path Navigation**: Switches to the optimal execution directory based on inference to shorten paths.
### 🤝 Integration & Coordination
- **vs. `gemini-chat`**: `gemini-chat` is for pure analysis; `/gemini-execute` performs analysis **and** execution.
- **vs. `code-developer`**: `code-developer` requires manual context provision; `/gemini-execute` infers context automatically.
- **Typical Workflow Sequence**:
1. `workflow:session "..."`
2. `workflow:brainstorm`
3. `workflow:plan`
4. `/gemini-execute IMPL-001 --yolo`
5. `workflow:review`
### 💾 Session Persistence
⚠️ **CRITICAL**: Before saving, MUST check for existing active session to avoid creating duplicate sessions.
- **Trigger**: Activated by the `--save-session` flag.
- **Action**: Saves the complete execution session, including inferred context, Gemini analysis, and implementation results.
- **Session Check**: Query `.workflow/session_status.jsonl` to identify current active session.
- **Location Strategy**:
- **IF active session exists**: Save to existing `.workflow/WFS-[topic-slug]/.chat/` directory
- **IF no active session**: Create new session directory following WFS naming convention
**Core Principles**: @~/.claude/workflows/core-principles.md
**File Structure**: @~/.claude/workflows/file-structure-standards.md
- **File Format**: `execute-YYYYMMDD-HHMMSS.md` with timestamp for unique identification.
- **Structure**: Integrates with session management system using WFS-[topic-slug] format for consistency.
- **Coordination**: Session files coordinate with workflow-session.json and maintain document-state separation.
### 🔗 Execution Session Integration
**Storage Structure:**
```
.workflow/WFS-[topic-slug]/.chat/
├── execute-20240307-143022.md # Execution sessions with timestamps
├── execute-20240307-151445.md # Chronologically ordered
└── analysis-[topic].md # Referenced analysis sessions
```
**Execution Session Template:**
```markdown
# Execution Session: [Timestamp] - [Task/Description]
## Input
[Original user description or Task ID]
## Context Inference
[Intelligently inferred file patterns and rationale]
## Task Details (if Task ID mode)
[Extracted task data from .task/*.json]
## Gemini Execution
[Complete Gemini CLI command and parameters]
## Implementation Results
[Code generated, files modified, test cases]
## Key Outcomes
- [Files modified/created]
- [Features implemented]
- [Issues resolved]
## Integration Links
- [🔙 Workflow Session](../workflow-session.json)
- [📋 Implementation Plan](../IMPL_PLAN.md)
- [📝 Task Definitions](../.task/)
- [📑 Summary](../.summaries/)
```
### ✅ Quality Assurance Principles
- **Inference Accuracy**: Keyword mapping tables are regularly updated based on project patterns and user feedback.
- **Execution Reliability**: Implements robust error handling and leverages debug mode for detailed tracing.
- **Documentation Completeness**: Ensures auto-generated summaries are structured and workflow statuses are synced in real-time.
### 📚 Related Documentation

178
.claude/commands/gemini-mode.md Normal file
View File

@@ -0,0 +1,178 @@
---
name: gemini-mode
description: Advanced Gemini CLI analysis with template-driven pattern detection and comprehensive codebase insights
usage: /gemini-mode <analysis-type> <target> [options]
argument-hint: pattern|architecture|security|performance|feature|quality|dependencies|migration|custom "analysis target" [--yolo|--debug|--interactive]
examples:
- /gemini-mode pattern "Find all React hooks usage patterns"
- /gemini-mode architecture "Analyze component hierarchy and structure"
- /gemini-mode security "Scan for authentication vulnerabilities"
- /gemini-mode feature "Trace user login implementation"
- /gemini-mode performance "Identify potential bottlenecks"
- /gemini-mode custom "Find all API endpoints" --yolo
model: haiku
---
### 🚀 Command Overview: `/gemini-mode`
- **Purpose**: To perform advanced, template-driven analysis on a codebase for various insights like patterns, architecture, and security.
- **Core Principle**: Leverages intelligent context detection to apply optimized analysis templates.
### 🔄 High-Level Execution Flow
`User Input` **->** `Intelligent Context Detection` **->** `Template-Based Analysis`
### 🎯 Analysis Types
| Type | Purpose | Example Usage |
| :------------- | :------------------------------- | :------------------------------------------ |
| **pattern** | Code pattern detection | `/gemini-mode pattern "React hooks usage"` |
| **architecture** | System structure analysis | `/gemini-mode architecture "component hierarchy"` |
| **security** | Security vulnerabilities | `/gemini-mode security "auth vulnerabilities"` |
| **performance** | Performance bottlenecks | `/gemini-mode performance "rendering issues"` |
| **feature** | Feature implementation tracing | `/gemini-mode feature "user authentication"`|
| **quality** | Code quality assessment | `/gemini-mode quality "testing coverage"` |
| **dependencies** | Third-party dependencies | `/gemini-mode dependencies "outdated packages"` |
| **migration** | Legacy modernization | `/gemini-mode migration "React class to hooks"` |
| **custom** | Custom analysis | `/gemini-mode custom "find user data processing"` |
### ⚙️ Command Options
| Option | Purpose |
| :--------------- | :------------------------------------ |
| `--yolo` | Auto-approve analysis (non-interactive mode). |
| `--debug` | Enable debug mode for verbose logging. |
| `--interactive` | Start an interactive session for follow-up questions. |
| `--model <name>` | Specify which Gemini model to use. |
| `--sandbox` | Run the analysis in a secure sandbox environment. |
### 📚 Template System
The command's intelligence is powered by a set of predefined templates for different analysis categories.
| Template Category | Purpose | Source Reference |
| :-------------------- | :---------------------------------- | :------------------------------------------------ |
| **Core Analysis** | Pattern, architecture, security, etc. | `@~/.claude/workflows/gemini-core-templates.md` |
| **DMS Operations** | Documentation management | `@~/.claude/workflows/gemini-dms-templates.md` |
| **Agent Workflows** | Agent-specific templates | `@~/.claude/workflows/gemini-agent-templates.md` |
| **Intelligent Context** | Smart targeting & detection logic | `@~/.claude/workflows/gemini-intelligent-context.md` |
### 🧠 Smart File Targeting Logic
The command automatically determines which files to analyze based on context.
```pseudo
FUNCTION determine_target_files(analysis_type, keywords):
// 1. Detect technology stack (e.g., React, Python)
tech_stack = detect_project_tech()
file_extensions = get_extensions_for(tech_stack) // e.g., {js,ts,jsx} for React
// 2. Generate patterns based on keywords
// Corresponds to: Keywords: "auth" -> auth files, "api" -> API files
IF "auth" in keywords:
add_pattern("@{**/auth/**/*,**/user/**/*}")
ELSE IF "api" in keywords:
add_pattern("@{api/**/*,routes/**/*,controllers/**/*}")
// 3. Generate patterns based on analysis type
// Corresponds to: Analysis type: Security -> auth/security files
CASE analysis_type:
WHEN "security":
add_pattern("@{**/auth/**/*,**/security/**/*}")
WHEN "architecture":
add_pattern("@{src/**/*,app/**/*,lib/**/*}")
// 4. Inject standard relevant context
add_pattern("@{CLAUDE.md,**/*CLAUDE.md}")
RETURN combined_patterns
END FUNCTION
```
### 📂 File Reference Syntax Guide
```
# Basic @ Syntax
@{file} # Single file
@{dir/*} # All files in directory
@{dir/**/*} # All files recursively
@{*.ext} # Files by extension
@{**/*.ext} # Files by extension recursively
# Advanced Patterns
@{file1,file2,file3} # Multiple specific files
@{dir1/**/*,dir2/**/*} # Multiple directories
@{**/*.{js,ts,jsx,tsx}} # Multiple extensions
@{**/[module]/**/*} # Pattern matching
# Context-Specific Targeting
# Frontend components
@{src/components/**/*,src/ui/**/*,src/views/**/*}
# Backend APIs
@{api/**/*,routes/**/*,controllers/**/*,middleware/**/*}
# Configuration files
@{*.config.js,*.json,.env*,config/**/*}
# Test files
@{**/*.test.*,**/*.spec.*,test/**/*,spec/**/*}
# Documentation and guidelines
@{*.md,docs/**/*,CLAUDE.md,**/*CLAUDE.md}
```
### 🔗 Workflow Integration Patterns
⚠️ **CRITICAL**: Before analysis, MUST check for existing active session to ensure proper workflow context and documentation storage.
**Session Check Process:**
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions
2. **Context Integration**: Use existing active session for proper analysis context
3. **Documentation Strategy**: Store analysis results in appropriate session directory structure
- **Planning Phase**:
`Check Active Session` **->** `Run /gemini-mode architecture` **->** `Run /gemini-mode pattern` **->** `Feed results into Task(planning-agent, ...)`
- **Code Review**:
`Check Active Session` **->** `Run /gemini-mode security "auth"` **->** `Run /gemini-mode performance "rendering"` **->** `Summarize findings for PR comments`
- **Research & Discovery**:
`Check Active Session` **->** `Run /gemini-mode architecture "overview"` **->** `Run /gemini-mode dependencies "key libraries"` **->** `Document for new team members`
### 🛠️ Task Tool Integration Example
Integrate `/gemini-mode` directly into automated tasks for analysis-driven actions.
```python
Task(subagent_type="general-purpose", prompt="""
Use /gemini-mode pattern "auth patterns" to analyze authentication.
Summarize findings for implementation planning.
""")
```
### 👍 Best Practices
- **Scope**: Use specific, focused targets for faster, more accurate results.
- **Chaining**: Combine analysis types (`architecture` then `pattern`) for a comprehensive view.
- **Interpretation**: Use Gemini's raw output as input for Claude to interpret, summarize, and act upon.
- **Performance**: Use `--yolo` for non-destructive analysis to skip confirmations. Be mindful that analyzing all files may be slow on large projects.
### 📋 Common Use Cases
| Use Case | Recommended Commands |
| :--------------------- | :------------------------------------------------------------------------------------ |
| **Project Onboarding** | `/gemini-mode architecture "overview"`, `/gemini-mode dependencies "key tech"` |
| **Security Audit** | `/gemini-mode security "auth vulnerabilities"`, `/gemini-mode security "XSS"` |
| **Performance Review** | `/gemini-mode performance "bottlenecks"`, `/gemini-mode performance "optimization"` |
| **Migration Planning** | `/gemini-mode migration "legacy patterns"`, `/gemini-mode migration "modernization"`|
| **Feature Research** | `/gemini-mode feature "existing system"`, `/gemini-mode pattern "approaches"` |
### 🆘 Troubleshooting
| Issue | Solution |
| :--------------------- | :-------------------------------------------------- |
| **Analysis timeout** | Use `--debug` to monitor progress and identify slow steps. |
| **Context limits** | Break the analysis into smaller, more focused scopes. |
| **Permission errors** | Ensure the CLI has read access to the target files. |
| **Complex analysis** | Use `--interactive` mode to ask follow-up questions. |

466
.claude/commands/task/breakdown.md Normal file
View File

@@ -0,0 +1,466 @@
---
name: task-breakdown
description: Intelligent task decomposition with context-aware subtask generation
usage: /task:breakdown <task-id> [--strategy=<auto|interactive>] [--depth=<1-3>]
argument-hint: task-id [optional: strategy and depth]
examples:
- /task:breakdown IMPL-1
- /task:breakdown IMPL-1 --strategy=auto
- /task:breakdown IMPL-1.1 --depth=2 --strategy=interactive
---
# Task Breakdown Command (/task:breakdown)
## Overview
Intelligently breaks down complex tasks into manageable subtasks with automatic context distribution and agent assignment.
## Core Principles
**System:** @~/.claude/workflows/unified-workflow-system-principles.md
**Task Schema:** @~/.claude/workflows/task-management-principles.md
## Features
⚠️ **CRITICAL**: Before breakdown, MUST check for existing active session to avoid creating duplicate sessions.
### Session Check Process
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions
2. **Session Validation**: Use existing active session containing the parent task
3. **Context Integration**: Load existing session state and task hierarchy
### Smart Decomposition
- **Auto Strategy**: AI-powered subtask generation based on title
- **Interactive Mode**: Guided breakdown with suggestions
- **Context Distribution**: Subtasks inherit parent context
- **Agent Mapping**: Automatic agent assignment per subtask
### Built-in Task Management
- **JSON Task Hierarchy**: Creates hierarchical JSON subtasks (impl-N.M.P)
- **TODO_LIST.md Integration**: Automatically updates progress display with new subtask structure
- **TODO_LIST.md Maintenance**: Updates task hierarchy display with parent-child relationships
- **Context Distribution**: Subtasks inherit and refine parent context
- **Progress Synchronization**: Updates hierarchical progress calculations in TODO_LIST.md
- **No External Commands**: All task operations are internal to this command
### Breakdown Rules
- Only `pending` tasks can be broken down
- Parent becomes container (not directly executable)
- Subtasks use hierarchical format: impl-N.M.P (e.g., IMPL-1.1.2)
- Maximum depth: 3 levels (impl-N.M.P)
- Parent task progress = average of subtask progress
- Automatically updates TODO_LIST.md with hierarchical structure
## Usage
### Basic Breakdown
```bash
/task:breakdown IMPL-1
```
Interactive prompt with automatic task management:
```
Task: Build authentication module
Workflow: 28 total tasks (Complex workflow detected)
Suggested subtasks:
1. Design authentication schema
2. Implement login endpoint
3. Add JWT token handling
4. Write unit tests
Internal task processing:
✅ Level 2 hierarchy will be created (embedded logic)
Reason: >15 total tasks detected
Process: Automatic task hierarchy creation without external command calls
Accept task breakdown? (y/n/edit): y
```
### Auto Strategy with Override Options
```bash
/task:breakdown IMPL-1 --strategy=auto
/task:breakdown IMPL-1 --force-level=2 # Force specific document level
/task:breakdown IMPL-1 --no-split # Disable automatic document splitting
```
Automatic generation:
```
✅ Task IMPL-1 broken down:
├── IMPL-1.1: Design authentication schema
├── IMPL-1.2: Implement core auth logic
├── IMPL-1.3: Add security middleware
└── IMPL-1.4: Write comprehensive tests
Agents assigned:
- IMPL-1.1 → planning-agent
- IMPL-1.2 → code-developer
- IMPL-1.3 → code-developer
- IMPL-1.4 → test-agent
📄 Internal task processing:
- JSON subtasks: IMPL-1.1, IMPL-1.2, IMPL-1.3, IMPL-1.4 created
- Task structure: Level 2 hierarchy established through embedded logic
- Progress tracking: TODO_LIST.md updated with hierarchical progress display
- Cross-references: All task links generated and validated internally
```
## Decomposition Patterns
### Feature Task Pattern
```
Feature: "Implement shopping cart"
├── Design data model
├── Build API endpoints
├── Add state management
├── Create UI components
└── Write tests
```
### Bug Fix Pattern
```
Bug: "Fix performance issue"
├── Profile and identify bottleneck
├── Implement optimization
├── Verify fix
└── Add regression test
```
### Refactor Pattern
```
Refactor: "Modernize auth system"
├── Analyze current implementation
├── Design new architecture
├── Migrate incrementally
├── Update documentation
└── Deprecate old code
```
## Context Distribution
Parent context is intelligently distributed:
```json
{
"parent": {
"id": "IMPL-1",
"context": {
"inherited_from": "WFS-[topic-slug]",
"requirements": ["JWT auth", "2FA support"],
"scope": ["src/auth/*"],
"acceptance": ["Authentication system works"]
}
},
"subtasks": [
{
"id": "IMPL-1.1",
"title": "Design authentication schema",
"status": "pending",
"agent": "planning-agent",
"context": {
"inherited_from": "IMPL-1",
"requirements": ["JWT auth schema", "User model design"],
"scope": ["src/auth/models/*"],
"acceptance": ["Schema validates JWT tokens", "User model complete"]
}
}
]
}
```
## Agent Assignment Logic
Based on subtask type:
- **Design/Planning** → `planning-agent`
- **Implementation** → `code-developer`
- **Testing** → `test-agent`
- **Documentation** → `docs-agent`
- **Review** → `review-agent`
## Validation
### Pre-breakdown Checks
1. Task exists and is valid
2. Task status is `pending`
3. Not already broken down
4. Workflow in IMPLEMENT phase
### Post-breakdown Actions
1. Update parent status to `container`
2. Create subtask JSON files with document references
3. Update IMPL_PLAN.md with enhanced task hierarchy structure
4. Create/update TODO_LIST.md with progress tracking
5. Update workflow session with document references
6. Validate phase alignment with IMPL_PLAN.md (if exists)
7. Generate execution plan with document coordination
## Execution Planning
After breakdown, generates execution order:
```
Execution Plan for IMPL-1:
Phase 1 (Parallel):
- IMPL-1.1: Design authentication schema
Phase 2 (Sequential):
- IMPL-1.2: Implement core auth logic
- IMPL-1.3: Add security middleware
Phase 3 (Parallel):
- IMPL-1.4: Write comprehensive tests
Dependencies resolved automatically
```
## Built-in Document Management
### Automatic File Structure Creation (Based on Workflow Scale)
#### Level 0: Unified Documents (<15 tasks)
```
.workflow/WFS-[topic-slug]/
├── IMPL_PLAN.md (enhanced) # Updated with new task hierarchy
├── TODO_LIST.md # Updated with new progress entries
├── workflow-session.json # Session state
└── .task/
├── IMPL-1.json # Parent task (container)
├── IMPL-1.1.json # Subtask 1
└── IMPL-1.2.json # Subtask 2
```
#### Level 1: Enhanced Structure (5-15 tasks)
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json
├── IMPL_PLAN.md # Combined planning document
├── TODO_LIST.md # Progress tracking (auto-generated)
├── .summaries/ # Task completion summaries
│ ├── IMPL-*.md # Main task summaries
│ └── IMPL-*.*.md # Subtask summaries
└── .task/
├── IMPL-*.json # Main task definitions
└── IMPL-*.*.json # Subtask definitions (up to 3 levels)
```
#### Level 2: Complete Structure (>15 tasks)
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json
├── IMPL_PLAN.md # Comprehensive planning document
├── TODO_LIST.md # Progress tracking and monitoring
├── .summaries/ # Task completion summaries
│ ├── IMPL-*.md # Main task summaries
│ ├── IMPL-*.*.md # Subtask summaries
│ └── IMPL-*.*.*.md # Detailed subtask summaries
└── .task/
├── IMPL-*.json # Task hierarchy (max 3 levels deep)
├── IMPL-*.*.json # Subtasks
└── IMPL-*.*.*.json # Detailed subtasks
```
### Built-in Document Creation Process
#### Level 0: Unified Document Updates (<15 tasks)
When task count is below threshold, command automatically updates unified documents:
- Updates existing IMPL_PLAN.md with enhanced task hierarchy structure
- Updates existing TODO_LIST.md with progress tracking
- Maintains TODO_LIST.md for progress coordination
#### Level 1: Task-Based Document Generation (15-50 tasks)
When enhanced complexity detected, command automatically:
**Updates IMPL_PLAN.md with task breakdown**:
- Adds hierarchical task structure with subtasks
- Updates requirements and acceptance criteria
- Maintains cross-references to JSON task files
- Preserves overall workflow context
**Creates/Updates TODO_LIST.md**:
- Displays hierarchical task structure with checkboxes
- Shows progress percentages and completion status
- Cross-references task details with JSON files
- Provides at-a-glance workflow progress overview
#### Level 2: Complete Structure Document Updates (>15 tasks)
When complex workflows detected, command automatically:
**Expands IMPL_PLAN.md with comprehensive planning**:
- Detailed task hierarchy with up to 3 levels deep
- Complete requirements analysis and acceptance criteria
- Risk assessment and mitigation strategies
- Cross-references to all JSON task files
**Maintains comprehensive TODO_LIST.md**:
- Full hierarchical display with progress rollups
- Multi-level task completion tracking
- Detailed progress percentages across task hierarchy
- Cross-references to .summaries/ for completed tasks
**Manages .summaries/ directory**:
- Creates task completion documentation structure
- Maintains audit trail of implementation decisions
- Links completed tasks back to workflow session
### JSON Task Management Integration
#### Task JSON Structure
```json
{
"id": "IMPL-1.1",
"title": "Design authentication schema",
"parent_id": "IMPL-1",
"status": "pending",
"type": "design",
"agent": "planning-agent",
"effort": "1h",
"context": {
"inherited_from": "IMPL-1",
"requirements": ["User model schema", "JWT token design"],
"scope": ["src/auth/models/*", "auth-schema.md"],
"acceptance": ["Schema validates JWT tokens", "User model complete"]
},
"hierarchy_context": {
"parent_task": "IMPL-1",
"level": 2,
"siblings": ["IMPL-1.2", "IMPL-1.3", "IMPL-1.4"]
},
"dependencies": {
"upstream": [],
"downstream": ["IMPL-1.2", "IMPL-1.3"]
},
"metadata": {
"created_by": "task:breakdown IMPL-1 --split-docs",
"document_sync": "2025-09-05T10:35:00Z",
"splitting_level": 2
}
}
```
#### TODO_LIST.md Integration
The task breakdown automatically updates TODO_LIST.md with:
- **Hierarchical Task Display**: Shows parent-child relationships using checkbox indentation
- **Progress Tracking**: Calculates completion percentages based on subtask status
- **JSON Cross-References**: Links to .task/ JSON files for detailed task information
- **Status Synchronization**: Keeps TODO_LIST.md checkboxes in sync with JSON task status
### Coordination with IMPL_PLAN.md
If IMPL_PLAN.md exists (complex workflows), task breakdown validates against phase structure:
```markdown
### Phase 1: Foundation
- **Tasks**: IMPL-1 → Now broken down to IMPL-1.1-4
- **Validation**: ✅ All subtasks align with phase objectives
- **Dependencies**: ✅ Phase dependencies preserved
```
## Advanced Options
### Depth Control
```bash
# Single level (default)
/task:breakdown IMPL-1 --depth=1
# Two levels (for complex tasks)
/task:breakdown IMPL-1 --depth=2
```
### Custom Breakdown
```bash
/task:breakdown IMPL-1 --custom
> Enter subtask 1: Custom subtask title
> Assign agent (auto/manual): auto
> Enter subtask 2: ...
```
## Task Validation & Error Handling
### Comprehensive Validation Checks
```bash
/task:breakdown impl-1 --validate
Pre-breakdown validation:
✅ workflow-session.json exists and is writable
✅ .task/ directory accessible
✅ Parent task JSON file valid
✅ Hierarchy depth within limits (max 3 levels)
⚠️ Complexity threshold reached - will generate TODO_LIST.md
Post-breakdown validation:
✅ All subtask JSON files created in .task/
✅ Parent-child relationships established
✅ Cross-references consistent across files
✅ TODO_LIST.md generated/updated (if triggered)
✅ workflow-session.json synchronized
✅ File structure matches complexity level
```
### Error Recovery & File Management
```bash
# JSON file conflicts
⚠️ Parent task JSON structure inconsistent with breakdown
→ Auto-sync parent JSON file? (y/n)
# Missing directory structure
❌ .task/ directory not found
→ Create required directory structure? (y/n)
# Complexity level mismatch
⚠️ Task count suggests Level 1 but structure is Level 0
→ 1. Upgrade structure 2. Keep minimal 3. Manual adjustment
# Hierarchy depth violation
❌ Attempting to create impl-1.2.3.4 (exceeds 3-level limit)
→ 1. Flatten hierarchy 2. Reorganize structure 3. Abort
```
## Integration
### Workflow Updates
- Updates task count in session
- Recalculates progress metrics
- Maintains task hierarchy in both JSON and documents
- Synchronizes document references across all files
### File System Integration
- **Real-time Sync**: JSON task files updated immediately during breakdown
- **Bidirectional Sync**: Maintains consistency between JSON, TODO_LIST.md, and session
- **Conflict Resolution**: JSON files are authoritative for task details and hierarchy
- **Version Control**: All task changes tracked in .task/ directory
- **Backup Recovery**: Can restore task hierarchy from workflow-session.json
- **Structure Validation**: Ensures compliance with progressive structure standards
### Next Actions
After breakdown:
- `/task:execute` - Run subtasks using JSON task context
- `/task:status` - View hierarchy from JSON files and TODO_LIST.md
- `/task:context` - Analyze task relationships and JSON structure
- `/task:replan` - Adjust breakdown and update task structure
## Examples
### Complex Feature
```bash
/task:breakdown IMPL-1 --strategy=auto --depth=2
Result:
IMPL-1: E-commerce checkout
├── IMPL-1.1: Payment processing
│ ├── IMPL-1.1.1: Integrate payment gateway
│ ├── IMPL-1.1.2: Handle transactions
│ └── IMPL-1.1.3: Add error handling
├── IMPL-1.2: Order management
│ ├── IMPL-1.2.1: Create order model
│ └── IMPL-1.2.2: Implement order workflow
└── IMPL-1.3: Testing suite
```
## Related Commands
- `/task:create` - Create new tasks
- `/task:context` - Manage task context
- `/task:execute` - Execute subtasks
- `/task:replan` - Adjust breakdown
- `/task:status` - View task hierarchy

349
.claude/commands/task/context.md Normal file
View File

@@ -0,0 +1,349 @@
---
name: task-context
description: Unified task context analysis, status management, and intelligent execution support
usage: /task:context [task-id|--filter=<filter>] [--analyze] [--update] [--sync] [--format=<tree|list|json>] [--detailed]
argument-hint: [task-id or filter] [optional: actions and format options]
examples:
- /task:context
- /task:context IMPL-001 --analyze --detailed
- /task:context --filter="status:active" --format=tree
- /task:context IMPL-001 --update
- /task:context --sync
---
### 🚀 Command Overview: /task:context
- **Purpose**: Provides unified task context analysis, status visualization, progress tracking, and intelligent execution support.
- **Core Function**: Acts as a central hub for understanding and managing the state of tasks within a workflow.
### 📜 Core Principles
- **Task Management**: @~/.claude/workflows/task-management-principles.md
- **File Structure**: @~/.claude/workflows/file-structure-standards.md
- **Session Management**: @~/.claude/workflows/session-management-principles.md
### ✨ Core Capabilities
- **Context Awareness**
- Analyzes current state and progress from JSON task files.
- Tracks hierarchical task dependencies.
- Detects changes in JSON files and status.
- Assesses the impact of changes across tasks and files.
- Suggests next actions based on current context.
- Monitors compliance with file structure standards.
- **Status Management**
- Visualizes task status in `tree`, `list`, and `json` formats.
- Tracks hierarchical progress from task files.
- Performs batch operations on tasks using filters.
- Monitors file integrity and task health.
- Exports analysis and status data to various file formats.
- Generates status reports and analysis documents.
### 🧠 Primary Operations Logic
The command's behavior is determined by the provided arguments.
```pseudo
FUNCTION main(arguments):
// Options like --filter and --format modify the behavior of display functions.
IF --sync is present:
// Corresponds to: /task:context --sync
run_context_synchronization()
ELSE IF --update is present AND task_id is given:
// Corresponds to: /task:context <task-id> --update
run_interactive_update_for(task_id)
ELSE IF --analyze is present AND task_id is given:
// Corresponds to: /task:context <task-id> --analyze
run_detailed_analysis_for(task_id)
ELSE IF --health, --progress, --timeline, etc. are present:
// Corresponds to specific reporting sub-commands
generate_specific_report(report_type)
ELSE IF task_id is provided without other primary action flags:
// Corresponds to: /task:context <task-id>
display_task_context_and_quick_actions(task_id)
ELSE:
// Default action with no arguments or only filters/formatters
// Corresponds to: /task:context
display_global_context_view(filters, format)
END FUNCTION
```
### 🎯 Main Usage Modes & Examples
#### 1. Global Context View
- **Command**: `/task:context`
- **Description**: Provides a high-level overview of the entire workflow's task status.
- **Example Output**:
```
📊 Task Context Overview
━━━━━━━━━━━━━━━━━━━━━━
Workflow: WFS-[topic-slug]
Phase: IMPLEMENT
Progress: 45% (5/11 tasks)
Summary:
✅ Completed: 5
🔄 Active: 2
⏳ Pending: 3
🚫 Blocked: 1
Active Context:
- Current focus: IMPL-002 (In Progress)
- Dependencies clear: Yes
- Blockers: IMPL-004 blocked by IMPL-003
Critical Path:
IMPL-001 → IMPL-003 → IMPL-006
Next Actions:
1. Complete IMPL-002 (90% done)
2. Unblock IMPL-004
3. Start IMPL-005 (ready)
```
#### 2. Task-Specific Analysis
- **Command**: `/task:context IMPL-001 --analyze`
- **Description**: Shows a detailed breakdown of a single task's context, dependencies, and related changes.
- **Example Output**:
```
📋 Task Context: IMPL-001
━━━━━━━━━━━━━━━━━━━━
Status: In Progress
Started: 2h ago
Progress: 60% (2/3 subtasks complete)
Dependencies:
✅ No upstream dependencies
⬇️ Blocks: IMPL-003, IMPL-004
Context Data:
- Requirements: [inherited from workflow]
- Scope: src/auth/*, tests/auth/*
- Agent: code-developer
- Priority: high
Related Changes:
- src/auth/login.ts modified 30m ago
- New issue: "Login timeout too short"
- Workflow update: Security requirement added
Impact if delayed:
⚠️ Will block 2 downstream tasks
⚠️ Critical path - affects timeline
```
#### 3. Interactive Context Update
- **Command**: `/task:context IMPL-001 --update`
- **Description**: Initiates an interactive prompt to modify a task's context data.
- **Example Interaction**:
```
Current context for IMPL-001:
1. Requirements: [JWT, OAuth2]
2. Scope: [src/auth/*]
3. Priority: normal
What to update?
1. Add requirement
2. Modify scope
3. Change priority
4. Add note
> 1
Enter new requirement: Add 2FA support
✅ Context updated
```
#### 4. Context Synchronization
- **Command**: `/task:context --sync`
- **Description**: Reconciles context across the entire task hierarchy, propagating changes and resolving conflicts.
- **Example Output**:
```
🔄 Synchronizing task contexts...
- Workflow → Tasks: Updated 3 tasks
- Parent → Children: Propagated 2 changes
- Dependencies: Resolved 1 conflict
✅ All contexts synchronized
```
### 🖥️ Display Formats (`--format`)
#### Tree Format (`--format=tree`)
```
📁 IMPLEMENT Tasks
├── ✅ IMPL-001: Authentication [Complete]
│ ├── ✅ IMPL-001.1: Design schema
│ ├── ✅ IMPL-001.2: Core implementation
│ └── ✅ IMPL-001.3: Tests
├── 🔄 IMPL-002: Database layer [60%]
│ ├── ✅ IMPL-002.1: Models
│ ├── 🔄 IMPL-002.2: Migrations
│ └── ⏳ IMPL-002.3: Seeds
├── ⏳ IMPL-003: API endpoints [Pending]
└── 🚫 IMPL-004: Integration [Blocked by IMPL-003]
```
#### List Format (`--format=list`)
```
ID | Title | Status | Progress | Agent | Priority
---------|--------------------------|-----------|----------|-----------------|----------
IMPL-001 | Authentication | completed | 100% | code-developer | normal
IMPL-002 | Database layer | active | 60% | code-developer | high
IMPL-003 | API endpoints | pending | 0% | planning-agent | normal
IMPL-004 | Integration | blocked | 0% | - | low
```
#### JSON Format (`--format=json`)
- **Description**: Outputs machine-readable JSON, suitable for scripting and tool integration.
### 🔍 Filtering (`--filter`)
- **By Status**:
- `status:active`
- `status:pending`
- `status:blocked`
- `status:completed`
- **By Other Attributes**:
- `type:feature`
- `priority:high`
- **Combining Filters**:
- `status:active,priority:high`
### 🧠 Context Intelligence Features
- **Change Detection**: Automatically detects file modifications, new issues, workflow updates, and dependency status changes.
- **Impact Analysis**: Assesses the effect of delays or failures on downstream tasks and the overall timeline (`--impact`).
- **Smart Recommendations**: Provides actionable suggestions like which task to focus on, what can be parallelized, or which tasks need breaking down (`--recommend`).
### 📄 Context Data Structure (JSON Schema)
This is the standard schema for a task's context data stored in JSON files.
```json
{
"task_id": "IMPL-001",
"title": "Build authentication module",
"type": "feature",
"status": "active",
"priority": "high",
"agent": "code-developer",
"context": {
"inherited_from": "WFS-[topic-slug]",
"requirements": ["JWT authentication", "OAuth2 support", "2FA support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented", "2FA integration works"]
},
"dependencies": {
"upstream": [],
"downstream": ["IMPL-003", "IMPL-004"]
},
"execution": {
"attempts": 1,
"current_attempt": {
"started_at": "2025-09-05T10:35:00Z",
"checkpoints": ["setup", "implement", "test", "validate"],
"completed_checkpoints": ["setup", "implement"]
},
"history": []
},
"environment": {
"files_modified": ["src/auth/login.ts", "src/auth/middleware.ts"],
"issues": ["ISS-001"],
"last_activity": "2025-09-05T12:15:00Z"
},
"recommendations": {
"next_action": "Complete test checkpoint",
"risk": "low",
"priority_adjustment": "none"
}
}
```
### 📊 Analysis & Monitoring
- **Progress Report (`--progress`)**: Shows overall progress broken down by type, priority, and velocity.
- **Health Checks (`--health`)**: Reports on task health, highlighting issues like blockers, delays, and repeated failures.
- **Timeline View (`--timeline`)**: Displays a chronological view of recent and upcoming task activities.
### 🛠️ Advanced Features
- **Conflict Detection (`--conflicts`)**: Identifies potential conflicts, such as multiple tasks modifying the same file.
- **Historical Context (`--history`)**: Shows the version history of a task's context data.
- **Context Validation (`--validate`)**: Checks a task's context for completeness and validity against defined rules.
### 🚦 Status Management
- **Update Status**: Change a single task's status using `--set`. Example: `/task:context IMPL-002 --set=active`
- **Bulk Update**: Update multiple tasks matching a filter. Example: `/task:context --filter="status:pending" --set=blocked --reason="Waiting for API"`
- **Valid Status Transitions**:
`pending` -> `active` -> `completed`
`pending` -> `blocked`
`active` -> `blocked`
`active` -> `failed` -> `pending`
### 💾 File Output Generation
- **Analysis Report (`--report --save`)**:
- Generates a comprehensive markdown report.
- **Output**: `.workflow/WFS-[topic-slug]/.summaries/analysis-[timestamp].md`
- **Data Export (`--export=<format>`)**:
- Exports task data to various formats (`markdown`, `json`, `csv`).
- **Output**: `.summaries/[output-name]-[timestamp].[format]`
- **Validation Report (`--validate --save`)**:
- Saves the output of context validation to a file.
- **Output**: `.summaries/validation-report-[timestamp].md`
- **TODO_LIST.md Generation (`--generate-todo-list`)**:
- Creates a `TODO_LIST.md` file from the current state of JSON task files.
- **Output**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
### 🔗 Integration Points
- **Workflow**: Inherits context from the main workflow and updates `session.json`.
- **Task Relationships**: Manages parent-child and sibling dependencies, including circular dependency detection.
- **Agent Context**: Prepares and optimizes context data for execution by different agent types.
- **TodoWrite Tool**: Coordinates bidirectionally with the TodoWrite tool and `TODO_LIST.md` for seamless status updates (`--sync-todos`).
### ⚠️ Error Handling Examples
- **No Active Workflow**:
- `❌ No workflow context found`
- `→ Initialize with: /workflow init`
- **Task Not Found**:
- `❌ Task IMPL-999 does not exist`
- `→ View tasks with: /task:status`
- **Context Conflict**:
- `⚠️ Context conflict detected`
- `→ Resolve with: /task:context --resolve`
### ⚡ Quick Actions
- **Description**: When viewing a single task, an interactive menu of relevant actions is presented.
- **Example Interaction**:
```bash
/task:context IMPL-002
Quick actions available:
1. Execute task (/task:execute IMPL-002)
2. Analyze context (/task:context IMPL-002 --analyze)
3. Replan task (/task:replan IMPL-002)
4. Break down (/task:breakdown IMPL-002)
Select action: 1
→ Executing IMPL-002...
```
### 🤝 Related Commands
- `/task:create`: Creates new tasks.
- `/task:execute`: Executes a specific task.
- `/task:replan`: Replans a task.
- `/task:breakdown`: Breaks a task into subtasks.
- `/task:sync`: Synchronizes all file systems.
- `/workflow:context`: Provides overall workflow status.

303
.claude/commands/task/create.md Normal file
View File

@@ -0,0 +1,303 @@
---
name: task-create
description: Create implementation tasks with automatic context awareness
usage: /task:create "<title>" [--type=<type>] [--priority=<level>]
argument-hint: "task title" [optional: type and priority]
examples:
- /task:create "Implement user authentication"
- /task:create "Build REST API endpoints" --type=feature
- /task:create "Fix login validation bug" --type=bugfix --priority=high
---
# Task Create Command (/task:create)
## Overview
Creates new implementation tasks during IMPLEMENT phase with automatic context awareness and ID generation.
## Core Principles
**System:** @~/.claude/workflows/core-principles.md
**Task Management:** @~/.claude/workflows/task-management-principles.md
## Features
### Automatic Behaviors
- **ID Generation**: Auto-generates impl-N hierarchical format (impl-N.M.P max depth)
- **Context Inheritance**: Inherits from workflow session and IMPL_PLAN.md
- **JSON File Creation**: Generates task JSON in `.workflow/WFS-[topic-slug]/.task/`
- **Document Integration**: Creates/updates TODO_LIST.md based on complexity triggers
- **Status Setting**: Initial status = "pending"
- **Workflow Sync**: Updates workflow-session.json task list automatically
- **Agent Assignment**: Suggests agent based on task type
- **Hierarchy Support**: Creates parent-child relationships up to 3 levels
- **Progressive Structure**: Auto-triggers enhanced structure at complexity thresholds
### Context Awareness
- Detects current workflow phase (must be IMPLEMENT)
- Reads existing tasks from `.task/` directory to avoid duplicates
- Inherits requirements and scope from workflow-session.json
- Suggests related tasks based on existing JSON task hierarchy
- Analyzes complexity for structure level determination (Level 0-2)
## Usage
### Basic Creation
```bash
/task:create "Build authentication module"
```
Output:
```
✅ Task created: impl-1
Title: Build authentication module
Type: feature
Status: pending
Depth: 1 (main task)
Context inherited from workflow
```
### With Options
```bash
/task:create "Fix security vulnerability" --type=bugfix --priority=critical
```
### Task Types
- `feature` - New functionality (default)
- `bugfix` - Bug fixes
- `refactor` - Code improvements
- `test` - Test implementation
- `docs` - Documentation
### Priority Levels
- `low` - Can be deferred
- `normal` - Standard priority (default)
- `high` - Should be done soon
- `critical` - Must be done immediately
## Task Structure
```json
{
"id": "impl-1",
"parent_id": null,
"title": "Build authentication module",
"type": "feature",
"priority": "normal",
"status": "pending",
"depth": 1,
"agent": "code-developer",
"effort": "4h",
"context": {
"inherited_from": "WFS-user-auth-system",
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"]
},
"dependencies": {
"upstream": [],
"downstream": [],
"parent_dependencies": []
},
"subtasks": [],
"execution": {
"attempts": 0,
"current_attempt": null,
"history": []
},
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"started_at": null,
"completed_at": null,
"last_updated": "2025-09-05T10:30:00Z",
"version": "1.0"
}
}
```
## Document Integration Features
### JSON Task File Generation
**File Location**: `.workflow/WFS-[topic-slug]/.task/impl-[N].json`
**Hierarchical Naming**: Follows impl-N.M.P format for nested tasks
**Schema Compliance**: All JSON files follow unified task schema from task-management-principles.md
### Import from IMPL_PLAN.md
```bash
/task:create --from-plan
```
- Reads existing IMPL_PLAN.md implementation strategy
- Creates JSON task files based on planned structure
- Maintains hierarchical relationships in JSON format
- Preserves acceptance criteria from plan in task context
### Progressive Document Creation
Based on complexity analysis triggers:
#### Level 0 Structure (<5 tasks)
- Creates individual JSON task files in `.task/`
- No TODO_LIST.md generation (minimal overhead)
- Updates workflow-session.json with task references
#### Level 1 Structure (5-15 tasks)
- Creates hierarchical JSON task files (impl-N.M format)
- **Auto-generates TODO_LIST.md** when complexity threshold reached
- Creates `.summaries/` directory structure
- Enhanced cross-referencing between files
#### Level 2 Structure (>15 tasks)
- Creates complete hierarchical JSON files (impl-N.M.P format)
- Always maintains TODO_LIST.md with progress tracking
- Full `.summaries/` directory with detailed task documentation
- Comprehensive cross-references and validation
### Document Creation Triggers
TODO_LIST.md auto-generation conditions:
- **Task count > 5** OR **modules > 3** OR **estimated effort > 4h** OR **complex dependencies detected**
- **Always** for workflows with >15 tasks (Level 2 structure)
### Cross-Reference Management
- All JSON files contain proper parent_id relationships
- TODO_LIST.md links to individual JSON task files
- workflow-session.json maintains task list with hierarchy depth
- Automatic validation of cross-file references
## Context Inheritance
Tasks automatically inherit:
1. **Requirements** - From workflow-session.json context and IMPL_PLAN.md
2. **Scope** - File patterns from workflow and IMPL_PLAN.md strategy
3. **Standards** - Quality standards from workflow session
4. **Dependencies** - Related tasks from existing JSON task hierarchy in `.task/`
5. **Parent Context** - When created as subtasks, inherit from parent JSON file
6. **Session Context** - Global workflow context from active session
## Smart Suggestions
Based on title analysis:
```bash
/task:create "Write unit tests for auth module"
Suggestions:
- Related task: impl-1 (Build authentication module)
- Suggested agent: test-agent
- Estimated effort: 2h
- Dependencies: [impl-1]
- Suggested hierarchy: impl-1.3 (as subtask of impl-1)
```
## Validation Rules
1. **Phase Check** - Must be in IMPLEMENT phase (from workflow-session.json)
2. **Duplicate Check** - Title similarity detection across existing JSON files
3. **Session Validation** - Active workflow session must exist in `.workflow/`
4. **ID Uniqueness** - Auto-increment to avoid conflicts in `.task/` directory
5. **Hierarchy Validation** - Parent-child relationships must be valid (max 3 levels)
6. **File System Validation** - Proper directory structure and naming conventions
7. **JSON Schema Validation** - All task files conform to unified schema
## Error Handling
```bash
# Not in IMPLEMENT phase
❌ Cannot create tasks in PLAN phase
→ Use: /workflow implement
# No workflow session
❌ No active workflow found
→ Use: /workflow init "project name"
# Duplicate task
⚠️ Similar task exists: impl-3
→ Continue anyway? (y/n)
# Maximum depth exceeded
❌ Cannot create impl-1.2.3.1 (exceeds 3-level limit)
→ Suggest: impl-1.2.4 or promote to impl-2?
```
## Batch Creation
Create multiple tasks at once:
```bash
/task:create --batch
> Enter tasks (empty line to finish):
> Build login endpoint
> Add session management
> Write authentication tests
>
Created 3 tasks:
- impl-1: Build login endpoint
- impl-2: Add session management
- impl-3: Write authentication tests
```
## File Output Management
### JSON Task Files
**Output Location**: `.workflow/WFS-[topic-slug]/.task/impl-[id].json`
**Schema**: Follows unified task JSON schema with hierarchical support
**Contents**: Complete task definition including context, dependencies, and metadata
### TODO_LIST.md Generation
**Trigger Logic**: Auto-created based on complexity thresholds
**Location**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
**Format**: Hierarchical task display with checkboxes and progress tracking
### Summary Directory Structure
**Location**: `.workflow/WFS-[topic-slug]/.summaries/`
**Purpose**: Ready for task completion summaries
**Structure**: Created when Level 1+ complexity detected
### Workflow Session Updates
**File**: `.workflow/WFS-[topic-slug]/workflow-session.json`
**Updates**: Task list, counters, progress calculations, hierarchy depth
## Integration
### Workflow Integration
- Updates workflow-session.json with new task references
- Increments task counter and updates complexity assessment
- Updates IMPLEMENT phase progress and task hierarchy depth
- Maintains bidirectional sync with TodoWrite tool
### File System Coordination
- Validates and creates required directory structure
- Maintains cross-references between all generated files
- Ensures proper naming conventions and hierarchy limits
- Provides rollback capability for failed operations
### Next Steps
After creation, use:
- `/task:breakdown` - Split into hierarchical subtasks with JSON files
- `/task:execute` - Run the task with summary generation
- `/task:context` - View task details and file references
- `/task:sync` - Validate file consistency across system
## Examples
### Feature Development
```bash
/task:create "Implement shopping cart functionality" --type=feature
```
### Bug Fix
```bash
/task:create "Fix memory leak in data processor" --type=bugfix --priority=high
```
### Refactoring
```bash
/task:create "Refactor database connection pool" --type=refactor
```
## Related Commands
- `/task:breakdown` - Break task into hierarchical subtasks
- `/task:context` - View/modify task context
- `/task:execute` - Execute task with agent
- `/task:status` - View task status and hierarchy

216
.claude/commands/task/execute.md Normal file
View File

@@ -0,0 +1,216 @@
---
name: task-execute
description: Execute tasks with appropriate agents and context-aware orchestration
usage: /task:execute <task-id> [--mode=<auto|guided|review>] [--agent=<agent-type>]
argument-hint: task-id [optional: mode and agent override]
examples:
- /task:execute impl-1
- /task:execute impl-1 --mode=guided
- /task:execute impl-1.2 --agent=code-developer --mode=review
---
### 🚀 **Command Overview: `/task:execute`**
- **Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
- **Core Principles**:
- **Task Management**: @~/.claude/workflows/task-management-principles.md
- **File Structure**: @~/.claude/workflows/file-structure-standards.md
- **Session Management**: @~/.claude/workflows/session-management-principles.md
### ⚙️ **Execution Modes**
- **auto (Default)**
- Fully autonomous execution with automatic agent selection.
- Provides progress updates at each checkpoint.
- Automatically completes the task when done.
- **guided**
- Executes step-by-step, requiring user confirmation at each checkpoint.
- Allows for dynamic adjustments and manual review during the process.
- **review**
- Executes under the supervision of a `review-agent`.
- Performs quality checks and provides detailed feedback at each step.
### 🤖 **Agent Selection Logic**
The system determines the appropriate agent for a task using the following logic.
```pseudo
FUNCTION select_agent(task, agent_override):
// A manual override always takes precedence.
// Corresponds to the --agent=<agent-type> flag.
IF agent_override IS NOT NULL:
RETURN agent_override
// If no override, select based on keywords in the task title.
ELSE:
CASE task.title:
WHEN CONTAINS "Build API", "Implement":
RETURN "code-developer"
WHEN CONTAINS "Design schema", "Plan":
RETURN "planning-agent"
WHEN CONTAINS "Write tests":
RETURN "test-agent"
WHEN CONTAINS "Review code":
RETURN "review-agent"
DEFAULT:
RETURN "code-developer" // Default agent
END CASE
END FUNCTION
```
### 🔄 **Core Execution Protocol**
`Pre-Execution` **->** `Execution` **->** `Post-Execution`
### ✅ **Pre-Execution Protocol**
`Validate Task & Dependencies` **->** `Prepare Execution Context` **->** `Coordinate with TodoWrite`
- **Validation**: Checks for the task's JSON file in `.task/` and resolves its dependencies.
- **Context Preparation**: Loads task and workflow context, preparing it for the selected agent.
- **TodoWrite Coordination**: Generates execution Todos and checkpoints, syncing with `TODO_LIST.md`.
### 🏁 **Post-Execution Protocol**
`Update Task Status` **->** `Generate Summary` **->** `Save Artifacts` **->** `Sync All Progress` **->** `Validate File Integrity`
- Updates status in the task's JSON file and `TODO_LIST.md`.
- Creates a summary in `.summaries/`.
- Stores outputs and syncs progress across the entire workflow session.
### 🧠 **Task & Subtask Execution Logic**
This logic defines how single, multiple, or parent tasks are handled.
```pseudo
FUNCTION execute_task_command(task_id, mode, parallel_flag):
// Handle parent tasks by executing their subtasks.
IF is_parent_task(task_id):
subtasks = get_subtasks(task_id)
EXECUTE_SUBTASK_BATCH(subtasks, mode)
// Handle wildcard execution (e.g., IMPL-001.*)
ELSE IF task_id CONTAINS "*":
subtasks = find_matching_tasks(task_id)
IF parallel_flag IS true:
EXECUTE_IN_PARALLEL(subtasks)
ELSE:
FOR each subtask in subtasks:
EXECUTE_SINGLE_TASK(subtask, mode)
// Default case for a single task ID.
ELSE:
EXECUTE_SINGLE_TASK(task_id, mode)
END FUNCTION
```
### 🛡️ **Error Handling & Recovery Logic**
```pseudo
FUNCTION pre_execution_check(task):
// Ensure dependencies are met before starting.
IF task.dependencies ARE NOT MET:
LOG_ERROR("Cannot execute " + task.id)
LOG_INFO("Blocked by: " + unmet_dependencies)
HALT_EXECUTION()
FUNCTION on_execution_failure(checkpoint):
// Provide user with recovery options upon failure.
LOG_WARNING("Execution failed at checkpoint " + checkpoint)
PRESENT_OPTIONS([
"Retry from checkpoint",
"Retry from beginning",
"Switch to guided mode",
"Abort execution"
])
AWAIT user_input
// System performs the selected action.
END FUNCTION
```
### ✨ **Advanced Execution Controls**
- **Dry Run (`--dry-run`)**: Simulates execution, showing the agent, estimated time, and files affected without making changes.
- **Custom Checkpoints (`--checkpoints="..."`)**: Overrides the default checkpoints with a custom, comma-separated list (e.g., `"design,implement,deploy"`).
- **Conditional Execution (`--if="..."`)**: Proceeds with execution only if a specified condition (e.g., `"tests-pass"`) is met.
- **Rollback (`--rollback`)**: Reverts file modifications and restores the previous task state.
### 📄 **Standard Context Structure (JSON)**
This is the standard data structure loaded to provide context for task execution.
```json
{
"task": {
"id": "IMPL-001",
"title": "Build authentication module",
"type": "feature",
"status": "active",
"agent": "code-developer",
"context": {
"inherited_from": "WFS-[topic-slug]",
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"]
}
},
"workflow": {
"session": "WFS-[topic-slug]",
"phase": "IMPLEMENT",
"global_context": ["Security first", "Backward compatible"]
},
"execution": {
"agent": "code-developer",
"mode": "auto",
"checkpoints": ["setup", "implement", "test", "validate"],
"attempts": 1,
"current_attempt": {
"started_at": "2025-09-05T10:35:00Z",
"completed_checkpoints": ["setup"]
}
}
}
```
### 🎯 **Agent-Specific Context**
Different agents receive context tailored to their function:
- **`code-developer`**: Code patterns, dependencies, file scopes.
- **`planning-agent`**: High-level requirements, constraints, success criteria.
- **`test-agent`**: Test requirements, code to be tested, coverage goals.
- **`review-agent`**: Quality standards, style guides, review criteria.
### 🗃️ **File Output & System Integration**
- **Task JSON File (`.task/<task-id>.json`)**: The authoritative source. Updated with status, execution history, and metadata.
- **TODO List (`TODO_LIST.md`)**: The task's checkbox is updated, progress is recalculated, and links to the summary file are added.
- **Session File (`workflow-session.json`)**: Task completion status and overall phase progress are updated.
- **Summary File**: Generated in `.workflow/WFS-[...]/summaries/` upon successful completion.
### 📝 **Summary File Template**
A summary file is generated at `.workflow/WFS-[topic-slug]/.summaries/IMPL-[task-id]-summary.md`.
```markdown
# Task Summary: IMPL-001 Build Authentication Module
## What Was Done
- Created src/auth/login.ts with JWT validation
- Modified src/auth/validate.ts for enhanced security
- Added comprehensive tests in tests/auth.test.ts
## Execution Results
- **Duration**: 23 minutes
- **Agent**: code-developer
- **Tests Passed**: 12/12 (100%)
- **Coverage**: 87%
## Files Modified
- `src/auth/login.ts` (created)
- `src/auth/validate.ts` (modified)
- `tests/auth.test.ts` (created)
## Links
- [🔙 Back to Task List](../TODO_LIST.md#impl-001)
- [📌 Task Details](../.task/impl-001.json)
```

466
.claude/commands/task/replan.md Normal file
View File

@@ -0,0 +1,466 @@
---
name: task-replan
description: Dynamically replan tasks based on changes, blockers, or new requirements
usage: /task:replan [task-id|--all] [--reason=<reason>] [--strategy=<adjust|rebuild>]
argument-hint: [task-id or --all] [optional: reason and strategy]
examples:
- /task:replan IMPL-001 --reason="requirements changed"
- /task:replan --all --reason="new security requirements"
- /task:replan IMPL-003 --strategy=rebuild
---
# Task Replan Command (/task:replan)
## Overview
Dynamically adjusts task planning based on changes, new requirements, blockers, or execution results.
## Core Principles
**System Architecture:** @~/.claude/workflows/unified-workflow-system-principles.md
## Replan Triggers
⚠️ **CRITICAL**: Before replanning, MUST check for existing active session to avoid creating duplicate sessions.
### Session Check Process
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions
2. **Session Validation**: Use existing active session containing the task to be replanned
3. **Context Integration**: Load existing session state and task hierarchy
### Automatic Detection
System detects replanning needs from file monitoring:
- Requirements changed in workflow-session.json
- Dependencies blocked in JSON task hierarchy
- Task failed execution (logged in JSON execution history)
- New issues discovered and associated with tasks
- Scope modified in task context or IMPL_PLAN.md
- File structure complexity changes requiring reorganization
### Manual Triggers
```bash
/task:replan IMPL-001 --reason="API spec updated"
```
## Replan Strategies
### 1. Adjust Strategy (Default)
Minimal changes to existing plan:
```bash
/task:replan IMPL-001 --strategy=adjust
Adjustments for IMPL-001:
- Updated requirements
- Modified subtask IMPL-001.2
- Added validation step
- Kept 80% of original plan
```
### 2. Rebuild Strategy
Complete replanning from scratch:
```bash
/task:replan IMPL-001 --strategy=rebuild
Rebuilding IMPL-001:
- Analyzing new requirements
- Generating new breakdown
- Reassigning agents
- New execution plan created
```
## Usage Scenarios
### Scenario 1: Requirements Change
```bash
/task:replan IMPL-001 --reason="Added OAuth2 requirement"
Analyzing impact...
Current plan:
- IMPL-001.1: Basic login ✅ Complete
- IMPL-001.2: Session management (in progress)
- IMPL-001.3: Tests
Recommended changes:
+ Add IMPL-001.4: OAuth2 integration
~ Modify IMPL-001.2: Include OAuth session
~ Update IMPL-001.3: Add OAuth tests
Apply changes? (y/n): y
✅ Task replanned successfully
```
### Scenario 2: Blocked Task
```bash
/task:replan IMPL-003 --reason="API not ready"
Task blocked analysis:
- IMPL-003 depends on external API
- API delayed by 2 days
- 3 tasks depend on IMPL-003
Replan options:
1. Defer IMPL-003 and dependents
2. Create mock API for development
3. Reorder to work on independent tasks
Select option: 2
Creating new plan:
+ IMPL-003.0: Create API mock
~ IMPL-003.1: Use mock for development
~ Add note: Replace mock when API ready
```
### Scenario 3: Failed Execution
```bash
/task:replan IMPL-002 --reason="execution failed"
Failure analysis:
- Failed at: Testing phase
- Reason: Performance issues
- Impact: Blocks 2 downstream tasks
Replan approach:
1. Break down into smaller tasks
2. Add performance optimization task
3. Adjust testing approach
New structure:
IMPL-002 (failed) →
├── IMPL-002.1: Core functionality (smaller scope)
├── IMPL-002.2: Performance optimization
├── IMPL-002.3: Load testing
└── IMPL-002.4: Integration
✅ Replanned with focus on incremental delivery
```
## Global Replanning
### Replan All Tasks
```bash
/task:replan --all --reason="Architecture change"
Global replan analysis:
- Total tasks: 8
- Completed: 3 (keep as-is)
- In progress: 2 (need adjustment)
- Pending: 3 (full replan)
Changes summary:
- 2 tasks modified
- 1 task removed (no longer needed)
- 2 new tasks added
- Dependencies reordered
Preview changes? (y/n): y
[Detailed change list]
Apply all changes? (y/n): y
✅ All tasks replanned
```
## Impact Analysis
### Before Replanning
```bash
/task:replan IMPL-001 --preview
Impact Preview:
If IMPL-001 is replanned:
- Affected tasks: 4
- Timeline impact: +1 day
- Resource changes: Need planning-agent
- Risk level: Medium
Dependencies affected:
- IMPL-003: Will need adjustment
- IMPL-004: Delay expected
- IMPL-005: No impact
Continue? (y/n):
```
## Replan Operations
### Add Subtasks
```bash
/task:replan IMPL-001 --add-subtask
Current subtasks:
1. IMPL-001.1: Design
2. IMPL-001.2: Implement
Add new subtask:
Title: Add security layer
Position: After IMPL-001.2
Agent: code-developer
✅ Added IMPL-001.3: Add security layer
```
### Remove Subtasks
```bash
/task:replan IMPL-001 --remove-subtask=IMPL-001.3
⚠️ Remove IMPL-001.3?
This will:
- Delete subtask and its context
- Update parent progress
- Adjust dependencies
Confirm? (y/n): y
✅ Subtask removed
```
### Reorder Tasks
```bash
/task:replan --reorder
Current order:
1. IMPL-001: Auth
2. IMPL-002: Database
3. IMPL-003: API
Suggested reorder (based on dependencies):
1. IMPL-002: Database
2. IMPL-001: Auth
3. IMPL-003: API
Apply reorder? (y/n): y
✅ Tasks reordered
```
## Smart Recommendations
### AI-Powered Suggestions
```bash
/task:replan IMPL-001 --suggest
Analysis complete. Suggestions:
1. 🔄 Split IMPL-001.2 (too complex)
2. ⏱️ Reduce scope to meet deadline
3. 🤝 Parallelize IMPL-001.1 and IMPL-001.3
4. 📝 Add documentation task
5. 🧪 Increase test coverage requirement
Apply suggestion: 1
Splitting IMPL-001.2:
→ IMPL-001.2.1: Core implementation
→ IMPL-001.2.2: Error handling
→ IMPL-001.2.3: Optimization
✅ Applied successfully
```
## Version Control & File Management
### JSON Task Version History
**File-Based Versioning**: Each replan creates version history in JSON metadata
```bash
/task:replan impl-001 --history
Plan versions for impl-001 (from JSON file):
v3 (current): 4 subtasks, 2 complete - JSON files: impl-001.1.json to impl-001.4.json
v2: 3 subtasks (archived) - Backup: .task/archive/impl-001-v2-backup.json
v1: 2 subtasks (initial) - Backup: .task/archive/impl-001-v1-backup.json
Version files available:
- Current: .task/impl-001.json
- Backups: .task/archive/impl-001-v[N]-backup.json
- Change log: .summaries/replan-history-impl-001.md
Rollback to version: 2
⚠️ This will:
- Restore JSON files from backup
- Regenerate TODO_LIST.md structure
- Update workflow-session.json
- Archive current version
Continue? (y/n):
```
### Replan Documentation Generation
**Change Tracking Files**: Auto-generated documentation of all changes
```bash
# Generates: .summaries/replan-[task-id]-[timestamp].md
/task:replan impl-001 --reason="API changes" --document
Creating replan documentation...
📝 Replan Report: impl-001
Generated: 2025-09-07 16:00:00
Reason: API changes
Version: v2 → v3
## Changes Made
- Added subtask impl-001.4: Handle new API endpoints
- Modified impl-001.2: Updated authentication flow
- Removed impl-001.3: No longer needed due to API changes
## File Changes
- Created: .task/impl-001.4.json
- Modified: .task/impl-001.2.json
- Archived: .task/impl-001.3.json → .task/archive/
- Updated: TODO_LIST.md hierarchy
- Updated: workflow-session.json task count
## Impact Analysis
- Timeline: +2 days (new subtask)
- Dependencies: impl-002 now depends on impl-001.4
- Resources: Need API specialist for impl-001.4
Report saved: .summaries/replan-impl-001-20250907-160000.md
```
### Enhanced JSON Change Tracking
**Complete Replan History**: All changes documented in JSON files and reports
```json
{
"task_id": "impl-001",
"title": "Build authentication module",
"status": "active",
"version": "1.2",
"replan_history": [
{
"version": "1.2",
"timestamp": "2025-09-07T16:00:00Z",
"reason": "API changes",
"changes_summary": "Added API endpoint handling, removed deprecated auth flow",
"backup_location": ".task/archive/impl-001-v1.1-backup.json",
"documentation": ".summaries/replan-impl-001-20250907-160000.md",
"files_affected": [
{
"action": "created",
"file": ".task/impl-001.4.json",
"description": "New API endpoint handling subtask"
},
{
"action": "modified",
"file": ".task/impl-001.2.json",
"description": "Updated authentication flow"
},
{
"action": "archived",
"file": ".task/impl-001.3.json",
"location": ".task/archive/impl-001.3-deprecated.json"
}
],
"todo_list_regenerated": true,
"session_updated": true
}
],
"subtasks": ["impl-001.1", "impl-001.2", "impl-001.4"],
"metadata": {
"version": "1.2",
"last_updated": "2025-09-07T16:00:00Z",
"last_replan": "2025-09-07T16:00:00Z",
"replan_count": 2
}
}
```
## File System Integration
### Comprehensive File Updates
**Multi-File Synchronization**: Ensures consistency across all workflow files
#### JSON Task File Management
- **Version Backups**: Automatic backup before major changes
- **Hierarchical Updates**: Cascading changes through parent-child relationships
- **Archive Management**: Deprecated task files moved to `.task/archive/`
- **Metadata Tracking**: Complete change history in JSON metadata
#### TODO_LIST.md Regeneration
**Smart Regeneration**: Updates based on structural changes
```bash
/task:replan impl-001 --regenerate-todo
Analyzing structural changes from replan...
Current TODO_LIST.md: 8 tasks displayed
New task structure: 9 tasks (1 added, 1 removed, 2 modified)
Regenerating TODO_LIST.md...
✅ Updated task hierarchy display
✅ Recalculated progress percentages
✅ Updated cross-references to JSON files
✅ Added links to new summary files
TODO_LIST.md updated with new structure
```
#### Workflow Session Updates
- **Task Count Updates**: Reflect additions/removals in session
- **Progress Recalculation**: Update completion percentages
- **Complexity Assessment**: Re-evaluate structure level if needed
- **Dependency Validation**: Check all task dependencies remain valid
### Documentation Generation
**Automatic Report Creation**: Every replan generates documentation
- **Replan Report**: `.summaries/replan-[task-id]-[timestamp].md`
- **Change Summary**: Detailed before/after comparison
- **Impact Analysis**: Effects on timeline, dependencies, resources
- **File Change Log**: Complete list of affected files
- **Rollback Instructions**: How to revert changes if needed
### Issue Integration
```bash
/task:replan IMPL-001 --from-issue=ISS-001
Loading issue ISS-001...
Issue: "Login timeout too short"
Type: Bug
Priority: High
Suggested replan:
+ Add IMPL-001.4: Fix login timeout
~ Adjust IMPL-001.3: Include timeout tests
Apply? (y/n): y
```
## Error Handling
```bash
# Cannot replan completed task
❌ Task IMPL-001 is completed
→ Create new task instead
# No reason provided
⚠️ Please provide reason for replanning
→ Use --reason="explanation"
# Conflicts detected
⚠️ Replan conflicts with IMPL-002
→ Resolve with --force or adjust plan
```
## File Output Summary
### Generated Files
- **Backup Files**: `.task/archive/[task-id]-v[N]-backup.json`
- **Replan Reports**: `.summaries/replan-[task-id]-[timestamp].md`
- **Change Logs**: Embedded in JSON task file metadata
- **Updated TODO_LIST.md**: Reflects new task structure
- **Archive Directory**: `.task/archive/` for deprecated files
### File System Maintenance
- **Automatic Cleanup**: Archive old versions after 30 days
- **Integrity Validation**: Ensure all references remain valid after changes
- **Rollback Support**: Complete restoration capability from backups
- **Cross-Reference Updates**: Maintain links between all workflow files
## Related Commands
- `/task:breakdown` - Initial task breakdown with JSON file creation
- `/task:context` - Analyze current state from file system
- `/task:execute` - Execute replanned tasks with new structure
- `/task:sync` - Validate file consistency after replanning
- `/workflow:replan` - Replan entire workflow with session updates

280
.claude/commands/task/sync.md Normal file
View File

@@ -0,0 +1,280 @@
---
name: task-sync
description: Synchronize task data with workflow session
usage: /task:sync [--force] [--dry-run]
argument-hint: [optional: force sync or dry run]
examples:
- /task:sync
- /task:sync --force
- /task:sync --dry-run
---
# Task Sync Command (/task:sync)
## Overview
Ensures bidirectional synchronization between hierarchical JSON tasks, TODO_LIST.md, and workflow-session.json.
## Core Principles
**System Architecture:** @~/.claude/workflows/unified-workflow-system-principles.md
## Bidirectional Sync Operations
### 1. JSON Task Files → TODO_LIST.md Sync
**Authoritative Source**: JSON task files in `.task/` directory
- **Status Updates**: pending → active → completed reflected in checkboxes
- **Hierarchical Progress**: Parent progress = average of children (up to 3 levels)
- **Structure Sync**: TODO_LIST.md hierarchy matches JSON parent_id relationships
- **Cross-References**: Links to JSON files and summary files validated
- **Progress Rollup**: Automatic calculation from leaf tasks to root
### 2. JSON Task Files → Workflow Session Sync
**Session State Updates**: workflow-session.json reflects current task state
- **Task Lists**: Main task IDs updated per phase
- **Progress Metrics**: Overall and phase-specific completion percentages
- **Complexity Assessment**: Structure level based on current task count
- **Blocked Task Detection**: Dependency analysis across entire hierarchy
- **Session Metadata**: Last sync timestamps and validation status
### 3. Workflow Session → JSON Task Sync
**Context Propagation**: Session context distributed to individual tasks
- **Global Context**: Workflow requirements inherited by all tasks
- **Requirement Updates**: Changes in session context propagated
- **Issue Associations**: Workflow-level issues linked to relevant tasks
- **Phase Transitions**: Task context updated when phases change
### 4. TodoWrite Tool → File System Sync
**Real-time Coordination**: TodoWrite tool state synced with persistent files
- **Active Task Sync**: TodoWrite status reflected in JSON files
- **Completion Triggers**: TodoWrite completion updates JSON and TODO_LIST.md
- **Progress Coordination**: TodoWrite progress synced with file-based tracking
- **Session Continuity**: TodoWrite state preserved in TODO_LIST.md
## Sync Rules
### Automatic Sync Points
- After `/task:create` - Add to workflow
- After `/task:execute` - Update progress
- After `/task:replan` - Sync changes
- After `/workflow:*` commands - Propagate context
### Conflict Resolution
Priority order:
1. Recently modified (timestamp)
2. More complete data
3. User confirmation (if needed)
## Usage Examples
### Standard Sync with Report Generation
```bash
/task:sync
🔄 Comprehensive Task Synchronization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Analyzing file system state...
- JSON task files: 8 tasks across 3 levels in .task/
- TODO_LIST.md: Present, 8 displayed tasks, last modified 2h ago
- workflow-session.json: 3 main tasks tracked, Level 1 structure
- Summary files: 3 completed task summaries in .summaries/
Validating cross-references...
✅ Parent-child relationships: All valid
✅ Hierarchy depth: Within limits (max 3 levels)
✅ File naming: Follows impl-N.M.P format
Found synchronization differences:
- Task impl-1.2: completed in JSON, pending in TODO_LIST.md checkbox
- Progress: impl-1 shows 75% (from subtasks) vs 45% in session
- Hierarchy: impl-2.3.1 exists in JSON but missing from TODO_LIST.md
- Cross-refs: Summary link for impl-1.2 missing in TODO_LIST.md
Synchronizing files...
✅ Updated impl-1.2 checkbox: [ ] → [x] in TODO_LIST.md
✅ Recalculated hierarchical progress: impl-1 = 75%
✅ Added impl-2.3.1 to TODO_LIST.md hierarchy display
✅ Updated summary link: impl-1.2 → .summaries/IMPL-1.2-summary.md
✅ Propagated context updates to 3 task files
✅ Updated workflow-session.json progress metrics
Generating sync report...
✅ Sync report saved: .summaries/sync-report-20250907-160000.md
Sync complete: 6 updates applied, 0 conflicts resolved
Next sync recommended: In 1 hour or after next task operation
```
### Dry Run with Detailed Analysis
```bash
/task:sync --dry-run
🔍 Sync Analysis (Dry Run Mode)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scanning .task/ directory: 8 JSON files found
Analyzing TODO_LIST.md: Last modified 2h ago
Checking workflow-session.json: In sync
Validating .summaries/: 3 summary files present
Potential changes identified:
ℹ️ Update 2 task statuses: impl-1.2, impl-1.3
ℹ️ Recalculate progress for parent: impl-1 (67% → 75%)
ℹ️ Add 1 missing cross-reference in TODO_LIST.md
ℹ️ Update workflow session progress: 45% → 62%
ℹ️ Generate missing summary link for impl-1.2
File changes would be made to:
- TODO_LIST.md (3 line changes)
- workflow-session.json (progress update)
- No JSON task files need changes (already authoritative)
Conflicts detected: None
Risk level: Low
Estimated sync time: <5 seconds
(No actual changes made - run without --dry-run to apply)
```
### Force Sync with Backup
```bash
/task:sync --force
⚠️ Force Sync Mode - Creating Backups
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Backing up current state...
✅ TODO_LIST.md → .summaries/backup-TODO_LIST-20250907-160000.md
✅ workflow-session.json → .summaries/backup-session-20250907-160000.json
Force sync operations:
❗ Using JSON task files as authoritative source
❗ Overwriting TODO_LIST.md without conflict resolution
❗ Rebuilding workflow-session.json task data
❗ Regenerating all cross-references
❗ Recalculating all progress from scratch
Sync completed with authority conflicts resolved:
✅ 3 conflicts overwritten in favor of JSON files
✅ TODO_LIST.md completely regenerated
✅ workflow-session.json task list rebuilt
✅ All cross-references validated and updated
Backup files available for rollback if needed:
- .summaries/backup-TODO_LIST-20250907-160000.md
- .summaries/backup-session-20250907-160000.json
Force sync report: .summaries/force-sync-20250907-160000.md
```
## Data Integrity Checks
### Validation Steps
1. **File Existence**: Both JSON files exist
2. **Session Match**: Same session_id
3. **ID Consistency**: All task IDs valid
4. **Status Logic**: No impossible states
5. **Progress Math**: Calculation accurate
### Error Recovery
```bash
❌ Sync failed: tasks.json corrupted
→ Attempting recovery from backup...
✅ Restored from backup
→ Retry sync? (y/n)
```
## Progress Calculation
```javascript
progress = (completed_tasks / total_tasks) * 100
// With subtasks
weighted_progress = sum(task.weight * task.progress) / total_weight
```
## JSON Updates
### workflow-session.json
```json
{
"phases": {
"IMPLEMENT": {
"tasks": ["IMPL-001", "IMPL-002", "IMPL-003"],
"completed_tasks": ["IMPL-001", "IMPL-002"],
"progress": 67,
"last_sync": "2025-01-16T14:00:00Z"
}
}
}
```
### Individual Task Files
Each task file maintains sync metadata:
```json
{
"id": "IMPL-001",
"title": "Build authentication module",
"status": "completed",
"type": "feature",
"agent": "code-developer",
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"started_at": "2025-09-05T10:35:00Z",
"completed_at": "2025-09-05T13:15:00Z",
"last_updated": "2025-09-05T13:15:00Z",
"last_sync": "2025-09-05T13:15:00Z",
"version": "1.0"
}
}
```
## Performance & File Management
### Sync Performance
- **Incremental Analysis**: Only processes changed files since last sync
- **Cached Validation**: Reuses validation results for unchanged files
- **Batch File Updates**: Groups related changes for efficiency
- **Typical Sync Time**: <100ms for standard workflows, <500ms for complex
### Generated Reports
**Automatic Documentation**: Every sync creates audit trail
- **Standard Sync Report**: `.summaries/sync-report-[timestamp].md`
- **Dry Run Analysis**: `.summaries/sync-analysis-[timestamp].md`
- **Force Sync Report**: `.summaries/force-sync-[timestamp].md`
- **Conflict Resolution Log**: Embedded in sync reports
- **Backup Files**: Created during force operations
### File System Maintenance
- **Cleanup Policy**: Keep last 10 sync reports, archive older ones
- **Backup Management**: Automatic cleanup of force sync backups after 7 days
- **Error Recovery**: Complete rollback capability from backup files
- **Integrity Monitoring**: Continuous validation of file system consistency
## File System Integration
### Integration Points
- **JSON Task Files**: Authoritative source for all task data
- **TODO_LIST.md**: Display layer synchronized from JSON files
- **workflow-session.json**: High-level session state and progress
- **Summary Files**: Completion documentation linked from TODO_LIST.md
- **TodoWrite Tool**: Real-time task management interface
### File Output Summary
**Generated Files**:
- **Sync Reports**: `.summaries/sync-report-[timestamp].md`
- **Backup Files**: `.summaries/backup-[file]-[timestamp].[ext]`
- **Analysis Reports**: `.summaries/sync-analysis-[timestamp].md`
- **Updated TODO_LIST.md**: Refreshed with current task state
- **Updated workflow-session.json**: Current progress and task references
### Quality Assurance
- **Pre-sync Validation**: File existence and format checks
- **Post-sync Verification**: Cross-reference validation
- **Rollback Testing**: Backup restoration validation
- **Performance Monitoring**: Sync time and efficiency tracking
## Related Commands
- `/task:context --sync-check` - Validate current sync status
- `/task:create` - Creates tasks requiring sync
- `/task:execute` - Generates summaries requiring sync
- `/task:replan` - Structural changes requiring sync
- `/workflow:sync` - Full workflow document synchronization

266
.claude/commands/update_dms.md Normal file
View File

@@ -0,0 +1,266 @@
---
name: update_dms
description: Distributed Memory System management with intelligent classification
usage: /update_dms [mode] [target]
argument-hint: [full|fast|deep] [path or scope]
examples:
- /update_dms # Fast mode on current directory
- /update_dms full # Complete initialization
- /update_dms fast src/api/ # Quick update on specific path
- /update_dms deep auth-system # Deep analysis on scope
---
### 🚀 **Command Overview: `/update_dms`**
- **Type**: Distributed Memory System (DMS) Management.
- **Purpose**: Manages a hierarchical `CLAUDE.md` documentation system using intelligent project classification and agent-based task integration.
- **Features**: Supports multiple operation modes, automatic complexity detection, and parallel execution for high performance.
### ⚙️ **Processing Modes**
- **`fast` (Default)**
- **Purpose**: Targeted content updates based on current context or a specific path.
- **Scope**: Single module or file, no cross-module analysis.
- **`deep`**
- **Purpose**: Analyze relational impacts and update all associated files across modules.
- **Scope**: A specific feature or scope that touches multiple modules (e.g., `auth-system`).
- **`full`**
- **Purpose**: Complete, project-wide documentation reconstruction and overhaul.
- **Scope**: The entire project, executed via modular, bottom-up task orchestration.
### 🤔 **When to Use Each Mode**
- **⚡ Fast Mode**: Use for daily development, quick updates, and single-module changes or bug fixes.
- **🔬 Deep Mode**: Use for multi-module features, integration work, or complex refactoring with cross-module impacts.
- **🚀 Full Mode**: Use for new project setup, major architectural changes, or a comprehensive documentation overhaul.
### 🔄 **Mode-Specific Workflows**
- **⚡ Fast Mode Flow**
`Execute 3-step scan` -> `Identify target scope` -> `Invoke single agent` -> `Update specific CLAUDE.md` -> `Validate & cleanup`
- **🔬 Deep Mode Flow**
`Project structure scan` -> `Impact analysis` -> `Multi-module detection` -> `Decide on parallel execution` -> `Orchestrate agent(s)` -> `Synchronize updates` -> `Cross-module validation`
- **🚀 Full Mode Flow**
`Project analysis` -> `Module discovery` -> `Task decomposition & dependency sorting` -> `Create parallel batches` -> `Execute Batch 1 (Base modules)` -> `...` -> `Execute Batch N (Top-level)` -> `Invoke global summary agent` -> `Generate root CLAUDE.md`
### 🧠 **Parallel Execution Logic**
This describes the command's internal logic for selecting an execution strategy. It is handled automatically by `/update_dms`.
```pseudo
FUNCTION select_execution_strategy(project_structure):
file_count = analyze_file_count(project_structure)
module_count = analyze_module_count(project_structure)
// Based on the 'Parallel Execution Decision Matrix'
IF file_count < 20:
RETURN "single_agent_fast_mode"
ELSE IF file_count >= 20 AND file_count <= 100:
RETURN "directory_based_parallel" // Use 2-3 agents
ELSE IF file_count > 100 AND file_count <= 500:
RETURN "hybrid_parallel" // Use 3-5 agents
ELSE IF file_count > 500:
RETURN "dependency_aware_batching" // Use 5+ agents
END IF
END FUNCTION
FUNCTION orchestrate_full_mode(project_structure):
// 1. Decompose project into modules and dependencies
tasks = create_task_list(project_structure) // Corresponds to JSON Task Instructions
// 2. Group tasks into batches for parallel execution
batches = create_dependency_batches(tasks)
// 3. Execute batches sequentially, with parallel agents within each batch
FOR each batch in batches:
// This action corresponds to the orchestration script example.
// e.g., Task(memory-gemini-bridge, "task for module A") &
execute_batch_in_parallel(batch)
wait_for_batch_completion() // Barrier synchronization
// 4. Final summary step
// e.g., Task(memory-gemini-bridge, "global_summary task")
execute_global_summary_task()
END FUNCTION
```
### 📂 **Distributed Memory System (DMS) Structure**
The command assumes and manages a hierarchical `CLAUDE.md` file structure.
```
project/
├── CLAUDE.md # Project overview and architecture
├── src/
│ ├── CLAUDE.md # Core implementation guidelines
│ ├── components/
│ │ └── CLAUDE.md # Component-specific patterns
│ └── api/
│ └── CLAUDE.md # API implementation details
├── tests/
│ └── CLAUDE.md # Testing guidelines (if needed)
└── docs/
└── CLAUDE.md # Documentation standards (if needed)
```
### 📜 **Documentation Hierarchy Rules**
- **Root Level (`./CLAUDE.md`):** Focus on project architecture, technology stack, and global standards.
- **Module Level (`./src/CLAUDE.md`):** Focus on core implementation guidelines, module responsibilities, and patterns.
- **Sub-Module Level (`./src/api/CLAUDE.md`):** Focus on detailed technical specifications and component-specific patterns.
### 🛠️ **Pre-defined Analysis Commands**
This 3-step script is used for initial project structure analysis.
```bash
# Step 1: Get project directory structure
tree -L 3 -d 2>/dev/null || find . -type d -maxdepth 3
# Step 2: Find existing CLAUDE.md files
find . -name "CLAUDE.md" -o -name "*CLAUDE.md" | sort
# Step 3: Generate context-aware file list (adapts to target scope)
# If target specified: focus on target-related files
# If no target: analyze current context and recent changes
find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.md" \) | head -50
```
### 📝 **Task Instructions Format (Full Mode)**
In `full` mode, the orchestrator generates tasks for agents in this JSON format.
```json
{
"task_type": "module_update" | "global_summary",
"target_module": "src/api" | "tests" | "root",
"analysis_commands": [
"find ./src/api -type f \\( -name '*.js' -o -name '*.ts' \\) | head -30",
"find ./src/api -name 'CLAUDE.md'"
],
"dependencies": ["src/utils", "src/core"],
"priority": 1,
"context": {
"module_purpose": "API endpoint implementations",
"existing_files": ["./src/api/CLAUDE.md"],
"focus_areas": ["implementation patterns", "error handling", "integration points"]
}
}
```
### 🤖 **Agent Integration Examples**
The `/update_dms` command orchestrates `memory-gemini-bridge` agents using tasks formatted like this.
#### **Single Agent (Fast/Deep Mode)**
```yaml
Task:
description: "Module analysis with Gemini CLI"
subagent_type: "memory-gemini-bridge"
prompt: |
Task Type: module_update
Target Module: src/api/auth
Analysis Commands:
1. find ./src/api/auth -type f \( -name "*.js" -o -name "*.ts" \) | head -30
2. cd src/api/auth && gemini --all-files -p "analyze authentication patterns"
3. Generate module-level CLAUDE.md for auth subsystem
Context:
- Module Purpose: Authentication service implementation
- Focus Areas: ["security patterns", "JWT handling", "middleware integration"]
- Dependencies: ["src/utils", "src/core"]
Success Criteria: Generate complete module CLAUDE.md with security patterns
```
#### **Multiple Parallel Agents (Full Mode)**
```yaml
# Agent 1: API Module
Task:
description: "API Module Analysis"
subagent_type: "memory-gemini-bridge"
prompt: |
Task Type: module_update
Target Module: src/api
Parallel Config: { batch_id: 1, partition_id: 1, max_concurrent: 3 }
Generate: ./src/api/CLAUDE.md
Sync Point: batch_complete
# Agent 2: Components Module (Parallel)
Task:
description: "Components Module Analysis"
subagent_type: "memory-gemini-bridge"
prompt: |
Task Type: module_update
Target Module: src/components
Parallel Config: { batch_id: 1, partition_id: 2, max_concurrent: 3 }
Generate: ./src/components/CLAUDE.md
Sync Point: batch_complete
```
#### **Global Summary Agent (Full Mode - Final Step)**
```yaml
Task:
description: "Project Global Summary"
subagent_type: "memory-gemini-bridge"
prompt: |
Task Type: global_summary
Wait For: All module updates complete (batch_complete barrier)
Analysis Commands:
1. find . -name "CLAUDE.md" | grep -E "(src|lib)/" | sort
2. Read all module CLAUDE.md files
3. gemini -p "@./src/*/CLAUDE.md synthesize project architecture"
Generate: Root ./CLAUDE.md
```
### 🌐 **Advanced Parallel Execution Strategies**
The command auto-selects the optimal strategy. Below are the patterns it uses.
#### **Strategy 1: Directory-Based Partitioning**
- **Best For**: Well-organized projects with clear module boundaries.
- **Example Command**: `Agent-1: cd src/components && gemini --all-files -p "analyze React components"`
#### **Strategy 2: File Reference Partitioning**
- **Best For**: Feature-based or cross-cutting concerns (e.g., authentication).
- **Example Command**: `Agent-1: gemini -p "@src/**/*auth* analyze authentication patterns"`
#### **Strategy 3: Hybrid Approach**
- **Best For**: Complex projects with mixed organization patterns.
- **Example Command**: Mixes directory-based (`cd src/components`) and pattern-based (`@src/**/*{auth,security}*`) analysis.
#### **Strategy 4: Dependency-Aware Batching**
- **Best For**: Large enterprise projects with complex interdependencies.
- **Example Flow**:
1. **Batch 1**: Analyze foundation modules (e.g., `types`, `utils`). `wait`
2. **Batch 2**: Analyze service modules that depend on Batch 1 (e.g., `api`, `database`). `wait`
3. **Batch 3**: Analyze application modules that depend on Batch 2 (e.g., `components`).
| Strategy | Best For | Scaling | Complexity | Performance |
|---|---|---|---|---|
| Directory-Based | Modular projects | Excellent | Low | High |
| File Pattern | Feature-focused | Good | Medium | Medium |
| Hybrid | Mixed structures | Very Good | High | High |
| Dependency-Aware | Large enterprise | Excellent | Very High | Maximum |
### 🧹 **Automatic Content Management**
- **Cleanup**: Removes duplicate content, outdated references, and deprecated patterns across the hierarchy.
- **Validation**: Ensures content is relevant to the current state of the project.
- **Focus**:
- **Fast Mode**: Quick relevance validation and dead reference removal.
- **Deep Mode**: Comprehensive redundancy elimination across affected modules.
- **Full Mode**: Complete project-wide cleanup and hierarchy optimization.
### ⏱️ **Performance & Time Investment**
- **⚡ Fast Mode**: Minutes (Ideal for daily use).
- **🔬 Deep Mode**: ~10-30 minutes with parallel execution.
- **🚀 Full Mode**: ~30-45 minutes with parallel execution.
- **Benefit**: Parallel execution provides a massive speedup, offsetting a small coordination overhead.

428
.claude/commands/workflow/action-plan.md Normal file
View File

@@ -0,0 +1,428 @@
---
name: workflow-action-plan
description: Action planning phase that integrates brainstorming insights or user input to create executable implementation plans
usage: /workflow:action-plan [--from-brainstorming] [--skip-brainstorming] [--replan] [--trigger=<reason>]
argument-hint: [optional: from brainstorming, skip brainstorming, replan mode, or replan trigger]
examples:
- /workflow:action-plan --from-brainstorming
- /workflow:action-plan --skip-brainstorming "implement OAuth authentication"
- /workflow:action-plan --replan --trigger=requirement-change
- /workflow:action-plan --from-brainstorming --scope=all --strategy=minimal-disruption
---
# Workflow Action Plan Command (/workflow:action-plan)
## Overview
Creates actionable implementation plans based on brainstorming insights or direct user input. Establishes project structure, understands existing workflow context, and generates executable plans with proper task decomposition and resource allocation.
## Core Principles
**System:** @~/.claude/workflows/unified-workflow-system-principles.md
## Input Sources & Planning Approaches
### Brainstorming-Based Planning (--from-brainstorming)
**Prerequisites**: Completed brainstorming session with multi-agent analysis
**Input Sources**:
- `.workflow/WFS-[topic-slug]/.brainstorming/[agent]/analysis.md` files
- `.workflow/WFS-[topic-slug]/.brainstorming/synthesis-analysis.md`
- `.workflow/WFS-[topic-slug]/.brainstorming/recommendations.md`
- `workflow-session.json` brainstorming phase results
### Direct User Input Planning (--skip-brainstorming)
**Prerequisites**: User provides task description and requirements
**Input Sources**:
- User task description and requirements
- Existing project structure analysis
- Session context from workflow-session.json (if exists)
### Session Context Detection
⚠️ **CRITICAL**: Before planning, MUST check for existing active session to avoid creating duplicate sessions.
**Session Check Process:**
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions
2. **Session Selection**: Use existing active session or create new one only if none exists
3. **Context Integration**: Load existing session state and brainstorming outputs
```json
{
"session_id": "WFS-[topic-slug]",
"type": "simple|medium|complex",
"current_phase": "PLAN",
"session_source": "existing_active|new_creation",
"brainstorming": {
"status": "completed|skipped",
"output_directory": ".workflow/WFS-[topic-slug]/.brainstorming/",
"insights_available": true|false
}
}
```
### Planning Depth & Document Generation
- **Simple**: Skip detailed planning, generate minimal IMPL_PLAN.md or go direct to IMPLEMENT
- **Medium**: Standard planning with IMPL_PLAN.md generation (1-2 agents)
- **Complex**: Full planning with comprehensive IMPL_PLAN.md (enhanced structure)
## Execution Flow
### Phase 1: Context Understanding & Structure Establishment
1. **Session Detection & Selection**:
- **Check Active Sessions**: Query `.workflow/session_status.jsonl` for existing active sessions
- **Session Priority**: Use existing active session if available, otherwise create new session
- **Session Analysis**: Read and understand workflow-session.json from selected session
- Detect existing brainstorming outputs
- Identify current phase and progress
- Understand project context and requirements
2. **File Structure Assessment**:
- **If brainstorming exists**: Verify `.workflow/WFS-[topic-slug]/.brainstorming/` structure
- **If no structure exists**: Create complete workflow directory structure
- **Document Discovery**: Identify all existing planning documents
3. **Input Source Determination**:
- **From Brainstorming**: Read all agent analyses and synthesis documents
- **Skip Brainstorming**: Collect user requirements and context directly
- **Hybrid**: Combine existing insights with new user input
### Phase 2: Context Integration & Requirements Analysis
4. **Requirements Synthesis**:
- **From Brainstorming**: Integrate multi-agent perspectives and recommendations
- **From User Input**: Analyze and structure user-provided requirements
- **Gap Analysis**: Identify missing information and clarify with user
5. **Complexity Assessment**: Determine planning depth needed based on:
- Scope of requirements (brainstorming insights or user input)
- Technical complexity indicators
- Resource and timeline constraints
- Risk assessment from available information
### Phase 3: Document Generation & Planning
6. **Create Document Directory**: Setup `.workflow/WFS-[topic-slug]/` structure (if needed)
7. **Execute Planning**:
- **Simple**: Minimal documentation, direct to IMPLEMENT
- **Medium**: Generate IMPL_PLAN.md with task breakdown
- **Complex**: Generate comprehensive IMPL_PLAN.md with staged approach and risk assessment
8. **Update Session**: Mark PLAN phase complete with document references
9. **Link Documents**: Update JSON state with generated document paths
## Session State Analysis & Document Understanding
### Workflow Session Discovery
**Command**: `workflow:action-plan` automatically detects and analyzes:
**Session Detection Process**:
1. **Find Active Sessions**: Locate `.workflow/WFS-*/workflow-session.json` files
2. **Session Validation**: Verify session completeness and current phase
3. **Context Extraction**: Read session metadata, progress, and phase outputs
**Session State Analysis**:
```json
{
"session_id": "WFS-user-auth-system",
"current_phase": "PLAN",
"brainstorming": {
"status": "completed",
"agents_completed": ["system-architect", "ui-designer", "security-expert"],
"synthesis_available": true,
"recommendations_count": 12
},
"documents": {
"brainstorming": {
"system-architect/analysis.md": {"status": "available", "insights": ["scalability", "microservices"]},
"synthesis-analysis.md": {"status": "available", "key_themes": ["security-first", "user-experience"]}
}
}
}
```
### Document Intelligence & Content Understanding
**Process**: Action planning reads and interprets existing workflow documents
**Brainstorming Document Analysis**:
- **Agent Analyses**: Extract key insights, recommendations, and constraints from each agent
- **Synthesis Reports**: Understand cross-perspective themes and convergent solutions
- **Recommendation Prioritization**: Identify high-impact, actionable items
- **Context Preservation**: Maintain user requirements and constraints from discussions
**Content Integration Strategy**:
- **Technical Requirements**: From system-architect, data-architect, security-expert analyses
- **User Experience**: From ui-designer, user-researcher perspectives
- **Business Context**: From product-manager, business-analyst insights
- **Implementation Constraints**: From all agent recommendations and user discussions
**Gap Detection**:
- Identify missing technical specifications
- Detect undefined user requirements
- Find unresolved architectural decisions
- Highlight conflicting recommendations requiring resolution
## Output Format
### IMPL_PLAN.md Structure (Enhanced for Action Planning)
```markdown
# Action Implementation Plan
## Context & Requirements
### From Brainstorming Analysis (if --from-brainstorming)
- **Key Insights**: Synthesized from multi-agent perspectives
- **Technical Requirements**: Architecture, security, data considerations
- **User Experience Requirements**: UI/UX design and usability needs
- **Business Requirements**: Product goals, stakeholder priorities, constraints
- **User Discussion Context**: Captured requirements from user interactions
### From User Input (if --skip-brainstorming)
- **User Provided Requirements**: Direct input and specifications
- **Context Analysis**: Interpreted requirements and technical implications
- **Gap Identification**: Areas needing clarification or additional information
## Strategic Approach
- **Implementation Philosophy**: Core principles guiding development
- **Success Metrics**: How progress and completion will be measured
- **Risk Mitigation**: Key risks identified and mitigation strategies
## Task Breakdown
- **IMPL-001**: Foundation/Infrastructure setup
- **IMPL-002**: Core functionality implementation
- **IMPL-003**: Integration and testing
- **IMPL-004**: [Additional tasks based on complexity]
## Dependencies & Sequence
- **Critical Path**: Essential task sequence
- **Parallel Opportunities**: Tasks that can run concurrently
- **External Dependencies**: Third-party integrations or resources needed
## Resource Allocation
- **Technical Resources**: Required skills and expertise
- **Timeline Estimates**: Duration estimates for each phase
- **Quality Gates**: Review and approval checkpoints
## Success Criteria
- **Functional Acceptance**: Core functionality validation
- **Technical Acceptance**: Performance, security, scalability criteria
- **User Acceptance**: Usability and experience validation
```
### Enhanced IMPL_PLAN.md Structure (Complex Workflows)
```markdown
# Implementation Plan - [Project Name]
## Context & Requirements
### From Brainstorming Analysis (if --from-brainstorming)
- **Key Insights**: Synthesized from multi-agent perspectives
- **Technical Requirements**: Architecture, security, data considerations
- **User Experience Requirements**: UI/UX design and usability needs
- **Business Requirements**: Product goals, stakeholder priorities, constraints
- **User Discussion Context**: Captured requirements from user interactions
### From User Input (if --skip-brainstorming)
- **User Provided Requirements**: Direct input and specifications
- **Context Analysis**: Interpreted requirements and technical implications
- **Gap Identification**: Areas needing clarification or additional information
## Strategic Approach
- **Implementation Philosophy**: Core principles guiding development
- **Success Metrics**: How progress and completion will be measured
- **Risk Mitigation**: Key risks identified and mitigation strategies
## Phase Breakdown
### Phase 1: Foundation
- **Objective**: [Core infrastructure/base components]
- **Tasks**: IMPL-001, IMPL-002
- **Duration**: [Estimate]
- **Success Criteria**: [Measurable outcomes]
### Phase 2: Core Implementation
- **Objective**: [Main functionality]
- **Tasks**: IMPL-003, IMPL-004, IMPL-005
- **Duration**: [Estimate]
- **Dependencies**: Phase 1 completion
### Phase 3: Integration & Testing
- **Objective**: [System integration and validation]
- **Tasks**: IMPL-006, IMPL-007
- **Duration**: [Estimate]
## Risk Assessment
- **High Risk**: [Description] - Mitigation: [Strategy]
- **Medium Risk**: [Description] - Mitigation: [Strategy]
## Quality Gates
- Code review requirements
- Testing coverage targets
- Performance benchmarks
- Security validation checks
## Rollback Strategy
- Rollback triggers and procedures
- Data preservation approach
```
## Document Storage
Generated documents are stored in session directory:
```
.workflow/WFS-[topic-slug]/
├── IMPL_PLAN.md # Combined planning document (all complexities)
└── workflow-session.json # Updated with document references
```
## Session Updates
```json
{
"phases": {
"PLAN": {
"status": "completed",
"output": {
"primary": "IMPL_PLAN.md"
},
"documents_generated": ["IMPL_PLAN.md"],
"completed_at": "2025-09-05T11:00:00Z",
"tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"]
}
},
"documents": {
"planning": {
"IMPL_PLAN.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md"
}
}
}
}
```
## Complexity Decision Rules
### Document Generation Matrix
| Complexity | IMPL_PLAN.md | Structure | Agent Requirements |
|------------|--------------|-----------|-------------------|
| **Simple** | Optional/Skip | Minimal | Direct to IMPLEMENT |
| **Medium** | Required | Standard | planning-agent |
| **Complex** | Required | Enhanced with phases + risk assessment | planning-agent + detailed analysis |
### Auto-Detection Triggers
Complex planning triggered when:
- Architecture changes required
- Security implementation needed
- Performance optimization planned
- System integration involved
- Estimated effort > 8 hours
- Risk level assessed as high
### Manual Override
```bash
# Force complex planning even for medium tasks
/workflow:action-plan --force-complex
# Force simple planning for quick fixes
/workflow:action-plan --force-simple
```
## Skip Option
```bash
/workflow:action-plan --skip-to-implement
```
- Generates minimal plan
- Immediately transitions to IMPLEMENT
- Useful for urgent fixes
## Replanning Mode
### Usage
```bash
# Basic replanning
/workflow:action-plan --replan --trigger=requirement-change
# Strategic replanning with impact analysis
/workflow:action-plan --replan --trigger=new-issue --scope=all --strategy=minimal-disruption --impact-analysis
# Conflict resolution
/workflow:action-plan --replan --trigger=dependency-conflict --auto-resolve
```
### Replan Parameters
- `--trigger=<reason>` → Replanning trigger: `new-issue|requirement-change|dependency-conflict|optimization`
- `--scope=<scope>` → Scope: `current-phase|all|documents-only|tasks-only`
- `--strategy=<strategy>` → Strategy: `minimal-disruption|optimal-efficiency|risk-minimization|time-optimization`
- `--impact-analysis` → Detailed impact analysis
- `--auto-resolve` → Auto-resolve conflicts
- `--dry-run` → Simulation mode
### Replanning Strategies
#### Minimal Disruption
- Preserve completed tasks
- Minimize impact on active work
- Insert changes optimally
#### Optimal Efficiency
- Re-optimize task order
- Maximize parallelization
- Optimize critical path
#### Risk Minimization
- Prioritize high-risk tasks
- Add buffer time
- Strengthen dependencies
#### Time Optimization
- Focus on core requirements
- Defer non-critical tasks
- Maximize parallel execution
### Integration with Issues
When issues are created, replanning can be automatically triggered:
```bash
# Create issue then replan
/workflow:issue create --type=feature "OAuth2 support"
/workflow:action-plan --replan --trigger=new-issue --issue=ISS-001
```
## Integration with Workflow System
### Action Planning Integration Points
**Prerequisite Commands**:
- `/workflow:session start` → Initialize workflow session
- `/brainstorm` → (Optional) Multi-agent brainstorming phase
**Action Planning Execution**:
- `/workflow:action-plan --from-brainstorming` → Plan from completed brainstorming
- `/workflow:action-plan --skip-brainstorming "task description"` → Plan from user input
- `/workflow:action-plan --replan` → Revise existing plans
**Follow-up Commands**:
- `/workflow:implement` → Execute the action plan
- `/workflow:status` → View current workflow state
- `/task:create` → Create specific implementation tasks
- `/workflow:review` → Validate completed implementation
### Session State Updates
After action planning completion:
```json
{
"current_phase": "IMPLEMENT",
"phases": {
"BRAINSTORM": {"status": "completed|skipped"},
"PLAN": {
"status": "completed",
"input_source": "brainstorming|user_input",
"documents_generated": ["IMPL_PLAN.md"],
"tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"],
"complexity_assessed": "simple|medium|complex"
}
}
}
```
### Quality Assurance
**Action Planning Excellence**:
- **Context Integration** → All brainstorming insights or user requirements incorporated
- **Actionable Output** → Plans translate directly to executable tasks
- **Comprehensive Coverage** → Technical, UX, and business considerations included
- **Clear Sequencing** → Dependencies and critical path clearly defined
- **Measurable Success** → Concrete acceptance criteria established
This action planning command bridges brainstorming insights and implementation execution, ensuring comprehensive planning based on multi-perspective analysis or direct user input.

509
.claude/commands/workflow/brainstorm.md Normal file
View File

@@ -0,0 +1,509 @@
---
name: brainstorm
description: Multi-perspective brainstorming coordination command that orchestrates multiple agents for comprehensive ideation and solution exploration
usage: /brainstorm <topic|challenge> [--mode=<creative|analytical|strategic>] [--perspectives=<role1,role2,...>] [--execution=<serial|parallel>]
argument-hint: "brainstorming topic or challenge description" [optional: mode, perspectives, execution]
examples:
- /brainstorm "innovative user authentication methods"
- /brainstorm "solving scalability challenges" --mode=analytical
- /brainstorm "redesigning the onboarding experience" --perspectives=ui-designer,user-researcher,product-manager
- /brainstorm "reducing system complexity" --mode=strategic --execution=parallel
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*)
---
### 🚀 **Command Overview: `/brainstorm`**
- **Type**: Coordination Command
- **Purpose**: To orchestrate multiple specialized agents for comprehensive multi-perspective brainstorming on challenges and opportunities.
- **Core Tools**: `Task(conceptual-planning-agent)`, `TodoWrite(*)`
- **Core Principles**: @~/.claude/workflows/core-principles.md
- **Integration Rules**:
- @~/.claude/workflows/brainstorming-principles.md
- @~/.claude/workflows/todowrite-coordination-rules.md
### 🔄 **Overall Brainstorming Protocol**
`Phase 1: Coordination Setup` **->** `Phase 1.5: User Discussion & Validation` **->** `Phase 2: Agent Coordination` **->** `Phase 3: Synthesis & Documentation`
### ⚙️ **Brainstorming Modes**
- **`creative` (Default)**
- **Approach**: Divergent thinking, "what if" scenarios.
- **Agent Selection**: Auto-selects `innovation-lead`, `ui-designer`, `user-researcher`, and a business agent.
- **Execution**: Typically parallel.
- **`analytical`**
- **Approach**: Root cause analysis, data-driven insights.
- **Agent Selection**: Auto-selects `business-analyst`, `data-architect`, `system-architect`, and a domain expert.
- **Execution**: Typically serial.
- **`strategic`**
- **Approach**: Systems thinking, long-term visioning.
- **Agent Selection**: Auto-selects `innovation-lead`, `product-manager`, `business-analyst`, and a technical expert.
- **Execution**: Mixed serial/parallel.
### 🚦 **Execution Patterns**
- **`serial` (Default)**
- **Use Case**: When perspectives need to build on each other.
- **Process**: Agents run one at a time, informed by previous outputs.
- **`parallel`**
- **Use Case**: When diverse, independent perspectives are needed quickly.
- **Process**: All selected agents run simultaneously.
- **`hybrid`**
- **Use Case**: Complex, multi-phase brainstorming.
- **Process**: Combines parallel initial ideation with serial refinement phases.
### 🎭 **Available Perspectives (Agent Roles)**
- `product-manager`: User needs, business value, market positioning.
- `system-architect`: Technical architecture, scalability, integration.
- `ui-designer`: User experience, interface design, usability.
- `data-architect`: Data flow, storage, analytics, insights.
- `security-expert`: Security implications, threat modeling, compliance.
- `user-researcher`: User behavior, pain points, research insights.
- `business-analyst`: Process optimization, efficiency, ROI.
- `innovation-lead`: Emerging trends, disruptive technologies, opportunities.
- `feature-planner`: Feature planning and development strategy.
- `test-strategist`: Testing strategy and quality assurance.
### 🤖 **Agent Selection & Loading Logic**
This logic determines which agents participate in the brainstorming session.
```pseudo
FUNCTION select_agents(mode, perspectives_arg):
IF perspectives_arg is provided:
// User explicitly defines roles via --perspectives flag
RETURN perspectives_arg.split(',')
ELSE:
// Automatic selection based on mode or topic analysis
CASE topic_type:
WHEN "Technical Challenge":
selected = ["system-architect", "security-expert"]
IF topic is data_heavy: ADD "data-architect"
RETURN selected
WHEN "User-Facing Feature":
RETURN ["ui-designer", "user-researcher", "product-manager"]
WHEN "Business Process":
RETURN ["business-analyst", "product-manager"]
WHEN "Innovation/Strategy":
RETURN ["innovation-lead", "product-manager"]
DEFAULT:
// Fallback to mode-based selection
CASE mode:
WHEN "creative": RETURN ["innovation-lead", "ui-designer", "user-researcher", ...]
WHEN "analytical": RETURN ["business-analyst", "data-architect", "system-architect", ...]
WHEN "strategic": RETURN ["innovation-lead", "product-manager", "business-analyst", ...]
END CASE
END CASE
END IF
END FUNCTION
FUNCTION load_agent_role(role_name):
// Dynamically loads role capabilities using the specified shell script
execute_tool("Bash", "~/.claude/scripts/plan-executor.sh " + role_name)
END FUNCTION
```
### 🏗️ **Phase 1: Coordination Setup Protocol**
⚠️ **CRITICAL**: Before brainstorming, MUST check for existing active session to avoid creating duplicate sessions.
**Session Check Process:**
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions
2. **Session Selection**: Use existing active session or create new one only if none exists
3. **Context Integration**: Load existing session state and continue brainstorming phase
`Check Active Session` **->** `Generate Topic Slug (WFS-[topic-slug]) if needed` **->** `Create Project Directories (.workflow/WFS-[slug]/.brainstorming/{agent1}, {agent2}, ...)` **->** `Initialize/Update session-state.json` **->** `Verify Structure` **->** `Initialize TodoWrite`
### 📝 **Initial TodoWrite Structure (Template)**
This `TodoWrite` call establishes the complete workflow plan at the beginning of the session.
```
TodoWrite([
{"content": "Establish project structure and initialize session", "status": "completed", "activeForm": "Establishing project structure"},
{"content": "Set up brainstorming session and select perspectives", "status": "in_progress", "activeForm": "Setting up brainstorming session"},
{"content": "Discuss [agent1] scope and gather user requirements", "status": "pending", "activeForm": "Discussing [agent1] requirements with user"},
{"content": "Coordinate [selected_agent1] perspective analysis", "status": "pending", "activeForm": "Coordinating [agent1] perspective"},
{"content": "Discuss [agent2] scope and gather user requirements", "status": "pending", "activeForm": "Discussing [agent2] requirements with user"},
{"content": "Coordinate [selected_agent2] perspective analysis", "status": "pending", "activeForm": "Coordinating [agent2] perspective"},
{"content": "Discuss [agent3] scope and gather user requirements", "status": "pending", "activeForm": "Discussing [agent3] requirements with user"},
{"content": "Coordinate [selected_agent3] perspective analysis", "status": "pending", "activeForm": "Coordinating [agent3] perspective"},
{"content": "Synthesize multi-perspective insights", "status": "pending", "activeForm": "Synthesizing insights"},
{"content": "Generate prioritized recommendations", "status": "pending", "activeForm": "Generating recommendations"},
{"content": "Create comprehensive brainstorming documentation", "status": "pending", "activeForm": "Creating documentation"}
])
```
### 💬 **Phase 1.5: Mandatory User Discussion Protocol**
This validation loop is **required** before *each* agent is executed.
```pseudo
FUNCTION validate_and_run_agents(selected_agents):
FOR EACH agent in selected_agents:
// Update the task list to show which discussion is active
update_todowrite("Discuss " + agent + " scope", "in_progress") // Corresponds to TodoWrite(*) tool
present_agent_scope(agent)
user_context = ask_context_questions(agent) // Example questions in next card
present_task_roadmap(agent)
LOOP:
user_response = get_user_input("Ready to proceed with " + agent + " analysis?")
IF user_response is "Yes, proceed" or similar:
// User has given explicit approval
update_todowrite("Discuss " + agent + " scope", "completed") // Corresponds to TodoWrite(*)
execute_agent_task(agent, user_context) // Proceeds to Phase 2 for this agent
BREAK
ELSE IF user_response is "No", "Wait", or requests changes:
// User has feedback, revise the plan
revise_approach(user_feedback)
present_task_roadmap(agent) // Re-present the revised plan
END IF
END LOOP
END FOR
END FUNCTION
```
### ❓ **User Discussion Question Templates**
- **System Architect**: Technical constraints? Integrations? Scalability needs?
- **UI Designer**: Primary users? Usability challenges? Brand guidelines? Accessibility?
- **Product Manager**: Business goals? Key stakeholders? Market factors? Success metrics?
- **Data Architect**: Data sources? Privacy/compliance? Quality challenges?
- **Security Expert**: Threat models? Compliance needs (GDPR, etc.)? Security level?
### 🧠 **Phase 2: Agent Coordination Logic**
This logic executes after user approval for each agent.
```pseudo
FUNCTION execute_agent_task(agent, user_context):
update_todowrite("Coordinate " + agent + " perspective", "in_progress") // Corresponds to TodoWrite(*) tool
// This action corresponds to calling the allowed tool: Task(conceptual-planning-agent)
// The specific prompt templates are provided in the source documentation.
status = execute_tool("Task(conceptual-planning-agent)", agent, user_context)
IF status is 'SUCCESS':
update_todowrite("Coordinate " + agent + " perspective", "completed")
ELSE:
// Handle potential agent execution failure
log_error("Agent " + agent + " failed.")
HALT_WORKFLOW()
END IF
END FUNCTION
```
### 📋 **Agent Execution Task Templates (Serial & Parallel)**
These templates show the exact structure of the `Task(conceptual-planning-agent)` call.
- **For Serial Execution (one agent at a time):**
```
Task(conceptual-planning-agent): "Conduct brainstorming analysis for: [topic]. Use [mode] brainstorming approach. Required perspective: [agent1].
Load role definition using: ~/.claude/scripts/plan-executor.sh [agent1]
USER CONTEXT FROM DISCUSSION:
- Specific focus areas: [user_specified_challenges_goals]
- Constraints and requirements: [user_specified_constraints]
- Expected outcomes: [user_expected_outcomes]
- Additional user requirements: [other_user_inputs]
OUTPUT REQUIREMENT: Save all generated documents to: .workflow/WFS-[topic-slug]/.brainstorming/[agent1]/
- analysis.md (main perspective analysis incorporating user context)
- [agent1-specific-output].md (specialized deliverable addressing user requirements)
Apply the returned planning template and generate comprehensive analysis from this perspective, ensuring all user-specified requirements and context are fully incorporated."
```
- **For Parallel Execution (multiple agents at once):**
```
Task(conceptual-planning-agent): "Conduct multi-perspective brainstorming analysis for: [topic]. Use [mode] brainstorming approach. Required perspectives: [agent1, agent2, agent3].
For each perspective, follow this protocol:
1. Load role definition using: ~/.claude/scripts/plan-executor.sh [role]
2. Incorporate user discussion context for each agent:
- [Agent1]: Focus areas: [user_input_agent1], Constraints: [constraints_agent1], Expected outcomes: [outcomes_agent1]
- [Agent2]: Focus areas: [user_input_agent2], Constraints: [constraints_agent2], Expected outcomes: [outcomes_agent2]
- [Agent3]: Focus areas: [user_input_agent3], Constraints: [constraints_agent3], Expected outcomes: [outcomes_agent3]
3. OUTPUT REQUIREMENT: Save documents to: .workflow/WFS-[topic-slug]/.brainstorming/[role]/
- analysis.md (main perspective analysis incorporating user context)
- [role-specific-output].md (specialized deliverable addressing user requirements)
Apply all perspectives in parallel analysis, ensuring each agent's output incorporates their specific user discussion context and is saved to their designated directory."
```
### 🏁 **Phase 3: Synthesis & Documentation Flow**
`Integrate All Agent Insights` **->** `Prioritize Solutions (by feasibility & impact)` **->** `Generate Comprehensive Summary Document` **->** `Mark All Todos as 'completed'`
### ✅ **Core Principles & Quality Standards**
- **User-Driven Process**: Every agent execution **must** be preceded by user discussion and explicit approval.
- **Context Integration**: All user inputs (focus areas, constraints, goals) must be fully incorporated into agent analysis.
- **`TodoWrite` First**: A `TodoWrite` plan must be established before any agent coordination begins.
- **Single Active Task**: Only one `TodoWrite` item should be marked `"in_progress"` at any time.
- **Transparent & Flexible**: The user understands what each agent will do and can provide feedback to revise the plan.
### 📄 **Synthesis Output Structure**
A guide for the final comprehensive report generated at the end of the workflow.
- **Session Summary**:
- Coordination approach (serial/parallel)
- Agent perspectives involved
- Brainstorming mode applied
- **Individual Agent Insights**:
- Summary of each agent's analysis.
- Note areas of agreement or disagreement.
- **Cross-Perspective Synthesis**:
- Identify convergent themes and breakthrough ideas.
- **Actionable Recommendations**:
- Categorize actions (immediate, strategic, research).
- **Implementation Guidance**:
- Suggested phases, resource needs, success metrics.
## 📁 **File Generation System**
### Automatic File Generation
Every brainstorming session generates a comprehensive set of structured output files:
#### Generated File Structure
```
.workflow/WFS-[topic-slug]/.brainstorming/
├── synthesis-analysis.md # Cross-perspective analysis
├── recommendations.md # Actionable recommendations
├── brainstorm-session.json # Session metadata
├── [agent1]/ # Individual agent outputs
│ ├── analysis.md # Main perspective analysis
│ └── [specific-deliverable].md # Agent-specific outputs
├── [agent2]/
│ ├── analysis.md
│ └── [specific-deliverable].md
└── artifacts/ # Supporting materials
├── user-context.md # Captured user discussion
├── session-transcript.md # Brainstorming session log
└── export/ # Export formats
├── brainstorm-summary.pdf
└── recommendations.json
```
### Core Output Documents
#### 1. synthesis-analysis.md
Cross-perspective synthesis of all agent insights:
```markdown
# Brainstorming Synthesis Analysis
*Session: WFS-[topic-slug] | Generated: 2025-09-07 16:00:00*
## Session Overview
- **Topic**: [brainstorming topic]
- **Mode**: [creative|analytical|strategic]
- **Execution**: [serial|parallel]
- **Participants**: [list of agent roles]
- **Duration**: [session duration]
## Individual Agent Insights Summary
### 🎨 UI Designer Perspective
**Focus Areas**: User experience, interface design, usability
**Key Insights**:
- Modern, intuitive design approach
- Mobile-first considerations
- Accessibility requirements
**Recommendations**: [specific design recommendations]
### 🏗️ System Architect Perspective
**Focus Areas**: Technical architecture, scalability, integration
**Key Insights**:
- Microservices architecture benefits
- Database optimization strategies
- Security considerations
**Recommendations**: [specific technical recommendations]
[Additional agent perspectives...]
## Cross-Perspective Analysis
### Convergent Themes
1. **User-Centric Approach**: All agents emphasized user experience priority
2. **Scalability Focus**: Common concern for system growth capacity
3. **Security Integration**: Unanimous priority on security-by-design
### Breakthrough Ideas
1. **Unified Authentication System**: Cross-platform identity management
2. **Progressive Web App**: Mobile and desktop feature parity
3. **AI-Powered Analytics**: Smart user behavior insights
### Areas of Disagreement
1. **Technology Stack**: [description of disagreement and perspectives]
2. **Implementation Timeline**: [varying estimates and approaches]
## Strategic Synthesis
[Integrated analysis combining all perspectives into coherent strategy]
---
*Generated by /brainstorm synthesis phase*
```
#### 2. recommendations.md
Actionable recommendations categorized by priority and scope:
```markdown
# Brainstorming Recommendations
*Session: WFS-[topic-slug] | Generated: 2025-09-07 16:15:00*
## Executive Summary
[High-level summary of key recommendations]
## Immediate Actions (0-2 weeks)
### High Priority - Critical
- **REC-001**: [Recommendation title]
- **Context**: [Background and rationale]
- **Action**: [Specific steps to take]
- **Resources**: [Required resources/skills]
- **Impact**: [Expected outcomes]
- **Owner**: [Suggested responsible party]
### Medium Priority - Important
- **REC-002**: [Recommendation title]
[Same structure as above]
## Strategic Actions (2-8 weeks)
### Architecture & Infrastructure
- **REC-003**: [Technical improvements]
- **REC-004**: [System optimizations]
### User Experience & Design
- **REC-005**: [UX improvements]
- **REC-006**: [Design system updates]
## Research Actions (Future Investigation)
### Technical Research
- **REC-007**: [Emerging technology evaluation]
- **REC-008**: [Performance optimization study]
### Market Research
- **REC-009**: [User behavior analysis]
- **REC-010**: [Competitive analysis]
## Implementation Roadmap
### Phase 1: Foundation (Weeks 1-2)
- Execute REC-001, REC-002
- Establish core infrastructure
### Phase 2: Development (Weeks 3-6)
- Implement REC-003, REC-004, REC-005
- Build core features
### Phase 3: Enhancement (Weeks 7-8)
- Deploy REC-006
- Optimize and refine
## Success Metrics
- [Quantifiable measures of success]
- [Key performance indicators]
## Risk Assessment
- [Potential obstacles and mitigation strategies]
---
*Generated by /brainstorm recommendations synthesis*
```
#### 3. brainstorm-session.json
Session metadata and tracking:
```json
{
"session_id": "WFS-[topic-slug]",
"brainstorm_id": "BRM-2025-09-07-001",
"topic": "[brainstorming topic]",
"mode": "creative",
"execution": "parallel",
"created_at": "2025-09-07T15:30:00Z",
"completed_at": "2025-09-07T16:30:00Z",
"duration_minutes": 60,
"participants": {
"agents": ["ui-designer", "system-architect", "product-manager"],
"user_interaction": true
},
"outputs": {
"agent_analyses": {
"ui-designer": {
"analysis_path": ".brainstorming/ui-designer/analysis.md",
"deliverable_path": ".brainstorming/ui-designer/design-mockups.md",
"completed_at": "2025-09-07T15:50:00Z"
},
"system-architect": {
"analysis_path": ".brainstorming/system-architect/analysis.md",
"deliverable_path": ".brainstorming/system-architect/architecture-proposal.md",
"completed_at": "2025-09-07T15:55:00Z"
},
"product-manager": {
"analysis_path": ".brainstorming/product-manager/analysis.md",
"deliverable_path": ".brainstorming/product-manager/feature-roadmap.md",
"completed_at": "2025-09-07T16:00:00Z"
}
},
"synthesis": {
"analysis_path": "synthesis-analysis.md",
"recommendations_path": "recommendations.md",
"completed_at": "2025-09-07T16:30:00Z"
}
},
"user_context": {
"focus_areas": "[captured from user discussion]",
"constraints": "[user-specified limitations]",
"expected_outcomes": "[user goals and expectations]"
},
"metrics": {
"insights_generated": 24,
"recommendations_count": 10,
"breakthrough_ideas": 3,
"consensus_areas": 3,
"disagreement_areas": 2
}
}
```
### Session Integration
After brainstorming completion, the main workflow-session.json is updated:
```json
{
"phases": {
"BRAINSTORM": {
"status": "completed",
"completed_at": "2025-09-07T16:30:00Z",
"output_directory": ".workflow/WFS-[topic-slug]/.brainstorming/",
"documents_generated": [
"synthesis-analysis.md",
"recommendations.md",
"brainstorm-session.json"
],
"agents_participated": ["ui-designer", "system-architect", "product-manager"],
"insights_available": true
}
},
"documents": {
"brainstorming": {
"synthesis-analysis.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/.brainstorming/synthesis-analysis.md",
"generated_at": "2025-09-07T16:30:00Z",
"type": "synthesis_analysis"
},
"recommendations.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/.brainstorming/recommendations.md",
"generated_at": "2025-09-07T16:30:00Z",
"type": "actionable_recommendations"
}
}
}
}
```
### Export and Integration Features
- **PDF Export**: Automatic generation of consolidated brainstorming report
- **JSON Export**: Machine-readable recommendations for integration tools
- **Action Plan Integration**: Direct feeding into `/workflow:action-plan --from-brainstorming`
- **Cross-Referencing**: Links to specific agent insights from synthesis documents

398
.claude/commands/workflow/context.md Normal file
View File

@@ -0,0 +1,398 @@
---
name: workflow-context
description: Unified workflow context analysis and status overview with file export capabilities
usage: /workflow:context [--detailed] [--health-check] [--format=<tree|json|summary>] [--export]
argument-hint: Optional flags for analysis depth, output format, and file export
examples:
- /workflow:context
- /workflow:context --detailed
- /workflow:context --health-check
- /workflow:context --format=tree
- /workflow:context --detailed --export
- /workflow:context --health-check --export
---
# Workflow Context Command (/workflow:context)
## Overview
Unified workflow context analysis command providing comprehensive state analysis and quick overview of current work status.
## Core Principles
**System:** @~/.claude/workflows/unified-workflow-system-principles.md
## Features
### Core Functionality
- **Real-time Status Snapshot** → Complete workflow state display
- **Task Progress Overview** → Completed, active, pending task statistics
- **Document Health Check** → Document consistency and completeness analysis
- **Dependency Analysis** → Task dependency and conflict identification
- **Time Estimation** → Completion time prediction based on current progress
### Advanced Analysis
- **Blocker Identification** → Automatic detection of progress obstacles
- **Priority Recommendations** → Next action suggestions based on dependencies
- **Risk Assessment** → Execution risk evaluation for current plan
## Core Principles
**System:** @~/.claude/workflows/unified-workflow-system-principles.md
## Display Modes
### Summary View (/workflow:context)
```
🔍 Workflow Status Overview
========================
📋 Session Information:
- Session ID: WFS-2025-001
- Current Phase: Implementation
- Start Time: 2025-01-15 09:30:00
- Duration: 2h 45m
📊 Task Progress:
✅ Completed: 9/15 (60%)
🔄 In Progress: 2 tasks
⏳ Pending: 4 tasks
🚫 Blocked: 0 tasks
📁 Document Status:
✅ IMPL_PLAN.md - Healthy
✅ TODO_LIST.md - Healthy
⚠️ TODO_CHECKLIST.md - Needs sync
❌ WORKFLOW_ISSUES.md - Missing
⏱️ Estimated Completion: 2025-01-15 16:45 (4h 15m remaining)
🎯 Next Steps:
1. Complete current API endpoint implementation
2. Update TODO_CHECKLIST.md status
3. Start frontend user interface development
```
### Detailed View (/workflow:context --detailed)
```
🔍 Detailed Workflow Analysis
========================
📋 Session Details:
Session ID: WFS-2025-001
Workflow Type: Complex
Main Task: "Implement OAuth2 User Authentication System"
📊 Detailed Progress Analysis:
✅ Completed Tasks (9):
- [PLAN-001] Requirements analysis and architecture design
- [PLAN-002] Database model design
- [IMPL-001] User model implementation
- [IMPL-002] JWT token service
- [IMPL-003] Password encryption service
- [TEST-001] Unit tests - User model
- [TEST-002] Unit tests - JWT service
- [DOC-001] API documentation - Auth endpoints
- [DOC-002] Database migration documentation
🔄 In Progress Tasks (2):
- [IMPL-004] OAuth2 provider integration (70% complete)
↳ Dependencies: [PLAN-002], [IMPL-001]
↳ Estimated remaining: 1.5h
- [TEST-003] Integration tests - OAuth flow (30% complete)
↳ Dependencies: [IMPL-004]
↳ Estimated remaining: 2h
⏳ Pending Tasks (4):
- [IMPL-005] Frontend login interface
- [IMPL-006] Session management middleware
- [TEST-004] End-to-end testing
- [DOC-003] User documentation
📁 Document Health Analysis:
✅ IMPL_PLAN.md:
- Status: Healthy
- Last updated: 2025-01-15 10:15
- Coverage: 100% (all tasks defined)
✅ TODO_LIST.md:
- Status: Healthy
- Progress tracking: 15 tasks, 4 levels
- Dependencies: Verified
⚠️ TODO_CHECKLIST.md:
- Status: Needs sync
- Issue: 3 completed tasks not marked
- Recommendation: Run /workflow:sync
🔗 Dependency Analysis:
Critical Path:
[IMPL-004] → [TEST-003] → [IMPL-005] → [TEST-004]
Potential Blockers:
❌ No blockers detected
Parallel Execution Suggestions:
- [IMPL-005] can start immediately after [TEST-003] completes
- [DOC-003] can run in parallel with [IMPL-006]
⚠️ Risk Assessment:
🟢 Low Risk (Current Status)
- OAuth2 integration progressing as expected
- All tests passing
- No technical debt accumulation
Potential Risks:
- Frontend interface design not finalized (Impact: Medium)
- Third-party OAuth service dependency (Impact: Low)
```
### Tree Format (/workflow:context --format=tree)
```
📁 WFS-2025-001: User Authentication
├── 📋 PLAN [Completed]
│ └── Output: IMPL_PLAN.md
├── 🔨 IMPLEMENT [Active - 45%]
│ ├── ✅ IMPL-001: Authentication
│ ├── ✅ IMPL-002: Database
│ ├── ✅ IMPL-003: JWT
│ ├── 🔄 IMPL-004: OAuth2 (70%)
│ ├── ⏳ IMPL-005: Testing
│ ├── 🚫 IMPL-006: Integration
│ └── ⏳ IMPL-007: Documentation
└── 📝 REVIEW [Pending]
```
### JSON Format (/workflow:context --format=json)
Returns merged workflow-session.json + task data for programmatic access.
## File Export Feature
### Export Mode (/workflow:context --export)
When `--export` flag is used, generates persistent status report files in addition to console output.
#### Generated Files
**Status Report Generation:**
- **Standard Mode**: Creates `reports/STATUS_REPORT.md`
- **Detailed Mode**: Creates `reports/DETAILED_STATUS_REPORT.md`
- **Health Check Mode**: Creates `reports/HEALTH_CHECK.md`
#### File Storage Location
```
.workflow/WFS-[topic-slug]/reports/
├── STATUS_REPORT.md # Standard context export
├── DETAILED_STATUS_REPORT.md # Detailed context export
├── HEALTH_CHECK.md # Health check export
└── context-exports/ # Historical exports
├── status-2025-09-07-14-30.md
├── detailed-2025-09-07-15-45.md
└── health-2025-09-07-16-15.md
```
#### Export File Structure
**STATUS_REPORT.md Format:**
```markdown
# Workflow Status Report
*Generated: 2025-09-07 14:30:00*
## Session Information
- **Session ID**: WFS-2025-001
- **Current Phase**: Implementation
- **Start Time**: 2025-01-15 09:30:00
- **Duration**: 2h 45m
## Task Progress Summary
- **Completed**: 9/15 (60%)
- **In Progress**: 2 tasks
- **Pending**: 4 tasks
- **Blocked**: 0 tasks
## Document Status
- ✅ IMPL_PLAN.md - Healthy
- ✅ TODO_LIST.md - Healthy
- ⚠️ TODO_CHECKLIST.md - Needs sync
- ❌ WORKFLOW_ISSUES.md - Missing
## Time Estimation
- **Estimated Completion**: 2025-01-15 16:45
- **Remaining Time**: 4h 15m
## Next Steps
1. Complete current API endpoint implementation
2. Update TODO_CHECKLIST.md status
3. Start frontend user interface development
---
*Report generated by /workflow:context --export*
```
**HEALTH_CHECK.md Format:**
```markdown
# Workflow Health Check Report
*Generated: 2025-09-07 16:15:00*
## Overall Health Score: 85/100 (Good)
## System Health Analysis
### ✅ Session State Check
- **workflow-session.json**: Exists and valid
- **Backup files**: 3 backups available
- **Data integrity**: Verified
### 📋 Document Consistency Check
- **IMPL_PLAN.md ↔ TODO_LIST.md**: ✅ 100% consistency
- **TODO_CHECKLIST.md ↔ TodoWrite status**: ⚠️ 80% (3 items out of sync)
- **WORKFLOW_ISSUES.md**: ❌ Missing file
### 🔄 Progress Tracking Health
- **TodoWrite integration**: ✅ Running normally
- **Timestamp recording**: ✅ Complete
- **Progress estimation**: ⚠️ 85% accuracy
## Recommendations
### Immediate Actions
1. Run /workflow:sync to sync document status
2. Execute /workflow:issue create to establish issue tracking
### Planned Actions
3. Consider creating more checkpoints to improve recovery capability
4. Optimize dependencies to reduce critical path length
## Detailed Analysis
[Detailed health metrics and analysis...]
---
*Health check generated by /workflow:context --health-check --export*
```
#### Session Updates
When files are exported, the workflow-session.json is updated:
```json
{
"documents": {
"reports": {
"STATUS_REPORT.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/reports/STATUS_REPORT.md",
"generated_at": "2025-09-07T14:30:00Z",
"type": "status_report"
},
"HEALTH_CHECK.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/reports/HEALTH_CHECK.md",
"generated_at": "2025-09-07T16:15:00Z",
"type": "health_check"
}
}
},
"export_history": [
{
"type": "status_report",
"timestamp": "2025-09-07T14:30:00Z",
"file": "reports/STATUS_REPORT.md"
}
]
}
```
#### Historical Exports
- **Automatic archiving**: Previous exports moved to `context-exports/` with timestamps
- **Retention policy**: Keep last 10 exports of each type
- **Cross-referencing**: Links to historical data in current reports
### Health Check Mode (/workflow:context --health-check)
```
🏥 Workflow Health Diagnosis
========================
✅ Session State Check:
- workflow-session.json: Exists and valid
- Backup files: 3 backups available
- Data integrity: Verified
📋 Document Consistency Check:
✅ IMPL_PLAN.md ↔ TODO_LIST.md
- Task definition consistency: ✅ 100%
- Progress synchronization: ✅ 100%
⚠️ TODO_CHECKLIST.md ↔ TodoWrite status
- Sync status: ❌ 80% (3 items out of sync)
- Recommended action: Run /workflow:sync
❌ WORKFLOW_ISSUES.md
- Status: File does not exist
- Recommendation: Create issue tracking document
🔄 Progress Tracking Health:
✅ TodoWrite integration: Running normally
✅ Timestamp recording: Complete
⚠️ Progress estimation: Based on historical data, 85% accuracy
🔧 System Recommendations:
Immediate Actions:
1. Run /workflow:sync to sync document status
2. Execute /workflow:issue create to establish issue tracking
Planned Actions:
3. Consider creating more checkpoints to improve recovery capability
4. Optimize dependencies to reduce critical path length
🎯 Overall Health Score: 85/100 (Good)
```
## Use Cases
### Case 1: Work Recovery
User returns after interrupting work and needs quick status understanding:
```bash
/workflow:context
# Get quick overview, understand progress and next actions
```
### Case 2: Status Reporting
Need to report project progress to team or management:
```bash
/workflow:context --detailed
# Get detailed progress analysis and estimates
```
### Case 3: Problem Diagnosis
Workflow shows anomalies and needs problem diagnosis:
```bash
/workflow:context --health-check
# Comprehensive health check and repair recommendations
```
### Case 4: Pre-change Assessment
Before adding new requirements or modifying plans, assess current state:
```bash
/workflow:context --detailed --health-check
# Complete status analysis to inform change decisions
```
## Technical Implementation
### Data Source Integration
- **workflow-session.json** - Session state and history
- **TodoWrite status** - Real-time task progress
- **Document analysis** - Workflow-related document parsing
- **Git status** - Code repository change tracking
### Intelligent Analysis Algorithms
- **Dependency graph construction** - Auto-build dependency graphs from task definitions
- **Critical path algorithm** - Identify key task sequences affecting overall progress
- **Health scoring** - Multi-dimensional workflow state health assessment
- **Time estimation model** - Intelligent estimation based on historical data and current progress
### Caching and Performance Optimization
- **Status caching** - Cache computationally intensive analysis results
- **Incremental updates** - Only recalculate changed portions
- **Asynchronous analysis** - Background execution of complex analysis tasks

345
.claude/commands/workflow/implement.md Normal file
View File

@@ -0,0 +1,345 @@
---
name: workflow-implement
description: Implementation phase with simple, medium, and complex execution modes
usage: /workflow:implement [--type=<simple|medium|complex>] [--auto-create-tasks]
argument-hint: [optional: complexity type and auto-create]
examples:
- /workflow:implement
- /workflow:implement --type=simple
- /workflow:implement --type=complex --auto-create-tasks
---
# Workflow Implement Command (/workflow:implement)
## Overview
Executes implementation phase with three complexity modes (simple/medium/complex), replacing separate complexity commands.
## Core Principles
**Session Management:** @~/.claude/workflows/session-management-principles.md
## Complexity Modes
### Simple Mode (Single file, bug fixes)
```bash
/workflow:implement --type=simple
```
**Agent Flow:** code-developer → code-review-agent
**TodoWrite:** 3-4 items
**Documents:** TODO_LIST.md + IMPLEMENTATION_LOG.md (auto-generated)
- Streamlined planning, direct implementation
- Quick review cycle
- < 2 hours effort
### Medium Mode (Multi-file features)
```bash
/workflow:implement --type=medium
```
**Agent Flow:** planning-agent → code-developer → code-review-agent
**TodoWrite:** 5-7 items
**Documents:** IMPL_PLAN.md + TODO_LIST.md (auto-triggered)
- Structured planning with hierarchical JSON task decomposition
- Test-driven development
- Comprehensive review
- 2-8 hours effort
### Complex Mode (System-level changes)
```bash
/workflow:implement --type=complex
```
**Agent Flow:** planning-agent → code-developer → code-review-agent → iterate
**TodoWrite:** 7-10 items
**Documents:** IMPL_PLAN.md + TODO_LIST.md (mandatory)
- Detailed planning with mandatory 3-level JSON task hierarchy
- Risk assessment and quality gates
- Multi-faceted review with multiple iterations
- > 8 hours effort
## Execution Flow
1. **Detect Complexity** (if not specified)
- Read from workflow-session.json
- Auto-detect from task description
- Default to medium if unclear
2. **Initialize Based on Complexity**
**Simple:**
- Use existing IMPL_PLAN.md (minimal updates)
- Direct JSON task creation (impl-*.json)
- Minimal state tracking
**Medium:**
- Update IMPL_PLAN.md with implementation strategy
- Auto-trigger TODO_LIST.md creation
- Create hierarchical JSON tasks (impl-*.*.json up to 2 levels)
- Standard agent flow
**Complex:**
- Comprehensive IMPL_PLAN.md with risk assessment
- Mandatory TODO_LIST.md with progress tracking
- Full 3-level JSON task hierarchy (impl-*.*.*.json)
- Full iteration support with cross-document synchronization
3. **Update Session**
```json
{
"current_phase": "IMPLEMENT",
"type": "simple|medium|complex",
"phases": {
"IMPLEMENT": {
"status": "active",
"complexity": "simple|medium|complex",
"agent_flow": [...],
"todos": [...],
"tasks": ["impl-1", "impl-2", "impl-3"],
"progress": 0,
"documents_generated": ["TODO_LIST.md", "IMPLEMENTATION_LOG.md"],
"documents_updated": ["IMPL_PLAN.md"]
}
},
"documents": {
"IMPL_PLAN.md": {
"status": "updated",
"path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md",
"last_updated": "2025-09-05T10:30:00Z"
},
"TODO_LIST.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/TODO_LIST.md",
"last_updated": "2025-09-05T11:20:00Z",
"type": "task_tracking"
},
"IMPLEMENTATION_LOG.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/IMPLEMENTATION_LOG.md",
"last_updated": "2025-09-05T11:20:00Z",
"type": "execution_log",
"auto_update": true
}
},
"task_system": {
"max_depth": 3,
"task_count": {
"main_tasks": 3,
"total_tasks": 8
}
}
}
```
4. **Execute Agent Flow**
- Create TodoWrite entries
- Execute agents based on complexity
- Track checkpoints
- Support pause/resume
## Document Generation Rules
### Decomposition Triggers (Medium Workflows)
Task decomposition documents generated when ANY condition met:
- Task involves >3 modules/components
- >5 distinct subtasks identified
- Complex interdependencies detected
- Estimated effort >4 hours
- Cross-team coordination required
### Mandatory Generation (Complex Workflows)
Always generates complete document suite:
- **Enhanced IMPL_PLAN.md structure** - Hierarchical task breakdown integrated into main plan
- **TODO_LIST.md** - Progress tracking with cross-links
- Links to existing IMPL_PLAN.md from planning phase
### Document-JSON Synchronization
- **Document Creation** → Update workflow session with document references
- **Task Status Changes** → Update TODO_LIST.md progress
- **Task Completion** → Mark items complete in checklist
- **New Tasks Added** → Add to both JSON and enhanced implementation plan
### Document Storage Structure
```
.workflow/WFS-[topic-slug]/
├── IMPL_PLAN.md # From planning phase (all complexities)
├── (enhanced IMPL_PLAN.md) # Enhanced structure in implement phase (medium+/complex)
├── TODO_LIST.md # Generated in implement phase (ALL complexities)
├── IMPLEMENTATION_LOG.md # Execution progress log (ALL complexities)
├── workflow-session.json # Updated with document references
└── artifacts/
├── logs/
├── backups/ # Task state backups
└── implementation/ # Implementation artifacts
```
## File Generation Details
### TODO_LIST.md Generation (All Complexities)
**Always Generated**: Now created for Simple, Medium, and Complex workflows
**Simple Workflow Structure:**
```markdown
# Implementation Task List
*Session: WFS-[topic-slug]*
## Quick Implementation Tasks
- [ ] **IMPL-001**: Core implementation
- [ ] **IMPL-002**: Basic testing
- [ ] **IMPL-003**: Review and cleanup
## Progress Tracking
- **Total Tasks**: 3
- **Completed**: 0/3 (0%)
- **Estimated Time**: < 2 hours
---
*Generated by /workflow:implement --type=simple*
```
**Medium/Complex Workflow Structure:**
```markdown
# Implementation Task List
*Session: WFS-[topic-slug]*
## Main Implementation Tasks
### Phase 1: Foundation
- [ ] **IMPL-001**: Set up base infrastructure
- Dependencies: None
- Effort: 2h
- Agent: code-developer
### Phase 2: Core Features
- [ ] **IMPL-002**: Implement main functionality
- Dependencies: IMPL-001
- Effort: 4h
- Agent: code-developer
### Phase 3: Testing & Review
- [ ] **IMPL-003**: Comprehensive testing
- Dependencies: IMPL-002
- Effort: 2h
- Agent: code-review-agent
## Progress Summary
- **Total Tasks**: 8
- **Completed**: 0/8 (0%)
- **Current Phase**: Foundation
- **Estimated Completion**: 2025-09-07 18:00
---
*Generated by /workflow:implement --type=medium*
```
### IMPLEMENTATION_LOG.md Generation (All Complexities)
**Always Generated**: Real-time execution progress tracking
```markdown
# Implementation Execution Log
*Session: WFS-[topic-slug] | Started: 2025-09-07 14:00:00*
## Execution Summary
- **Workflow Type**: Medium
- **Total Tasks**: 8
- **Current Status**: In Progress
- **Progress**: 3/8 (37.5%)
## Execution Timeline
### 2025-09-07 14:00:00 - Implementation Started
- **Phase**: IMPLEMENT
- **Agent**: code-developer
- **Status**: Task execution initialized
### 2025-09-07 14:15:00 - IMPL-001 Started
- **Task**: Set up base infrastructure
- **Agent**: code-developer
- **Approach**: Standard project structure setup
### 2025-09-07 14:45:00 - IMPL-001 Completed
- **Duration**: 30 minutes
- **Status**: ✅ Successful
- **Output**: Base project structure created
- **Next**: IMPL-002
### 2025-09-07 15:00:00 - IMPL-002 Started
- **Task**: Implement main functionality
- **Agent**: code-developer
- **Dependencies**: IMPL-001 ✅
## Current Task Progress
- **Active Task**: IMPL-002
- **Progress**: 60%
- **Estimated Completion**: 15:30
- **Agent**: code-developer
## Issues & Resolutions
- No issues reported
## Next Actions
1. Complete IMPL-002 implementation
2. Begin IMPL-003 testing phase
3. Schedule review checkpoint
---
*Log updated: 2025-09-07 15:15:00*
```
## Individual Task Files Structure
```json
{
"id": "IMPL-001",
"title": "Build authentication module",
"status": "pending",
"type": "feature",
"agent": "code-developer",
"effort": "4h",
"context": {
"inherited_from": "WFS-2025-001",
"requirements": ["JWT authentication"],
"scope": ["src/auth/*"],
"acceptance": ["Module handles JWT tokens"]
},
"dependencies": {
"upstream": [],
"downstream": ["IMPL-002"]
},
"subtasks": [],
"execution": {
"attempts": 0,
"current_attempt": null,
"history": []
},
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"version": "1.0"
}
}
```
## Integration Points
### Automatic Behaviors
- Creates individual task JSON files (.task/tasks/IMPL-XXX.json) as needed
- Generates decomposition documents based on complexity triggers
- Links documents to workflow-session.json with paths and status
- Enables task commands (/task:*) with document integration
- Starts progress tracking in both JSON and TODO_CHECKLIST.md
- Synchronizes task creation between documents and JSON states
### Next Actions
```bash
# After /workflow:implement
/task:create "First task" # Create tasks
/task:status # View task list
/task:execute IMPL-001 # Execute tasks
```
## Sync Mechanism
- Every task operation updates workflow-session.json
- Progress calculated from task completion
- Issues automatically linked
## Related Commands
- `/workflow:plan` - Should complete first
- `/task:create` - Create implementation tasks
- `/task:status` - Monitor progress
- `/workflow:review` - Next phase after implementation

356
.claude/commands/workflow/issue.md Normal file
View File

@@ -0,0 +1,356 @@
---
name: workflow-issue
description: Comprehensive issue and change request management within workflow sessions
usage: /workflow:issue <subcommand> [options]
argument-hint: create|list|update|integrate|close [additional parameters]
examples:
- /workflow:issue create --type=feature "Add OAuth2 social login support"
- /workflow:issue create --type=bug --priority=high "User avatar security vulnerability"
- /workflow:issue list
- /workflow:issue list --status=open --priority=high
- /workflow:issue update ISS-001 --status=integrated --priority=medium
- /workflow:issue integrate ISS-001 --position=after-current
- /workflow:issue close ISS-002 --reason="Duplicate of ISS-001"
---
### 🚀 Command Overview: `/workflow:issue`
- **Purpose**: A comprehensive issue and change request management system for use within workflow sessions.
- **Function**: Enables dynamic creation, tracking, integration, and closure of tasks and changes.
### 🏛️ Subcommand Architecture
- **`create`**: Creates a new issue or change request.
- **`list`**: Lists and filters existing issues.
- **`update`**: Modifies the status, priority, or other attributes of an issue.
- **`integrate`**: Integrates an issue into the current workflow plan.
- **`close`**: Closes a completed or obsolete issue.
### 📜 Core Principles
- **Dynamic Change Management**: @~/.claude/workflows/dynamic-change-management.md
- **Session State Management**: @~/.claude/workflows/session-management-principles.md
- **TodoWrite Coordination Rules**: @~/.claude/workflows/todowrite-coordination-rules.md
### (1) Subcommand: `create`
Creates a new issue or change request.
- **Syntax**: `/workflow:issue create [options] "issue description"`
- **Options**:
- `--type=<type>`: `feature|bug|optimization|refactor|documentation`
- `--priority=<priority>`: `critical|high|medium|low`
- `--category=<category>`: `frontend|backend|database|testing|deployment`
- `--estimated-impact=<impact>`: `high|medium|low`
- `--blocking`: Marks the issue as a blocker.
- `--parent=<issue-id>`: Specifies a parent issue for creating a sub-task.
### (2) Subcommand: `list`
Lists and filters all issues related to the current workflow.
- **Syntax**: `/workflow:issue list [options]`
- **Options**:
- `--status=<status>`: Filter by `open|integrated|completed|closed`.
- `--type=<type>`: Filter by issue type.
- `--priority=<priority>`: Filter by priority level.
- `--category=<category>`: Filter by category.
- `--blocking-only`: Shows only blocking issues.
- `--sort=<field>`: Sort by `priority|created|updated|impact`.
- `--detailed`: Displays more detailed information for each issue.
### (3) Subcommand: `update`
Updates attributes of an existing issue.
- **Syntax**: `/workflow:issue update <issue-id> [options]`
- **Options**:
- `--status=<status>`: Update issue status.
- `--priority=<priority>`: Update issue priority.
- `--description="<new-desc>"`: Update the description.
- `--category=<category>`: Update the category.
- `--estimated-impact=<impact>`: Update estimated impact.
- `--add-comment="<comment>"`: Add a new comment to the issue history.
- `--assign-to=<assignee>`: Assign the issue to a person or team.
- `--blocking` / `--non-blocking`: Change the blocking status.
### (4) Subcommand: `integrate`
Integrates a specified issue into the current workflow plan.
- **Syntax**: `/workflow:issue integrate <issue-id> [options]`
- **Options**:
- `--position=<position>`: `immediate|after-current|next-phase|end-of-workflow`
- `--mode=<mode>`: `insert|replace|merge`
- `--impact-analysis`: Performs a detailed impact analysis before integration.
- `--auto-replan`: Automatically replans the workflow after integration.
- `--preserve-dependencies`: Tries to maintain existing task dependencies.
- `--dry-run`: Simulates integration without making actual changes.
- **Execution Logic**:
```pseudo
FUNCTION integrate_issue(issue_id, options):
// Perform an analysis of how the issue affects the project plan.
analysis_report = create_impact_analysis(issue_id, options)
present_report_to_user(analysis_report)
// Require explicit user confirmation before modifying the workflow.
user_response = get_user_input("Confirm integration? (y/N)")
IF user_response is "y":
log("Executing integration...")
// These steps correspond to the "集成步骤" in the example output.
update_document("IMPL_PLAN.md")
update_document("TODO_CHECKLIST.md")
update_tool_state("TodoWrite")
update_session_file("workflow-session.json")
log("Integration complete!")
ELSE:
log("Integration cancelled by user.")
HALT_OPERATION()
END FUNCTION
```
### (5) Subcommand: `close`
Closes an issue that is completed or no longer relevant.
- **Syntax**: `/workflow:issue close <issue-id> [options]`
- **Options**:
- `--reason=<reason>`: `completed|duplicate|wont-fix|invalid`
- `--comment="<comment>"`: Provides a final closing comment.
- `--reference=<issue-id>`: References a related issue (e.g., a duplicate).
- `--auto-cleanup`: Automatically cleans up references to this issue in other documents.
### ✨ Advanced Features
- **Batch Operations**:
- Update multiple issues at once: `/workflow:issue update ISS-001,ISS-002 --priority=high`
- Integrate a parent issue with its children: `/workflow:issue integrate ISS-001,ISS-001-1,ISS-001-2`
- **Smart Analysis**:
- Performs conflict detection, dependency analysis, priority suggestions, and effort estimations.
- **Reporting**:
- Generate reports on impact or priority: `/workflow:issue report --type=impact`
### 🤝 Command Integrations
- **Automatic Triggers**:
- `/workflow:context`: Automatically displays the status of relevant issues.
- `/workflow:replan`: Can be automatically called by `integrate` to update the plan.
- `/workflow:sync`: Ensures issue status is synchronized with project documents.
- **Shared Data**:
- `workflow-session.json`: Stores core issue data and statistics.
- `WORKFLOW_ISSUES.md`: Provides a human-readable tracking document.
- `CHANGE_LOG.md`: Logs all historical changes related to issues.
### 🗄️ File Generation System
- **Process Flow**: All issue operations trigger a file system update.
`Issue Operation` -> `Generate/Update issues/ISS-###.json` -> `Update WORKFLOW_ISSUES.md` -> `Update workflow-session.json`
### 📄 Template: Individual Issue File (`issues/ISS-###.json`)
This file stores all details for a single issue.
```json
{
"id": "ISS-003",
"title": "Add OAuth2 social login support",
"description": "Add OAuth2 social login support (Google, GitHub, Facebook)",
"type": "feature",
"priority": "high",
"category": "backend",
"status": "open",
"estimated_impact": "medium",
"blocking": false,
"created_at": "2025-01-15T14:30:00Z",
"created_by": "WFS-2025-001",
"parent_issue": null,
"sub_issues": [],
"integration": {
"status": "pending",
"position": "after-current",
"estimated_effort": "6h",
"dependencies": []
},
"history": [
{
"action": "created",
"timestamp": "2025-01-15T14:30:00Z",
"details": "Initial issue creation"
}
],
"metadata": {
"session_id": "WFS-2025-001",
"version": "1.0"
}
}
```
### 📋 Template: Tracking Master File (`WORKFLOW_ISSUES.md`)
This Markdown file provides a human-readable overview of all issues.
```markdown
# Workflow Issues Tracking
*Session: WFS-2025-001 | Updated: 2025-01-15 14:30:00*
## Issue Summary
- **Total Issues**: 3
- **Open**: 2
- **In Progress**: 1
- **Closed**: 0
- **Blocking Issues**: 0
## Open Issues
### 🔥 High Priority
- **[ISS-003](issues/ISS-003.json)** - Add OAuth2 social login support
- Type: Feature | Category: Backend | Created: 2025-01-15
- Status: Open | Impact: Medium
- Integration: Pending (after current phase)
- **[ISS-001](issues/ISS-001.json)** - User avatar security vulnerability
- Type: Bug | Category: Frontend | Created: 2025-01-14
- Status: Open | Impact: High | 🚫 **BLOCKING**
- Integration: Immediate (critical security fix)
### 📊 Medium Priority
- **[ISS-002](issues/ISS-002.json)** - Database performance optimization
- Type: Optimization | Category: Database | Created: 2025-01-14
- Status: In Progress | Impact: High
- Integration: Phase 3 (optimization phase)
## Integration Queue
1. **ISS-001** - Immediate (blocking security issue)
2. **ISS-002** - Phase 3 (performance optimization)
3. **ISS-003** - After current phase (new feature)
## Recent Activity
- **2025-01-15 14:30** - ISS-003 created: Add OAuth2 social login support
- **2025-01-15 10:15** - ISS-002 status updated: In Progress
- **2025-01-14 16:45** - ISS-001 created: User avatar security vulnerability
---
*Generated by /workflow:issue create*
```
### 📁 Template: File Storage Structure
The command organizes all related files within a dedicated workflow directory.
```
.workflow/WFS-[topic-slug]/
├── WORKFLOW_ISSUES.md # 主问题跟踪文件
├── issues/ # 个别问题详情目录
│ ├── ISS-001.json # 问题详细信息
│ ├── ISS-002.json
│ ├── ISS-003.json
│ └── archive/ # 已关闭问题存档
│ └── ISS-###.json
├── issue-reports/ # 问题报告和分析
│ ├── priority-analysis.md
│ ├── integration-impact.md
│ └── resolution-summary.md
└── workflow-session.json # 会话状态更新
```
### 🔄 Template: Session State Update (`workflow-session.json`)
This file is updated after each issue operation to reflect the new state.
```json
{
"issues": {
"total_count": 3,
"open_count": 2,
"blocking_count": 1,
"last_issue_id": "ISS-003",
"integration_queue": ["ISS-001", "ISS-002", "ISS-003"]
},
"documents": {
"WORKFLOW_ISSUES.md": {
"status": "updated",
"path": ".workflow/WFS-[topic-slug]/WORKFLOW_ISSUES.md",
"last_updated": "2025-01-15T14:30:00Z",
"type": "issue_tracking"
},
"issues": {
"ISS-003.json": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/issues/ISS-003.json",
"created_at": "2025-01-15T14:30:00Z",
"type": "issue_detail",
"priority": "high",
"blocking": false
}
}
},
"recent_activity": [
{
"type": "issue_created",
"issue_id": "ISS-003",
"timestamp": "2025-01-15T14:30:00Z",
"description": "Add OAuth2 social login support"
}
]
}
```
### 🧱 Issue Data Structure
The canonical JSON structure for an issue object.
```json
{
"id": "ISS-001",
"type": "feature|bug|optimization|refactor|documentation",
"status": "open|integrated|in-progress|completed|closed",
"priority": "critical|high|medium|low",
"category": "frontend|backend|database|testing|deployment",
"blocking": false,
"metadata": {
"title": "OAuth2 social login support",
"description": "Add OAuth2 integration for Google, GitHub, Facebook",
"created_at": "2025-01-15T14:30:00Z",
"updated_at": "2025-01-15T15:45:00Z",
"created_by": "workflow-session:WFS-2025-001"
},
"estimation": {
"impact": "high|medium|low",
"effort": "2-4 hours|1-2 days|3-5 days",
"complexity": "simple|medium|complex"
},
"integration": {
"integrated_at": "2025-01-15T16:00:00Z",
"position": "after-current",
"affected_documents": ["IMPL_PLAN.md"],
"added_tasks": 5,
"modified_tasks": 2
},
"relationships": {
"parent": "ISS-000",
"children": ["ISS-001-1", "ISS-001-2"],
"blocks": ["ISS-002"],
"blocked_by": [],
"relates_to": ["ISS-003"]
},
"comments": [
{
"timestamp": "2025-01-15T15:30:00Z",
"content": "需要考虑用户隐私设置集成",
"type": "note|decision|change"
}
],
"closure": {
"closed_at": "2025-01-16T10:30:00Z",
"reason": "completed|duplicate|wont-fix|invalid",
"final_comment": "功能实现完成，测试通过"
}
}
```

88
.claude/commands/workflow/review.md Normal file
View File

@@ -0,0 +1,88 @@
---
name: workflow-review
description: Execute review phase for quality validation
usage: /workflow:review [--auto-fix]
argument-hint: [optional: auto-fix identified issues]
examples:
- /workflow:review
- /workflow:review --auto-fix
---
# Workflow Review Command (/workflow:review)
## Overview
Final phase for quality validation, testing, and completion.
## Core Principles
**Session Management:** @~/.claude/workflows/session-management-principles.md
## Review Process
1. **Validation Checks**
- All tasks completed
- Tests passing
- Code quality metrics
- Documentation complete
2. **Generate Review Report**
```markdown
# Review Report
## Task Completion
- Total: 10
- Completed: 10
- Success Rate: 100%
## Quality Metrics
- Test Coverage: 85%
- Code Quality: A
- Documentation: Complete
## Issues Found
- Minor: 2
- Major: 0
- Critical: 0
```
3. **Update Session**
```json
{
"current_phase": "REVIEW",
"phases": {
"REVIEW": {
"status": "completed",
"output": "REVIEW.md",
"test_results": {
"passed": 45,
"failed": 0,
"coverage": 85
}
}
}
}
```
## Auto-fix Option
```bash
/workflow:review --auto-fix
```
- Automatically fixes minor issues
- Runs formatters and linters
- Updates documentation
- Re-runs tests
## Completion Criteria
- All tasks marked complete
- Tests passing (configurable threshold)
- No critical issues
- Documentation updated
## Output Files
- `REVIEW.md` - Review report
- `workflow-session.json` - Updated with results
- `test-results.json` - Detailed test output
## Related Commands
- `/workflow:implement` - Must complete first
- `/task:status` - Check task completion
- `/workflow:status` - View overall status

352
.claude/commands/workflow/session.md Normal file
View File

@@ -0,0 +1,352 @@
---
name: workflow-session
description: Workflow session management with multi-session registry support
usage: /workflow:session <start|pause|resume|list|switch|status> [complexity] ["task description"]
argument-hint: start|pause|resume|list|switch|status [simple|medium|complex] ["task description or session ID"]
examples:
- /workflow:session start complex "implement OAuth2 authentication"
- /workflow:session start simple "fix login bug"
- /workflow:session pause
- /workflow:session resume
- /workflow:session list
- /workflow:session switch WFS-oauth-integration
- /workflow:session status
---
# Workflow Session Management Commands
## Overview
Enhanced session management with multi-session registry support. Provides unified state tracking through `workflow-session.json` (individual sessions) and `session_status.jsonl` (lightweight registry).
## Core Principles
**Session Management:** @~/.claude/workflows/session-management-principles.md
## Session Registry System
### Multi-Session Management
The system maintains a lightweight registry (`.workflow/session_status.jsonl`) tracking all sessions:
```jsonl
{"id":"WFS-oauth-integration","status":"paused","description":"OAuth2 authentication implementation","created":"2025-09-07T10:00:00Z","directory":".workflow/WFS-oauth-integration"}
{"id":"WFS-user-profile","status":"active","description":"User profile feature","created":"2025-09-07T11:00:00Z","directory":".workflow/WFS-user-profile"}
{"id":"WFS-bug-fix-123","status":"completed","description":"Fix login timeout issue","created":"2025-09-06T14:00:00Z","directory":".workflow/WFS-bug-fix-123"}
```
### Registry Rules
- **Single Active Session**: Only one session can be active at a time
- **Automatic Registration**: New sessions auto-register on creation
- **Session Discovery**: Commands query registry to find active session
- **Context Inheritance**: Active session provides default context for all commands
## Commands
### Start Workflow Session (初始化)
```bash
/workflow:session start <complexity> "task description"
```
**Session Initialization Process:**
- **Replaces /workflow:init** - Initializes new workflow session
- Generates unique session ID (WFS-[topic-slug] format)
- **Registers in session registry** - Adds entry to `.workflow/session_status.jsonl`
- **Sets as active session** - Deactivates other sessions automatically
- Creates comprehensive directory structure
- Determines complexity (auto-detect if not specified)
- Sets initial phase based on complexity
**Directory Structure Creation:**
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json # Session state and metadata
├── IMPL_PLAN.md # Combined planning document (always created)
├── [.brainstorming/] # Optional brainstorming phase
├── [TODO_LIST.md] # Progress tracking (auto-triggered)
├── reports/ # Generated reports directory
└── .task/ # Task management directory
├── impl-*.json # Hierarchical task definitions
├── impl-*.*.json # Subtasks (up to 3 levels deep)
└── impl-*.*.*.json # Detailed subtasks
```
**File Generation Standards:**
- **workflow-session.json**: Core session state with comprehensive document tracking
- **IMPL_PLAN.md**: Initial planning document template (all complexity levels)
- **reports/ directory**: Created for future report generation by other workflow commands
- **.task/ directory**: Hierarchical task management system setup
- **Automatic backups**: Session state backups created during critical operations
**Phase Initialization:**
- **Simple**: Ready for direct IMPLEMENT (minimal documentation)
- **Medium/Complex**: Ready for PLAN phase (document generation enabled)
**Session State Setup:**
- Creates workflow-session.json with simplified document tracking
- Initializes hierarchical task management system (max 3 levels)
- Creates IMPL_PLAN.md for all complexity levels
- Auto-triggers TODO_LIST.md for Medium/Complex workflows
- **NOTE:** Does NOT execute workflow - only sets up infrastructure
**Next Steps After Initialization:**
- Use `/workflow:plan` to populate IMPL_PLAN.md (all workflows)
- Use `/workflow:implement` for task execution (all workflows)
- Use `/workflow:review` for validation phase
## File Generation and State Management
### Initial File Creation
When starting a new session, the following files are automatically generated:
#### workflow-session.json Structure
```json
{
"session_id": "WFS-[topic-slug]",
"created_at": "2025-09-07T14:00:00Z",
"type": "simple|medium|complex",
"description": "[user task description]",
"current_phase": "INIT",
"status": "active",
"phases": {
"INIT": {
"status": "completed",
"completed_at": "2025-09-07T14:00:00Z",
"files_created": ["IMPL_PLAN.md", "workflow-session.json"],
"directories_created": [".task", "reports"]
},
"BRAINSTORM": {
"status": "pending",
"enabled": false
},
"PLAN": {
"status": "pending",
"enabled": true
},
"IMPLEMENT": {
"status": "pending",
"enabled": true
},
"REVIEW": {
"status": "pending",
"enabled": true
}
},
"documents": {
"planning": {
"IMPL_PLAN.md": {
"status": "template_created",
"path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md",
"created_at": "2025-09-07T14:00:00Z",
"type": "planning_document"
}
}
},
"task_system": {
"enabled": true,
"max_depth": 3,
"task_count": 0,
"directory": ".task"
},
"registry": {
"registered_in": ".workflow/session_status.jsonl",
"active_session": true
}
}
```
#### Initial IMPL_PLAN.md Template
```markdown
# Implementation Plan
*Session: WFS-[topic-slug] | Created: 2025-09-07 14:00:00*
## Project Overview
- **Description**: [user task description]
- **Complexity**: [simple|medium|complex]
- **Estimated Effort**: [TBD]
- **Target Completion**: [TBD]
## Requirements Analysis
*To be populated by planning phase*
## Task Breakdown
*To be populated by planning phase*
## Implementation Strategy
*To be populated by planning phase*
## Success Criteria
*To be populated by planning phase*
---
*Template created by /workflow:session start*
*Use /workflow:plan to populate this document*
```
### Backup and Recovery System
#### Automatic Backup Creation
- **Trigger Events**: Session pause, critical state changes, error recovery
- **Backup Location**: `.workflow/WFS-[topic-slug]/.backups/`
- **Retention**: Last 5 backups per session
- **Format**: Timestamped JSON and markdown backups
#### Backup Structure
```
.workflow/WFS-[topic-slug]/.backups/
├── session-2025-09-07-14-00.json # Session state backup
├── session-2025-09-07-15-30.json
├── session-2025-09-07-16-45.json
├── IMPL_PLAN-2025-09-07-14-00.md # Document backups
└── TODO_LIST-2025-09-07-15-30.md
```
#### Recovery Operations
- **Auto-recovery**: On session corruption or inconsistency
- **Manual recovery**: Via `/workflow:session recover --from-backup`
- **Integrity checks**: Automatic validation on session load
### Session Registry Management
#### Session Status Registry (.workflow/session_status.jsonl)
```jsonl
{"id":"WFS-oauth-integration","status":"active","description":"OAuth2 authentication implementation","created":"2025-09-07T14:00:00Z","directory":".workflow/WFS-oauth-integration","complexity":"complex"}
```
#### Registry Operations
- **Registration**: Automatic on session creation
- **Status Updates**: Real-time status synchronization
- **Cleanup**: Automatic removal of completed sessions (optional)
- **Discovery**: Used by all workflow commands for session context
### Pause Workflow
```bash
/workflow:session pause
```
- Immediately saves complete session state
- Preserves context across all phases (conceptual/action/implementation)
- Sets status to "interrupted" with timestamp
- Shows resume instructions
- Maintains TodoWrite synchronization
### Resume Workflow
```bash
/workflow:session resume
```
- Detects current phase from workflow-session.json
- Loads appropriate agent context and state
- Continues from exact interruption point
- Maintains full context continuity
- Restores TodoWrite state
### List Sessions
```bash
/workflow:session list
```
- Displays all sessions from registry with status
- Shows session ID, status, description, and creation date
- Highlights currently active session
- Provides quick overview of all workflow sessions
### Switch Active Session
```bash
/workflow:session switch <session-id>
```
- Switches the active session to the specified session ID
- Automatically pauses the currently active session
- Updates registry to set new session as active
- Validates that target session exists and is valid
- Commands executed after switch will use new active session context
### Session Status
```bash
/workflow:session status
```
- Shows current active session details
- Displays session phase, progress, and document status
- Lists available sessions from registry
- Provides quick session health check
### Session State
Session state is tracked through two complementary systems:
#### Registry State (`.workflow/session_status.jsonl`)
Lightweight multi-session tracking:
```jsonl
{"id":"WFS-user-auth-system","status":"active","description":"OAuth2 authentication","created":"2025-09-07T10:30:00Z","directory":".workflow/WFS-user-auth-system"}
```
#### Individual Session State (`workflow-session.json`)
Detailed session state with document management:
```json
{
"session_id": "WFS-user-auth-system",
"project": "OAuth2 authentication",
"type": "complex",
"status": "active|paused|completed",
"current_phase": "PLAN|IMPLEMENT|REVIEW",
"created": "2025-09-05T10:30:00Z",
"directory": ".workflow/WFS-user-auth-system",
"documents": {
"IMPL_PLAN.md": {
"status": "generated",
"path": ".workflow/WFS-user-auth-system/IMPL_PLAN.md",
"last_updated": "2025-09-05T10:30:00Z"
},
"TODO_LIST.md": {
"status": "auto_triggered",
"path": ".workflow/WFS-user-auth-system/TODO_LIST.md",
"last_updated": "2025-09-05T11:20:00Z"
}
},
"task_system": {
"enabled": true,
"directory": ".workflow/WFS-user-auth-system/.task",
"next_main_task_id": 1,
"max_depth": 3,
"task_count": {
"total": 0,
"main_tasks": 0,
"subtasks": 0
}
}
}
```
To check status, use: `/workflow:status`
To mark complete: Simply finish all tasks and review phase
## Session State Management
### Session Responsibilities
- **Lifecycle Management**: Start, pause, resume sessions
- **State Persistence**: Save and restore workflow state
- **Phase Tracking**: Monitor current phase (PLAN/IMPLEMENT/REVIEW)
- **Context Preservation**: Maintain context across interruptions
### What Session Does NOT Do
- **No Execution**: Does not run agents or execute tasks
- **No Planning**: Does not generate planning documents
- **No Implementation**: Does not run code development
- **Execution Delegation**: All execution via appropriate phase commands:
- `/workflow:plan` - Planning execution
- `/workflow:implement` - Implementation execution
- `/workflow:review` - Review execution
## Automatic Checkpoints
@~/.claude/workflows/session-management-principles.md
Checkpoints created by phase commands:
- `/workflow:plan` creates checkpoints during planning
- `/workflow:implement` creates checkpoints after agents
- `/workflow:review` creates final validation checkpoint
- Session commands only manage checkpoint restoration
## Cross-Phase Context Preservation
- All phase outputs preserved in session
- Context automatically transferred between phases
- PRD documents bridge conceptual → action planning
- Implementation plans bridge action → implementation
- Full audit trail maintained for decisions
## State Validation
- Verify required artifacts exist for resumption
- Check file system consistency with session state
- Validate TodoWrite synchronization
- Ensure agent context completeness

311
.claude/commands/workflow/sync.md Normal file
View File

@@ -0,0 +1,311 @@
---
name: workflow-sync
description: Synchronize workflow documents and validate data integrity with comprehensive reporting
usage: /workflow:sync [--check] [--fix] [--force] [--export-report]
argument-hint: [optional: check-only, auto-fix, force, or export report]
examples:
- /workflow:sync
- /workflow:sync --check
- /workflow:sync --fix
- /workflow:sync --force
- /workflow:sync --export-report
---
# Workflow Sync Command (/workflow:sync)
## Overview
Ensures consistency between workflow-session.json, tasks.json, and related documents.
## Core Principles
**Dynamic Change Management:** @~/.claude/workflows/dynamic-change-management.md
## Sync Targets
### Primary Files
- `workflow-session.json` - Workflow state
- `tasks.json` - Task data
- `IMPL_PLAN.md` - Planning document
- `REVIEW.md` - Review results
### Validation Checks
- Session ID consistency
- Task ID references
- Progress calculations
- Status transitions
- Timestamp logic
## Usage Modes
### Default Mode
```bash
/workflow:sync
🔄 Workflow Synchronization
━━━━━━━━━━━━━━━━━━━━━
Checking consistency...
Issues found:
- Progress mismatch: 45% vs 60%
- Task IMPL-003 status differs
- 2 tasks missing from workflow
Fixing...
✅ Updated progress to 60%
✅ Synced IMPL-003 status
✅ Added missing tasks
Sync complete: 3 fixes applied
```
### Check Mode (--check)
```bash
/workflow:sync --check
```
- Read-only validation
- Reports issues without fixing
- Safe for production
### Fix Mode (--fix)
```bash
/workflow:sync --fix
```
- Auto-fixes safe issues
- Prompts for conflicts
- Creates backup first
### Force Mode (--force)
```bash
/workflow:sync --force
```
- Overwrites all conflicts
- No confirmation prompts
- Use with caution
## Sync Rules
### Data Authority
1. **workflow-session.json** - Highest (main state)
2. **tasks.json** - High (task details)
3. **Markdown files** - Medium (documentation)
4. **TodoWrite** - Low (temporary state)
### Conflict Resolution
- Recent changes win (timestamp)
- More complete data preferred
- User confirmation for ambiguous
### Auto-fix Scenarios
- Progress calculation errors
- Missing task references
- Invalid status transitions
## Report Generation
### Sync Report Export (--export-report)
When `--export-report` flag is used, generates comprehensive sync reports:
#### Generated Files
- **reports/SYNC_REPORT.md** - Detailed synchronization analysis
- **reports/sync-backups/** - Backup files created during sync
- **reports/sync-history/** - Historical sync reports
#### File Storage Structure
```
.workflow/WFS-[topic-slug]/reports/
├── SYNC_REPORT.md # Latest sync report
├── sync-backups/ # Pre-sync backups
│ ├── workflow-session-backup.json
│ ├── TODO_LIST-backup.md
│ └── IMPL_PLAN-backup.md
├── sync-history/ # Historical reports
│ ├── sync-2025-09-07-14-30.md
│ ├── sync-2025-09-07-15-45.md
│ └── sync-2025-09-07-16-15.md
└── sync-logs/ # Detailed sync logs
└── sync-operations.jsonl
```
### SYNC_REPORT.md Structure
```markdown
# Workflow Synchronization Report
*Generated: 2025-09-07 14:30:00*
## Sync Operation Summary
- **Operation Type**: Full Sync with Auto-fix
- **Duration**: 2.3 seconds
- **Files Processed**: 5
- **Issues Found**: 3
- **Issues Fixed**: 3
- **Backup Created**: Yes
## Pre-Sync State Analysis
### Document Integrity Check
- ✅ **workflow-session.json**: Valid JSON structure
- ⚠️ **TODO_LIST.md**: 3 completed tasks not marked
- ❌ **IMPL_PLAN.md**: Missing 2 task references
- ✅ **WORKFLOW_ISSUES.md**: Healthy
- ⚠️ **IMPLEMENTATION_LOG.md**: Timestamp inconsistency
### Data Consistency Analysis
- **Task References**: 85% consistent (missing 2 references)
- **Progress Tracking**: 78% accurate (3 items out of sync)
- **Cross-Document Links**: 92% valid (1 broken link)
## Synchronization Operations
### 1. Progress Calculation Fix
- **Issue**: Progress mismatch between JSON and markdown
- **Before**: workflow-session.json: 45%, TODO_LIST.md: 60%
- **Action**: Updated workflow-session.json progress to 60%
- **Result**: ✅ Progress synchronized
### 2. Task Reference Update
- **Issue**: Missing task references in IMPL_PLAN.md
- **Before**: 8 tasks in JSON, 6 tasks in IMPL_PLAN.md
- **Action**: Added IMPL-007 and IMPL-008 references
- **Result**: ✅ All tasks referenced
### 3. TodoWrite Status Sync
- **Issue**: 3 completed tasks not marked in checklist
- **Before**: TodoWrite showed completed, TODO_LIST.md showed pending
- **Action**: Updated TODO_LIST.md completion status
- **Result**: ✅ TodoWrite and documents synchronized
## Post-Sync State
### Document Health Status
- ✅ **workflow-session.json**: Healthy (100% consistent)
- ✅ **TODO_LIST.md**: Healthy (100% accurate)
- ✅ **IMPL_PLAN.md**: Healthy (all references valid)
- ✅ **WORKFLOW_ISSUES.md**: Healthy (no issues)
- ✅ **IMPLEMENTATION_LOG.md**: Healthy (timestamps corrected)
### Data Integrity Metrics
- **Task References**: 100% consistent
- **Progress Tracking**: 100% accurate
- **Cross-Document Links**: 100% valid
- **Timestamp Consistency**: 100% aligned
## Backup Information
### Created Backups
- **workflow-session-backup.json**: Original session state
- **TODO_LIST-backup.md**: Original task list
- **IMPL_PLAN-backup.md**: Original implementation plan
### Backup Location
```
.workflow/WFS-[topic-slug]/reports/sync-backups/2025-09-07-14-30/
```
## Recommendations
### Immediate Actions
- No immediate actions required
- All issues successfully resolved
### Preventive Measures
1. Consider running sync more frequently during active development
2. Enable auto-sync triggers for task completion events
3. Review document update procedures to maintain consistency
## Next Sync Recommendation
- **Frequency**: Every 2 hours during active development
- **Trigger Events**: After task completion, before major operations
- **Auto-fix**: Enabled for minor consistency issues
---
*Report generated by /workflow:sync --export-report*
```
### Session Updates
After sync operations, workflow-session.json is updated with sync metadata:
```json
{
"sync_history": [
{
"timestamp": "2025-09-07T14:30:00Z",
"type": "full_sync_with_autofix",
"duration_seconds": 2.3,
"issues_found": 3,
"issues_fixed": 3,
"backup_created": true,
"report_path": "reports/SYNC_REPORT.md"
}
],
"last_sync": {
"timestamp": "2025-09-07T14:30:00Z",
"status": "successful",
"integrity_score": 100
},
"documents": {
"reports": {
"SYNC_REPORT.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/reports/SYNC_REPORT.md",
"generated_at": "2025-09-07T14:30:00Z",
"type": "sync_report"
}
}
}
}
```
### Sync Operation Logging
All sync operations are logged in `sync-logs/sync-operations.jsonl`:
```jsonl
{"timestamp":"2025-09-07T14:30:00Z","operation":"progress_fix","before":{"session":45,"checklist":60},"after":{"session":60,"checklist":60},"status":"success"}
{"timestamp":"2025-09-07T14:30:01Z","operation":"task_reference_update","tasks_added":["IMPL-007","IMPL-008"],"status":"success"}
{"timestamp":"2025-09-07T14:30:02Z","operation":"todowrite_sync","tasks_updated":3,"status":"success"}
```
- Timestamp inconsistencies
## Example Outputs
### Success
```
✅ All documents in sync
- Files checked: 4
- Issues found: 0
- Last sync: 2 minutes ago
```
### With Issues
```
⚠️ Sync issues detected:
1. Progress: 45% (should be 60%)
2. Task IMPL-003: 'completed' vs 'active'
3. Missing: IMPL-005 not in workflow
Run with --fix to resolve
```
### After Fix
```
✅ Sync completed:
- Fixed: 3 issues
- Backup: .backup/sync-20250116
- Verified: All consistent
```
## Error Handling
### Common Errors
```bash
❌ workflow-session.json not found
→ Run: /workflow:init first
❌ tasks.json corrupted
→ Restoring from backup...
✅ Restored successfully
❌ Permission denied
→ Check file permissions
```
## Performance
- Incremental checks (fast)
- Cached validations
- Typical time: < 200ms
## Related Commands
- `/task:sync` - Task-specific sync
- `/workflow:status` - View current state
- `/task:status` - Task details