From adecc9aea31a5ebaba829bd0eddb03e9b6aa53bd Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Wed, 1 Oct 2025 22:10:18 +0200
Subject: [PATCH] docs: Consolidate and update development documentation for
 Issue #59
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 ISSUE_46_COMPLETION.md   |  94 +++++++++++
 ISSUE_59_GAMEPLAN.md     | 330 +++++++++++++++++++++++++++++++++++++++
 NEXT.md                  | 175 ---------------------
 NEXT_SESSION_BRIEFING.md | 231 +++++++++++----------------
 4 files changed, 511 insertions(+), 319 deletions(-)
 create mode 100644 ISSUE_46_COMPLETION.md
 create mode 100644 ISSUE_59_GAMEPLAN.md
 delete mode 100644 NEXT.md

diff --git a/ISSUE_46_COMPLETION.md b/ISSUE_46_COMPLETION.md
new file mode 100644
index 00000000..6ef564d5
--- /dev/null
+++ b/ISSUE_46_COMPLETION.md
@@ -0,0 +1,94 @@
+# Issue #46 - Schema Generation Capability Outline - COMPLETED ✅
+
+## Issue Summary
+**Title**: Schema generation capability outline
+**Status**: ✅ COMPLETED
+**Implementation Date**: October 1, 2025
+
+## Problem Solved
+Issue #46 addressed the integration gap between outline mode schema generation and draft generation. While outline mode could capture heading text correctly, draft generation wasn't using it, resulting in generic placeholder headings instead of preserving document structure.
+
+## Solution Implemented
+
+### Core Fix
+Enhanced `StubGenerator._extract_heading_text_from_schema()` to extract actual heading text from enum constraints in outline mode schemas, enabling draft generation to preserve source document structure.
+
+### Key Features Delivered
+
+1. **✅ Heading Text Capture in Outline Mode**
+   - Schemas capture exact heading text as enum constraints
+   - Command: `markitect schema-generate --mode outline --capture-heading-text`
+
+2. **✅ Draft Generation Integration**
+   - Generated drafts use actual headings from source documents
+   - No more generic "## Introduction", "## Main Content" placeholders
+   - Preserves structure: "## Overview", "## Features", etc.
+
+3. **✅ Content Instructions Integration**
+   - Works seamlessly with `--include-content-instructions`
+   - Provides specific guidance instead of generic TODO placeholders
+
+4. **✅ Proper Title Formatting**
+   - Outline mode uses "Schema from" format instead of "Schema for"
+   - Consistent metadata with `x-markitect-outline-mode: true`
+
+5. **✅ End-to-End Workflow**
+   - Complete workflow: example document → outline schema → draft
+   - Maintains document structure throughout the process
+
+## Technical Implementation
+
+### Files Modified
+- `markitect/stub_generator.py` - Core implementation
+  - Added `_extract_heading_text_from_schema()` method
+  - Modified `_generate_content_from_headings()` to use captured text
+  - Enhanced both H1 and H2+ heading generation logic
+
+### Tests Added
+- `tests/test_issue_46_schema_generation_outline.py` - Comprehensive test suite
+  - 8 test methods covering all functionality
+  - End-to-end workflow validation
+  - Integration with existing features
+
+## Verification Results
+
+### Manual Testing ✅
+```bash
+# Create test document
+echo "# Test Document
+## Overview
+This is an overview.
+## Features
+These are features." > test.md
+
+# Generate outline schema with heading text capture
+markitect schema-generate --mode outline --capture-heading-text --depth 2 test.md
+
+# Generate draft from schema
+markitect generate-stub schema.json
+
+# Result: Draft preserves "# Test Document", "## Overview", "## Features"
+```
+
+### Automated Testing ✅
+- All 8 tests in `test_issue_46_schema_generation_outline.py` passing
+- End-to-end workflow validation successful
+- Integration with content instructions working
+- Backward compatibility maintained
+
+## Impact
+- 🎯 **Problem Solved**: Draft generation now preserves document structure from outline schemas
+- 🔄 **Workflow Complete**: End-to-end outline mode workflow fully functional
+- 📊 **Test Coverage**: Comprehensive test suite ensures reliability
+- 🔧 **Integration Ready**: Works with all existing features (content instructions, depth limiting, etc.)
+
+## Commits
+- `7198041` - feat: Fix Issue #46 - Schema generation outline mode draft integration
+- `f33c8ac` - feat: Implement test timeout infrastructure and fix failing tests
+
+## Status: READY TO CLOSE ✅
+
+Issue #46 is fully implemented, tested, and verified. All acceptance criteria have been met and the feature is working correctly in production.
+
+---
+*Generated on October 1, 2025*
\ No newline at end of file
diff --git a/ISSUE_59_GAMEPLAN.md b/ISSUE_59_GAMEPLAN.md
new file mode 100644
index 00000000..54fa7b52
--- /dev/null
+++ b/ISSUE_59_GAMEPLAN.md
@@ -0,0 +1,330 @@
+# Issue #59 GAMEPLAN - Issue Management CLI Tool with Plugin Architecture
+
+## 🎯 Mission Statement
+
+Create a unified CLI wrapper/facade for issue management that provides a consistent interface across multiple backends (Gitea, local files, future Jira) to improve Claude's efficiency and eliminate API call failures.
+
+---
+
+## 📋 Issue Analysis
+
+### Problem Statement
+- **Current Pain Point**: Claude sometimes misses existing issue functions and tries direct API calls that fail
+- **Root Cause**: Fragmented issue management tools scattered across Makefile targets and tddai_cli.py
+- **Impact**: Workflow inefficiencies, failed operations, inconsistent issue interactions
+
+### Success Criteria
+1. ✅ Unified CLI interface for all issue operations
+2. ✅ Plugin architecture supporting multiple backends
+3. ✅ Gitea plugin integrating existing functionality
+4. ✅ Local file-based plugin for offline/repo-only workflows
+5. ✅ Improved Claude workflow efficiency
+6. ✅ Extensible foundation for future backends (Jira, GitHub, etc.)
+
+---
+
+## 🏗️ Architecture Design
+
+### Core Components
+
+#### 1. Issue Management CLI (`markitect issues`)
+```bash
+markitect issues list                    # List all issues
+markitect issues list --state open      # List open issues
+markitect issues show 59                # Show specific issue
+markitect issues create "Title" "Body"  # Create new issue
+markitect issues comment 59 "Comment"   # Add comment
+markitect issues close 59               # Close issue
+markitect issues config                 # Show/configure backend
+```
+
+#### 2. Plugin Architecture
+```
+markitect/
+├── issues/
+│   ├── __init__.py           # Core CLI interface
+│   ├── manager.py            # Issue manager with plugin loading
+│   ├── base.py               # Abstract base plugin interface
+│   ├── plugins/
+│   │   ├── __init__.py
+│   │   ├── gitea.py          # Gitea backend plugin
+│   │   ├── local.py          # Local file backend plugin
+│   │   └── jira.py           # Future Jira plugin
+│   └── models.py             # Issue data models
+```
+
+#### 3. Plugin Interface
+```python
+class IssueBackend(ABC):
+    @abstractmethod
+    def list_issues(self, state: Optional[str] = None) -> List[Issue]
+
+    @abstractmethod
+    def get_issue(self, issue_id: str) -> Issue
+
+    @abstractmethod
+    def create_issue(self, title: str, body: str) -> Issue
+
+    @abstractmethod
+    def add_comment(self, issue_id: str, comment: str) -> None
+
+    @abstractmethod
+    def close_issue(self, issue_id: str) -> None
+```
+
+---
+
+## 🎯 TDD8 Implementation Phases
+
+### Phase 1: ISSUE Analysis
+**Scope**: Understand existing infrastructure and design plugin architecture
+
+**Tasks**:
+1. ✅ Analyze current tddai_cli.py issue management functions
+2. ✅ Review Makefile issue targets and integration points
+3. ✅ Design plugin architecture and interfaces
+4. ✅ Define CLI command structure and user experience
+5. ✅ Identify integration points with existing MarkiTect CLI
+
+**Deliverable**: Architecture design and interface definitions
+
+### Phase 2: TEST - Core Infrastructure Tests
+**Scope**: Write failing tests for plugin architecture and CLI interface
+
+**Test Categories**:
+1. **Plugin Manager Tests**
+   - Plugin discovery and loading
+   - Backend switching and configuration
+   - Error handling for missing/invalid plugins
+
+2. **CLI Interface Tests**
+   - Command parsing and routing
+   - Output formatting consistency
+   - Error message standardization
+
+3. **Mock Plugin Tests**
+   - Abstract interface compliance
+   - Plugin lifecycle management
+
+**Deliverable**: Comprehensive test suite (initially failing)
+
+### Phase 3: RED - Verify Test Failures
+**Scope**: Confirm all tests fail before implementation
+
+**Validation**:
+- Plugin loading fails (no plugins exist)
+- CLI commands fail (no implementation)
+- Interface violations detected properly
+- Error handling works as expected
+
+### Phase 4: GREEN - Minimal Implementation
+**Scope**: Implement core infrastructure to pass tests
+
+**Implementation Priority**:
+1. **Core Models**: Issue, Comment data classes
+2. **Plugin Manager**: Discovery, loading, configuration
+3. **Base CLI**: Command structure and routing
+4. **Mock Plugin**: For testing and validation
+
+**Deliverable**: Basic plugin architecture with mock backend
+
+### Phase 5: GREEN+ - Gitea Plugin Implementation
+**Scope**: Implement Gitea plugin integrating existing functionality
+
+**Integration Tasks**:
+1. **Migrate tddai_cli.py Functions**: Extract and adapt existing Gitea code
+2. **API Integration**: Reuse existing Gitea API connections
+3. **Configuration**: Inherit existing URL and authentication settings
+4. **Testing**: Verify compatibility with current workflows
+
+**Deliverable**: Fully functional Gitea plugin
+
+### Phase 6: GREEN++ - Local File Plugin
+**Scope**: Implement file-based local issue management
+
+**Features**:
+1. **Directory Structure**: `.markitect/issues/` with markdown files
+2. **Issue Format**: YAML frontmatter + markdown body
+3. **State Management**: File naming and organization
+4. **Git Integration**: Version control friendly format
+
+**File Structure**:
+```
+.markitect/issues/
+├── open/
+│   ├── 059-issue-management-cli.md
+│   └── 060-next-feature.md
+├── closed/
+│   └── 058-completed-issue.md
+└── config.yml
+```
+
+**Deliverable**: Offline-capable local issue management
+
+### Phase 7: REFACTOR - Code Quality & Performance
+**Scope**: Clean up architecture and optimize performance
+
+**Improvements**:
+1. **Code Quality**: Remove duplication, improve naming
+2. **Performance**: Caching, lazy loading of plugins
+3. **Error Handling**: Comprehensive error messages
+4. **Documentation**: Inline documentation and help text
+
+### Phase 8: DOCUMENT - CLI Help & Documentation
+**Scope**: Update CLI help and create user documentation
+
+**Documentation Tasks**:
+1. **CLI Help**: Comprehensive help for all commands
+2. **Plugin Development**: Guide for creating new backend plugins
+3. **Configuration**: Backend setup and switching instructions
+4. **Migration**: Guide from existing tddai_cli.py usage
+
+### Phase 9: REFINE - Integration & Polish
+**Scope**: Polish integration with existing MarkiTect CLI
+
+**Integration Tasks**:
+1. **CLI Integration**: Seamless integration with `markitect` command
+2. **Backward Compatibility**: Maintain existing Makefile targets
+3. **Configuration**: Integration with existing config system
+4. **Testing**: End-to-end workflow validation
+
+### Phase 10: PUBLISH - Deployment & Issue Closure
+**Scope**: Commit implementation and close Issue #59
+
+**Deployment Tasks**:
+1. **Git Commit**: Comprehensive commit with all changes
+2. **Issue Closure**: Close Issue #59 with implementation summary
+3. **Documentation Update**: Update NEXT_SESSION_BRIEFING.md
+4. **Future Planning**: Identify follow-up improvements
+
+---
+
+## 🛠️ Technical Implementation Details
+
+### CLI Integration Strategy
+```python
+# Add to markitect/cli.py
+@cli.group()
+def issues():
+    """Issue management with multiple backend support."""
+    pass
+
+@issues.command()
+@click.option('--state', type=click.Choice(['open', 'closed', 'all']), default='all')
+@click.option('--backend', help='Override configured backend')
+def list(state, backend):
+    """List issues from configured backend."""
+    manager = IssueManager(backend=backend)
+    issues = manager.list_issues(state=state)
+    # Format and display
+```
+
+### Plugin Discovery Mechanism
+```python
+class IssueManager:
+    def __init__(self, backend: Optional[str] = None):
+        self.backend = backend or self._get_configured_backend()
+        self.plugin = self._load_plugin(self.backend)
+
+    def _discover_plugins(self) -> Dict[str, Type[IssueBackend]]:
+        # Plugin discovery logic
+        pass
+```
+
+### Configuration Strategy
+```yaml
+# .markitect/config/issues.yml
+default_backend: gitea
+backends:
+  gitea:
+    url: "http://92.205.130.254:32166"
+    repo: "coulomb/markitect_project"
+  local:
+    directory: ".markitect/issues"
+    auto_git: true
+```
+
+---
+
+## 🧪 Testing Strategy
+
+### Test Categories
+1. **Unit Tests**: Individual plugin methods and CLI commands
+2. **Integration Tests**: Plugin manager with real/mock backends
+3. **End-to-End Tests**: Complete workflows from CLI to backend
+4. **Compatibility Tests**: Existing Makefile target compatibility
+
+### Mock Strategy
+- **Gitea Mock**: Simulate API responses for testing
+- **Local Mock**: Temporary filesystem for testing
+- **Network Mock**: Handle API failures gracefully
+
+### Test Data
+- **Sample Issues**: Realistic issue data for testing
+- **Edge Cases**: Error conditions, malformed data
+- **Performance**: Large issue lists, concurrent operations
+
+---
+
+## 🎯 Success Metrics
+
+### Functional Success
+- ✅ All issue operations work through unified CLI
+- ✅ Plugin switching works seamlessly
+- ✅ Existing workflows remain compatible
+- ✅ Error handling provides clear guidance
+
+### Performance Success
+- ✅ Response times under 2 seconds for list operations
+- ✅ Plugin loading under 500ms
+- ✅ No regression in existing functionality
+
+### User Experience Success
+- ✅ Claude can perform all issue operations without API failures
+- ✅ Clear, consistent CLI interface across backends
+- ✅ Helpful error messages and guidance
+- ✅ Backward compatibility with existing tools
+
+---
+
+## 🚀 Development Timeline
+
+### Sprint 1 (TDD8 Phases 1-4): Foundation
+- **Duration**: 2-3 hours
+- **Deliverable**: Core plugin architecture with tests
+- **Milestone**: Mock plugin working through CLI
+
+### Sprint 2 (TDD8 Phases 5-6): Backend Implementation
+- **Duration**: 3-4 hours
+- **Deliverable**: Gitea and Local plugins functional
+- **Milestone**: All backends operational
+
+### Sprint 3 (TDD8 Phases 7-10): Polish & Integration
+- **Duration**: 2-3 hours
+- **Deliverable**: Production-ready integration
+- **Milestone**: Issue #59 complete and closed
+
+**Total Estimated Time**: 7-10 hours across multiple sessions
+
+---
+
+## 🔄 Next Steps
+
+### Immediate Actions
+1. **Start TDD8 Cycle**: `make tdd-start NUM=59`
+2. **Create Test Workspace**: Set up Issue #59 TDD environment
+3. **Begin ISSUE Phase**: Analyze existing code and design interfaces
+4. **Write Failing Tests**: Comprehensive test coverage for plugin architecture
+
+### Long-term Vision
+- **Extensible Backend System**: Easy addition of new issue management systems
+- **Unified Developer Experience**: Consistent issue management regardless of backend
+- **Offline Capabilities**: Local file-based workflows for environments without external services
+- **Enterprise Integration**: Future support for Jira, Azure DevOps, etc.
+
+---
+
+*GAMEPLAN Generated: October 1, 2025*
+*Target: Issue #59 - Issue Management CLI Tool*
+*Strategy: TDD8 with Plugin Architecture*
+*Estimated Completion: 7-10 hours across multiple sessions*
\ No newline at end of file
diff --git a/NEXT.md b/NEXT.md
deleted file mode 100644
index 2b1e0272..00000000
--- a/NEXT.md
+++ /dev/null
@@ -1,175 +0,0 @@
-# MarkiTect Development Roadmap - Next Steps After Recent Milestone Achievements
-
-## 🎯 **CURRENT STATUS: Core Workflow Complete - Enhanced User Experience Ready**
-
-### 📊 **Recently Completed Achievements**
-- ✅ **Issue #3**: Schema Management with Enhanced Format Control - COMPLETED 🎉
-- ✅ **Issue #5**: Schema Generation Foundation for arc42 Architecture Documentation - COMPLETED
-- ✅ **Issue #6**: Generate Markdown Stub from Schema - COMPLETED 🎉
-- ✅ **Issue #7**: Schema Validation - COMPLETED
-- ✅ **Issue #8**: Detailed Validation Error Reporting and CLI Enhancements - COMPLETED
-- ✅ **Issue #4**: Retrieve All Stored Files - COMPLETED
-- ✅ **Issue #18**: Configuration and Environment Management CLI - COMPLETED
-- ✅ **Issue #39**: Prefix Database Access Commands with 'db' - COMPLETED 🎉
-- ✅ **Issue #40**: Associated Files Management - COMPLETED 🎉
-- ✅ **Revolutionary Test Architecture**: 7-Layer Organization with 474 tests - COMPLETED
-- ✅ **Legacy Compatibility System**: Comprehensive versioned interface management - COMPLETED
-- ✅ **Clean Test Suite**: Removed legacy test pollution with enhanced db- command coverage - COMPLETED
-
-### 🚀 **Current Capabilities Achieved**
-- **Complete Schema-Driven Architecture**: Generate, validate, and get detailed error reports for markdown schemas
-- **Template Generation Workflow**: Create markdown stubs from schemas with intelligent placeholder content
-- **Reorganized CLI Interface**: Clean `db-` prefixed commands with full configuration, cache, and database management
-- **Associated Files Management**: Coordinated handling of markdown-schema file pairs with auto-discovery
-- **Legacy Compatibility System**: Comprehensive versioned interface management with intelligent agent
-- **Production-Ready Foundation**: 474 tests across 7 architectural layers with clean test execution
-- **High-Performance Processing**: AST caching with 60-85% speedup
-- **Comprehensive Error Handling**: User-friendly validation error reporting with actionable recommendations
-
-## 🎯 **STRATEGIC NEXT STEPS: Enhanced User Experience & Advanced Features**
-
-### **Phase 1: Enhanced CLI User Experience (IMMEDIATE PRIORITY)**
-
-#### **🎯 Issue #38: Access Metadata, Frontmatter, Content Separately in CLI** ⭐ **HIGHEST PRIORITY**
-**Strategic Value**: Enhance CLI usability and data access granularity for improved developer experience
-**Foundation**: Build on existing CLI and database infrastructure with complete schema workflow
-**Deliverable**: Separate CLI commands for accessing metadata, frontmatter, and content independently
-**Impact**: Enables fine-grained access to document components for automation and tooling
-**Timeline**: 1 week
-
-**Next Command**: `make tdd-start NUM=38` - Begin enhanced CLI component access
-
-### **Phase 2: Enhanced User Experience Features**
-
-#### **🎯 Issue #37: Emoji Flag and Preferences**
-**Strategic Value**: Enhanced user experience with engaging output options
-**Timeline**: 1 week
-
-#### **🎯 Issue #36: MarkiTect Tutorial**
-**Strategic Value**: User onboarding and feature discoverability
-**Timeline**: 1 week
-
-### **Phase 3: Advanced Processing Capabilities**
-
-#### **🎯 Issue #17: Batch Processing and Recursive Operations**
-**Strategic Value**: Enable large-scale document processing workflows
-**Timeline**: 2 weeks
-
-## 📋 **Issue Priority Matrix - Updated After Template Generation Completion**
-
-### **🔥 CRITICAL PATH (Start Immediately)**
-1. **Issue #38**: Access Metadata, Frontmatter, Content Separately in CLI ⭐ **START NOW**
-
-### **🎯 HIGH PRIORITY (Enhanced User Experience)**
-2. **Issue #37**: Emoji Flag and Preferences
-3. **Issue #36**: MarkiTect Tutorial
-
-### **🚀 MEDIUM PRIORITY (Advanced Features)**
-4. **Issue #17**: Batch Processing and Recursive Operations
-5. **Issue #16**: Performance Validation CLI
-6. **Issue #18**: Configuration and Environment Management CLI (if enhancements needed)
-
-### **🎯 FUTURE PLANNING (Advanced Architecture)**
-7. **Issue #9**: Expose GraphQL Read Interface
-8. **Issue #10**: Expose GraphQL Write Interface
-9. **Issue #19**: Plugin Architecture and Extensions System
-
-### **⏸️ DEFERRED (Specialized Use Cases)**
-- **Issue #35**: Architectural Chaos Testing (advanced robustness testing)
-- **Issue #31**: Spin out TDDAI/TDD8 methodology into independent repository
-- **Issue #32**: Extract Gitea Integration into Independent Library
-
-## ⚡ **IMMEDIATE ACTION PLAN**
-
-### **NEXT DEVELOPMENT SESSION: Start Issue #38**
-```bash
-make tdd-start NUM=38  # Begin enhanced CLI component access implementation
-```
-
-**Why Issue #38 Is The Perfect Next Step:**
-- **Natural Progression**: Builds on completed core workflow to enhance usability
-- **High User Value**: Enables fine-grained access to document components for automation
-- **Strong Foundation**: Complete schema workflow, database CLI, and test infrastructure exists
-- **Developer Experience**: Significantly improves CLI flexibility for advanced use cases
-
-### **Development Context**
-- **Clean Workspace**: Working tree is clean, no pending changes
-- **Green Test State**: 474/474 tests passing across 7 architectural layers with clean execution
-- **Complete Core Workflow**: Schema generation → validation → template creation → database CLI reorganization
-- **CLI Maturity**: Comprehensive command-line interface with db- prefixed commands, configuration, and legacy management
-
-## 🏆 **STRATEGIC ACHIEVEMENTS TO DATE**
-
-### **Complete Schema-Driven Architecture Foundation**
-- ✅ **Schema Generation**: Extract document structure patterns from markdown files (Issue #5)
-- ✅ **Schema Validation**: Validate markdown against defined schemas with detailed error reporting (Issue #7)
-- ✅ **Template Generation**: Create markdown stubs from schemas with intelligent placeholders (Issue #6)
-- ✅ **Error Reporting**: User-friendly validation errors with actionable recommendations (Issue #8)
-- ✅ **Format Support**: JSON and YAML schema formats with CLI control
-
-### **Production-Ready Infrastructure**
-- ✅ **Test Architecture**: 474 tests across 7 layers with clean execution and no legacy pollution
-- ✅ **CLI Excellence**: Complete db- prefixed command interface with configuration, cache, and database management
-- ✅ **Legacy Compatibility**: Comprehensive versioned interface management with intelligent agent
-- ✅ **Performance**: High-speed AST processing with intelligent caching (60-85% speedup)
-- ✅ **Error Handling**: Comprehensive error handling with user-friendly messages
-
-### **Development Methodology**
-- ✅ **TDD8 Workflow**: Proven ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH methodology
-- ✅ **Gitea Integration**: Complete issue-driven development with API integration
-- ✅ **Quality Assurance**: 100% green test state requirement before all commits
-
-## 🚫 **STRATEGIC FOCUS - AVOID SCOPE CREEP**
-
-**Current Focus Area: Template Generation & Document Workflows**
-- ✅ Continue building on the solid schema foundation
-- ✅ Focus on practical user workflows and CLI improvements
-- ❌ Avoid architectural refactoring (foundation is excellent)
-- ❌ Avoid performance optimizations (already optimized)
-- ❌ Avoid adding new infrastructure until core workflows are complete
-
-## 📈 **SUCCESS METRICS**
-
-### **Completion Indicators for Issue #6**
-- [ ] CLI command `generate-stub` accepts schema file input
-- [ ] Generated markdown contains proper headings structure from schema
-- [ ] Placeholder content is intelligently generated
-- [ ] Round-trip validation: generated stub validates against source schema
-- [ ] Comprehensive test coverage with TDD8 methodology
-- [ ] Documentation and user examples
-
-### **Project Health Indicators**
-- **Test Coverage**: Maintain 394+ passing tests
-- **CLI Usability**: Clear, intuitive command structure
-- **Performance**: Sub-second response times for common operations
-- **User Experience**: Comprehensive error messages and help text
-
-## 🎖️ **PATH TO ARC42 DOCUMENTATION SYSTEM**
-
-**Current Position**: Schema foundation complete (Issues #3, #5, #7, #8 ✅)
-**Next Milestone**: Template generation workflow (Issue #6)
-**Target**: Complete arc42 architecture documentation system with AI intelligence
-
-**Estimated Timeline to Full Arc42 Capability**:
-- **Template Generation (Issue #6)**: 1-2 weeks
-- **Enhanced CLI (Issues #38, #39, #40)**: 3-4 weeks
-- **Document Relationships**: 2-3 weeks
-- **🎯 Total to Production Arc42 System: 6-9 weeks**
-
----
-
-## ✅ **IMMEDIATE NEXT STEPS SUMMARY**
-
-1. **Start Issue #6** with `make tdd-start NUM=6`
-2. **Implement markdown stub generation** from schema files
-3. **Maintain TDD8 methodology** with comprehensive test coverage
-4. **Focus on user workflow completion** rather than architectural expansion
-
-**Mission**: Transform MarkiTect from advanced markdown processor to complete template-driven documentation platform with schema validation and intelligent stub generation.
-
----
-
-*Strategic Analysis: 2025-09-30*
-*Status: Schema Foundation COMPLETE - Template Generation Ready*
-*Achievement: 394 tests, 7-layer architecture, comprehensive CLI - EXCEPTIONAL foundation*
-*Next Target: Complete bidirectional schema ↔ markdown workflow with Issue #6*
\ No newline at end of file
diff --git a/NEXT_SESSION_BRIEFING.md b/NEXT_SESSION_BRIEFING.md
index 8cfb35df..789b2187 100644
--- a/NEXT_SESSION_BRIEFING.md
+++ b/NEXT_SESSION_BRIEFING.md
@@ -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.
\ No newline at end of file
+**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*
\ No newline at end of file