Skip to content

Commit ce93056

Browse files
EchoingVesperEchoingVesper
authored
Merge pull request #18 from EchoingVesper/release/v1.5.0-documentation-and-bugfixes
Release v1.5.0: Documentation Infrastructure & Developer Experience Enhancement
2 parents 882bd69 + 891b2ac commit ce93056

File tree

78 files changed

+7774
-553
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

78 files changed

+7774
-553
lines changed

‎CLAUDE.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# MCP Task Orchestrator - Claude Code Development Guide
2+
3+
This file provides context and guidance for Claude Code development sessions in the MCP Task Orchestrator project.
4+
5+
## Project Overview
6+
7+
**Version**: 1.4.1 (stable, production-ready)
8+
**Architecture**: Python-based MCP server with SQLite persistence and enhanced features
9+
**Location**: `E:\My Work\Programming\MCP Servers\mcp-task-orchestrator`
10+
11+
### Key Capabilities
12+
- **Task Orchestration**: Intelligent breakdown with specialized AI roles
13+
- **Artifact Storage**: Context limit prevention for complex workflows
14+
- **Maintenance Coordination**: Automated task lifecycle management
15+
- **Enhanced Testing**: Advanced infrastructure with alternative runners
16+
- **Feature Management**: 8 approved features with implementation roadmap
17+
18+
## Quick Commands
19+
20+
### System Diagnostics
21+
```bash
22+
# Comprehensive health check
23+
python scripts/diagnostics/check_status.py
24+
25+
# Installation verification
26+
python scripts/diagnostics/verify_tools.py
27+
28+
# Database optimization
29+
python scripts/diagnostics/diagnose_db.py
30+
```
31+
32+
### Enhanced Testing
33+
```bash
34+
# Enhanced test runners (preferred)
35+
python simple_test_runner.py
36+
python test_validation_runner.py
37+
38+
# Resource management validation
39+
python tests/test_resource_cleanup.py
40+
41+
# Traditional pytest (still supported)
42+
python -m pytest tests/ -v
43+
```
44+
45+
### Development Server
46+
```bash
47+
# Launch orchestrator
48+
python -m mcp_task_orchestrator.server
49+
python launch_orchestrator.py
50+
51+
# CLI interface
52+
python launch_cli.py
53+
```
54+
55+
## Claude Code Integration
56+
57+
### Context-Specific Development
58+
- **Root Context**: Universal project guidance (current directory)
59+
- **Documentation**: `cd docs && claude` for multi-audience documentation workflows
60+
- **Testing**: `cd tests && claude` for enhanced testing procedures
61+
- **Core Implementation**: `cd mcp_task_orchestrator && claude` for orchestrator development
62+
- **Diagnostics**: `cd scripts && claude` for system tools and troubleshooting
63+
64+
### Enhanced Orchestrator Workflows
65+
- **Artifact System**: Seamless integration with Claude Code file operations
66+
- **Maintenance Coordination**: Automated task lifecycle and cleanup
67+
- **Testing Infrastructure**: Optimized for Claude Code development patterns
68+
- **Feature Management**: Strategic planning and implementation tracking
69+
70+
## Architecture
71+
72+
### Core Components
73+
- **Orchestrator Core** (`orchestrator/`): Task breakdown and specialist management
74+
- **Database Persistence** (`db/`): SQLAlchemy ORM with SQLite backend
75+
- **Testing Infrastructure** (`testing/`): Enhanced framework with alternative runners
76+
- **Monitoring Systems** (`monitoring/`): Diagnostics and health checking
77+
78+
### Development Patterns
79+
- **Async Safety**: All database operations with proper timeout handling
80+
- **Singleton Management**: Lazy initialization for core components
81+
- **Error Recovery**: Retry mechanisms with exponential backoff
82+
- **Type Safety**: Pydantic models for data validation
83+
84+
## Git Workflow
85+
86+
### Repository Sync (CRITICAL)
87+
**NEVER make individual file changes without considering full repository state.**
88+
89+
```bash
90+
# Before any changes
91+
git status
92+
git pull origin main
93+
94+
# After making changes
95+
git status
96+
git add [related-files]
97+
git commit -m "feat: descriptive message"
98+
git push origin main
99+
```
100+
101+
### Atomic Development
102+
- Group related changes in single commits
103+
- Test thoroughly before committing
104+
- Push only complete, working features
105+
- Use descriptive commit messages with scope
106+
107+
## Enhanced Features (v1.4.1)
108+
109+
### Artifact Storage System
110+
- **Context Limit Prevention**: Detailed work stored as filesystem artifacts
111+
- **Cross-Session Continuity**: Complete history preservation across contexts
112+
- **Professional Handovers**: Comprehensive documentation for team transitions
113+
- **File Integration**: Works with all MCP file operation tools
114+
115+
### Maintenance Coordinator
116+
- **Automated Management**: `orchestrator_maintenance_coordinator` tool
117+
- **Cleanup Operations**: Smart removal of stale tasks with artifact preservation
118+
- **Structure Validation**: Task hierarchy and data integrity analysis
119+
- **Handover Preparation**: Complete transition documentation generation
120+
121+
### Advanced Testing Infrastructure
122+
- **Enhanced Runners**: Alternative to pytest with improved reliability
123+
- **File-Based Output**: Complete result capture without truncation
124+
- **Hang Detection**: Timeout mechanisms and process monitoring
125+
- **Resource Management**: Automatic cleanup of connections and resources
126+
127+
## Development Guidelines
128+
129+
### Code Quality Standards
130+
- Use `black` for formatting: `black mcp_task_orchestrator/ tests/`
131+
- Organize imports with `isort`: `isort mcp_task_orchestrator/ tests/`
132+
- Type checking with `mypy` when available
133+
- Comprehensive error handling and input validation
134+
135+
### Testing Best Practices
136+
- Prefer enhanced test runners over standard pytest
137+
- Use file-based output for complex test scenarios
138+
- Include timeout mechanisms for all operations
139+
- Validate resource cleanup in database tests
140+
141+
### Database Operations
142+
- Use managed connections with proper cleanup
143+
- Implement retry logic with exponential backoff
144+
- Leverage WAL mode for better concurrency
145+
- Monitor connection health and performance
146+
147+
## Project Structure
148+
149+
```
150+
mcp-task-orchestrator/
151+
├── .task_orchestrator/ # Runtime state and custom roles
152+
├── docs/ # Multi-audience documentation
153+
│ ├── llm-agents/ # AI-optimized documentation
154+
│ ├── user-guide/ # Human-readable guides
155+
│ ├── architecture/ # System design records
156+
│ ├── testing/ # Testing documentation
157+
│ ├── troubleshooting/ # Issue resolution guides
158+
│ └── prompts/features/ # Feature lifecycle management
159+
├── mcp_task_orchestrator/ # Main Python package
160+
│ ├── orchestrator/ # Core orchestration logic
161+
│ ├── db/ # Database persistence layer
162+
│ ├── testing/ # Enhanced testing infrastructure
163+
│ └── monitoring/ # Diagnostics and monitoring
164+
├── tests/ # Test suite with alternative runners
165+
├── scripts/diagnostics/ # System diagnostic tools
166+
└── architecture/ # Architectural documentation
167+
```
168+
169+
## Troubleshooting
170+
171+
### Common Issues
172+
- **Database Schema**: Run `python scripts/diagnostics/diagnose_db.py` for analysis
173+
- **Installation**: Use `python scripts/diagnostics/verify_tools.py` for validation
174+
- **Testing Failures**: Try enhanced runners: `python simple_test_runner.py`
175+
- **Resource Warnings**: Use resource cleanup validation tests
176+
177+
### Emergency Procedures
178+
- **Database Issues**: Emergency schema fix scripts available in project root
179+
- **Test Hanging**: Enhanced infrastructure includes hang detection and timeouts
180+
- **Context Limits**: Artifact storage system prevents work loss in complex sessions
181+
182+
## Performance Optimization
183+
184+
### Development Workflow
185+
1. **Health Check**: Run diagnostics before major work
186+
2. **Git Sync**: Always pull latest changes before development
187+
3. **Feature Development**: Make logical, atomic changes
188+
4. **Enhanced Testing**: Use improved test infrastructure
189+
5. **Validation**: Verify system health after changes
190+
191+
### Resource Management
192+
- Close resource-intensive tools when done
193+
- Use enhanced testing for reliable validation
194+
- Monitor database performance with diagnostic tools
195+
- Leverage artifact storage for complex workflows
196+
197+
---
198+
199+
**For specialized contexts**: Use `cd <directory> && claude` to access area-specific guidance and workflows.

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
44
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
5-
[![Version 1.4.0](https://img.shields.io/badge/version-1.4.0-green.svg)](https://github.com/EchoingVesper/mcp-task-orchestrator/releases/tag/v1.4.0)
5+
[![Version 1.4.1](https://img.shields.io/badge/version-1.4.1-green.svg)](https://github.com/EchoingVesper/mcp-task-orchestrator/releases/tag/v1.4.1)
66

77
A Model Context Protocol server that breaks down complex tasks into structured workflows with specialized AI roles. Works with Claude Desktop, Cursor IDE, Windsurf, and VS Code.
88

‎REPOSITORY_CLEANUP_SUMMARY.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Repository Cleanup Summary
2+
3+
**Date**: June 2, 2025
4+
**Scope**: Comprehensive organization of miscellaneous files and development artifacts
5+
6+
## Overview
7+
8+
Successfully organized and cleaned up the mcp-task-orchestrator repository by categorizing and relocating development artifacts, experimental scripts, and historical documentation that had accumulated in the root directory and tests folder.
9+
10+
## Cleanup Statistics
11+
12+
### Files Moved to Archives: 33 files total
13+
14+
#### Development Scripts (20 files)
15+
- `cleanup_commands.sh`
16+
- `create_pytest_investigation.py`
17+
- `debug_timing_analysis.py`
18+
- `file_tracking_migration.py`
19+
- `fix_db_schema.py`
20+
- `fix_orchestrator_db.py`
21+
- `install.py` (deprecated legacy installer)
22+
- `investigate_pytest_output.py`
23+
- `live_stale_task_analysis.py`
24+
- `pytest_investigation_instructions.md`
25+
- `run_automation_migration.py`
26+
- `run_db_migration.py`
27+
- `simple_output_test.py`
28+
- `simple_stale_cleanup.py`
29+
- `stale_task_cleanup.py`
30+
- `test_import.py`
31+
- `test_import_fix.py`
32+
- `test_output_comparison.py`
33+
- `validate_maintenance_features.py`
34+
- `validate_pytest_config.py`
35+
36+
#### Analysis Reports (5 files)
37+
- `execution_flow_analysis.md`
38+
- `GIT_CHANGE_ANALYSIS.md`
39+
- `live_stale_task_analysis_report.json`
40+
- `stale_task_cleanup_report.json`
41+
- `stale_task_cleanup_test_report.md`
42+
43+
#### Historical Documentation (4 files)
44+
- `ARTIFACT_SYSTEM_ENHANCEMENT_SUMMARY.md`
45+
- `CLEANUP_SUMMARY.md`
46+
- `PULL_REQUEST_DOCUMENTATION.md`
47+
- `VERSION_PROGRESSION_PLAN.md`
48+
49+
### Files Moved to tests/ Directory: 3 files
50+
- `test_context_continuity.py` - Legitimate test file moved from root
51+
- `test_enhanced_integration.py` - Legitimate test file moved from root
52+
- `test_file_tracking.py` - Legitimate test file moved from root
53+
54+
### Legitimate Files Kept in Root: 4 files
55+
- `context_continuity.py` - Part of the core system
56+
- `decision_tracking.py` - Part of the core system
57+
- `simple_test_runner.py` - Enhanced testing infrastructure utility
58+
- `test_validation_runner.py` - Enhanced testing infrastructure utility
59+
60+
## Archive Structure Created
61+
62+
```
63+
archives/
64+
├── development-scripts/ # One-off scripts, debugging tools, migration scripts
65+
├── analysis-reports/ # Analysis documents and JSON reports
66+
└── historical-docs/ # Historical documentation and planning documents
67+
```
68+
69+
## Repository State After Cleanup
70+
71+
### Root Directory Status
72+
✅ **Clean and organized** - Only essential files remain in root directory
73+
✅ **No development artifacts** - All one-off scripts moved to archives
74+
✅ **No experimental files** - Test experiments moved to appropriate locations
75+
✅ **Preserved system components** - Core functionality files retained
76+
77+
### Tests Directory Status
78+
✅ **Legitimate tests added** - Moved proper test files from root to tests/
79+
✅ **Experimental scripts removed** - Debugging and investigation scripts archived
80+
✅ **Enhanced testing infrastructure preserved** - Kept validation_suite.py and run_maintenance_tests.py
81+
82+
## Items Still Requiring Attention
83+
84+
### Directory Cleanup (Requires manual removal)
85+
- `venv_test/` - Old virtual environment directory (should be deleted)
86+
- `__pycache__/` - Python cache directory (should be deleted)
87+
- `.pytest_cache/` - Pytest cache directory (should be deleted)
88+
89+
### .gitignore Enhancement
90+
The current .gitignore already covers most development artifacts, but could be enhanced to prevent future accumulation of:
91+
- Additional cache directories
92+
- IDE-specific files
93+
- Temporary development scripts
94+
95+
## Impact Assessment
96+
97+
### Before Cleanup Issues:
98+
- ❌ 33 miscellaneous files scattered in root directory
99+
- ❌ Test files mixed with development scripts
100+
- ❌ Historical documents cluttering current workspace
101+
- ❌ Difficult to identify legitimate vs. experimental code
102+
103+
### After Cleanup Benefits:
104+
- ✅ Clean, professional repository structure
105+
- ✅ Clear separation of core files vs. development artifacts
106+
- ✅ Historical content preserved but organized
107+
- ✅ Development artifacts easily accessible in archives
108+
- ✅ Proper test organization
109+
110+
## Recommendations for Future Development
111+
112+
### File Organization Best Practices
113+
1. **Keep root directory clean** - Only essential project files
114+
2. **Use scripts/ directory** - For legitimate utilities and tools
115+
3. **Archive development artifacts** - Move one-off scripts to archives/development-scripts/
116+
4. **Document experimental work** - Add README files to archive directories
117+
118+
### Development Workflow
119+
1. **Create temporary files in isolated directories** during development
120+
2. **Clean up after feature completion** - Archive or remove experimental files
121+
3. **Use consistent naming** - Prefix experimental files with `dev_` or `test_`
122+
4. **Regular maintenance** - Quarterly cleanup of development artifacts
123+
124+
## Files Available in Archives
125+
126+
All archived files remain accessible and can be referenced or restored if needed. The archive structure preserves the complete development history while maintaining a clean working environment.
127+
128+
### Archive Navigation
129+
- **`archives/development-scripts/`** - Contains all one-off scripts, debugging tools, and migration utilities
130+
- **`archives/analysis-reports/`** - Contains analysis documents and generated reports
131+
- **`archives/historical-docs/`** - Contains historical planning and documentation files
132+
133+
## Conclusion
134+
135+
The repository cleanup successfully transformed a cluttered development environment into a clean, organized, and professional codebase while preserving all historical work in accessible archives. The new structure will make development more efficient and help maintain repository hygiene going forward.
136+
137+
**Repository Status**: ✅ **CLEAN AND ORGANIZED**

0 commit comments

Comments
 (0)