coulomb/markitect-main
2
0
Fork 0
Code Issues 62 Pull Requests Actions Projects 12 Releases 1 Wiki Activity

docs: Consolidate and update development documentation for Issue #59

Browse Source 
Streamline development documentation by removing redundancy and focusing
on next target Issue #59 - Issue Management CLI Tool.

Key changes:
- Remove obsolete NEXT.md file (redundant with NEXT_SESSION_BRIEFING.md)
- Condense NEXT_SESSION_BRIEFING.md removing outdated issue information
- Focus briefing on Issue #59: Issue management CLI with plugin architecture
- Create comprehensive ISSUE_59_GAMEPLAN.md with TDD8 implementation strategy
- Add ISSUE_46_COMPLETION.md documenting completed schema generation work

Documentation Improvements:
- Clear Issue #59 requirements: unified CLI wrapper with plugin system
- Detailed plugin architecture design (Gitea, Local file, future Jira)
- Complete TDD8 implementation phases (10 phases from ISSUE to PUBLISH)
- Integration strategy with existing tddai_cli.py and Makefile targets
- Success criteria and timeline estimation (7-10 hours across sessions)

Issue #59 Problem:
- Claude sometimes misses existing issue functions and tries direct API calls
- Need unified CLI interface to improve workflow efficiency
- Plugin architecture for multiple backends (Gitea, local files, Jira)

Next Action: make tdd-start NUM=59

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2025-10-01 22:10:18 +02:00
parent 1358ca17ec
commit adecc9aea3
4 changed files with 511 additions and 319 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
NEXT_SESSION_BRIEFING.md
View File

@@ -1,32 +1,37 @@
# Next Session Briefing - MarkiTect Development
## 🎯 Current Status: Phase 2 Complete!
## 🎯 Current Status: Issue Management Enhancement Ready
**Completed Issues:**
- ✅ Issue #51: Add outline mode to schema generation
- ✅ Issue #52: Capture actual heading text in schemas
- ✅ Issue #54: Add content field instruction capabilities
**Recently Completed Issues:**
- ✅ Issue #46: Schema generation outline mode with heading text capture - COMPLETED
- ✅ Issue #50: Metaschema definition - COMPLETED
- ✅ Issue #51: Outline mode schema generation - COMPLETED
- ✅ Issue #52: Heading text capture - COMPLETED
- ✅ Issue #54: Content field instruction capabilities - COMPLETED
- ✅ Issue #55: Schema-based draft generation - COMPLETED
- ✅ Issue #56: Data-driven draft generation - COMPLETED
- ✅ Issue #57: Test efficiency improvements - COMPLETED
**Next Phase Goals**: Continue with remaining schema generation enhancements
**Mode**: Autonomous TDD8 implementation following established patterns
**Expected Outcome**: Continue building advanced schema generation features
**Current Achievement**: Complete schema-driven architecture with outline mode, heading text capture, content instructions, and draft generation workflows.
---
## 📊 Current Project Status
## 🎯 Next Target: Issue #59 - Issue Management CLI Tool
### ✅ Recently Completed
- **Issue #50**: Metaschema definition COMPLETE (TDD8 cycle successful)
- Files: `markitect/metaschema.py`, `markitect/schemas/markitect-metaschema.json`
- CLI integration in `schema-ingest` command
- 15 comprehensive tests (100% passing)
- Foundation established for advanced schema features
**Issue #59: "Issue management as a cli tool with different backends"**
- **Priority**: High (addresses Claude's workflow inefficiencies)
- **Problem**: Claude sometimes misses existing issue functions and tries direct API calls that fail
- **Goal**: Create a unified CLI wrapper/facade for issue management with plugin system
### 🎯 Next Target: Issue #51 - Add outline mode to schema generation
- **Priority**: High
- **Dependencies**: ✅ Metaschema definition (Issue #50) COMPLETE
- **Goal**: `markitect schema-generate --mode outline --depth 3 --outfile invoice.json example.md`
- **Status**: Ready to start
**Requirements:**
1. **Core CLI Tool**: Create, modify, retrieve, comment, and close issues
2. **List Operations**: Get open issues and closed issues
3. **Plugin System**: Extensible backend architecture
4. **Gitea Plugin**: Connect to existing gitea tooling (first plugin)
5. **Local Plugin**: Markdown-based local infrastructure without external services
6. **Future**: Jira plugin support
**Expected Impact**: Improve Claude's efficiency in issue interaction and provide flexible backend options.
---
@@ -40,27 +45,36 @@
### Key Commands
```bash
# Start new issue workspace
make tdd-start NUM=51
make tdd-start NUM=59
# Run tests
PYTHONPATH=. python3 -m pytest tests/ --tb=short -q --maxfail=5
python3 -m pytest tests/ --tb=short -q --maxfail=5
# Close issue when complete
make close-issue NUM=51
# Issue management (current Makefile targets)
make list-issues # Show all gitea issues
make list-open-issues # Show only open issues
make show-issue NUM=X # Show specific issue
make close-issue NUM=X # Close specific issue
# Show issues
make show-issue NUM=51
make list-issues
# Gitea API (current)
curl -s "http://92.205.130.254:32166/api/v1/repos/coulomb/markitect_project/issues"
```
### Available Subagents
- **general-purpose**: Multi-step research and complex tasks
- **tddai-assistant**: TDD8 workflow expert
- **refactoring-assistant**: Code quality and improvement (use proactively)
- **repository-assistant**: Directory structure optimization (use proactively)
- **project-assistant**: Project tracking and planning
### Available Infrastructure
- **Gitea Integration**: Existing tddai_cli.py with issue management
- **Makefile Targets**: Comprehensive issue operations already defined
- **API Access**: Working Gitea API at http://92.205.130.254:32166
- **TDD8 Workflow**: Proven development methodology
### Test Infrastructure
- **Current Status**: 689 tests passing (cleaned up circular dependencies)
- **Timeout Infrastructure**: Implemented with pytest-timeout
- **Clean Test Execution**: Removed meta-testing anti-patterns
---
## 🧪 TDD8 Workflow Protocol
### TDD8 Workflow Protocol
1. **ISSUE** - Understand requirements and analyze existing code
2. **TEST** - Write failing tests first (RED state required)
3. **RED** - Verify tests fail before implementation
@@ -72,136 +86,65 @@ make list-issues
---
## 📋 Issue #51 Implementation Plan
## 🔧 Implementation Context
### Requirements Analysis
- Add `--mode outline` option to `schema-generate` command
- Add `--depth` parameter for outline depth control
- Schema title should be "Schema from example.md" (not "for")
- Capture actual heading text in generated schemas
- Integrate with metaschema extensions from Issue #50
### Existing Issue Management Infrastructure
- **tddai_cli.py**: Current CLI with gitea integration
- **Makefile**: Comprehensive issue targets (list, show, close, etc.)
- **Gitea API**: Working connection to http://92.205.130.254:32166
- **Database**: markitect.db with AST caching and workspace management
### Key Files to Examine/Modify
- `markitect/cli.py` - schema-generate command (around line 1800+)
- `markitect/schema_generator.py` - SchemaGenerator class
- `tests/test_l4_service_schema_generation.py` - Existing schema tests
- Create new test file for Issue #51 functionality
### Expected CLI Usage Pattern
```bash
# Current command
markitect schema-generate document.md --max-depth 2 --output schema.json
# New outline mode
markitect schema-generate --mode outline --depth 3 --outfile invoice.json example.md
```
### Technical Integration Points
- Use `x-markitect-outline-mode: true` in generated schemas
- Use `x-markitect-outline-depth` to record depth setting
- Integrate `x-markitect-heading-text` for actual heading capture
- Ensure backward compatibility with existing `--max-depth` option
---
## 🧪 Testing Strategy
### Test File Structure
- Create `.markitect_workspace/issue_51/tests/test_issue_51_outline_mode.py`
- Follow established test patterns from Issue #50
- Include CLI integration tests
- Test backward compatibility
### Critical Test Cases
1. Outline mode flag acceptance and processing
2. Depth parameter validation and functionality
3. Schema title format ("from" vs "for")
4. Heading text capture in outline mode
5. Metaschema compliance (validate against Issue #50 metaschema)
6. Backward compatibility with existing schema-generate
7. CLI help text and error handling
---
## 🔧 Implementation Notes
### Code Patterns to Follow
- Use existing SchemaGenerator class as foundation
- Add mode parameter to `generate_schema_from_file()` method
- Implement outline-specific logic in separate methods
- Follow existing CLI argument patterns in Click
- Use metaschema validation from Issue #50
### Quality Standards
- Maintain 100% test pass rate for existing 478 tests
- Follow project conventions (no unnecessary comments unless asked)
- Use TodoWrite tool proactively for task tracking
- Commit frequently with descriptive messages
- Update CLI help text appropriately
### Project Health Indicators
- **Test Coverage**: 689 passing tests across architectural layers
- **CLI Maturity**: Complete db- prefixed commands with configuration
- **Performance**: AST caching with 60-85% speedup
- **Clean Architecture**: 7-layer organization with proper separation
### Git Workflow
- Current branch: `main` (2 commits ahead of origin)
- Last commit: "feat: Complete Issue #50 - Define metaschema for JSON schema structure"
- Modified files since last session: `Makefile`, `markitect/cli.py`, `markitect/database.py`
- **Current branch**: main
- **Working tree**: Clean
- **Recent work**: Test infrastructure cleanup, Issue #46 completion
---
## 🎮 Autonomous Work Protocols
### Do NOT Forget
### Key Practices
- ✅ Use TodoWrite tool to track all tasks and phases
- ✅ Run tests after each change to verify state
- ✅ Follow complete TDD8 cycle (don't skip steps)
- ✅ Update CLI help when adding new features
- ✅ Run tests after each change to verify state
- ✅ Maintain backward compatibility
- ✅ Use proper PYTHONPATH=. for all test runs
- ✅ Update CLI help when adding new features
- ✅ Commit frequently with descriptive messages
### Success Criteria for Issue #51
- [ ] `--mode outline` option implemented and functional
- [ ] `--depth` parameter working with validation
- [ ] Schema title format updated ("from" not "for")
- [ ] Actual heading text captured in schemas
- [ ] Metaschema integration working
- [ ] All tests passing (new + existing 478)
- [ ] CLI help updated and comprehensive
- [ ] Backward compatibility maintained
- [ ] Issue closed via `make close-issue NUM=51`
### Next Issues After #51
- **Issue #52**: Capture actual heading text in schemas (may overlap with #51)
- **Issue #54**: Add content field instruction capabilities
- **Issue #55**: Schema-based draft generation
---
## 🎯 Session Success Metrics
### Minimum Viable Success
- Issue #51 basic functionality implemented
- Core tests passing
- CLI integration working
### Optimal Success
- Complete TDD8 cycle for Issue #51
- All 478+ tests passing
- Issue #51 closed and committed
- Foundation laid for Issue #52
### Stretch Goals
- Begin Issue #52 if time permits
- Proactive refactoring improvements
- Documentation enhancements
### Quality Standards
- Maintain 100% test pass rate for existing tests
- Follow project conventions (minimal comments unless requested)
- Use proper separation of concerns (plugin architecture)
- Implement comprehensive error handling
- Provide clear CLI help and documentation
---
## 🚀 Start Command
When beginning the session:
When beginning Issue #59:
```bash
make tdd-start NUM=51
make tdd-start NUM=59
```
Then follow TDD8 methodology autonomously, using TodoWrite for task tracking and committing/closing when complete.
Then follow TDD8 methodology autonomously, focusing on:
1. **Plugin Architecture Design**: Extensible backend system
2. **CLI Interface**: Unified issue management commands
3. **Gitea Plugin**: Integration with existing infrastructure
4. **Local Plugin**: File-based issue management
5. **Testing**: Comprehensive test coverage with mocks
**Remember**: This is autonomous work mode - proceed through full TDD8 cycle without checking in unless hitting technical blockers or token limits.
**Success Criteria**: Claude can efficiently manage issues through unified CLI without API failures, with support for multiple backends.
---
*Updated: October 1, 2025*
*Status: Issue #46 COMPLETE - Issue #59 Ready for Implementation*
*Achievement: Clean test infrastructure, complete schema workflows*
*Next Target: Unified issue management CLI with plugin architecture*