mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
Add session status file creation rule across workflow commands
Updates all workflow commands to create .workflow/session_status.jsonl if it doesn't exist when checking for active sessions. This ensures consistent behavior across: - gemini-chat.md: Added creation rule and updated workflow pseudocode - gemini-execute.md: Added session file creation requirement - gemini-mode.md: Updated session check process - workflow/action-plan.md: Updated both session check locations - task/replan.md: Added creation rule to session validation - task/breakdown.md: Updated session check process - workflow/brainstorm.md: Added creation rule to session registry query Also includes cleanup of deprecated command files (context.md, sync.md) and documentation updates for task creation complexity escalation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
344
.claude/commands/context.md
Normal file
344
.claude/commands/context.md
Normal file
@@ -0,0 +1,344 @@
|
||||
---
|
||||
name: context
|
||||
description: Unified context command - Single source of truth for all workflow and task status information
|
||||
usage: /context [task-id] [--format=<tree|list|json|progress>] [--health-check] [--detailed] [--export]
|
||||
argument-hint: [optional task-id] [display format] [analysis options] [export flag]
|
||||
examples:
|
||||
- /context
|
||||
- /context IMPL-001
|
||||
- /context --format=tree
|
||||
- /context --health-check
|
||||
- /context --detailed --export
|
||||
- /context --format=progress
|
||||
---
|
||||
|
||||
# Unified Context Command (/context)
|
||||
|
||||
## Overview
|
||||
|
||||
**Single Source of Truth**: This command replaces `/workflow:context` and `/task:context` with a unified interface that generates all views on-demand from JSON data. Eliminates synchronization complexity by making documents read-only views.
|
||||
|
||||
## Core Architecture
|
||||
|
||||
### Single Source of Truth Principle
|
||||
- **JSON Authority**: All data read from `.task/*.json` and `workflow-session.json` files
|
||||
- **Generated Views**: All markdown displays generated on-demand (never manually edited)
|
||||
- **No Synchronization**: Documents are views, not synchronized states
|
||||
- **Conflict-Free**: Single direction data flow eliminates conflicts
|
||||
|
||||
### Unified Command Interface
|
||||
- **Global Context**: `/context` shows complete workflow status
|
||||
- **Task-Specific**: `/context IMPL-001` shows individual task details
|
||||
- **Health Checking**: `/context --health-check` validates JSON data integrity
|
||||
- **Multiple Formats**: Tree, list, progress, and JSON output formats
|
||||
|
||||
## Usage Modes
|
||||
|
||||
### 1. Global Workflow Context (Default)
|
||||
```bash
|
||||
/context
|
||||
```
|
||||
|
||||
**Generated Output** (from JSON data):
|
||||
```
|
||||
🔍 Workflow Status Overview
|
||||
========================
|
||||
|
||||
📋 Session Information:
|
||||
- Session ID: WFS-workflow-optimization
|
||||
- Current Phase: IMPLEMENT
|
||||
- Complexity: complex
|
||||
- Start Time: 2025-09-07 14:30:22Z
|
||||
- Duration: 4h 15m
|
||||
|
||||
📊 Task Progress (from .task/*.json):
|
||||
✅ Completed: 2/5 (40%)
|
||||
🔄 In Progress: 1 task
|
||||
⏳ Pending: 2 tasks
|
||||
🚫 Blocked: 0 tasks
|
||||
|
||||
📁 JSON Data Health:
|
||||
✅ workflow-session.json - Valid JSON, complete data
|
||||
✅ .task/ directory - 5 task files, all valid JSON
|
||||
✅ Task relationships - All dependencies valid
|
||||
✅ Progress calculations - Mathematically consistent
|
||||
|
||||
⏱️ Estimated Completion: 2025-09-07 20:45 (2h 30m remaining)
|
||||
|
||||
🎯 Next Actions (generated from JSON state):
|
||||
1. Complete IMPL-003 (currently in progress)
|
||||
2. Begin IMPL-004 (dependencies satisfied)
|
||||
3. Review completed IMPL-001 and IMPL-002
|
||||
```
|
||||
|
||||
### 2. Task-Specific Context
|
||||
```bash
|
||||
/context IMPL-001
|
||||
```
|
||||
|
||||
**Generated Output** (from JSON file):
|
||||
```
|
||||
📋 Task Context: IMPL-001
|
||||
━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📄 JSON Source: .task/impl-001.json
|
||||
Status: completed (from JSON authority)
|
||||
Created: 2025-09-07T14:45:00Z
|
||||
Completed: 2025-09-07T16:30:00Z
|
||||
Duration: 1h 45m
|
||||
|
||||
🎯 Task Definition (from JSON):
|
||||
Title: Implement single source of truth architecture by removing sync commands
|
||||
Type: architecture
|
||||
Agent: code-developer
|
||||
Priority: critical
|
||||
|
||||
📋 Context (from JSON):
|
||||
Requirements:
|
||||
- Remove workflow:sync and task:sync commands
|
||||
- Update coordination system documentation
|
||||
- Establish JSON as single authority source
|
||||
Scope:
|
||||
- .claude/commands/workflow/sync.md
|
||||
- .claude/commands/task/sync.md
|
||||
- .claude/workflows/json-document-coordination-system.md
|
||||
|
||||
🔗 Dependencies (from JSON):
|
||||
Upstream: None
|
||||
Downstream: IMPL-002, IMPL-003
|
||||
Parent: None
|
||||
|
||||
✅ Completion Status (from JSON):
|
||||
Result: success
|
||||
Files Modified: 3 files moved to deprecated, 1 file updated
|
||||
Next Task: IMPL-002 ready to begin
|
||||
```
|
||||
|
||||
### 3. Health Check Mode
|
||||
```bash
|
||||
/context --health-check
|
||||
```
|
||||
|
||||
**Generated Analysis** (from JSON validation):
|
||||
```
|
||||
🏥 System Health Check (JSON Data Analysis)
|
||||
========================================
|
||||
|
||||
✅ JSON File Integrity:
|
||||
- workflow-session.json: ✅ Valid JSON, complete schema
|
||||
- .task/impl-001.json: ✅ Valid JSON, all required fields
|
||||
- .task/impl-002.json: ✅ Valid JSON, all required fields
|
||||
- .task/impl-003.json: ✅ Valid JSON, all required fields
|
||||
- .task/impl-004.json: ✅ Valid JSON, all required fields
|
||||
- .task/impl-005.json: ✅ Valid JSON, all required fields
|
||||
|
||||
🔗 Data Consistency Check:
|
||||
✅ Task IDs: All unique, follow impl-N format
|
||||
✅ Dependencies: All referenced tasks exist
|
||||
✅ Status Logic: All transitions valid
|
||||
✅ Progress Math: Calculations consistent
|
||||
✅ Timestamps: All valid, chronologically ordered
|
||||
|
||||
📊 Data Completeness:
|
||||
✅ All tasks have required fields
|
||||
✅ All tasks have context information
|
||||
✅ All dependencies properly defined
|
||||
✅ Session state complete
|
||||
|
||||
🎯 Overall System Health: 100% (Excellent)
|
||||
- Zero data conflicts (Single source of truth benefit)
|
||||
- All JSON files valid and consistent
|
||||
- No synchronization issues (eliminated by design)
|
||||
- Ready for continued execution
|
||||
```
|
||||
|
||||
### 4. Tree Format Display
|
||||
```bash
|
||||
/context --format=tree
|
||||
```
|
||||
|
||||
**Generated Tree** (from JSON hierarchy):
|
||||
```
|
||||
📁 WFS-workflow-optimization (from workflow-session.json)
|
||||
├── 📋 PLAN [Completed]
|
||||
│ └── Output: IMPL_PLAN.md, 5 tasks generated
|
||||
├── 🔨 IMPLEMENT [Active - 40% complete]
|
||||
│ ├── ✅ IMPL-001: Single source of truth architecture (completed)
|
||||
│ ├── ✅ IMPL-002: Automated planning-to-execution flow (completed)
|
||||
│ ├── 🔄 IMPL-003: Unified context commands (in_progress)
|
||||
│ ├── ⏳ IMPL-004: Dynamic complexity escalation (pending)
|
||||
│ └── ⏳ IMPL-005: Update session management (pending)
|
||||
└── 📝 REVIEW [Pending]
|
||||
└── Awaiting implementation completion
|
||||
```
|
||||
|
||||
### 5. Progress Format
|
||||
```bash
|
||||
/context --format=progress
|
||||
```
|
||||
|
||||
**Generated Progress View** (calculated from JSON data):
|
||||
```
|
||||
📊 Implementation Progress Report
|
||||
==============================
|
||||
|
||||
🎯 Overall Progress: 40% (2/5 tasks complete)
|
||||
|
||||
📈 Progress by Phase:
|
||||
┌─────────────┬─────────┬──────────┬─────────┐
|
||||
│ Phase │ Status │ Progress │ Tasks │
|
||||
├─────────────┼─────────┼──────────┼─────────┤
|
||||
│ PLAN │ ✅ │ 100% │ N/A │
|
||||
│ IMPLEMENT │ 🔄 │ 40% │ 2/5 │
|
||||
│ REVIEW │ ⏳ │ 0% │ 0/0 │
|
||||
└─────────────┴─────────┴──────────┴─────────┘
|
||||
|
||||
📋 Task Progress Details (from JSON files):
|
||||
✅ IMPL-001: single source of truth [100%] ⏱️ 1h 45m
|
||||
✅ IMPL-002: automated planning flow [100%] ⏱️ 2h 10m
|
||||
🔄 IMPL-003: unified context commands [75%] ⏱️ 1h 30m (in progress)
|
||||
⏳ IMPL-004: dynamic complexity [0%] ⏱️ 2h 00m (estimated)
|
||||
⏳ IMPL-005: session management updates [0%] ⏱️ 1h 15m (estimated)
|
||||
|
||||
⏰ Time Analysis (calculated from JSON):
|
||||
Time Spent: 5h 25m
|
||||
Remaining: 2h 45m
|
||||
Estimated Total: 8h 10m
|
||||
Completion: 2025-09-07 21:15
|
||||
```
|
||||
|
||||
## File Export Feature
|
||||
|
||||
### Export Generated Views
|
||||
```bash
|
||||
/context --export
|
||||
```
|
||||
|
||||
**Generated Files** (all from JSON data):
|
||||
```
|
||||
.workflow/WFS-workflow-optimization/reports/
|
||||
├── CONTEXT_REPORT.md # Current context view
|
||||
├── PROGRESS_REPORT.md # Progress analysis
|
||||
├── HEALTH_CHECK.md # System health status
|
||||
└── context-exports/ # Historical exports
|
||||
├── context-2025-09-07-14-30.md
|
||||
├── progress-2025-09-07-15-45.md
|
||||
└── health-2025-09-07-16-15.md
|
||||
```
|
||||
|
||||
**Report Structure** (generated from JSON):
|
||||
```markdown
|
||||
# Workflow Context Report
|
||||
*Generated: 2025-09-07 16:15:00 from JSON data sources*
|
||||
|
||||
## Data Sources
|
||||
- workflow-session.json (last updated: 2025-09-07T15:45:00Z)
|
||||
- 5 task JSON files in .task/ directory
|
||||
- All sources validated and consistent
|
||||
|
||||
## Session Overview
|
||||
[Generated from workflow-session.json]
|
||||
|
||||
## Task Analysis
|
||||
[Generated from .task/*.json files]
|
||||
|
||||
## Health Assessment
|
||||
[Validated from JSON data integrity]
|
||||
|
||||
---
|
||||
*This report is a generated view from authoritative JSON data*
|
||||
*No manual editing required - data updates automatically in JSON files*
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### JSON Output for Scripting
|
||||
```bash
|
||||
/context --format=json
|
||||
```
|
||||
|
||||
**Generated JSON** (compiled from all sources):
|
||||
```json
|
||||
{
|
||||
"session": {
|
||||
"id": "WFS-workflow-optimization",
|
||||
"status": "active",
|
||||
"phase": "implement",
|
||||
"progress": 40,
|
||||
"data_source": "workflow-session.json"
|
||||
},
|
||||
"tasks": [
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"status": "completed",
|
||||
"progress": 100,
|
||||
"data_source": ".task/impl-001.json"
|
||||
}
|
||||
],
|
||||
"health": {
|
||||
"json_integrity": 100,
|
||||
"data_consistency": 100,
|
||||
"completeness": 100
|
||||
},
|
||||
"generated_at": "2025-09-07T16:15:00Z",
|
||||
"data_freshness": "current"
|
||||
}
|
||||
```
|
||||
|
||||
### Health Check Integration
|
||||
- **Validation Engine**: Checks all JSON files for schema compliance
|
||||
- **Consistency Verification**: Validates cross-references between files
|
||||
- **Data Integrity**: Ensures all dependencies and relationships are valid
|
||||
- **Performance Monitoring**: Tracks data loading and generation speed
|
||||
|
||||
## Benefits of Unified Architecture
|
||||
|
||||
### Eliminated Complexity
|
||||
- **No Sync Commands**: Removed `/workflow:sync` and `/task:sync`
|
||||
- **No Conflicts**: Single source eliminates data drift
|
||||
- **No Manual Document Editing**: All documents are generated views
|
||||
- **Simplified User Experience**: One command for all context needs
|
||||
|
||||
### Enhanced Reliability
|
||||
- **Data Consistency**: JSON authority ensures consistent state
|
||||
- **Error Reduction**: No synchronization bugs or conflicts
|
||||
- **Simplified Recovery**: Only JSON files need backup/restore
|
||||
- **Predictable Behavior**: Views always reflect current JSON state
|
||||
|
||||
### Improved Performance
|
||||
- **On-Demand Generation**: Views created only when requested
|
||||
- **Efficient Data Access**: Direct JSON file reading
|
||||
- **No Background Sync**: No overhead from synchronization processes
|
||||
- **Cached Calculations**: Smart caching for expensive operations
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Data Flow Architecture
|
||||
```
|
||||
JSON Files (.task/*.json + workflow-session.json)
|
||||
↓ (Single Direction - Read Only)
|
||||
View Generation Engine
|
||||
↓
|
||||
Formatted Output (Console/File)
|
||||
```
|
||||
|
||||
### View Generation Process
|
||||
1. **Load JSON Data**: Read all relevant JSON files
|
||||
2. **Validate Data**: Check integrity and consistency
|
||||
3. **Calculate Views**: Generate requested format/content
|
||||
4. **Format Output**: Apply formatting and display
|
||||
5. **Export (Optional)**: Save generated views to files
|
||||
|
||||
### Error Handling
|
||||
- **Missing Files**: Clear error messages with recovery suggestions
|
||||
- **Invalid JSON**: Schema validation with specific error details
|
||||
- **Broken References**: Dependency validation with repair recommendations
|
||||
- **Data Inconsistencies**: Automatic detection and resolution suggestions
|
||||
|
||||
|
||||
### Data Management
|
||||
- All commands now work with JSON as single source of truth
|
||||
- Document generation happens on-demand
|
||||
- No synchronization commands needed
|
||||
- Simplified data model improves reliability
|
||||
|
||||
@@ -131,7 +131,7 @@ END FUNCTION
|
||||
|
||||
- **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.
|
||||
- **Session Check**: Query `.workflow/session_status.jsonl` to identify current active session. If the file doesn't exist, create it.
|
||||
- **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
|
||||
@@ -146,7 +146,11 @@ END FUNCTION
|
||||
**Session Detection Workflow:**
|
||||
```pseudo
|
||||
FUNCTION determine_save_location():
|
||||
// STEP 1: Check for existing active session
|
||||
// STEP 1: Ensure session status file exists
|
||||
IF NOT file_exists(".workflow/session_status.jsonl"):
|
||||
create_empty_session_registry(".workflow/session_status.jsonl")
|
||||
|
||||
// STEP 2: Check for existing active session
|
||||
active_sessions = query_session_registry(".workflow/session_status.jsonl")
|
||||
|
||||
IF active_sessions.count > 0:
|
||||
|
||||
@@ -192,7 +192,7 @@ This template is automatically filled and generated after execution.
|
||||
|
||||
- **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.
|
||||
- **Session Check**: Query `.workflow/session_status.jsonl` to identify current active session. If the file doesn't exist, create it.
|
||||
- **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
|
||||
|
||||
@@ -128,7 +128,7 @@ END FUNCTION
|
||||
⚠️ **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
|
||||
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it.
|
||||
2. **Context Integration**: Use existing active session for proper analysis context
|
||||
3. **Documentation Strategy**: Store analysis results in appropriate session directory structure
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Intelligently breaks down complex tasks into manageable subtasks with automatic
|
||||
⚠️ **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
|
||||
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it.
|
||||
2. **Session Validation**: Use existing active session containing the parent task
|
||||
3. **Context Integration**: Load existing session state and task hierarchy
|
||||
|
||||
|
||||
@@ -1,349 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -30,6 +30,7 @@ Creates new implementation tasks during IMPLEMENT phase with automatic context a
|
||||
- **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
|
||||
- **Dynamic Complexity Escalation**: Automatically upgrades workflow complexity when thresholds are exceeded
|
||||
|
||||
### Context Awareness
|
||||
- Detects current workflow phase (must be IMPLEMENT)
|
||||
@@ -165,6 +166,127 @@ TODO_LIST.md auto-generation conditions:
|
||||
- workflow-session.json maintains task list with hierarchy depth
|
||||
- Automatic validation of cross-file references
|
||||
|
||||
## Dynamic Complexity Escalation (NEW FEATURE)
|
||||
|
||||
### Automatic Workflow Upgrade System
|
||||
After each task creation, the system automatically evaluates current workflow complexity and upgrades structure when thresholds are exceeded.
|
||||
|
||||
### Escalation Process
|
||||
```
|
||||
1. Create New Task → Generate JSON file
|
||||
2. Count All Tasks → Read all .task/*.json files
|
||||
3. Calculate Metrics → Tasks, modules, dependencies, effort
|
||||
4. Check Thresholds → Compare against complexity criteria
|
||||
5. Trigger Upgrade → If threshold exceeded, escalate complexity
|
||||
6. Generate Documents → Auto-create missing structure documents
|
||||
7. Update Session → Record complexity change in workflow-session.json
|
||||
8. Notify User → Inform about automatic upgrade
|
||||
```
|
||||
|
||||
### Escalation Triggers
|
||||
|
||||
#### Simple → Medium Escalation
|
||||
**Triggered when ANY condition met:**
|
||||
- Task count reaches 5 (primary trigger)
|
||||
- Module count exceeds 3
|
||||
- Total estimated effort > 4 hours
|
||||
- Complex dependencies detected
|
||||
- Cross-component changes required
|
||||
|
||||
**Actions taken:**
|
||||
```bash
|
||||
✅ Task created: impl-5
|
||||
⚠️ Complexity threshold reached: 5 tasks (exceeds Simple limit)
|
||||
🔄 Escalating workflow: Simple → Medium
|
||||
|
||||
Auto-generating enhanced structure:
|
||||
✅ Created TODO_LIST.md with hierarchical task display
|
||||
✅ Created .summaries/ directory for task completion tracking
|
||||
✅ Updated workflow-session.json complexity level
|
||||
✅ Enabled 2-level task hierarchy (impl-N.M)
|
||||
|
||||
Workflow now supports:
|
||||
- Progress tracking via TODO_LIST.md
|
||||
- Task decomposition up to 2 levels
|
||||
- Summary generation for completed tasks
|
||||
```
|
||||
|
||||
#### Medium → Complex Escalation
|
||||
**Triggered when ANY condition met:**
|
||||
- Task count reaches 15 (primary trigger)
|
||||
- Module count exceeds 5
|
||||
- Total estimated effort > 2 days
|
||||
- Multi-repository impacts detected
|
||||
- Architecture pattern changes required
|
||||
|
||||
**Actions taken:**
|
||||
```bash
|
||||
✅ Task created: impl-15
|
||||
⚠️ Complexity threshold reached: 15 tasks (exceeds Medium limit)
|
||||
🔄 Escalating workflow: Medium → Complex
|
||||
|
||||
Auto-generating comprehensive structure:
|
||||
✅ Enhanced IMPL_PLAN.md with detailed phases and risk assessment
|
||||
✅ Expanded TODO_LIST.md with progress monitoring
|
||||
✅ Created comprehensive .summaries/ structure
|
||||
✅ Updated workflow-session.json complexity level
|
||||
✅ Enabled 3-level task hierarchy (impl-N.M.P maximum)
|
||||
|
||||
Workflow now supports:
|
||||
- Comprehensive progress tracking and monitoring
|
||||
- Full 3-level task decomposition
|
||||
- Enhanced documentation and audit trails
|
||||
- Advanced dependency management
|
||||
```
|
||||
|
||||
### Complexity Calculation Algorithm
|
||||
```javascript
|
||||
function calculateComplexity(tasks, modules, effort, dependencies) {
|
||||
// Primary thresholds (hard limits)
|
||||
if (tasks >= 15 || modules > 5 || effort > 48) return 'complex';
|
||||
if (tasks >= 5 || modules > 3 || effort > 4) return 'medium';
|
||||
|
||||
// Override factors (can force higher complexity)
|
||||
if (dependencies.includes('multi-repo') ||
|
||||
dependencies.includes('architecture-change')) return 'complex';
|
||||
if (dependencies.includes('cross-component') ||
|
||||
dependencies.includes('complex-integration')) return 'medium';
|
||||
|
||||
return 'simple';
|
||||
}
|
||||
```
|
||||
|
||||
### Session State Updates During Escalation
|
||||
```json
|
||||
{
|
||||
"complexity": "medium",
|
||||
"escalation_history": [
|
||||
{
|
||||
"from": "simple",
|
||||
"to": "medium",
|
||||
"triggered_at": "2025-09-07T16:45:00Z",
|
||||
"trigger_reason": "task_count_threshold",
|
||||
"task_count_at_escalation": 5,
|
||||
"auto_generated_documents": ["TODO_LIST.md", ".summaries/"],
|
||||
"task_hierarchy_enabled": 2
|
||||
}
|
||||
],
|
||||
"task_system": {
|
||||
"max_depth": 2,
|
||||
"structure_level": "enhanced",
|
||||
"documents_generated": ["TODO_LIST.md"],
|
||||
"auto_escalation_enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Benefits of Dynamic Escalation
|
||||
- **Seamless Growth**: Workflows grow naturally without user intervention
|
||||
- **No Overhead for Simple Tasks**: Simple workflows remain minimal
|
||||
- **Automatic Structure**: Enhanced documentation appears when needed
|
||||
- **Progressive Enhancement**: Users get appropriate tooling for current complexity
|
||||
- **Transparent Process**: All escalations logged and reversible
|
||||
|
||||
## Context Inheritance
|
||||
|
||||
Tasks automatically inherit:
|
||||
|
||||
@@ -23,7 +23,7 @@ Dynamically adjusts task planning based on changes, new requirements, blockers,
|
||||
⚠️ **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
|
||||
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it.
|
||||
2. **Session Validation**: Use existing active session containing the task to be replanned
|
||||
3. **Context Integration**: Load existing session state and task hierarchy
|
||||
|
||||
|
||||
@@ -1,280 +0,0 @@
|
||||
---
|
||||
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
|
||||
@@ -40,7 +40,7 @@ Creates actionable implementation plans based on brainstorming insights or direc
|
||||
⚠️ **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
|
||||
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it.
|
||||
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
|
||||
|
||||
@@ -67,7 +67,7 @@ Creates actionable implementation plans based on brainstorming insights or direc
|
||||
|
||||
### Phase 1: Context Understanding & Structure Establishment
|
||||
1. **Session Detection & Selection**:
|
||||
- **Check Active Sessions**: Query `.workflow/session_status.jsonl` for existing active sessions
|
||||
- **Check Active Sessions**: Query `.workflow/session_status.jsonl` for existing active sessions. If the file doesn't exist, create it.
|
||||
- **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
|
||||
@@ -104,9 +104,70 @@ Creates actionable implementation plans based on brainstorming insights or direc
|
||||
- **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
|
||||
8. **Auto-Generate Tasks (NEW)**: Parse IMPL_PLAN.md and automatically create corresponding task JSON files
|
||||
- **Extract Tasks**: Parse task identifiers (IMPL-001, IMPL-002, etc.) from plan
|
||||
- **Create Task Files**: Generate `.task/impl-*.json` files with plan context
|
||||
- **Link to Plan**: Include `source_plan_ref` field linking tasks back to plan sections
|
||||
- **Set Dependencies**: Establish task dependencies based on plan structure
|
||||
|
||||
9. **Link Documents**: Update JSON state with generated document paths
|
||||
9. **Update Session**: Mark PLAN phase complete with document references and generated task list
|
||||
|
||||
10. **Link Documents**: Update JSON state with generated document paths and task file references
|
||||
|
||||
## Automated Task Generation (Single Source of Truth Integration)
|
||||
|
||||
### Planning-to-Execution Automation
|
||||
**NEW FEATURE**: Eliminates the gap between planning and execution by automatically creating executable task files from planning documents.
|
||||
|
||||
### Task Extraction Process
|
||||
1. **Parse IMPL_PLAN.md**: Scan for task identifiers in standardized format:
|
||||
- `IMPL-001`, `IMPL-002`, etc. (main tasks)
|
||||
- `IMPL-1.1`, `IMPL-1.2`, etc. (subtasks)
|
||||
- Task titles and descriptions from plan sections
|
||||
|
||||
2. **Generate Task JSON Files**: For each identified task, create structured JSON:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Foundation/Infrastructure setup",
|
||||
"status": "pending",
|
||||
"type": "infrastructure",
|
||||
"agent": "code-developer",
|
||||
"effort": "2h",
|
||||
|
||||
"context": {
|
||||
"inherited_from": "WFS-[topic-slug]",
|
||||
"source_plan_ref": "IMPL_PLAN.md#phase-1-foundation",
|
||||
"requirements": ["Extracted from plan description"],
|
||||
"scope": ["Derived from plan context"],
|
||||
"acceptance": ["Extracted from success criteria"]
|
||||
},
|
||||
|
||||
"dependencies": {
|
||||
"upstream": [],
|
||||
"downstream": ["IMPL-002"],
|
||||
"phase_group": "Phase 1: Foundation"
|
||||
},
|
||||
|
||||
"metadata": {
|
||||
"created_at": "2025-09-07T15:00:00Z",
|
||||
"created_by": "workflow:action-plan",
|
||||
"auto_generated": true,
|
||||
"plan_version": "1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Link Bidirectionally**:
|
||||
- Task files reference plan sections
|
||||
- Session state includes all generated task IDs
|
||||
- Ready for immediate execution via `/task:execute`
|
||||
|
||||
### Benefits of Automation
|
||||
- **Zero Manual Task Creation**: Plans immediately become executable
|
||||
- **Consistency**: All tasks derive from same authoritative plan
|
||||
- **Traceability**: Clear linkage from requirements through plan to tasks
|
||||
- **Immediate Execution**: Can run `/task:execute IMPL-001` immediately after planning
|
||||
|
||||
## Session State Analysis & Document Understanding
|
||||
|
||||
@@ -269,27 +330,42 @@ Generated documents are stored in session directory:
|
||||
└── workflow-session.json # Updated with document references
|
||||
```
|
||||
|
||||
## Session Updates
|
||||
## Session Updates (Enhanced with Task Generation)
|
||||
```json
|
||||
{
|
||||
"phases": {
|
||||
"PLAN": {
|
||||
"status": "completed",
|
||||
"output": {
|
||||
"primary": "IMPL_PLAN.md"
|
||||
"primary": "IMPL_PLAN.md",
|
||||
"tasks_generated": [".task/impl-001.json", ".task/impl-002.json", ".task/impl-003.json"]
|
||||
},
|
||||
"documents_generated": ["IMPL_PLAN.md"],
|
||||
"tasks_auto_created": 3,
|
||||
"completed_at": "2025-09-05T11:00:00Z",
|
||||
"tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"]
|
||||
"tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"],
|
||||
"ready_for_implementation": true
|
||||
}
|
||||
},
|
||||
"documents": {
|
||||
"planning": {
|
||||
"IMPL_PLAN.md": {
|
||||
"status": "generated",
|
||||
"path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md"
|
||||
"path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md",
|
||||
"tasks_extracted": 3,
|
||||
"auto_generation": "completed"
|
||||
}
|
||||
}
|
||||
},
|
||||
"task_system": {
|
||||
"enabled": true,
|
||||
"auto_generated": true,
|
||||
"directory": ".workflow/WFS-[topic-slug]/.task/",
|
||||
"task_count": {
|
||||
"total": 3,
|
||||
"pending": 3,
|
||||
"from_planning": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -109,7 +109,7 @@ END FUNCTION
|
||||
⚠️ **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
|
||||
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it.
|
||||
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
|
||||
|
||||
|
||||
@@ -1,398 +0,0 @@
|
||||
---
|
||||
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
|
||||
@@ -179,24 +179,6 @@ When starting a new session, the following files are automatically generated:
|
||||
*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`
|
||||
|
||||
@@ -1,311 +0,0 @@
|
||||
---
|
||||
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
|
||||
@@ -61,8 +61,8 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
|
||||
* **观察到的行为 (Observed Behavior):** [清晰、客观地转述用户报告的异常现象或日志中的错误信息。]
|
||||
* **预期的行为 (Expected Behavior):** [描述在正常情况下，系统或功能应有的表现。]
|
||||
* **1.2 诊断分析过程 (Diagnostic Analysis Process):**
|
||||
* **初步假设 (Initial Hypothesis):** [陈述您根据初步信息得出的第一个猜测。例如：“初步判断，问题可能出在数据解析环节，因为错误日志显示了‘格式不匹配’。”]
|
||||
* **根本原因分析 (Root Cause Analysis - RCA):** [**这是报告的核心。** 详细阐述您的逻辑推理过程，说明您是如何从表象追踪到根源的。例如：“通过检查 `data_parser.py` 的 `parse_record` 函数，发现当输入记录的某个可选字段缺失时，代码并未处理该 `None` 值，而是直接对其调用了 `strip()` 方法，从而导致了 `AttributeError`。因此，**根本原因**是：**对可能为 None 的变量在未进行空值检查的情况下直接调用了方法**。”]
|
||||
* **初步假设 (Initial Hypothesis):** [陈述您根据初步信息得出的第一个猜测。例如：初步判断，问题可能出在数据解析环节，因为错误日志显示了格式不匹配。]
|
||||
* **根本原因分析 (Root Cause Analysis - RCA):** [**这是报告的核心。** 详细阐述您的逻辑推理过程，说明您是如何从表象追踪到根源的。例如：通过检查 `data_parser.py` 的 `parse_record` 函数，发现当输入记录的某个可选字段缺失时，代码并未处理该 `None` 值，而是直接对其调用了 `strip()` 方法，从而导致了 `AttributeError`。因此，**根本原因**是：**对可能为 None 的变量在未进行空值检查的情况下直接调用了方法**。]
|
||||
* **1.3 根本原因摘要 (Root Cause Summary):** [用一句话高度概括 bug 的根本原因。]
|
||||
|
||||
### **第二部分：涉及文件概览 (Part 2: Involved Files Overview)**
|
||||
@@ -86,7 +86,7 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
|
||||
|
||||
* **3. 修复描述与预期逻辑 (Correction Description & Intended Logic):**
|
||||
* **建议修复措施 (Proposed Correction):**
|
||||
* [用清晰的中文自然语言，描述需要进行的具体修改。例如：“在调用 `.strip()` 方法之前，增加一个条件判断，检查 `value` 变量是否不为 `None`。”]
|
||||
* [用清晰的中文自然语言，描述需要进行的具体修改。例如：在调用 `.strip()` 方法之前，增加一个条件判断，检查 `value` 变量是否不为 `None`。]
|
||||
* **修复后逻辑示意 (Corrected Logic Sketch):**
|
||||
* [使用简洁的 `diff` 风格或伪代码来直观展示修改。]
|
||||
* **示例:**
|
||||
@@ -104,11 +104,11 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
|
||||
END IF
|
||||
... (后续逻辑使用 processed_value) ...
|
||||
```
|
||||
* **修复理由 (Reason for Correction):** [解释为什么这个修改能解决之前分析出的**根本原因**。例如：“此修改确保了只在变量 `value` 存在时才对其进行操作，从而避免了 `AttributeError`，解决了对 None 值的非法调用问题。”]
|
||||
* **修复理由 (Reason for Correction):** [解释为什么这个修改能解决之前分析出的**根本原因**。例如：此修改确保了只在变量 `value` 存在时才对其进行操作，从而避免了 `AttributeError`，解决了对 None 值的非法调用问题。]
|
||||
|
||||
* **4. 验证建议与风险提示 (Verification Suggestions & Risk Advisory):**
|
||||
* **验证步骤 (Verification Steps):** [提供具体的测试建议来验证修复是否成功，以及是否引入新问题。例如：“1. 构造一个‘optional_field’字段存在的测试用例，确认其能被正常处理。2. **构造一个‘optional_field’字段缺失的测试用例，确认程序不再崩溃，且 `processed_value` 为 `None` 或默认值。**”]
|
||||
* **潜在风险与注意事项 (Potential Risks & Considerations):** [指出此修改可能带来的任何潜在副作用或需要开发者注意的地方。例如：“请注意，下游消费 `processed_value` 的代码现在必须能够正确处理 `None` 值。请检查相关调用方是否已做相应处理。”]
|
||||
* **验证步骤 (Verification Steps):** [提供具体的测试建议来验证修复是否成功，以及是否引入新问题。例如：1. 构造一个optional_field字段存在的测试用例，确认其能被正常处理。2. **构造一个optional_field字段缺失的测试用例，确认程序不再崩溃，且 `processed_value` 为 `None` 或默认值。**]
|
||||
* **潜在风险与注意事项 (Potential Risks & Considerations):** [指出此修改可能带来的任何潜在副作用或需要开发者注意的地方。例如：请注意，下游消费 `processed_value` 的代码现在必须能够正确处理 `None` 值。请检查相关调用方是否已做相应处理。]
|
||||
|
||||
---
|
||||
*(对每个需要修改的文件重复上述格式)*
|
||||
|
||||
@@ -57,7 +57,7 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
|
||||
### **代码修改规划方案 (Code Modification Plan)**
|
||||
|
||||
### **第一部分：需求分析与规划总览 (Part 1: Requirements Analysis & Planning Overview)**
|
||||
* **1.1 用户原始需求结构化解析 (Structured Analysis of User's Original Requirements):**
|
||||
* **1.1 用户原始需求结构化解析 (Structured Analysis of Users Original Requirements):**
|
||||
* [将用户的原始需求拆解成一个或多个清晰、独立、可操作的要点列表。每个要点都是一个明确的目标。]
|
||||
* **- 需求点 A:** [描述第一个具体需求]
|
||||
* **- 需求点 B:** [描述第二个具体需求]
|
||||
@@ -78,7 +78,7 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
|
||||
* [清晰说明函数、类、方法或具体的代码区域，如果可能，指出大致行号范围。示例: 函数 `calculate_total_price` 内部，约第 75-80 行]
|
||||
|
||||
* **1.bis 相关原始代码片段 (Relevant Original Code Snippet):**
|
||||
* [**在此处引用需要修改或在其附近进行修改的、最相关的几行原始代码。** 这为开发者提供了直接的上下文。如果代码未提供，则注明“相关代码未提供，根据描述进行规划。]
|
||||
* [**在此处引用需要修改或在其附近进行修改的、最相关的几行原始代码。** 这为开发者提供了直接的上下文。如果代码未提供，则注明相关代码未提供，根据描述进行规划。]
|
||||
* ```[language]
|
||||
// 引用相关的1-5行原始代码
|
||||
```
|
||||
@@ -109,16 +109,16 @@ Your response **MUST** be in Chinese and structured in Markdown as follows:
|
||||
## VII. KEY DIRECTIVES & CONSTRAINTS
|
||||
1. **Language**: **All** descriptive parts of your plan **MUST** be in **Chinese**.
|
||||
2. **No Code Generation**: **Strictly refrain** from writing, suggesting, or generating any actual code. Your output is *purely* a descriptive modification plan.
|
||||
3. **Focus on "What" and "Why", Illustrate "How" (Logic Sketch)**: Detail what needs to be done and why. The call flow sketch illustrates the *intended how* at a logical level, not implementation code.
|
||||
4. **Completeness & Accuracy**: Ensure the plan is comprehensive. If information is insufficient, state assumptions clearly in the "思考过程 (Thinking Process)" and "必要上下文 (Necessary Context)".
|
||||
3. **Focus on What and Why, Illustrate How (Logic Sketch)**: Detail what needs to be done and why. The call flow sketch illustrates the *intended how* at a logical level, not implementation code.
|
||||
4. **Completeness & Accuracy**: Ensure the plan is comprehensive. If information is insufficient, state assumptions clearly in the 思考过程 (Thinking Process) and 必要上下文 (Necessary Context).
|
||||
5. **Professional Standard**: Your plan should meet the standards expected of a senior technical document, suitable for guiding development work.
|
||||
|
||||
## VIII. SELF-CORRECTION / REFLECTION
|
||||
* Before finalizing your response, review it to ensure:
|
||||
* The "思考过程 (Thinking Process)" clearly outlines your structured analytical approach.
|
||||
* All user requirements from "需求分析" have been addressed in the plan.
|
||||
* The 思考过程 (Thinking Process) clearly outlines your structured analytical approach.
|
||||
* All user requirements from 需求分析 have been addressed in the plan.
|
||||
* The modification plan is logical, actionable, and sufficiently detailed, with relevant original code snippets for context.
|
||||
* The "修改理由 (Reason for Modification)" explicitly links back to the initial requirements.
|
||||
* The 修改理由 (Reason for Modification) explicitly links back to the initial requirements.
|
||||
* All crucial context and risks are highlighted.
|
||||
* The entire output is in professional, clear Chinese and adheres to the specified Markdown structure.
|
||||
* You have strictly avoided generating any code.
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
# JSON-Document Coordination System
|
||||
# JSON-Document Coordination System (Single Source of Truth)
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides technical implementation details for JSON file structures, synchronization mechanisms, conflict resolution, and performance optimization.
|
||||
This document defines the **Single Source of Truth** architecture where JSON files are the authoritative state source and all markdown documents are read-only, generated views. This eliminates bidirectional synchronization complexity and data conflicts.
|
||||
|
||||
**Key Principle**: `.task/*.json` files are the **only** authoritative source of task state. All markdown documents (`TODO_LIST.md`, progress displays, etc.) are generated on-demand from JSON data.
|
||||
|
||||
### JSON File Hierarchy
|
||||
```
|
||||
@@ -184,23 +186,13 @@ TODO_LIST.md serves as both the task registry and progress display:
|
||||
}
|
||||
```
|
||||
|
||||
## Coordination Mechanisms
|
||||
## Single Source of Truth Architecture
|
||||
|
||||
### 1. Data Ownership Rules
|
||||
### 1. Data Authority (Simplified)
|
||||
|
||||
#### Documents Own (Authoritative)
|
||||
**IMPL_PLAN.md:**
|
||||
- **Implementation Strategy**: Overall approach, phases, risk assessment
|
||||
- **Requirements**: High-level functional requirements
|
||||
- **Context**: Global project context, constraints
|
||||
|
||||
**TODO_LIST.md:**
|
||||
- **Progress Visualization**: Task status display, completion tracking
|
||||
- **Checklist Format**: Checkbox representation of task hierarchy
|
||||
|
||||
#### JSON Files Own (Authoritative)
|
||||
- **Complete Task Definitions**: Full task context, requirements, acceptance criteria
|
||||
- **Hierarchical Relationships**: Parent-child links, depth management
|
||||
#### JSON Files Own (ONLY Authoritative Source)
|
||||
- **ALL Task State**: Complete task definitions, status, progress, metadata
|
||||
- **Hierarchical Relationships**: Parent-child links, depth management
|
||||
- **Execution State**: pending/active/completed/blocked/failed
|
||||
- **Progress Data**: Percentages, timing, checkpoints
|
||||
- **Agent Assignment**: Current agent, execution history
|
||||
@@ -208,154 +200,95 @@ TODO_LIST.md serves as both the task registry and progress display:
|
||||
- **Session Metadata**: Timestamps, versions, attempt counts
|
||||
- **Runtime State**: Current attempt, active processes
|
||||
|
||||
#### Shared Responsibility (Synchronized)
|
||||
- **Task Status**: JSON authoritative, TODO_LIST.md displays current state
|
||||
- **Progress Calculations**: Derived from JSON hierarchy, shown in TODO_LIST.md
|
||||
- **Cross-References**: JSON contains document refs, documents link to relevant tasks
|
||||
- **Task Hierarchy**: JSON defines structure, TODO_LIST.md visualizes it
|
||||
#### Documents Are Read-Only Views (Generated Only)
|
||||
- **IMPL_PLAN.md**: Static planning document (manually created, rarely changes)
|
||||
- **TODO_LIST.md**: **Generated view** from JSON files (never manually edited)
|
||||
- **Progress Reports**: **Generated views** from JSON data
|
||||
- **Status Displays**: **Generated views** from JSON state
|
||||
|
||||
### 2. Synchronization Events
|
||||
#### No Shared Responsibility (Eliminates Conflicts)
|
||||
- **Single Direction Flow**: JSON → Markdown (never Markdown → JSON)
|
||||
- **No Synchronization**: Documents are generated, not synchronized
|
||||
- **No Conflicts**: Only one source of truth eliminates data conflicts
|
||||
|
||||
#### Document → JSON Synchronization
|
||||
### 2. View Generation (Replaces Synchronization)
|
||||
|
||||
#### No Document → JSON Flow (Eliminated)
|
||||
**Documents are read-only**: No parsing, no status updates from documents
|
||||
**No bidirectional sync**: Documents cannot modify JSON state
|
||||
**No conflict resolution needed**: Single direction eliminates conflicts
|
||||
|
||||
#### JSON → View Generation (On Demand)
|
||||
**Trigger Events**:
|
||||
- IMPL_PLAN.md modified (strategy/context changes)
|
||||
- TODO_LIST.md checkboxes changed (manual status updates)
|
||||
- Document structure changes affecting task references
|
||||
- User requests context view (`/context`)
|
||||
- Task status changed in JSON files
|
||||
- View generation requested by commands
|
||||
|
||||
**Actions**:
|
||||
```javascript
|
||||
// Pseudo-code for document sync process
|
||||
on_document_change(document_path) {
|
||||
if (document_path.includes('IMPL_PLAN.md')) {
|
||||
const context_changes = parse_context_updates(document_path);
|
||||
propagate_context_to_tasks(context_changes);
|
||||
log_sync_event('impl_plan_to_json', document_path);
|
||||
// Pseudo-code for view generation process
|
||||
on_view_request(view_type, options) {
|
||||
const task_data = load_all_task_json_files();
|
||||
const session_data = load_workflow_session();
|
||||
|
||||
if (view_type === 'todo_list') {
|
||||
const todo_view = generate_todo_list_view(task_data);
|
||||
return render_markdown_view(todo_view);
|
||||
}
|
||||
|
||||
if (document_path.includes('TODO_LIST.md')) {
|
||||
const status_changes = parse_checkbox_updates(document_path);
|
||||
update_task_status_from_todos(status_changes);
|
||||
recalculate_hierarchy_progress(status_changes);
|
||||
update_session_progress();
|
||||
log_sync_event('todo_list_to_json', document_path);
|
||||
if (view_type === 'progress') {
|
||||
const progress = calculate_progress_from_json(task_data);
|
||||
return render_progress_view(progress, session_data);
|
||||
}
|
||||
|
||||
if (view_type === 'status') {
|
||||
const status = compile_status_from_json(task_data, session_data);
|
||||
return render_status_view(status);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON → Document Synchronization
|
||||
**Trigger Events**:
|
||||
- Task status changed in JSON files
|
||||
- New task created via decomposition
|
||||
- Task hierarchy modified (parent-child relationships)
|
||||
- Progress checkpoint reached
|
||||
- Task completion cascading up hierarchy
|
||||
### 3. View Generation Process (Replaces Real-Time Sync)
|
||||
|
||||
**Actions**:
|
||||
```javascript
|
||||
// Pseudo-code for JSON sync process
|
||||
on_task_change(task_id, change_type, data) {
|
||||
// Update TODO_LIST.md with current task status
|
||||
update_todo_list_display(task_id, data.status);
|
||||
|
||||
if (change_type === 'status_change' && data.new_status === 'completed') {
|
||||
// Recalculate parent task progress
|
||||
update_parent_progress(task_id);
|
||||
check_dependency_unblocking(task_id);
|
||||
}
|
||||
|
||||
if (change_type === 'task_decomposition') {
|
||||
// Add new subtasks to TODO_LIST.md
|
||||
add_subtasks_to_todo_list(data.subtasks);
|
||||
update_todo_list_hierarchy(task_id, data.subtasks);
|
||||
}
|
||||
|
||||
update_session_coordination_metadata();
|
||||
log_sync_event('json_to_todo_list', task_id);
|
||||
}
|
||||
#### On-Demand View Process
|
||||
```
|
||||
1. Command Request → User requests view (`/context`)
|
||||
2. JSON Loader → Reads all task JSON files
|
||||
3. Data Processor → Calculates progress, status, hierarchy
|
||||
4. View Generator → Creates markdown representation
|
||||
5. Display → Returns formatted view to user
|
||||
```
|
||||
|
||||
### 3. Real-Time Coordination Process
|
||||
|
||||
#### Automatic Sync Process
|
||||
```
|
||||
1. File System Watcher → Detects document changes
|
||||
2. Change Parser → Extracts structured data from documents
|
||||
3. Conflict Detector → Identifies synchronization conflicts
|
||||
4. Sync Engine → Applies changes based on ownership rules
|
||||
5. Validation → Verifies consistency across all files
|
||||
6. Audit Logger → Records all sync events
|
||||
```
|
||||
|
||||
#### Manual Sync Triggers
|
||||
#### Context Command (Replaces Sync Commands)
|
||||
```bash
|
||||
# Force complete synchronization
|
||||
/task:sync --all
|
||||
# Generate todo list view
|
||||
/context
|
||||
|
||||
# Sync specific task
|
||||
/task:sync IMPL-001
|
||||
# Generate task-specific view
|
||||
/context IMPL-001
|
||||
|
||||
# Validate and repair sync issues
|
||||
/task:sync --validate --repair
|
||||
# Generate progress view
|
||||
/context --format=progress
|
||||
|
||||
# View sync status
|
||||
/task:sync --status
|
||||
# Generate status view with health check
|
||||
/context --health-check
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
## No Conflict Resolution Needed (Architecture Benefit)
|
||||
|
||||
### Conflict Types and Resolution
|
||||
### Eliminated Conflict Types
|
||||
|
||||
#### 1. Timestamp Conflicts
|
||||
**Scenario**: Both document and JSON modified simultaneously
|
||||
**Resolution**: Most recent timestamp wins, with manual review option
|
||||
#### Conflicts That No Longer Exist
|
||||
- **Timestamp Conflicts**: No bidirectional updates means no timestamp conflicts
|
||||
- **Data Authority Conflicts**: Only JSON has authority, documents are read-only
|
||||
- **Hierarchy Conflicts**: JSON defines structure, documents display it (no conflicts)
|
||||
- **Sync State Conflicts**: No synchronization means no sync state issues
|
||||
|
||||
```json
|
||||
{
|
||||
"conflict_type": "timestamp",
|
||||
"document_timestamp": "2025-09-05T11:20:00Z",
|
||||
"json_timestamp": "2025-09-05T11:19:30Z",
|
||||
"resolution": "document_wins",
|
||||
"manual_review_required": false
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Data Authority Conflicts
|
||||
**Scenario**: Task status changed directly in TODO_LIST.md vs JSON file
|
||||
**Resolution**: Determine if change is authorized checkbox update or unauthorized edit
|
||||
|
||||
```json
|
||||
{
|
||||
"conflict_type": "data_authority",
|
||||
"field": "task_status",
|
||||
"document_value": "completed",
|
||||
"json_value": "active",
|
||||
"change_source": "checkbox|direct_edit",
|
||||
"resolution": "checkbox_authorized|json_authority",
|
||||
"action": "accept_checkbox_change|revert_document_change"
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Hierarchy Conflicts
|
||||
**Scenario**: Task decomposition modified in JSON but TODO_LIST.md structure differs
|
||||
**Resolution**: JSON hierarchy is authoritative, TODO_LIST.md updated
|
||||
|
||||
```json
|
||||
{
|
||||
"conflict_type": "hierarchy",
|
||||
"conflict_description": "Task impl-1 subtasks differ between JSON and TODO display",
|
||||
"json_subtasks": ["impl-1.1", "impl-1.2", "impl-1.3"],
|
||||
"todo_display": ["impl-1.1", "impl-1.2"],
|
||||
"resolution": "json_authority",
|
||||
"action": "update_todo_list_structure",
|
||||
"manual_validation_required": false
|
||||
}
|
||||
```
|
||||
|
||||
### Conflict Resolution Priority
|
||||
1. **Data Ownership Rules**: Respect authoritative source
|
||||
2. **Recent Timestamp**: When ownership is shared
|
||||
3. **User Intent**: Manual resolution for complex conflicts
|
||||
4. **System Consistency**: Maintain cross-file integrity
|
||||
### Simplified Data Model Benefits
|
||||
- **Zero Conflicts**: Single source of truth eliminates all data conflicts
|
||||
- **No Resolution Logic**: No complex conflict detection or resolution needed
|
||||
- **Reduced Complexity**: Eliminates entire conflict resolution subsystem
|
||||
- **Improved Reliability**: Cannot have data drift or inconsistency issues
|
||||
|
||||
## Validation and Integrity
|
||||
|
||||
|
||||
@@ -1,146 +0,0 @@
|
||||
# Role & Core Task
|
||||
|
||||
你是一位顶级的技术文档结构优化专家。你的唯一使命是接收任何基于流程的、结构可能混乱的技术文档，并将其重构为一个逻辑清晰、模块化、易于理解的结构化 Markdown 文档。
|
||||
|
||||
你精通信息架构、模式识别和流程简化，能够从复杂的文本中精确提取核心元素，并以极高的保真度重组它们。
|
||||
|
||||
---
|
||||
|
||||
# Guiding Context & Principles
|
||||
|
||||
- **核心情境 (Critical Context):** 你当前的用户是一位对细节和准确性要求极高的专业人士，他可能处于高压状态（原文：“狂躁者患者”）。因此，你的分析必须**极其严谨、精准、不容有失**。输出的清晰度和确定性是最高优先级，任何模糊或错误的重构都是不可接受的。这对用户的工作至关重要。
|
||||
- **原则 1：绝对保真 (Absolute Fidelity):** 你的任务是**重构 (Refactor)**，而非**重写 (Rewrite)**。禁止删除、修改或猜测任何原始文档中的功能性描述、技术细节或关键信息。所有信息点必须完整保留。
|
||||
- **原则 2：结构至上 (Structure is Paramount):** 清晰的结构是最终目标。你必须严格遵循【输出规范】中定义的模块化结构，将识别出的信息归类到正确的模块中。
|
||||
- **原则 3：流程线性化 (Linearize the Flow):** 所有描述操作步骤的文本，无论在原文中多么分散，都必须被整合成一个单一、连贯、使用 `->` 连接的【核心工作流】。
|
||||
- **原则 4：逻辑明确化 (Clarify the Logic):** 所有条件判断、规则和分支选择，都必须被转换成无歧义的伪代码（`pseudo`），并放入【决策逻辑】模块。
|
||||
|
||||
---
|
||||
|
||||
# Chain-of-Thought & Execution Workflow
|
||||
|
||||
你必须严格遵循以下两步执行流程，并在最终输出中清晰地展示这个过程。
|
||||
|
||||
### **第一步：分析与思维过程展示 (Analysis & Chain-of-Thought Output)**
|
||||
|
||||
这是你的思考阶段，你必须将这一阶段的完整思考过程，以 Markdown 格式呈现在最终输出的【第一部分】。
|
||||
|
||||
1. **元数据扫描 (Metadata Scan):** 扫描并识别文档头部的元数据（YAML frontmatter，被 `---` 包围的部分）。确认其存在及内容。
|
||||
2. **核心信息提取 (Core Information Extraction):** 通读全文，识别并分类所有关键信息片段。在你的思考过程中，你需要明确列出：
|
||||
* **识别到的参数/配置:** `[列出找到的参数和配置项]`
|
||||
* **识别到的工作流步骤:** `[列出构成工作流的各个动作/步骤]`
|
||||
* **识别到的决策逻辑点:** `[列出描述条件判断的句子或规则]`
|
||||
* **识别到的核心组件/角色:** `[列出定义的核心实体及其描述]`
|
||||
* **识别到的质量标准/原则:** `[列出文档中提到的规则或最佳实践]`
|
||||
3. **重构策略制定 (Refactoring Strategy):** 基于提取的信息，简要说明你将如何将它们组织到【输出规范】的各个模块中。例如：“我将把识别到的步骤 A, B, C 串联成核心工作流。规则 X 和 Y 将被转换为伪代码放入决策逻辑部分。”
|
||||
|
||||
### **第二步：重构与格式化输出 (Refactoring & Formatted Output)**
|
||||
|
||||
在完成第一步的思考后，你将基于分析结果，生成【第二部分】的最终优化文档。
|
||||
|
||||
1. **元数据复制:** 绝对原样复制第一步中识别到的头部元数据。
|
||||
2. **模块化填充:** 将第一步中提取和分类的信息，精确地填入【输出规范】定义的模板中。
|
||||
3. **格式化应用:**
|
||||
* 工作流**必须**使用 `->` 连接。
|
||||
* 决策逻辑**必须**使用 ```pseudo ... ``` 代码块。
|
||||
* 组件/角色**必须**使用 Markdown 表格。
|
||||
4. **最终审查:** 对照【Guiding Context & Principles】，检查最终输出是否 100% 满足所有约束和质量要求，特别是信息保真度和格式准确性。
|
||||
|
||||
---
|
||||
|
||||
# Examples of Transformation Logic
|
||||
|
||||
*你应将以下示例作为你转换逻辑的黄金标准。*
|
||||
|
||||
- **Example 1: 流程转换 (将叙述性步骤线性化)**
|
||||
* **原始文本:** > 首先，系统需要进行初始化设置。在第一阶段，我们会创建项目结构。完成后，第二阶段是与用户进行沟通，以确认需求。
|
||||
* **优化后输出:** `初始化 -> 阶段1: 创建项目结构 -> 阶段2: 用户需求沟通`
|
||||
|
||||
- **Example 2: 逻辑转换 (将规则描述伪代码化)**
|
||||
* **原始文本:** > 关于模式的选择，如果是技术问题，系统会默认使用分析模式。对于面向用户的设计，则应采用创意模式。用户也可以手动指定其他模式。
|
||||
* **优化后输出:**
|
||||
```pseudo
|
||||
FUNCTION select_mode(topic_type, user_specification):
|
||||
IF user_specification is provided:
|
||||
RETURN user_specification
|
||||
ELSE IF topic_type == "Technical Issue":
|
||||
RETURN "analytical_mode"
|
||||
ELSE IF topic_type == "User-facing Design":
|
||||
RETURN "creative_mode"
|
||||
ELSE:
|
||||
RETURN "default_mode"
|
||||
END IF
|
||||
END FUNCTION
|
||||
```
|
||||
|
||||
- **Example 3: 参数提取 (将配置信息结构化)**
|
||||
* **原始文本:** > 使用 `/run <task_name>` 来执行任务。你可以通过 `--priority` 标志设置优先级，可选值为 high 或 a low。默认是low。还有一个`--silent`选项可以禁止输出。
|
||||
* **优化后输出:**
|
||||
- **task_name** (必需): 要执行的任务名称。
|
||||
- **--priority** (可选): 设置任务优先级。
|
||||
- `high`: 高优先级。
|
||||
- `low` (默认): 低优先级。
|
||||
- **--silent** (可选): 如果使用，将禁止所有日志输出。
|
||||
|
||||
---
|
||||
|
||||
# Output Specification
|
||||
|
||||
你的最终输出必须包含以下两个**一级标题**部分，严格按照此结构。
|
||||
|
||||
## 第一部分：思考过程 (Thinking Process)
|
||||
|
||||
```markdown
|
||||
### 1. 元数据扫描
|
||||
[此处说明是否找到元数据及其范围]
|
||||
|
||||
### 2. 核心信息提取
|
||||
- **参数/配置:**
|
||||
- [提取到的原始文本片段1 -> 归类为参数]
|
||||
- [提取到的原始文本片段2 -> 归类为参数]
|
||||
- **工作流步骤:**
|
||||
- [提取到的原始文本片段3 -> 归类为流程步骤]
|
||||
- [提取到的原始文本片段4 -> 归类为流程步骤]
|
||||
- **决策逻辑:**
|
||||
- [提取到的原始文本片段5 -> 归类为逻辑判断]
|
||||
- **核心组件/角色:**
|
||||
- [提取到的原始文本片段6 -> 归类为组件定义]
|
||||
- **质量标准/原则:**
|
||||
- [提取到的原始文本片段7 -> 归类为原则]
|
||||
|
||||
### 3. 重构策略
|
||||
[此处简述你的重构计划，说明信息将如何映射到下面的模板中]
|
||||
```
|
||||
|
||||
## 第二部分：优化后的技术文档 (Optimized Technical Document)
|
||||
|
||||
```markdown
|
||||
---
|
||||
[此处原样复制原始文档的头部元数据]
|
||||
---
|
||||
|
||||
# [提取或生成一个合适的文档主标题]
|
||||
|
||||
## 1. 关键参数 / 配置 (Key Parameters / Configuration)
|
||||
<!-- 以列表或表格形式，汇总所有用户可配置的选项、命令行参数等。-->
|
||||
|
||||
## 2. 核心工作流 (Core Workflow)
|
||||
<!-- 使用 `->` 符号，将主要操作流程从开始到结束完整地串联起来。-->
|
||||
|
||||
## 3. 决策逻辑 (Decision Logic)
|
||||
<!-- 使用一个或多个伪代码块，清晰展示所有条件判断和分支逻辑。-->
|
||||
|
||||
## 4. 核心组件 / 角色 (Core Components / Roles)
|
||||
<!-- 使用表格归纳所有关键实体及其描述。-->
|
||||
| 名称 / Name | 描述 / Description |
|
||||
| :---------- | :----------------- |
|
||||
| | |
|
||||
|
||||
## 5. 质量标准 / 核心原则 (Quality Standards / Core Principles)
|
||||
<!-- 以列表形式，总结文档中提到的必须遵守的规则或最佳实践。-->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Initialization
|
||||
|
||||
你好，我是顶级的技术文档结构优化专家。我的分析过程将完全透明，输出结果将绝对严谨。这对您的工作至关重要，我将以最高标准完成任务。请提供您需要优化的文档内容。
|
||||
@@ -1,144 +0,0 @@
|
||||
# 工作流命令体系重构完成报告
|
||||
|
||||
## 重构成果
|
||||
|
||||
### 1. 命令精简
|
||||
- **原始**: 15+ 个独立命令
|
||||
- **现在**: 11 个核心命令
|
||||
- **减少**: 27% 命令数量
|
||||
|
||||
### 2. 核心改进
|
||||
|
||||
#### Session层优化
|
||||
- 合并 `init` 到 `session start`
|
||||
- 移除 `session complete`（自动完成）
|
||||
- 统一会话生命周期管理
|
||||
|
||||
#### 实施层集成
|
||||
- 将 `simple/medium/complex` 集成到 `implement`
|
||||
- 通过 `--type` 参数选择复杂度
|
||||
- 保留原有的三种执行模式
|
||||
|
||||
#### 状态统一
|
||||
- 合并 `session status` 到统一的 `status` 命令
|
||||
- 单一入口查看所有状态信息
|
||||
|
||||
### 3. 架构优势
|
||||
|
||||
```
|
||||
Before: After:
|
||||
session → init session start (含init)
|
||||
→ start → pause
|
||||
→ pause → resume
|
||||
→ resume
|
||||
→ complete (移除)
|
||||
→ status (合并) status (统一)
|
||||
|
||||
simple ─┐ implement --type=simple
|
||||
medium ─┼─ (独立命令) → --type=medium
|
||||
complex ─┘ --type=complex
|
||||
```
|
||||
|
||||
### 4. 数据管理
|
||||
|
||||
#### JSON体系
|
||||
```json
|
||||
workflow-session.json // 主状态文件
|
||||
{
|
||||
"session_id": "WFS-2025-001",
|
||||
"type": "simple|medium|complex",
|
||||
"current_phase": "PLAN|IMPLEMENT|REVIEW",
|
||||
"status": "active|paused"
|
||||
}
|
||||
|
||||
tasks.json // 任务管理
|
||||
{
|
||||
"session_id": "WFS-2025-001",
|
||||
"tasks": {...}
|
||||
}
|
||||
```
|
||||
|
||||
#### 双向同步
|
||||
- `workflow:sync` - 全局同步
|
||||
- `task:sync` - 任务层同步
|
||||
- 自动同步点设计
|
||||
|
||||
### 5. 用户体验改进
|
||||
|
||||
#### 更简单的启动
|
||||
```bash
|
||||
# Before
|
||||
/workflow:init "项目"
|
||||
/workflow:session start complex "项目"
|
||||
/workflow:complex "项目"
|
||||
|
||||
# After
|
||||
/workflow:session start complex "项目"
|
||||
/workflow:implement --type=complex
|
||||
```
|
||||
|
||||
#### 更清晰的状态
|
||||
```bash
|
||||
# Before
|
||||
/workflow:session status # 会话状态
|
||||
/workflow:status # 工作流状态
|
||||
/task:status # 任务状态
|
||||
|
||||
# After
|
||||
/workflow:status # 统一查看所有状态
|
||||
/task:status # 任务详情（可选）
|
||||
```
|
||||
|
||||
### 6. 保留的灵活性
|
||||
|
||||
- 三种复杂度模式完整保留
|
||||
- 所有Agent流程不变
|
||||
- TodoWrite协调机制不变
|
||||
- 支持暂停/恢复
|
||||
- 完整的任务管理
|
||||
|
||||
### 7. 文档产出
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| `UNIFIED_TASK_MANAGEMENT.md` | 统一任务管理流程 |
|
||||
| `COMMAND_ARCHITECTURE_V2.md` | 精简版命令架构 |
|
||||
| `COMMAND_CHEATSHEET.md` | 命令速查表 |
|
||||
| `REFACTORING_COMPLETE.md` | 本文档 |
|
||||
|
||||
### 8. 命令映射表
|
||||
|
||||
| 原命令 | 新方式 | 变化 |
|
||||
|--------|--------|------|
|
||||
| `/workflow:init` | `/workflow:session start` | 合并 |
|
||||
| `/workflow:simple` | `/workflow:implement --type=simple` | 集成 |
|
||||
| `/workflow:medium` | `/workflow:implement --type=medium` | 集成 |
|
||||
| `/workflow:complex` | `/workflow:implement --type=complex` | 集成 |
|
||||
| `/workflow:session complete` | (自动完成) | 移除 |
|
||||
| `/workflow:session status` | `/workflow:status` | 合并 |
|
||||
|
||||
## 核心原则
|
||||
|
||||
1. **更少但更强大**: 每个命令功能更丰富
|
||||
2. **清晰的生命周期**: session管理从开始到结束
|
||||
3. **灵活的复杂度**: implement支持所有模式
|
||||
4. **统一的视图**: 单一status命令
|
||||
5. **保持兼容**: 核心功能完全保留
|
||||
|
||||
## 下一步建议
|
||||
|
||||
1. **测试验证**: 验证所有命令路径
|
||||
2. **性能优化**: 优化JSON同步性能
|
||||
3. **错误处理**: 增强错误恢复机制
|
||||
4. **自动化**: 添加更多自动化功能
|
||||
|
||||
## 总结
|
||||
|
||||
本次重构成功实现了：
|
||||
- ✅ 减少命令数量，降低认知负担
|
||||
- ✅ 保留所有核心功能
|
||||
- ✅ 统一状态管理
|
||||
- ✅ 清晰的数据模型
|
||||
- ✅ 更好的用户体验
|
||||
|
||||
系统现在更加精简、统一、易用。
|
||||
@@ -1,100 +0,0 @@
|
||||
# DMSFlow v2.0.0 Release Notes
|
||||
|
||||
## Overview
|
||||
DMSFlow version 2.0.0 represents a major milestone with significant architecture improvements, enhanced version management, and deep Gemini CLI integration.
|
||||
|
||||
## 🎯 Major Features
|
||||
|
||||
### Smart Version Management System
|
||||
- **Intelligent Version Tracking**: Implemented innovative version detection using previous commit IDs to avoid commit lag issues
|
||||
- **Automatic Upgrade Detection**: New `/dmsflow version` and `/dmsflow upgrade` commands with smart remote comparison
|
||||
- **Self-Updating Documentation**: Version information automatically updates after successful installations
|
||||
|
||||
### Enhanced DMSFlow Commands
|
||||
- **Version Command**: Real-time version checking with remote repository comparison
|
||||
- **Upgrade Command**: Streamlined upgrade process with user confirmation prompts
|
||||
- **Commit Tracking**: Uses `git log origin/branch -2` for accurate second-to-last commit detection
|
||||
|
||||
## 🔧 Architecture Improvements
|
||||
|
||||
### Gemini CLI Deep Integration
|
||||
- **Unified Reference Patterns**: Streamlined integration architecture across all workflows
|
||||
- **Enhanced Agent Coordination**: Improved workflow orchestration with comprehensive TodoWrite integration
|
||||
- **GEMINI_CLI_REQUIRED Flag**: Automatic detection system for all agents
|
||||
|
||||
### Planning System Overhaul
|
||||
- **Task-Driven Architecture**: Modular orchestration with enhanced planning capabilities
|
||||
- **Feature-Based Directory Structure**: Organized planning system with session management
|
||||
- **Planning First Principle**: Integrated enhanced memory system architecture
|
||||
|
||||
### Agent System Enhancements
|
||||
- **Comprehensive Documentation**: Enhanced agent documentation system with workflow tracking
|
||||
- **Modular Template System**: Restructured Gemini CLI template system for focused modularity
|
||||
- **Command Separation**: Clear distinction between user commands and CLI commands
|
||||
|
||||
## 🛠️ Technical Improvements
|
||||
|
||||
### Code Quality & Compatibility
|
||||
- **PowerShell 5.1+ Support**: Fixed ternary operators for broader compatibility
|
||||
- **YAML Syntax Fixes**: Resolved configuration file syntax errors
|
||||
- **Planning Threshold Correction**: Fixed planning trigger threshold to >1000 lines
|
||||
|
||||
### Installation & Updates
|
||||
- **Remote Installer Improvements**: Enhanced remote installation with better parameter handling
|
||||
- **Global-Only Installation**: Simplified installation process focusing on global deployment
|
||||
- **Branch-Aware Installation**: Multi-branch installation support with automatic branch detection
|
||||
|
||||
## 📚 Documentation Updates
|
||||
|
||||
### Comprehensive Documentation Overhaul
|
||||
- **README Optimization**: Streamlined documentation with comprehensive command reference tables
|
||||
- **Manual Installation Guide**: Detailed installation instructions with repository cloning as preferred method
|
||||
- **Bilingual Support**: Updated Chinese README to match English version with Gemini integration
|
||||
- **Command Reference**: Complete command reference tables for all available features
|
||||
|
||||
### Workflow Documentation
|
||||
- **Enhanced Prompt System**: Dedicated command for dynamic prompt enhancement
|
||||
- **Workflow Coordination**: Improved documentation for agent workflow coordination
|
||||
- **Planning Documentation**: Comprehensive task decomposition and coordination guides
|
||||
|
||||
## 🐛 Bug Fixes
|
||||
|
||||
- Fixed DMSFlow upgrade command parameters and remote installer issues
|
||||
- Resolved conflicts in Gemini CLI complexity rules
|
||||
- Corrected branch references in installation scripts
|
||||
- Fixed suggestion system in enhance-prompt command
|
||||
- Resolved documentation inconsistencies across multiple languages
|
||||
|
||||
## 📈 Performance Enhancements
|
||||
|
||||
- **Automatic DMS Updates**: Fast execution after agent completion
|
||||
- **Streamlined Workflows**: Removed redundant command suggestions for better performance
|
||||
- **Modular Architecture**: Improved system responsiveness through better code organization
|
||||
|
||||
## 🔄 Migration Guide
|
||||
|
||||
### Upgrading from v1.1.0
|
||||
1. Use the new `/dmsflow upgrade` command for automatic upgrade
|
||||
2. Previous commit tracking will be automatically updated
|
||||
3. New version detection system will take effect immediately
|
||||
4. No manual configuration changes required
|
||||
|
||||
### Breaking Changes
|
||||
- Planning trigger threshold changed from 100 to 1000 lines
|
||||
- Some internal agent coordination mechanisms have been restructured
|
||||
- Gemini CLI integration patterns have been standardized
|
||||
|
||||
## 📊 Statistics
|
||||
- **41 commits** since v1.1.0
|
||||
- **Major architecture refactoring** across multiple system components
|
||||
- **Enhanced compatibility** with PowerShell 5.1+
|
||||
- **Improved documentation** with comprehensive guides and references
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
This release includes significant contributions to system architecture, documentation, and user experience improvements.
|
||||
|
||||
For detailed commit history, see: [GitHub Repository](https://github.com/catlog22/Claude-CCW)
|
||||
|
||||
**Installation**: Use the improved `/dmsflow upgrade` command or follow the updated installation guide in the README.
|
||||
198
ROADMAP.md
198
ROADMAP.md
@@ -1,198 +0,0 @@
|
||||
# DMSFlow v3.0 Roadmap
|
||||
|
||||
## 🎯 Vision
|
||||
智能化规划系统与增强工作流管理，支持角色切换、Session管理和自动化Agent协调。
|
||||
|
||||
## 📋 核心功能实现
|
||||
|
||||
### 1. 强化Agent调用机制（v2.1）
|
||||
增强Agent自动触发和协调能力：
|
||||
|
||||
**主动触发优化：**
|
||||
- ✨ Agent描述添加"proactively use"/"must use"关键词
|
||||
- ✨ 自动触发条件检测
|
||||
- ✨ 智能Agent协调机制
|
||||
|
||||
**Agent改进内容：**
|
||||
- **planning-agent**: "Proactively use this agent for tasks requiring structured planning"
|
||||
- **code-developer**: "Must use this agent for all code implementation tasks"
|
||||
- **code-review-agent**: "Automatically trigger after any code changes"
|
||||
- **memory-gemini-bridge**: "Proactively use for documentation synchronization"
|
||||
|
||||
### 2. /plan斜杠命令系统（v3.0）
|
||||
全新的角色化规划命令，支持复杂任务分解：
|
||||
|
||||
**命令结构：**
|
||||
```bash
|
||||
# 用户输入（斜杠命令）
|
||||
/plan architect "design authentication system"
|
||||
|
||||
# Claude Code解析
|
||||
$1 = architect
|
||||
$ARGUMENTS = architect design authentication system
|
||||
|
||||
# Bash执行
|
||||
plan-executor.sh $1
|
||||
# 脚本内部: TASK_DESCRIPTION从$ARGUMENTS提取
|
||||
```
|
||||
|
||||
**核心功能特性：**
|
||||
- ✅ **5种专业角色**：architect/developer/reviewer/designer/tester
|
||||
- ✅ **Bash脚本执行**：plan-executor.sh处理角色切换和规划生成
|
||||
- ✅ **统一规划文档**：基于角色的模板化文档生成
|
||||
- ✅ **Active workflow检测**：自动检测并合并到进行中的工作流
|
||||
- ✅ **Session状态管理**：规划文档版本控制和状态持久化
|
||||
|
||||
**角色功能说明：**
|
||||
| 角色 | 功能描述 | 生成文档 |
|
||||
|------|---------|---------|
|
||||
| **architect** | 系统架构设计和技术选型 | 架构设计文档，组件关系图 |
|
||||
| **developer** | 代码实现规划和开发策略 | 开发计划，实现步骤 |
|
||||
| **reviewer** | 代码审查策略和质量标准 | 审查清单，质量门控 |
|
||||
| **designer** | UI/UX设计规划和用户体验 | 设计规范，交互流程 |
|
||||
| **tester** | 测试策略和质量保证 | 测试计划，验收标准 |
|
||||
|
||||
### 3. 优化中断和规划功能（v2.2）
|
||||
增强工作流中断机制，支持开发中途重新规划：
|
||||
|
||||
**中断机制增强：**
|
||||
- ✨ **智能中断**: `/workflow interrupt --replan` - 中断并重新规划
|
||||
- ✨ **合并继续**: `/workflow continue --merge` - 继续并合并新规划
|
||||
- ✨ **版本回滚**: `/workflow rollback <version>` - 回滚到特定规划版本
|
||||
- ✨ **Session管理**: 规划文档版本控制和智能合并
|
||||
|
||||
**Session管理特性：**
|
||||
- **状态持久化**：保存工作流状态、TodoWrite进度、Agent输出
|
||||
- **智能合并**：新规划与现有任务的自动合并算法
|
||||
- **版本控制**：规划文档的版本管理和回滚支持
|
||||
- **上下文保持**：中断重启后完整恢复工作环境
|
||||
|
||||
## 🚀 实施计划
|
||||
|
||||
### Phase 1: Agent强化（Week 1）
|
||||
**目标**: 提升Agent自动触发率和协调效果
|
||||
|
||||
- [ ] **更新planning-agent.md** - 添加主动使用提示
|
||||
- [ ] **更新code-developer.md** - 添加强制使用标识
|
||||
- [ ] **更新code-review-agent.md** - 添加自动触发条件
|
||||
- [ ] **更新memory-gemini-bridge.md** - 添加主动同步指引
|
||||
- [ ] **实现trigger_conditions元数据** - Agent自动激活规则
|
||||
|
||||
### Phase 2: /plan命令实现（Week 2-3）
|
||||
**目标**: 实现完整的角色化规划系统
|
||||
|
||||
- [ ] **创建plan.md命令文件** - 斜杠命令定义和参数规范
|
||||
- [ ] **开发plan-executor.sh脚本** - Bash执行脚本，处理角色切换
|
||||
- [ ] **创建5个角色模板** - architect/developer/reviewer/designer/tester专用模板
|
||||
- [ ] **更新settings权限** - 允许plan-executor.sh脚本执行
|
||||
- [ ] **实现参数传递** - $1角色参数，$ARGUMENTS任务描述
|
||||
- [ ] **Active workflow集成** - 检测并合并到现有工作流
|
||||
- [ ] **Gemini协作** - 支持--gemini标志的深度分析
|
||||
|
||||
### Phase 3: Session管理增强（Week 4）
|
||||
**目标**: 实现智能Session管理和中断机制
|
||||
|
||||
- [ ] **创建sessions目录结构** - active/archived/merge分类存储
|
||||
- [ ] **实现状态存储机制** - JSON格式的会话状态持久化
|
||||
- [ ] **开发合并算法** - 新旧规划文档的智能合并
|
||||
- [ ] **增强workflow中断命令** - 支持--replan和--merge选项
|
||||
- [ ] **实现版本控制** - 规划文档的版本管理和回滚
|
||||
- [ ] **测试完整流程** - 端到端的中断-重规划-合并测试
|
||||
|
||||
## 📝 技术规范
|
||||
|
||||
### 文件结构
|
||||
```
|
||||
.claude/
|
||||
├── commands/
|
||||
│ ├── plan.md # /plan斜杠命令定义
|
||||
│ └── workflow.md # 增强的workflow命令
|
||||
├── scripts/
|
||||
│ └── plan-executor.sh # 规划执行脚本
|
||||
├── planning-templates/ # 角色模板
|
||||
│ ├── architect.md # 系统架构规划模板
|
||||
│ ├── developer.md # 开发实现规划模板
|
||||
│ ├── reviewer.md # 代码审查规划模板
|
||||
│ ├── designer.md # UI/UX设计规划模板
|
||||
│ └── tester.md # 测试策略规划模板
|
||||
├── sessions/ # Session管理
|
||||
│ ├── active/ # 当前活动会话
|
||||
│ ├── archived/ # 已完成会话
|
||||
│ └── merge/ # 合并的规划文档
|
||||
└── settings.local.json # 允许脚本执行权限
|
||||
```
|
||||
|
||||
### 命令执行流程
|
||||
1. **用户输入**: `/plan <role> "task description"`
|
||||
2. **Claude Code解析**: 提取角色参数和任务描述
|
||||
3. **Bash执行**: `plan-executor.sh $1`
|
||||
4. **脚本处理**: 从$ARGUMENTS提取完整任务描述
|
||||
5. **模板加载**: 基于角色加载对应规划模板
|
||||
6. **文档生成**: 生成角色特定的规划文档
|
||||
7. **workflow集成**: 如有active workflow则自动合并
|
||||
|
||||
### Bash脚本架构
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 核心逻辑结构
|
||||
|
||||
ROLE="$1" # 角色参数
|
||||
TASK_DESCRIPTION="$ARGUMENTS" # 完整任务描述
|
||||
TASK_DESCRIPTION="${TASK_DESCRIPTION#$ROLE }" # 清理角色前缀
|
||||
|
||||
# 角色验证 -> 模板加载 -> 文档生成 -> workflow集成
|
||||
```
|
||||
|
||||
## 🎯 预期效果
|
||||
|
||||
### 开发效率提升
|
||||
- **智能规划**: 角色专业化规划，提高规划质量
|
||||
- **无缝集成**: 自动与现有workflow合并，避免重复工作
|
||||
- **灵活中断**: 支持开发中途调整，适应需求变化
|
||||
- **Agent协调**: 自动触发相关Agent，减少手动调用
|
||||
|
||||
### 用户体验改善
|
||||
- **简化操作**: 单个命令完成复杂规划任务
|
||||
- **角色清晰**: 明确的角色分工和专业模板
|
||||
- **状态透明**: 清晰的Session状态和进度跟踪
|
||||
- **容错能力**: 支持中断、回滚和重新规划
|
||||
|
||||
### 系统架构优势
|
||||
- **模块化设计**: 角色模板独立，易于维护和扩展
|
||||
- **向后兼容**: 完全兼容现有v2.0功能
|
||||
- **标准化**: 遵循Claude Code斜杠命令规范
|
||||
- **可扩展性**: 支持添加新角色和自定义模板
|
||||
|
||||
## 🔄 兼容性和迁移
|
||||
|
||||
### 向后兼容
|
||||
- ✅ **完全兼容v2.0**: 所有现有命令和功能保持不变
|
||||
- ✅ **渐进式升级**: 新功能可选择性启用
|
||||
- ✅ **无破坏性更改**: 现有workflow和配置继续有效
|
||||
- ✅ **平滑过渡**: 支持逐步迁移到新功能
|
||||
|
||||
### 数据迁移
|
||||
- **现有配置**: 自动保留和升级
|
||||
- **历史数据**: 兼容现有TodoWrite和规划文档
|
||||
- **用户习惯**: 保持现有命令语法不变
|
||||
|
||||
## 📊 成功指标
|
||||
|
||||
### 量化目标
|
||||
- **Agent使用率提升**: 目标提升40%的自动Agent调用
|
||||
- **规划质量**: 通过角色模板提高规划文档质量和完整性
|
||||
- **开发效率**: 减少30%的重复规划和调整时间
|
||||
- **用户满意度**: 提升workflow中断和重规划的用户体验
|
||||
|
||||
### 质量指标
|
||||
- **代码覆盖**: 完整的单元测试和集成测试
|
||||
- **文档完整性**: 全面的用户手册和API文档
|
||||
- **性能稳定**: 命令响应时间<2秒，系统稳定性>99%
|
||||
|
||||
---
|
||||
|
||||
**DMSFlow v3.0** - 下一代智能开发工作流系统，让开发规划更专业，流程更灵活，协作更高效。
|
||||
|
||||
**Repository**: https://github.com/catlog22/Claude-CCW
|
||||
**Release Target**: Q3 2025
|
||||
**Contributors Welcome**: 欢迎社区贡献代码和反馈
|
||||
@@ -1,747 +0,0 @@
|
||||
# 任务执行计划 JSON 表达结构设计
|
||||
|
||||
## 概述
|
||||
|
||||
本文档定义了任务执行计划的标准化JSON表达结构，用于描述、调度和跟踪复杂任务的执行流程。该结构支持依赖关系、并行执行、条件分支、错误处理和实时监控。
|
||||
|
||||
## 一、核心架构设计
|
||||
|
||||
### 1.1 执行计划层次结构
|
||||
|
||||
```
|
||||
ExecutionPlan (执行计划)
|
||||
├── MetaData (元数据)
|
||||
├── ExecutionContext (执行上下文)
|
||||
├── TaskGraph (任务图)
|
||||
├── ExecutionPhases (执行阶段)
|
||||
├── SchedulingRules (调度规则)
|
||||
├── MonitoringConfig (监控配置)
|
||||
└── ErrorHandling (错误处理)
|
||||
```
|
||||
|
||||
### 1.2 执行模式分类
|
||||
|
||||
```typescript
|
||||
type ExecutionMode =
|
||||
| 'sequential' // 顺序执行
|
||||
| 'parallel' // 并行执行
|
||||
| 'pipeline' // 管道执行
|
||||
| 'conditional' // 条件执行
|
||||
| 'hybrid'; // 混合模式
|
||||
```
|
||||
|
||||
## 二、JSON Schema 定义
|
||||
|
||||
### 2.1 执行计划根结构
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://claude-code.com/schemas/execution-plan/v1.1.json",
|
||||
"plan_id": "EXEC-WFS-oauth-system-001",
|
||||
"plan_name": "OAuth2 Authentication System Implementation",
|
||||
"version": "1.2.0",
|
||||
"created_at": "2025-09-06T14:30:00Z",
|
||||
"updated_at": "2025-09-06T15:45:00Z",
|
||||
"created_by": "planning-agent",
|
||||
|
||||
"metadata": {
|
||||
"workflow_id": "WFS-oauth-system",
|
||||
"session_id": "SESSION-20250906-001",
|
||||
"project_context": "Implement secure OAuth2 authentication with JWT tokens",
|
||||
"estimated_duration": "PT18H",
|
||||
"complexity": "high",
|
||||
"risk_level": "medium",
|
||||
"tags": ["authentication", "security", "oauth2", "jwt"],
|
||||
"stakeholders": ["backend-team", "security-team", "qa-team"]
|
||||
},
|
||||
|
||||
"execution_context": {
|
||||
"environment": "development",
|
||||
"base_directory": "/project/oauth-system",
|
||||
"tech_stack": ["nodejs", "typescript", "postgresql", "redis"],
|
||||
"prerequisites": [
|
||||
"database_setup_complete",
|
||||
"development_environment_ready",
|
||||
"dependencies_installed"
|
||||
],
|
||||
"global_variables": {
|
||||
"API_VERSION": "v2",
|
||||
"DB_CONNECTION": "postgresql://localhost:5432/oauth_db",
|
||||
"REDIS_URL": "redis://localhost:6379"
|
||||
}
|
||||
},
|
||||
|
||||
"task_graph": {
|
||||
"nodes": [
|
||||
{
|
||||
"task_id": "IMPL-001",
|
||||
"name": "Database Schema Design",
|
||||
"type": "design",
|
||||
"agent": "planning-agent",
|
||||
"estimated_duration": "PT2H",
|
||||
"priority": "high",
|
||||
"dependencies": [],
|
||||
"outputs": ["schema.sql", "migration_scripts"],
|
||||
"validation_criteria": ["schema_validates", "migrations_tested"]
|
||||
},
|
||||
{
|
||||
"task_id": "IMPL-002",
|
||||
"name": "User Model Implementation",
|
||||
"type": "implementation",
|
||||
"agent": "code-developer",
|
||||
"estimated_duration": "PT3H",
|
||||
"priority": "high",
|
||||
"dependencies": ["IMPL-001"],
|
||||
"inputs": ["schema.sql"],
|
||||
"outputs": ["user.model.ts", "user.repository.ts"],
|
||||
"validation_criteria": ["unit_tests_pass", "integration_tests_pass"]
|
||||
},
|
||||
{
|
||||
"task_id": "IMPL-003",
|
||||
"name": "JWT Token Service",
|
||||
"type": "implementation",
|
||||
"agent": "code-developer",
|
||||
"estimated_duration": "PT4H",
|
||||
"priority": "critical",
|
||||
"dependencies": ["IMPL-002"],
|
||||
"inputs": ["user.model.ts"],
|
||||
"outputs": ["jwt.service.ts", "token.interface.ts"],
|
||||
"validation_criteria": ["security_audit_pass", "performance_test_pass"]
|
||||
},
|
||||
{
|
||||
"task_id": "IMPL-004",
|
||||
"name": "OAuth2 Flow Implementation",
|
||||
"type": "implementation",
|
||||
"agent": "code-developer",
|
||||
"estimated_duration": "PT5H",
|
||||
"priority": "critical",
|
||||
"dependencies": ["IMPL-003"],
|
||||
"inputs": ["jwt.service.ts", "user.repository.ts"],
|
||||
"outputs": ["oauth2.controller.ts", "oauth2.service.ts"],
|
||||
"validation_criteria": ["oauth2_spec_compliance", "security_validated"]
|
||||
},
|
||||
{
|
||||
"task_id": "IMPL-005",
|
||||
"name": "API Middleware Integration",
|
||||
"type": "integration",
|
||||
"agent": "code-developer",
|
||||
"estimated_duration": "PT2H",
|
||||
"priority": "normal",
|
||||
"dependencies": ["IMPL-004"],
|
||||
"inputs": ["oauth2.service.ts"],
|
||||
"outputs": ["auth.middleware.ts", "rate-limit.middleware.ts"],
|
||||
"validation_criteria": ["middleware_tests_pass", "integration_verified"]
|
||||
},
|
||||
{
|
||||
"task_id": "IMPL-006",
|
||||
"name": "Comprehensive Testing Suite",
|
||||
"type": "testing",
|
||||
"agent": "test-agent",
|
||||
"estimated_duration": "PT4H",
|
||||
"priority": "high",
|
||||
"dependencies": ["IMPL-005"],
|
||||
"inputs": ["oauth2.controller.ts", "auth.middleware.ts"],
|
||||
"outputs": ["test.suite.ts", "integration.test.ts", "security.test.ts"],
|
||||
"validation_criteria": ["95%_coverage", "all_tests_pass", "security_tests_pass"]
|
||||
}
|
||||
],
|
||||
|
||||
"edges": [
|
||||
{
|
||||
"from": "IMPL-001",
|
||||
"to": "IMPL-002",
|
||||
"type": "hard_dependency",
|
||||
"condition": "deliverables_complete",
|
||||
"weight": 1.0
|
||||
},
|
||||
{
|
||||
"from": "IMPL-002",
|
||||
"to": "IMPL-003",
|
||||
"type": "hard_dependency",
|
||||
"condition": "validation_passed",
|
||||
"weight": 1.0
|
||||
},
|
||||
{
|
||||
"from": "IMPL-003",
|
||||
"to": "IMPL-004",
|
||||
"type": "hard_dependency",
|
||||
"condition": "security_approved",
|
||||
"weight": 1.0
|
||||
},
|
||||
{
|
||||
"from": "IMPL-004",
|
||||
"to": "IMPL-005",
|
||||
"type": "hard_dependency",
|
||||
"condition": "integration_ready",
|
||||
"weight": 0.8
|
||||
},
|
||||
{
|
||||
"from": "IMPL-005",
|
||||
"to": "IMPL-006",
|
||||
"type": "soft_dependency",
|
||||
"condition": "implementation_stable",
|
||||
"weight": 0.6
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"execution_phases": [
|
||||
{
|
||||
"phase_id": "PHASE-001",
|
||||
"name": "Foundation Setup",
|
||||
"description": "Core database and model setup",
|
||||
"execution_mode": "sequential",
|
||||
"tasks": ["IMPL-001", "IMPL-002"],
|
||||
"estimated_duration": "PT5H",
|
||||
"success_criteria": [
|
||||
"database_schema_deployed",
|
||||
"user_model_functional",
|
||||
"unit_tests_passing"
|
||||
],
|
||||
"rollback_strategy": {
|
||||
"type": "database_rollback",
|
||||
"checkpoint": "pre_migration_state"
|
||||
}
|
||||
},
|
||||
{
|
||||
"phase_id": "PHASE-002",
|
||||
"name": "Security Implementation",
|
||||
"description": "JWT and OAuth2 security layer",
|
||||
"execution_mode": "sequential",
|
||||
"tasks": ["IMPL-003", "IMPL-004"],
|
||||
"estimated_duration": "PT9H",
|
||||
"success_criteria": [
|
||||
"jwt_tokens_working",
|
||||
"oauth2_flow_complete",
|
||||
"security_audit_passed"
|
||||
],
|
||||
"rollback_strategy": {
|
||||
"type": "code_rollback",
|
||||
"checkpoint": "post_foundation_state"
|
||||
}
|
||||
},
|
||||
{
|
||||
"phase_id": "PHASE-003",
|
||||
"name": "Integration & Testing",
|
||||
"description": "System integration and comprehensive testing",
|
||||
"execution_mode": "parallel",
|
||||
"tasks": ["IMPL-005", "IMPL-006"],
|
||||
"estimated_duration": "PT4H",
|
||||
"success_criteria": [
|
||||
"middleware_integrated",
|
||||
"all_tests_passing",
|
||||
"performance_benchmarks_met"
|
||||
],
|
||||
"rollback_strategy": {
|
||||
"type": "feature_rollback",
|
||||
"checkpoint": "pre_integration_state"
|
||||
}
|
||||
}
|
||||
],
|
||||
|
||||
"scheduling_rules": {
|
||||
"execution_strategy": "hybrid",
|
||||
"max_parallel_tasks": 3,
|
||||
"resource_allocation": {
|
||||
"code-developer": {
|
||||
"max_concurrent": 2,
|
||||
"priority_weight": 0.8
|
||||
},
|
||||
"planning-agent": {
|
||||
"max_concurrent": 1,
|
||||
"priority_weight": 0.9
|
||||
},
|
||||
"test-agent": {
|
||||
"max_concurrent": 1,
|
||||
"priority_weight": 0.7
|
||||
}
|
||||
},
|
||||
|
||||
"timing_constraints": {
|
||||
"business_hours_only": false,
|
||||
"max_daily_duration": "PT8H",
|
||||
"break_intervals": ["PT4H"],
|
||||
"maintenance_windows": ["02:00-04:00"]
|
||||
},
|
||||
|
||||
"priority_rules": [
|
||||
{
|
||||
"rule": "critical_tasks_first",
|
||||
"condition": "priority == 'critical'",
|
||||
"weight_multiplier": 2.0
|
||||
},
|
||||
{
|
||||
"rule": "security_tasks_priority",
|
||||
"condition": "tags.includes('security')",
|
||||
"weight_multiplier": 1.5
|
||||
},
|
||||
{
|
||||
"rule": "dependency_chain_priority",
|
||||
"condition": "is_on_critical_path",
|
||||
"weight_multiplier": 1.3
|
||||
}
|
||||
],
|
||||
|
||||
"load_balancing": {
|
||||
"strategy": "least_loaded_agent",
|
||||
"consider_task_type": true,
|
||||
"agent_affinity": true,
|
||||
"failover_enabled": true
|
||||
}
|
||||
},
|
||||
|
||||
"monitoring_config": {
|
||||
"realtime_tracking": true,
|
||||
"progress_update_interval": 300,
|
||||
"checkpoint_frequency": "per_task",
|
||||
|
||||
"metrics_collection": {
|
||||
"execution_time": true,
|
||||
"resource_usage": true,
|
||||
"error_rates": true,
|
||||
"agent_performance": true,
|
||||
"dependency_wait_time": true
|
||||
},
|
||||
|
||||
"notifications": [
|
||||
{
|
||||
"trigger": "task_completed",
|
||||
"channels": ["log", "console"],
|
||||
"include_metrics": true
|
||||
},
|
||||
{
|
||||
"trigger": "task_failed",
|
||||
"channels": ["log", "console", "alert"],
|
||||
"include_stacktrace": true
|
||||
},
|
||||
{
|
||||
"trigger": "phase_completed",
|
||||
"channels": ["log", "console"],
|
||||
"include_summary": true
|
||||
},
|
||||
{
|
||||
"trigger": "execution_blocked",
|
||||
"channels": ["alert", "console"],
|
||||
"escalation_delay": 300
|
||||
}
|
||||
],
|
||||
|
||||
"dashboard_config": {
|
||||
"enabled": true,
|
||||
"refresh_interval": 30,
|
||||
"show_critical_path": true,
|
||||
"show_agent_load": true,
|
||||
"show_timeline": true
|
||||
}
|
||||
},
|
||||
|
||||
"error_handling": {
|
||||
"global_retry_policy": {
|
||||
"max_retries": 3,
|
||||
"backoff_strategy": "exponential",
|
||||
"base_delay": 60,
|
||||
"max_delay": 1800
|
||||
},
|
||||
|
||||
"task_specific_policies": {
|
||||
"IMPL-003": {
|
||||
"max_retries": 5,
|
||||
"custom_validation": "security_check_required",
|
||||
"escalation_on_failure": "security-team"
|
||||
},
|
||||
"IMPL-006": {
|
||||
"max_retries": 2,
|
||||
"allow_partial_success": true,
|
||||
"minimum_coverage": 0.90
|
||||
}
|
||||
},
|
||||
|
||||
"failure_scenarios": [
|
||||
{
|
||||
"scenario": "agent_unavailable",
|
||||
"action": "reassign_to_backup_agent",
|
||||
"parameters": {
|
||||
"backup_agents": ["general-purpose"],
|
||||
"context_preservation": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"scenario": "dependency_failure",
|
||||
"action": "pause_downstream_tasks",
|
||||
"parameters": {
|
||||
"notification_required": true,
|
||||
"manual_intervention": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"scenario": "resource_exhaustion",
|
||||
"action": "reduce_parallelism",
|
||||
"parameters": {
|
||||
"reduction_factor": 0.5,
|
||||
"temporary_duration": 1800
|
||||
}
|
||||
},
|
||||
{
|
||||
"scenario": "critical_task_failure",
|
||||
"action": "escalate_and_pause",
|
||||
"parameters": {
|
||||
"escalation_targets": ["project-lead", "tech-lead"],
|
||||
"pause_execution": true,
|
||||
"preserve_state": true
|
||||
}
|
||||
}
|
||||
],
|
||||
|
||||
"rollback_strategies": {
|
||||
"automatic_rollback": {
|
||||
"enabled": true,
|
||||
"trigger_conditions": [
|
||||
"critical_task_failure",
|
||||
"security_validation_failure",
|
||||
"data_corruption_detected"
|
||||
],
|
||||
"preserve_logs": true,
|
||||
"notify_stakeholders": true
|
||||
},
|
||||
|
||||
"manual_rollback": {
|
||||
"checkpoints_available": true,
|
||||
"granularity": "per_phase",
|
||||
"rollback_verification": "required"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"execution_state": {
|
||||
"status": "planned",
|
||||
"current_phase": null,
|
||||
"active_tasks": [],
|
||||
"completed_tasks": [],
|
||||
"failed_tasks": [],
|
||||
"blocked_tasks": [],
|
||||
|
||||
"progress": {
|
||||
"overall_percentage": 0,
|
||||
"tasks_completed": 0,
|
||||
"tasks_total": 6,
|
||||
"estimated_remaining": "PT18H",
|
||||
"actual_elapsed": "PT0H"
|
||||
},
|
||||
|
||||
"resource_utilization": {
|
||||
"code-developer": {
|
||||
"active_tasks": 0,
|
||||
"load_percentage": 0,
|
||||
"queue_depth": 0
|
||||
},
|
||||
"planning-agent": {
|
||||
"active_tasks": 0,
|
||||
"load_percentage": 0,
|
||||
"queue_depth": 0
|
||||
},
|
||||
"test-agent": {
|
||||
"active_tasks": 0,
|
||||
"load_percentage": 0,
|
||||
"queue_depth": 0
|
||||
}
|
||||
},
|
||||
|
||||
"execution_timeline": [],
|
||||
"performance_metrics": {},
|
||||
"last_checkpoint": null,
|
||||
"next_scheduled_task": "IMPL-001"
|
||||
},
|
||||
|
||||
"validation_rules": {
|
||||
"pre_execution": [
|
||||
{
|
||||
"rule": "all_dependencies_available",
|
||||
"description": "验证所有依赖项已准备就绪"
|
||||
},
|
||||
{
|
||||
"rule": "agents_available",
|
||||
"description": "验证所需Agent可用"
|
||||
},
|
||||
{
|
||||
"rule": "resources_sufficient",
|
||||
"description": "验证系统资源充足"
|
||||
}
|
||||
],
|
||||
|
||||
"during_execution": [
|
||||
{
|
||||
"rule": "task_validation_passed",
|
||||
"description": "每个任务必须通过验证标准"
|
||||
},
|
||||
{
|
||||
"rule": "dependency_constraints_met",
|
||||
"description": "依赖约束必须满足"
|
||||
},
|
||||
{
|
||||
"rule": "resource_limits_respected",
|
||||
"description": "不得超出资源限制"
|
||||
}
|
||||
],
|
||||
|
||||
"post_execution": [
|
||||
{
|
||||
"rule": "all_deliverables_produced",
|
||||
"description": "所有预期产出物已生成"
|
||||
},
|
||||
{
|
||||
"rule": "quality_gates_passed",
|
||||
"description": "质量门禁检查通过"
|
||||
},
|
||||
{
|
||||
"rule": "integration_tests_passed",
|
||||
"description": "集成测试全部通过"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 三、执行计划操作接口
|
||||
|
||||
### 3.1 执行计划操作
|
||||
|
||||
```typescript
|
||||
// 执行计划操作接口
|
||||
interface ExecutionPlanOperations {
|
||||
// 基础操作
|
||||
create(plan: ExecutionPlanDefinition): Promise<ExecutionPlan>;
|
||||
validate(plan: ExecutionPlan): Promise<ValidationResult>;
|
||||
execute(planId: string, options?: ExecutionOptions): Promise<ExecutionSession>;
|
||||
pause(planId: string): Promise<void>;
|
||||
resume(planId: string): Promise<void>;
|
||||
abort(planId: string, reason: string): Promise<void>;
|
||||
|
||||
// 查询操作
|
||||
getStatus(planId: string): Promise<ExecutionStatus>;
|
||||
getProgress(planId: string): Promise<ProgressReport>;
|
||||
getMetrics(planId: string): Promise<PerformanceMetrics>;
|
||||
|
||||
// 修改操作
|
||||
updatePlan(planId: string, updates: Partial<ExecutionPlan>): Promise<ExecutionPlan>;
|
||||
addTask(planId: string, task: TaskDefinition): Promise<void>;
|
||||
removeTask(planId: string, taskId: string): Promise<void>;
|
||||
modifyDependency(planId: string, dependency: DependencyUpdate): Promise<void>;
|
||||
|
||||
// 高级操作
|
||||
optimizePlan(planId: string, criteria: OptimizationCriteria): Promise<OptimizedPlan>;
|
||||
simulateExecution(planId: string): Promise<SimulationResult>;
|
||||
generateReport(planId: string, format: 'json' | 'html' | 'markdown'): Promise<string>;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 执行状态查询
|
||||
|
||||
```json
|
||||
{
|
||||
"query_api": {
|
||||
"get_current_status": {
|
||||
"endpoint": "/execution-plans/{planId}/status",
|
||||
"response": {
|
||||
"plan_id": "EXEC-WFS-oauth-system-001",
|
||||
"status": "executing",
|
||||
"current_phase": "PHASE-002",
|
||||
"active_tasks": ["IMPL-003"],
|
||||
"progress": {
|
||||
"overall": 45,
|
||||
"current_phase": 60,
|
||||
"estimated_completion": "2025-09-07T08:30:00Z"
|
||||
},
|
||||
"agent_status": {
|
||||
"code-developer": "busy",
|
||||
"planning-agent": "idle",
|
||||
"test-agent": "idle"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"get_execution_timeline": {
|
||||
"endpoint": "/execution-plans/{planId}/timeline",
|
||||
"response": [
|
||||
{
|
||||
"timestamp": "2025-09-06T14:30:00Z",
|
||||
"event": "execution_started",
|
||||
"details": {"phase": "PHASE-001"}
|
||||
},
|
||||
{
|
||||
"timestamp": "2025-09-06T16:45:00Z",
|
||||
"event": "task_completed",
|
||||
"details": {"task_id": "IMPL-001", "duration": "PT2H15M"}
|
||||
},
|
||||
{
|
||||
"timestamp": "2025-09-06T17:00:00Z",
|
||||
"event": "task_started",
|
||||
"details": {"task_id": "IMPL-002", "agent": "code-developer"}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"get_performance_metrics": {
|
||||
"endpoint": "/execution-plans/{planId}/metrics",
|
||||
"response": {
|
||||
"execution_efficiency": 0.87,
|
||||
"average_task_duration": "PT2H30M",
|
||||
"agent_utilization": {
|
||||
"code-developer": 0.85,
|
||||
"planning-agent": 0.60,
|
||||
"test-agent": 0.40
|
||||
},
|
||||
"bottlenecks": [
|
||||
{
|
||||
"task_id": "IMPL-003",
|
||||
"reason": "complexity_underestimated",
|
||||
"impact": "15_minute_delay"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 四、执行计划模式库
|
||||
|
||||
### 4.1 常用执行模式模板
|
||||
|
||||
```json
|
||||
{
|
||||
"execution_patterns": {
|
||||
"feature_development": {
|
||||
"name": "Feature Development Pattern",
|
||||
"description": "Standard feature implementation workflow",
|
||||
"phases": [
|
||||
{"name": "Design", "mode": "sequential"},
|
||||
{"name": "Implementation", "mode": "parallel"},
|
||||
{"name": "Testing", "mode": "sequential"},
|
||||
{"name": "Integration", "mode": "sequential"}
|
||||
],
|
||||
"estimated_duration": "PT12H",
|
||||
"agent_requirements": ["planning-agent", "code-developer", "test-agent"],
|
||||
"success_rate": 0.92
|
||||
},
|
||||
|
||||
"bug_fix": {
|
||||
"name": "Bug Fix Pattern",
|
||||
"description": "Rapid bug diagnosis and resolution",
|
||||
"phases": [
|
||||
{"name": "Diagnosis", "mode": "sequential"},
|
||||
{"name": "Fix Implementation", "mode": "sequential"},
|
||||
{"name": "Verification", "mode": "parallel"}
|
||||
],
|
||||
"estimated_duration": "PT4H",
|
||||
"agent_requirements": ["code-developer", "test-agent"],
|
||||
"success_rate": 0.95
|
||||
},
|
||||
|
||||
"refactoring": {
|
||||
"name": "Code Refactoring Pattern",
|
||||
"description": "Safe code restructuring workflow",
|
||||
"phases": [
|
||||
{"name": "Analysis", "mode": "sequential"},
|
||||
{"name": "Planning", "mode": "sequential"},
|
||||
{"name": "Incremental Changes", "mode": "sequential"},
|
||||
{"name": "Validation", "mode": "parallel"}
|
||||
],
|
||||
"estimated_duration": "PT8H",
|
||||
"agent_requirements": ["code-review-agent", "code-developer", "test-agent"],
|
||||
"success_rate": 0.88
|
||||
},
|
||||
|
||||
"integration": {
|
||||
"name": "System Integration Pattern",
|
||||
"description": "Multi-component integration workflow",
|
||||
"phases": [
|
||||
{"name": "Compatibility Check", "mode": "parallel"},
|
||||
{"name": "Interface Design", "mode": "sequential"},
|
||||
{"name": "Integration Implementation", "mode": "parallel"},
|
||||
{"name": "End-to-End Testing", "mode": "sequential"}
|
||||
],
|
||||
"estimated_duration": "PT16H",
|
||||
"agent_requirements": ["planning-agent", "code-developer", "test-agent"],
|
||||
"success_rate": 0.83
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 执行优化建议
|
||||
|
||||
```json
|
||||
{
|
||||
"optimization_recommendations": {
|
||||
"parallelization_opportunities": [
|
||||
{
|
||||
"phase": "PHASE-003",
|
||||
"suggestion": "IMPL-005和IMPL-006可以并行执行",
|
||||
"estimated_time_saving": "PT2H",
|
||||
"risk_level": "low"
|
||||
}
|
||||
],
|
||||
|
||||
"resource_optimization": [
|
||||
{
|
||||
"recommendation": "在PHASE-001期间，test-agent处于空闲状态",
|
||||
"suggestion": "可以提前开始测试用例设计",
|
||||
"impact": "提高资源利用率15%"
|
||||
}
|
||||
],
|
||||
|
||||
"critical_path_optimization": [
|
||||
{
|
||||
"current_critical_path": "IMPL-001 → IMPL-002 → IMPL-003 → IMPL-004",
|
||||
"bottleneck": "IMPL-003 (JWT Token Service)",
|
||||
"optimization": "考虑将JWT实现分解为更小的子任务",
|
||||
"potential_benefit": "减少关键路径风险"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 五、实施指南
|
||||
|
||||
### 5.1 集成接口
|
||||
|
||||
```typescript
|
||||
// Claude Code命令集成
|
||||
interface TaskExecutionPlanIntegration {
|
||||
// 从任务分解生成执行计划
|
||||
generateFromBreakdown(taskBreakdown: TaskBreakdown): ExecutionPlan;
|
||||
|
||||
// 与Agent系统集成
|
||||
executeWithAgents(plan: ExecutionPlan): Promise<ExecutionResult>;
|
||||
|
||||
// 与监控系统集成
|
||||
setupMonitoring(plan: ExecutionPlan): MonitoringSession;
|
||||
|
||||
// 与文档系统集成
|
||||
syncWithDocuments(plan: ExecutionPlan): Promise<DocumentSyncResult>;
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 使用示例
|
||||
|
||||
```bash
|
||||
# 创建执行计划
|
||||
/task:plan create --from-breakdown IMPL-001 --template=feature_development
|
||||
|
||||
# 验证执行计划
|
||||
/task:plan validate EXEC-WFS-oauth-system-001
|
||||
|
||||
# 执行计划
|
||||
/task:plan execute EXEC-WFS-oauth-system-001 --mode=auto
|
||||
|
||||
# 监控执行状态
|
||||
/task:plan status EXEC-WFS-oauth-system-001 --dashboard
|
||||
|
||||
# 优化执行计划
|
||||
/task:plan optimize EXEC-WFS-oauth-system-001 --criteria=time_efficiency
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*本JSON Schema版本: v1.1 | 设计日期: 2025-09-06 | 兼容性: Claude Code v2.0+*
|
||||
@@ -1,308 +0,0 @@
|
||||
# 统一任务管理流程
|
||||
|
||||
## 架构概述
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Workflow Layer (宏观) │
|
||||
│ /workflow:init → plan → implement → review │
|
||||
│ workflow-session.json │
|
||||
└────────────────┬────────────────────────────┘
|
||||
│ 双向同步
|
||||
┌────────────────┴────────────────────────────┐
|
||||
│ Task Layer (微观) │
|
||||
│ /task:create → execute → status → sync │
|
||||
│ tasks.json │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 核心改进
|
||||
|
||||
### 1. 命令体系（精简版）
|
||||
**Workflow命令**（11个核心命令）：
|
||||
|
||||
**Session管理**：
|
||||
- `/workflow:session start` - 初始化并开始会话（含原init功能）
|
||||
- `/workflow:session pause` - 暂停当前会话
|
||||
- `/workflow:session resume` - 恢复会话
|
||||
|
||||
**阶段管理**：
|
||||
- `/workflow:plan` - 规划阶段（根据复杂度可选）
|
||||
- `/workflow:implement` - 实施阶段（集成simple/medium/complex模式）
|
||||
- `/workflow:review` - 评审阶段
|
||||
|
||||
**辅助功能**：
|
||||
- `/workflow:status` - 统一状态查看（含session状态）
|
||||
- `/workflow:sync` - 数据同步
|
||||
- `/workflow:context` - 上下文分析
|
||||
- `/workflow:issue` - Issue管理
|
||||
- `/workflow:replan` - 重新规划
|
||||
|
||||
**Task命令**（保持7个核心命令）：
|
||||
- `/task:create` - 创建任务
|
||||
- `/task:execute` - 执行任务
|
||||
- `/task:status` - 查看状态
|
||||
- `/task:replan` - 重新规划
|
||||
- `/task:sync` - 同步数据
|
||||
- `/task:breakdown` - 任务分解
|
||||
- `/task:context` - 上下文分析
|
||||
|
||||
### 2. JSON管理体系
|
||||
|
||||
#### workflow-session.json
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-2025-001",
|
||||
"project": "项目名称",
|
||||
"type": "simple|medium|complex",
|
||||
"current_phase": "PLAN|IMPLEMENT|REVIEW",
|
||||
"created": "2025-01-16T10:00:00Z",
|
||||
"phases": {
|
||||
"PLAN": {
|
||||
"status": "pending|active|completed",
|
||||
"output": "PLAN.md"
|
||||
},
|
||||
"IMPLEMENT": {
|
||||
"status": "pending|active|completed",
|
||||
"tasks": ["IMPL-001", "IMPL-002"],
|
||||
"completed_tasks": ["IMPL-001"],
|
||||
"progress": 50
|
||||
},
|
||||
"REVIEW": {
|
||||
"status": "pending|active|completed",
|
||||
"output": "REVIEW.md"
|
||||
}
|
||||
},
|
||||
"context": {
|
||||
"requirements": [],
|
||||
"scope": [],
|
||||
"issues": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### tasks.json
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-2025-001",
|
||||
"tasks": {
|
||||
"IMPL-001": {
|
||||
"id": "IMPL-001",
|
||||
"title": "任务标题",
|
||||
"status": "pending|in_progress|completed|blocked",
|
||||
"type": "feature|bugfix|refactor",
|
||||
"agent": "code-developer",
|
||||
"context": {},
|
||||
"created_at": "2025-01-16T12:00:00Z"
|
||||
}
|
||||
},
|
||||
"next_id": 2
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 双向同步机制
|
||||
|
||||
#### 自动同步点
|
||||
- Task创建 → 更新workflow tasks数组
|
||||
- Task完成 → 更新workflow progress
|
||||
- Workflow context变更 → 传播到tasks
|
||||
- Issue创建 → 关联到相关tasks
|
||||
|
||||
#### 同步命令
|
||||
- `/workflow:sync` - 全局文档同步
|
||||
- `/task:sync` - Task层同步
|
||||
|
||||
### 4. 统一执行流程
|
||||
|
||||
#### 简单任务流程（Bug修复）
|
||||
```bash
|
||||
# 初始化并开始
|
||||
/workflow:session start simple "修复登录按钮样式"
|
||||
→ 创建 workflow-session.json
|
||||
→ 设置复杂度: simple
|
||||
|
||||
# 直接实施（跳过规划）
|
||||
/workflow:implement --type=simple
|
||||
→ TodoWrite: 3-4项
|
||||
→ Agent: code-developer → code-review-agent
|
||||
→ 自动完成
|
||||
```
|
||||
|
||||
#### 中等复杂度流程（新特性）
|
||||
```bash
|
||||
# Step 1: 开始会话
|
||||
/workflow:session start medium "添加用户资料编辑功能"
|
||||
→ 创建 workflow-session.json
|
||||
→ 设置复杂度: medium
|
||||
|
||||
# Step 2: 轻量规划
|
||||
/workflow:plan
|
||||
→ 生成简单PLAN.md
|
||||
|
||||
# Step 3: 实施
|
||||
/workflow:implement --type=medium
|
||||
→ TodoWrite: 5-7项
|
||||
→ Agent: planning-agent → code-developer → code-review-agent
|
||||
|
||||
# Step 4: 暂停/恢复（如需要）
|
||||
/workflow:session pause
|
||||
/workflow:session resume
|
||||
|
||||
# Step 5: 评审
|
||||
/workflow:review
|
||||
```
|
||||
|
||||
#### 复杂系统流程（架构变更）
|
||||
```bash
|
||||
# Step 1: 开始复杂会话
|
||||
/workflow:session start complex "实现OAuth2认证系统"
|
||||
→ 创建 workflow-session.json
|
||||
→ 设置复杂度: complex
|
||||
|
||||
# Step 2: 详细规划
|
||||
/workflow:plan
|
||||
→ 生成: IMPLEMENTATION_PLAN.md, TASK_DECOMPOSITION.md
|
||||
→ 风险评估
|
||||
|
||||
# Step 3: 复杂实施
|
||||
/workflow:implement --type=complex
|
||||
→ TodoWrite: 7-10项
|
||||
→ 初始化 tasks.json
|
||||
→ 启用 task 命令
|
||||
|
||||
# Step 4: 任务管理
|
||||
/task:create "设计OAuth2架构"
|
||||
/task:breakdown IMPL-001
|
||||
/task:execute IMPL-001.1
|
||||
/task:status
|
||||
|
||||
# Step 5: 监控和同步
|
||||
/workflow:status # 查看整体进度
|
||||
/workflow:sync # 确保数据一致
|
||||
/task:sync # 任务层同步
|
||||
|
||||
# Step 6: 处理变更（如需要）
|
||||
/workflow:issue create "安全需求变更"
|
||||
/workflow:replan
|
||||
/task:replan IMPL-003
|
||||
|
||||
# Step 7: 评审和完成
|
||||
/workflow:review
|
||||
/workflow:session complete
|
||||
```
|
||||
|
||||
## 关键特性
|
||||
|
||||
### 1. 智能上下文感知
|
||||
- 基于Gemini的智能分析
|
||||
- 自动任务推荐
|
||||
- 依赖关系检测
|
||||
- 冲突预防
|
||||
|
||||
### 2. 状态持久化
|
||||
- JSON文件持久化所有状态
|
||||
- 支持会话恢复
|
||||
- 自动备份机制
|
||||
- 版本控制友好
|
||||
|
||||
### 3. 灵活性
|
||||
- 支持简单/中等/复杂三种模式
|
||||
- 可跳过规划直接实施
|
||||
- 支持任务重规划
|
||||
- 支持并行执行
|
||||
|
||||
### 4. 一致性保证
|
||||
- 双向同步机制
|
||||
- 数据完整性验证
|
||||
- 冲突自动解决
|
||||
- 实时进度计算
|
||||
|
||||
## 核心准则引用
|
||||
|
||||
所有命令共享以下核心准则（通过@引用）：
|
||||
- `session-management-principles.md` - 会话管理
|
||||
- `todowrite-coordination-rules.md` - TodoWrite协调
|
||||
- `agent-orchestration-patterns.md` - Agent编排
|
||||
- `dynamic-change-management.md` - 动态变更
|
||||
- `complexity-decision-tree.md` - 复杂度决策
|
||||
- `task-decomposition-integration.md` - 任务分解
|
||||
- `gemini-intelligent-context.md` - 智能上下文
|
||||
|
||||
## 优势总结
|
||||
|
||||
1. **清晰分层**：Workflow管理宏观流程，Task处理具体执行
|
||||
2. **完整持久化**：所有状态通过JSON文件管理
|
||||
3. **自动同步**：双向同步保证数据一致性
|
||||
4. **命令精简**：减少认知负担，易于使用
|
||||
5. **智能增强**：Gemini驱动的上下文分析
|
||||
6. **统一流程**：标准化的项目管理流程
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 简单任务（bug修复）
|
||||
/workflow:session start simple "修复登录问题"
|
||||
/workflow:implement --type=simple
|
||||
# 自动完成
|
||||
|
||||
# 中等任务（新特性）
|
||||
/workflow:session start medium "用户资料编辑"
|
||||
/workflow:plan # 轻量规划
|
||||
/workflow:implement --type=medium # 执行实施
|
||||
/workflow:review # 质量评审
|
||||
|
||||
# 复杂项目（系统级）
|
||||
/workflow:session start complex "OAuth2集成"
|
||||
/workflow:plan # 详细规划
|
||||
/workflow:implement --type=complex # 复杂实施
|
||||
/task:create "设计OAuth2架构" # 创建任务
|
||||
/task:breakdown IMPL-001 # 任务分解
|
||||
/task:execute IMPL-001.1 # 执行子任务
|
||||
/workflow:status # 查看状态
|
||||
/workflow:review # 最终评审
|
||||
```
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── commands/
|
||||
│ ├── workflow/
|
||||
│ │ ├── session.md # 会话管理(start/pause/resume)
|
||||
│ │ ├── plan.md # 规划阶段
|
||||
│ │ ├── implement.md # 实施阶段(含3种模式)
|
||||
│ │ ├── review.md # 评审阶段
|
||||
│ │ ├── status.md # 统一状态
|
||||
│ │ ├── sync.md # 数据同步
|
||||
│ │ ├── context.md # 上下文分析
|
||||
│ │ ├── issue.md # Issue管理
|
||||
│ │ └── replan.md # 重新规划
|
||||
│ └── task/
|
||||
│ ├── create.md # 创建任务
|
||||
│ ├── execute.md # 执行任务
|
||||
│ ├── status.md # 任务状态
|
||||
│ ├── replan.md # 任务重规划
|
||||
│ ├── sync.md # 任务同步
|
||||
│ ├── breakdown.md # 任务分解
|
||||
│ └── context.md # 任务上下文
|
||||
├── schemas/
|
||||
│ ├── workflow-session.json # 会话schema
|
||||
│ └── task.json # 任务schema
|
||||
└── workflows/
|
||||
├── session-management-principles.md
|
||||
├── todowrite-coordination-rules.md
|
||||
├── agent-orchestration-patterns.md
|
||||
├── task-decomposition-integration.md
|
||||
├── complexity-decision-tree.md
|
||||
└── [其他核心准则]
|
||||
|
||||
工作目录/
|
||||
├── workflow-session.json # 会话状态
|
||||
├── tasks.json # 任务数据
|
||||
├── PLAN.md # 规划文档(可选)
|
||||
├── REVIEW.md # 评审报告
|
||||
└── .workflow/ # 工作目录
|
||||
└── WFS-2025-001/ # 会话工作空间
|
||||
```
|
||||
|
||||
此统一任务管理流程提供了清晰、高效、智能的项目管理体系。
|
||||
@@ -1,523 +0,0 @@
|
||||
# Workflow Document System - Complete Integration Guide
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
This document provides a comprehensive guide to the integrated workflow document system that successfully merges the original design philosophy with the current command architecture. The system follows the core principle: **"Documents store primary plans, JSON manages state"**.
|
||||
|
||||
## 📋 Core Design Philosophy
|
||||
|
||||
### Document-State Separation
|
||||
- **Documents (Markdown)**: Store requirements, task decomposition, implementation strategies, and acceptance criteria
|
||||
- **JSON States**: Manage execution status, progress tracking, session coordination, and real-time state changes
|
||||
- **Bidirectional Sync**: Automatic coordination between planning documents and state management systems
|
||||
|
||||
### Planning-First Approach
|
||||
**"Measure twice, cut once"** - Comprehensive planning prevents costly mistakes and ensures quality outcomes.
|
||||
|
||||
## 🏗️ Complete Directory Structure
|
||||
|
||||
### Unified Workflow Directory
|
||||
```
|
||||
.workflow/WFS-[topic-slug]/
|
||||
├── workflow-session.json # Session state and document tracking
|
||||
├── PLAN.md # Basic planning (all complexities)
|
||||
├── IMPLEMENTATION_PLAN.md # Staged execution plan (complex only)
|
||||
├── TASK_DECOMPOSITION.md # Task breakdown (medium+/complex)
|
||||
├── TODO_CHECKLIST.md # Progress tracking (medium+/complex)
|
||||
├── .task/ # Task management system
|
||||
│ └── tasks/ # Individual task JSON files
|
||||
│ ├── IMPL-001.json
|
||||
│ ├── IMPL-002.json
|
||||
│ └── IMPL-003.json
|
||||
└── artifacts/ # Generated files and logs
|
||||
├── reports/ # Progress and analysis reports
|
||||
├── logs/ # Execution logs and checkpoints
|
||||
└── execution/ # Task execution artifacts
|
||||
└── IMPL-001/
|
||||
├── summary.json
|
||||
├── outputs/
|
||||
└── logs/
|
||||
```
|
||||
|
||||
## 📄 Document Types and Usage
|
||||
|
||||
### 1. PLAN.md - Universal Planning Document
|
||||
**Generated for**: All workflow complexities
|
||||
**Purpose**: Basic planning and task identification
|
||||
|
||||
```markdown
|
||||
# Implementation Plan - [Project Name]
|
||||
|
||||
## Overview
|
||||
Brief description of what needs to be implemented
|
||||
|
||||
## Requirements
|
||||
- [Inherited from workflow session context]
|
||||
- [Specific functional requirements]
|
||||
|
||||
## Task Breakdown
|
||||
- IMPL-001: [Task description]
|
||||
- IMPL-002: [Task description]
|
||||
- IMPL-003: [Task description]
|
||||
|
||||
## Dependencies
|
||||
- Task order and relationships
|
||||
- External dependencies
|
||||
|
||||
## Success Criteria
|
||||
- Acceptance criteria for completion
|
||||
- Definition of done
|
||||
```
|
||||
|
||||
### 2. IMPLEMENTATION_PLAN.md - Complex Workflow Strategy
|
||||
**Generated for**: Complex workflows only
|
||||
**Purpose**: Detailed staged execution plan with risk assessment
|
||||
|
||||
```markdown
|
||||
# Implementation Plan - [Project Name]
|
||||
|
||||
## Executive Summary
|
||||
High-level overview and strategic approach
|
||||
|
||||
## 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
|
||||
- **Dependencies**: Phase 1 completion
|
||||
|
||||
### Phase 3: Integration & Testing
|
||||
- **Objective**: [System integration and validation]
|
||||
- **Tasks**: IMPL-006, IMPL-007
|
||||
|
||||
## Risk Assessment
|
||||
- **High Risk**: [Description] - Mitigation: [Strategy]
|
||||
- **Medium Risk**: [Description] - Mitigation: [Strategy]
|
||||
|
||||
## Quality Gates
|
||||
- Code review requirements
|
||||
- Testing coverage targets
|
||||
- Performance benchmarks
|
||||
|
||||
## Rollback Strategy
|
||||
- Rollback triggers and procedures
|
||||
- Data preservation approach
|
||||
```
|
||||
|
||||
### 3. TASK_DECOMPOSITION.md - Hierarchical Task Breakdown
|
||||
**Generated for**: Medium+ workflows when triggered, Complex workflows always
|
||||
**Purpose**: Detailed task hierarchy with dependencies and context
|
||||
|
||||
```markdown
|
||||
# Task Decomposition - [Project Name]
|
||||
|
||||
## Task Hierarchy
|
||||
|
||||
### IMPL-001: [Parent Task Name]
|
||||
**Owner**: [Agent Type]
|
||||
**Effort**: [Estimate]
|
||||
**Status**: [pending|active|completed]
|
||||
|
||||
#### Context
|
||||
- **Requirements**: [Specific requirements for this task]
|
||||
- **Scope**: [Files and components to be modified]
|
||||
- **Acceptance Criteria**: [What constitutes completion]
|
||||
|
||||
#### Subtasks
|
||||
- IMPL-001.1: [Subtask name] - [Agent] - [Status]
|
||||
- IMPL-001.2: [Subtask name] - [Agent] - [Status]
|
||||
|
||||
#### Dependencies
|
||||
- **Upstream**: [Tasks that must complete first]
|
||||
- **Downstream**: [Tasks blocked by this task]
|
||||
|
||||
## Execution Order
|
||||
1. **Parallel Track A**: IMPL-001, IMPL-003
|
||||
2. **Sequential**: IMPL-002 (depends on Track A)
|
||||
3. **Final**: IMPL-006 (depends on all above)
|
||||
|
||||
## Progress Tracking
|
||||
- **Total Tasks**: [Count]
|
||||
- **Completed**: [Count] ([Percentage]%)
|
||||
- **In Progress**: [Count]
|
||||
- **Blocked**: [Count]
|
||||
```
|
||||
|
||||
### 4. TODO_CHECKLIST.md - Progress Tracking
|
||||
**Generated for**: Medium+ workflows when triggered, Complex workflows always
|
||||
**Purpose**: Real-time progress tracking with task status
|
||||
|
||||
```markdown
|
||||
# TODO Checklist - [Project Name]
|
||||
|
||||
## Progress Overview
|
||||
- **Overall Progress**: [X]% ([completed]/[total] items)
|
||||
- **Current Phase**: [Phase name]
|
||||
- **Active Tasks**: [Count]
|
||||
|
||||
## Phase 1: Foundation
|
||||
### IMPL-001: [Task Name]
|
||||
- [ ] **IMPL-001.1**: [Subtask] ([Agent])
|
||||
- [ ] Design component interface
|
||||
- [x] Implement basic structure
|
||||
- [ ] Add unit tests
|
||||
- [x] **IMPL-001.2**: [Completed subtask] ([Agent])
|
||||
|
||||
**Status**: In Progress (1/2 subtasks complete)
|
||||
|
||||
## Blocked Items
|
||||
- **IMPL-003**: Waiting for API specification
|
||||
- **Blocker**: External dependency
|
||||
- **Action**: Follow up with API team
|
||||
|
||||
## Completed Items ✅
|
||||
- **IMPL-000**: [Completed task] - Completed [Date]
|
||||
|
||||
## Cross-References
|
||||
- Task Details: See TASK_DECOMPOSITION.md
|
||||
- Implementation Strategy: See IMPLEMENTATION_PLAN.md
|
||||
```
|
||||
|
||||
## 🔄 Document Generation Rules
|
||||
|
||||
### Complexity-Based Generation
|
||||
|
||||
#### Simple Workflows
|
||||
**Document Requirements**: Minimal or skip documentation
|
||||
- **Generated**: Optional basic PLAN.md
|
||||
- **Focus**: Direct implementation over documentation
|
||||
- **Use Cases**: Single file changes, bug fixes, small modifications
|
||||
|
||||
#### Medium Workflows
|
||||
**Document Requirements**: Structured planning with conditional decomposition
|
||||
- **Always Generated**: PLAN.md
|
||||
- **Conditionally Generated**: TASK_DECOMPOSITION.md + TODO_CHECKLIST.md
|
||||
- **Trigger Conditions**:
|
||||
- Task involves >3 modules/components
|
||||
- >5 distinct subtasks identified
|
||||
- Complex interdependencies detected
|
||||
- Estimated effort >4 hours
|
||||
|
||||
#### Complex Workflows
|
||||
**Document Requirements**: Complete documentation suite (MANDATORY)
|
||||
- **Always Generated**:
|
||||
- PLAN.md
|
||||
- IMPLEMENTATION_PLAN.md
|
||||
- TASK_DECOMPOSITION.md
|
||||
- TODO_CHECKLIST.md
|
||||
- **Use Cases**: Architecture changes, security implementations, system integrations
|
||||
|
||||
### Automatic Generation Triggers
|
||||
|
||||
```
|
||||
Medium Complexity Triggers:
|
||||
IF (modules_affected > 3) OR
|
||||
(subtasks_count > 5) OR
|
||||
(estimated_effort > "4h") OR
|
||||
(dependencies_count > 2)
|
||||
THEN generate_task_decomposition()
|
||||
|
||||
Complex Complexity Triggers:
|
||||
IF (architecture_changes = true) OR
|
||||
(security_implementation = true) OR
|
||||
(performance_optimization = true) OR
|
||||
(estimated_effort > "8h") OR
|
||||
(risk_level = "high")
|
||||
THEN generate_full_documentation_suite()
|
||||
```
|
||||
|
||||
## 🔧 Command Integration
|
||||
|
||||
### Workflow Commands Integration
|
||||
|
||||
#### /workflow:session start
|
||||
```bash
|
||||
/workflow:session start <complexity> "task description"
|
||||
```
|
||||
**Document Actions**:
|
||||
- Creates session directory structure
|
||||
- Initializes document templates based on complexity
|
||||
- Prepares JSON state files with document references
|
||||
- Sets up document generation capabilities
|
||||
|
||||
#### /workflow:plan
|
||||
```bash
|
||||
/workflow:plan [--force-complex|--force-simple]
|
||||
```
|
||||
**Document Actions**:
|
||||
- Generates PLAN.md for all complexities
|
||||
- Generates IMPLEMENTATION_PLAN.md for complex workflows
|
||||
- Updates workflow-session.json with document references
|
||||
- Creates document directory structure
|
||||
|
||||
#### /workflow:implement
|
||||
```bash
|
||||
/workflow:implement --type=<simple|medium|complex>
|
||||
```
|
||||
**Document Actions**:
|
||||
- Checks decomposition triggers for medium workflows
|
||||
- MANDATORY generates TASK_DECOMPOSITION.md + TODO_CHECKLIST.md for complex
|
||||
- Creates individual task JSON files linked to documents
|
||||
- Synchronizes task creation between documents and JSON states
|
||||
|
||||
### Task Commands Integration
|
||||
|
||||
#### /task:create
|
||||
```bash
|
||||
/task:create "task title" [--from-decomposition]
|
||||
```
|
||||
**Document Actions**:
|
||||
- Updates TASK_DECOMPOSITION.md and TODO_CHECKLIST.md if they exist
|
||||
- Can import from existing TASK_DECOMPOSITION.md structure
|
||||
- Maintains cross-references between documents and JSON
|
||||
- Triggers document generation if conditions are met
|
||||
|
||||
#### /task:status
|
||||
```bash
|
||||
/task:status [--format=tree|list|json] [--detailed]
|
||||
```
|
||||
**Document Actions**:
|
||||
- Displays progress from TODO_CHECKLIST.md
|
||||
- Shows document-based task hierarchy
|
||||
- Indicates document sync status
|
||||
- Provides document-aware progress reporting
|
||||
|
||||
#### /task:breakdown
|
||||
```bash
|
||||
/task:breakdown <task-id> [--strategy=auto|interactive]
|
||||
```
|
||||
**Document Actions**:
|
||||
- Generates/updates TASK_DECOMPOSITION.md
|
||||
- Creates corresponding TODO_CHECKLIST.md entries
|
||||
- Maintains parent-child relationships in documents
|
||||
- Updates document cross-references
|
||||
|
||||
#### /task:execute
|
||||
```bash
|
||||
/task:execute <task-id> [--mode=auto|guided|review]
|
||||
```
|
||||
**Document Actions**:
|
||||
- Uses context from TASK_DECOMPOSITION.md if available
|
||||
- Updates TODO_CHECKLIST.md progress during execution
|
||||
- Stores execution artifacts in structured directory
|
||||
- Maintains document-JSON synchronization
|
||||
|
||||
## 🔄 Document-JSON Coordination
|
||||
|
||||
### Data Ownership Rules
|
||||
|
||||
#### Documents Own (Source of Truth)
|
||||
- Requirements and scope definition
|
||||
- Task breakdown and structure
|
||||
- Implementation strategies and approaches
|
||||
- Acceptance criteria and quality standards
|
||||
- Risk assessments and mitigation plans
|
||||
|
||||
#### JSON States Own (Source of Truth)
|
||||
- Current execution status (pending/active/completed/blocked)
|
||||
- Progress percentages and timing
|
||||
- Agent assignments and execution results
|
||||
- Session metadata and timestamps
|
||||
- Dynamic state changes
|
||||
|
||||
#### Shared Responsibility (Synchronized)
|
||||
- Task hierarchies (structure in docs, status in JSON)
|
||||
- Dependencies (defined in docs, status tracked in JSON)
|
||||
- Progress tracking (structure in docs, current state in JSON)
|
||||
|
||||
### Synchronization Mechanisms
|
||||
|
||||
#### Document → JSON Updates
|
||||
```
|
||||
Event: Task decomposition document created
|
||||
Action:
|
||||
- Create corresponding task entries in JSON
|
||||
- Import task hierarchy and dependencies
|
||||
- Initialize status as "pending"
|
||||
- Link JSON tasks to document sections
|
||||
```
|
||||
|
||||
#### JSON → Document Updates
|
||||
```
|
||||
Event: Task status changed in JSON
|
||||
Action:
|
||||
- Update TODO_CHECKLIST.md with new status
|
||||
- Update progress percentages
|
||||
- Mark completion timestamps
|
||||
- Update dependency blocking status
|
||||
```
|
||||
|
||||
### Session State with Document Tracking
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-[topic-slug]",
|
||||
"project": "OAuth2 authentication system",
|
||||
"type": "complex",
|
||||
"status": "active",
|
||||
"current_phase": "IMPLEMENT",
|
||||
"directory": ".workflow/WFS-[topic-slug]",
|
||||
"documents": {
|
||||
"planning": {
|
||||
"PLAN.md": {
|
||||
"status": "generated",
|
||||
"path": ".workflow/WFS-[topic-slug]/PLAN.md"
|
||||
},
|
||||
"IMPLEMENTATION_PLAN.md": {
|
||||
"status": "generated",
|
||||
"path": ".workflow/WFS-[topic-slug]/IMPLEMENTATION_PLAN.md"
|
||||
}
|
||||
},
|
||||
"implementation": {
|
||||
"TASK_DECOMPOSITION.md": {
|
||||
"status": "generated",
|
||||
"path": ".workflow/WFS-[topic-slug]/TASK_DECOMPOSITION.md"
|
||||
},
|
||||
"TODO_CHECKLIST.md": {
|
||||
"status": "generated",
|
||||
"path": ".workflow/WFS-[topic-slug]/TODO_CHECKLIST.md"
|
||||
}
|
||||
}
|
||||
},
|
||||
"task_system": {
|
||||
"enabled": true,
|
||||
"directory": ".workflow/WFS-[topic-slug]/.task",
|
||||
"next_task_id": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Individual Task JSON Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Build authentication module",
|
||||
"status": "pending",
|
||||
"type": "feature",
|
||||
"agent": "code-developer",
|
||||
"effort": "4h",
|
||||
"context": {
|
||||
"inherited_from": "WFS-[topic-slug]",
|
||||
"requirements": ["JWT authentication", "OAuth2 support"],
|
||||
"scope": ["src/auth/*", "tests/auth/*"],
|
||||
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"]
|
||||
},
|
||||
"dependencies": {
|
||||
"upstream": [],
|
||||
"downstream": ["IMPL-002"]
|
||||
},
|
||||
"subtasks": [],
|
||||
"execution": {
|
||||
"attempts": 0,
|
||||
"current_attempt": null,
|
||||
"history": []
|
||||
},
|
||||
"metadata": {
|
||||
"created_at": "2025-09-05T10:30:00Z",
|
||||
"last_updated": "2025-09-05T10:30:00Z",
|
||||
"last_sync": "2025-09-05T10:30:00Z",
|
||||
"version": "1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🚀 Usage Examples
|
||||
|
||||
### Example 1: Simple Bug Fix
|
||||
```bash
|
||||
# Start simple workflow - minimal documentation
|
||||
/workflow:session start simple "fix login timeout issue"
|
||||
/workflow:implement --type=simple
|
||||
# Documents: Optional PLAN.md or skip documentation
|
||||
# Focus: Direct implementation
|
||||
```
|
||||
|
||||
### Example 2: Medium Feature Implementation
|
||||
```bash
|
||||
# Start medium workflow - structured planning
|
||||
/workflow:session start medium "add user profile editing"
|
||||
/workflow:plan # Generates PLAN.md
|
||||
/workflow:implement --type=medium
|
||||
# If >3 modules detected: Auto-generates TASK_DECOMPOSITION.md + TODO_CHECKLIST.md
|
||||
```
|
||||
|
||||
### Example 3: Complex System Integration
|
||||
```bash
|
||||
# Start complex workflow - full documentation suite
|
||||
/workflow:session start complex "implement OAuth2 authentication"
|
||||
/workflow:plan # Generates PLAN.md + IMPLEMENTATION_PLAN.md
|
||||
/workflow:implement --type=complex
|
||||
# MANDATORY: Generates TASK_DECOMPOSITION.md + TODO_CHECKLIST.md
|
||||
```
|
||||
|
||||
### Example 4: Task Management with Documents
|
||||
```bash
|
||||
# Create tasks from decomposition document
|
||||
/task:create --from-decomposition
|
||||
# Monitor progress with document integration
|
||||
/task:status --format=tree # Shows document-based hierarchy
|
||||
# Execute with document context
|
||||
/task:execute IMPL-001 # Uses TASK_DECOMPOSITION.md context
|
||||
```
|
||||
|
||||
## 🎯 Key Benefits
|
||||
|
||||
### 1. **Unified Planning System**
|
||||
- Consistent document formats across all workflow types
|
||||
- Clear complexity-based requirements
|
||||
- Automatic generation based on triggers
|
||||
|
||||
### 2. **Seamless Integration**
|
||||
- Documents and JSON work together automatically
|
||||
- No manual synchronization required
|
||||
- Real-time coordination between planning and execution
|
||||
|
||||
### 3. **Scalable Complexity Management**
|
||||
- Simple tasks: minimal overhead
|
||||
- Medium tasks: structured when needed
|
||||
- Complex tasks: comprehensive documentation
|
||||
|
||||
### 4. **Comprehensive Tracking**
|
||||
- Progress visible in both documents and JSON
|
||||
- Cross-references maintained automatically
|
||||
- Full audit trail of decisions and changes
|
||||
|
||||
### 5. **Original Design Preserved**
|
||||
- **Documents**: Store primary plans and strategies
|
||||
- **JSON**: Manage execution state and progress
|
||||
- **Coordination**: Automatic bidirectional sync
|
||||
|
||||
## 📚 Technical Documentation References
|
||||
|
||||
**Core System Architecture**:
|
||||
- `@~/.claude/workflows/unified-workflow-system-principles.md` - **Master reference for all core principles**
|
||||
|
||||
**Implementation Details**:
|
||||
- `@~/.claude/workflows/workflow-document-management-principles.md` - Document generation templates and rules
|
||||
- `@~/.claude/workflows/hierarchical-document-splitting-system.md` - **Hierarchical document splitting with 3-level structure**
|
||||
- `@~/.claude/workflows/session-management-principles.md` - Session state management implementation
|
||||
- `@~/.claude/workflows/task-management-principles.md` - Task JSON schemas and validation
|
||||
- `@~/.claude/workflows/file-structure-establishment-process.md` - Directory structure creation process
|
||||
- `@~/.claude/workflows/json-document-coordination-system.md` - Technical synchronization details
|
||||
|
||||
## 🎉 Success Metrics
|
||||
|
||||
### Implementation Success
|
||||
✅ **Complete Document System**: All 4 document types implemented and integrated
|
||||
✅ **Hierarchical Structure**: 3-level progressive document splitting (Level 0/1/2)
|
||||
✅ **Unified Directory Structure**: Consistent `.workflow/WFS-[topic-slug]/` format across all commands
|
||||
✅ **Smart Document Management**: Automatic splitting/merging based on project scale
|
||||
✅ **Automatic Generation**: Smart triggers based on complexity and conditions
|
||||
✅ **Bidirectional Sync**: Documents and JSON states coordinate seamlessly
|
||||
✅ **Command Integration**: All workflow and task commands support hierarchical document system
|
||||
✅ **Scalable Architecture**: Handles projects from simple fixes to complex systems (>100 tasks)
|
||||
✅ **Original Design Fusion**: Successfully merged original workflow.md vision with current architecture
|
||||
|
||||
The workflow document system now fully realizes the vision of **"Documents for primary plans, JSON for state management"** while providing a scalable, integrated, and user-friendly development workflow experience.
|
||||
@@ -1,130 +0,0 @@
|
||||
# 工作流系统更新总结
|
||||
|
||||
## 更新概览
|
||||
已完成工作流命令体系的全面重构和相关文档更新。
|
||||
|
||||
## 主要更新内容
|
||||
|
||||
### 1. 命令体系重构 ✅
|
||||
**精简前**: 15+ 个独立命令
|
||||
**精简后**: 11 个核心命令
|
||||
|
||||
#### 核心变更
|
||||
- ✅ `workflow:init` 合并到 `workflow:session start`
|
||||
- ✅ `workflow:simple/medium/complex` 集成到 `workflow:implement --type=`
|
||||
- ✅ `workflow:session status` 合并到 `workflow:status`
|
||||
- ✅ 移除 `workflow:session complete`（自动完成）
|
||||
|
||||
### 2. Session 职责明确 ✅
|
||||
**session.md 现在只负责**：
|
||||
- 会话初始化 (start)
|
||||
- 会话暂停 (pause)
|
||||
- 会话恢复 (resume)
|
||||
- 状态管理
|
||||
|
||||
**不再包含**：
|
||||
- 执行功能（由 implement 负责）
|
||||
- 完成命令（自动处理）
|
||||
|
||||
### 3. 文档更新完成 ✅
|
||||
|
||||
#### 核心文档
|
||||
- ✅ `UNIFIED_TASK_MANAGEMENT.md` - 统一管理流程
|
||||
- ✅ `COMMAND_ARCHITECTURE_V2.md` - 新架构说明
|
||||
- ✅ `COMMAND_CHEATSHEET.md` - 命令速查表
|
||||
- ✅ `REFACTORING_COMPLETE.md` - 重构报告
|
||||
|
||||
#### 命令文档
|
||||
- ✅ `workflow/session.md` - 纯会话管理
|
||||
- ✅ `workflow/implement.md` - 集成三种模式
|
||||
- ✅ `workflow/status.md` - 统一状态查看
|
||||
- ✅ `workflow/plan.md` - 规划阶段
|
||||
- ✅ `workflow/review.md` - 评审阶段
|
||||
|
||||
#### 输出样式更新
|
||||
- ✅ `output-styles/agent-workflow-coordination.md`
|
||||
- 更新所有命令引用
|
||||
- 添加新命令架构说明
|
||||
- 更新工作流示例
|
||||
- 修正 session 集成说明
|
||||
|
||||
### 4. 新的执行流程
|
||||
|
||||
#### 简单任务 (Bug修复)
|
||||
```bash
|
||||
/workflow:session start simple "修复bug"
|
||||
/workflow:implement --type=simple
|
||||
# 完成
|
||||
```
|
||||
|
||||
#### 中等任务 (新特性)
|
||||
```bash
|
||||
/workflow:session start medium "新特性"
|
||||
/workflow:plan # 轻量规划
|
||||
/workflow:implement --type=medium # 执行
|
||||
/workflow:review # 评审
|
||||
```
|
||||
|
||||
#### 复杂任务 (系统级)
|
||||
```bash
|
||||
/workflow:session start complex "系统重构"
|
||||
/workflow:plan # 详细规划
|
||||
/workflow:implement --type=complex # 复杂执行
|
||||
/task:create "子任务" # 任务管理
|
||||
/workflow:status # 监控
|
||||
/workflow:review # 最终评审
|
||||
```
|
||||
|
||||
### 5. 关键改进
|
||||
|
||||
#### 用户体验
|
||||
- 🎯 **更少命令**: 认知负担降低
|
||||
- 🔄 **清晰职责**: 每个命令单一功能
|
||||
- 📊 **统一状态**: 一个命令查看所有信息
|
||||
- 🚀 **灵活模式**: implement 支持所有复杂度
|
||||
|
||||
#### 技术架构
|
||||
- 📁 **JSON 管理**: 完整状态持久化
|
||||
- 🔄 **双向同步**: workflow ↔ task 同步
|
||||
- 💾 **会话恢复**: 完整暂停/恢复支持
|
||||
- 🎯 **模块化**: 命令可独立使用
|
||||
|
||||
## 验证清单
|
||||
|
||||
### 命令测试
|
||||
- [x] Session 命令只做会话管理
|
||||
- [x] Implement 支持三种复杂度模式
|
||||
- [x] Status 显示统一视图
|
||||
- [x] 移除冗余命令
|
||||
|
||||
### 文档一致性
|
||||
- [x] 所有命令示例使用新语法
|
||||
- [x] 架构图反映新结构
|
||||
- [x] 速查表准确无误
|
||||
- [x] agent-workflow-coordination.md 更新完成
|
||||
|
||||
### 向后兼容
|
||||
- [x] 核心功能完全保留
|
||||
- [x] Agent 流程不变
|
||||
- [x] TodoWrite 机制不变
|
||||
- [x] 数据格式兼容
|
||||
|
||||
## 下一步建议
|
||||
|
||||
1. **测试验证**: 实际运行所有命令路径
|
||||
2. **用户反馈**: 收集使用体验
|
||||
3. **性能优化**: 监控 JSON 同步性能
|
||||
4. **文档维护**: 根据使用更新示例
|
||||
|
||||
## 总结
|
||||
|
||||
✅ 成功完成工作流系统精简
|
||||
✅ 所有相关文档已更新
|
||||
✅ 命令职责清晰分离
|
||||
✅ 保持完整功能同时提升易用性
|
||||
|
||||
系统现在更加：
|
||||
- **精简** - 更少但更强大的命令
|
||||
- **清晰** - 明确的职责划分
|
||||
- **统一** - 一致的使用体验
|
||||
- **灵活** - 适应不同复杂度需求
|
||||
@@ -1,176 +0,0 @@
|
||||
# gemini-execute Implementation Summary
|
||||
|
||||
## Overview
|
||||
Created `gemini-execute` - an intelligent context inference executor that combines Gemini CLI analysis with Claude Code implementation capabilities, featuring auto-approval functionality for workflow automation.
|
||||
|
||||
## What Was Implemented
|
||||
|
||||
### Core Architecture
|
||||
**gemini-execute** = **Intelligent Context Inference** + **Gemini CLI Integration** + **--yolo Auto-approval** + **Workflow Integration**
|
||||
|
||||
### Key Features Delivered
|
||||
|
||||
#### 1. Dual Execution Modes
|
||||
- **Mode 1**: User description with intelligent context inference
|
||||
- Automatic keyword recognition (React → .jsx/.tsx files)
|
||||
- Smart file pattern generation based on domain mapping
|
||||
- User override capability with `@{custom/path}` syntax
|
||||
|
||||
- **Mode 2**: Task ID execution with automatic context collection
|
||||
- Reads `.task/impl-*.json` task definitions
|
||||
- Analyzes task type, scope, and requirements
|
||||
- Integrates brainstorming_refs and related files
|
||||
|
||||
#### 2. Intelligent Inference Engine
|
||||
- **Keyword Mapping Table**: 7 categories covering frontend, auth, API, data, performance, testing, configuration
|
||||
- **Task Type Inference**: 5 task types (feature, bugfix, refactor, performance, test) with specific file patterns
|
||||
- **Progressive Inference**: From precise to broad pattern matching
|
||||
|
||||
#### 3. Auto-Approval Capabilities
|
||||
- **--yolo Mode**: Non-interactive execution for workflow automation
|
||||
- **Auto-approved Operations**: File pattern inference, Gemini CLI execution, code modifications, documentation generation
|
||||
- **Workflow Integration**: Seamless task execution in automated pipelines
|
||||
|
||||
#### 4. Workflow System Integration
|
||||
- **Documentation Generation**: Follows `unified-workflow-system-principles.md`
|
||||
- **Progress Tracking**: Updates TODO_LIST.md and workflow-session.json
|
||||
- **Summary Creation**: Generates structured task summaries in `.summaries/` directory
|
||||
|
||||
### Technical Implementation
|
||||
|
||||
#### Command Definition File
|
||||
**Location**: `D:\claudecode_dms2\.claude\commands\gemini-execute.md`
|
||||
|
||||
**Key Sections**:
|
||||
- YAML header with usage examples and parameters
|
||||
- Intelligent inference engine documentation
|
||||
- Two execution mode specifications
|
||||
- Keyword mapping and task type inference tables
|
||||
- Gemini CLI integration patterns
|
||||
- Workflow system integration guidelines
|
||||
- Error handling and performance optimization
|
||||
|
||||
#### Integration Points
|
||||
|
||||
- **Workflow Principles**: Implements `unified-workflow-system-principles.md`
|
||||
- **Code Developer Pattern**: Extends functionality from `code-developer.md` agent
|
||||
- **Template System**: Utilizes existing prompt templates and context loading
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
### Design Principles
|
||||
1. **Simplicity**: No separate bash script required - embedded logic in command file
|
||||
2. **Intelligence**: Automatic context inference reduces user cognitive load
|
||||
3. **Flexibility**: Supports both guided (intelligent inference) and explicit (user override) modes
|
||||
4. **Automation**: --yolo mode enables workflow automation and CI/CD integration
|
||||
|
||||
### Technical Choices
|
||||
- **Single File Implementation**: All logic contained in markdown command definition
|
||||
- **Keyword-Based Inference**: Scalable mapping system for file pattern generation
|
||||
- **Task Type Analysis**: JSON-based task definition parsing for context collection
|
||||
- **Gemini CLI Integration**: Direct CLI calls following established guidelines
|
||||
|
||||
## Workflow Integration Capabilities
|
||||
|
||||
### Session Management
|
||||
- Automatic workflow session detection and creation
|
||||
- Task ID generation following IMPL-* convention
|
||||
- Progress tracking and status synchronization
|
||||
|
||||
### Documentation Generation
|
||||
```markdown
|
||||
# Task Summary: [Task-ID] [Description]
|
||||
## Execution Content
|
||||
- Intelligently Inferred Files: [patterns]
|
||||
- Gemini Analysis Results: [findings]
|
||||
- Implemented Features: [content]
|
||||
- Modified Files: [file:line references]
|
||||
|
||||
## Issues Resolved
|
||||
- [problem list]
|
||||
|
||||
## Links
|
||||
- [🔙 Back to Task List](../TODO_LIST.md#[Task-ID])
|
||||
- [📋 Implementation Plan](../IMPL_PLAN.md#[Task-ID])
|
||||
```
|
||||
|
||||
### Command Coordination
|
||||
- **gemini-chat**: Analysis → **gemini-execute**: Analysis + Implementation
|
||||
- **gemini-mode**: Advanced analysis → **gemini-execute**: Execution-focused
|
||||
- **code-developer**: Manual context → **gemini-execute**: Intelligent inference
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Quick Implementation
|
||||
```bash
|
||||
/gemini-execute "implement user authentication system" --yolo
|
||||
# Infers: **/*auth*,**/*login*,**/*session* + src/**/* + **/*.test.*
|
||||
|
||||
/gemini-execute "optimize React performance @{src/components/dashboard}" --yolo
|
||||
# Uses: src/components/dashboard + performance-related patterns
|
||||
```
|
||||
|
||||
### Workflow Task Execution
|
||||
```bash
|
||||
/gemini-execute IMPL-001 --yolo # Auto-execute main task
|
||||
/gemini-execute IMPL-002.1 --debug # Debug subtask execution
|
||||
```
|
||||
|
||||
### Development Scenarios
|
||||
```bash
|
||||
/gemini-execute "fix API error handling" --debug --save-session
|
||||
/gemini-execute "add database migration" --yolo
|
||||
/gemini-execute "improve test coverage" --save-session
|
||||
```
|
||||
|
||||
## Quality Assurance Features
|
||||
|
||||
### Error Handling
|
||||
- Inference failure fallbacks (generic patterns → user prompts)
|
||||
- Gemini CLI error recovery (--all-files → @{patterns})
|
||||
- Context size optimization and batch processing
|
||||
|
||||
### Performance Optimization
|
||||
- Keyword mapping result caching
|
||||
- Progressive inference (precise → broad)
|
||||
- Optimal execution directory navigation
|
||||
|
||||
### Reliability Mechanisms
|
||||
- Debug mode with detailed logging
|
||||
- Session saving for review and replay
|
||||
- Integration with existing error recovery patterns
|
||||
|
||||
## Benefits Delivered
|
||||
|
||||
### For Developers
|
||||
- **Reduced Cognitive Load**: Automatic context inference eliminates manual file specification
|
||||
- **Faster Execution**: Direct implementation without separate planning phase
|
||||
- **Consistent Results**: Standardized inference patterns across team
|
||||
|
||||
### For Workflows
|
||||
- **Automation Ready**: --yolo mode enables CI/CD integration
|
||||
- **Progress Tracking**: Real-time workflow status updates
|
||||
- **Documentation**: Automatic summary generation for audit trails
|
||||
|
||||
### For System Architecture
|
||||
- **Modular Design**: Clean integration with existing command ecosystem
|
||||
- **Extensible**: Easy to add new keyword mappings and task types
|
||||
- **Maintainable**: Single file implementation with clear documentation
|
||||
|
||||
## Implementation Stats
|
||||
- **File Created**: 1 command definition file
|
||||
- **Lines of Code**: ~400 lines of comprehensive documentation
|
||||
- **Integration Points**: 5 major system integrations
|
||||
- **Execution Modes**: 2 distinct operational patterns
|
||||
- **Keyword Categories**: 7 domain mappings
|
||||
- **Task Types**: 5 inference patterns
|
||||
|
||||
## Future Enhancement Opportunities
|
||||
- Machine learning-based inference improvement
|
||||
- Project-specific keyword mapping customization
|
||||
- Parallel execution optimization for large codebases
|
||||
- Integration with additional workflow orchestration tools
|
||||
|
||||
---
|
||||
|
||||
The `gemini-execute` command successfully bridges the gap between analysis and implementation, providing an intelligent, automated execution pathway that maintains the flexibility and power of the existing Claude Code ecosystem while adding significant automation capabilities for workflow scenarios.
|
||||
@@ -1 +0,0 @@
|
||||
optimization
|
||||
Reference in New Issue
Block a user