chore: history cleanup

2025-10-03 03:39:43 +02:00
parent 280e740897
commit 19f1898d1a
45 changed files with 250 additions and 704 deletions
--- a/todo/2025-10-02_requirements_planning_summary.md
+++ b/todo/2025-10-02_requirements_planning_summary.md
@@ -0,0 +1,195 @@
+# Requirements Engineering & Strategic Planning Summary
+
+**Date**: 2025-10-02
+**Session**: Requirements and Planning for Business Application Transformation
+**Outcome**: ✅ Complete epic decomposition with 21 implementable issues
+
+## Requirements Engineering Process
+
+### **Foundation Analysis** ✅
+- **Domain Models**: 7 core models identified and validated
+- **Interfaces**: 6 key interfaces mapped with compatibility check
+- **Architecture**: Clean foundation with strong separation of concerns
+- **Risk Assessment**: No critical architectural risks identified
+
+### **Development Checklists Generated** ✅
+Applied requirements engineering methodology to all three epics:
+- **Foundation Analysis**: Understand existing architecture
+- **Interface Contract Definition**: Design compatible extensions
+- **Test Architecture Design**: Ensure comprehensive testing
+- **Incremental Implementation**: Build systematically
+- **Integration Validation**: Maintain backward compatibility
+
+## Strategic Epic Decomposition
+
+### **Epic #64: Template & Calculation Engine** (Issues #64-71)
+**Status**: ✅ Created with 7 decomposed issues
+**Priority**: Critical - Foundation for all business applications
+**Timeline**: 5-7 weeks
+
+#### **Created Issues**:
+1. **#65**: Template Engine Foundation (Critical/Large)
+2. **#66**: Mathematical Expression Evaluator (Critical/Large)
+3. **#67**: Conditional Content & Control Flow (High/Medium)
+4. **#68**: Template Management CLI Commands (High/Medium)
+5. **#69**: Template Validation & Quality Assurance (Medium/Medium)
+6. **#70**: Business Document Templates Library (Medium/Small)
+7. **#71**: Integration & Backward Compatibility (High/Small)
+
+#### **Success Criteria**:
+- Generate professional invoice from template + customer data
+- Calculate totals, taxes, and derived values automatically
+- Support conditional content rendering based on data
+- Performance: Render 100+ documents in under 10 seconds
+
+---
+
+### **Epic #65: Batch Processing & Workflows** (Issue #72)
+**Status**: ✅ Epic created, 7 sub-issues planned
+**Priority**: High - Required for production business use
+**Timeline**: 7-10 weeks
+
+#### **Planned Components**:
+1. **Batch Job Engine Foundation** - Core batch processing with progress tracking
+2. **Multi-Source Data Integration** - CSV, JSON, Database, API support
+3. **Workflow Orchestration Engine** - Multi-step process automation
+4. **Batch Validation & Quality Control** - Comprehensive validation pipeline
+5. **Batch Monitoring & Reporting** - Real-time monitoring and reporting
+6. **Enterprise Integration & APIs** - REST API and enterprise system integration
+7. **Performance Optimization & Scaling** - Enterprise-scale performance
+
+#### **Success Criteria**:
+- Process 1000+ documents in single batch operation
+- Orchestrate multi-step workflows (generate → validate → export → notify)
+- Scale to enterprise requirements with parallel processing
+
+---
+
+### **Epic #66: External Systems & Professional Export** (Issue #73)
+**Status**: ✅ Epic created, 7 sub-issues planned
+**Priority**: Medium - Enhances business system integration
+**Timeline**: 5-7 weeks
+
+#### **Planned Components**:
+1. **External Data Connectors** - Database, API, file system integration
+2. **Professional Export Engine** - PDF, DOCX, HTML with styling
+3. **Document Relationship System** - Cross-document references and validation
+4. **Professional Template System** - Styled templates with corporate branding
+5. **Security & Access Control** - Enterprise-grade security for integrations
+6. **Audit & Compliance Framework** - Document lifecycle tracking
+7. **Integration Testing & Documentation** - Comprehensive integration validation
+
+#### **Success Criteria**:
+- Export styled PDF reports with CRM data integration
+- Validate cross-document references automatically
+- Support enterprise authentication and authorization
+
+## Implementation Strategy
+
+### **Phase 1: Core Business Engine** (Epic #64) - Weeks 1-7
+**Focus**: Template rendering and mathematical calculations
+**Dependencies**: None (builds on existing foundation)
+**Critical Path**: Template Engine → Expression Evaluator → CLI Integration
+
+### **Phase 2: Automation & Scale** (Epic #65) - Weeks 8-17
+**Focus**: Batch processing and workflow orchestration
+**Dependencies**: Epic #64 (Template & Calculation Engine)
+**Critical Path**: Batch Engine → Data Integration → Workflow Orchestration
+
+### **Phase 3: Integration & Professional Output** (Epic #66) - Weeks 18-24
+**Focus**: External systems and professional document export
+**Dependencies**: Epics #64 and #65
+**Critical Path**: External Connectors → Export Engine → Security Framework
+
+### **Total Timeline**: 24 weeks (6 months)
+
+## Architecture Integration Points
+
+### **Existing Systems** (Preserved)
+- **CLI Architecture**: All new commands integrate with existing patterns
+- **Database Layer**: Template storage extends current database schema
+- **Frontmatter/Contentmatter/Tailmatter**: Full integration with template metadata
+- **Quality Assurance**: Template validation integrates with existing QA workflows
+- **Test Infrastructure**: All new features follow existing testing patterns
+
+### **New Components** (Added)
+- **Template Engine**: Core rendering with variable substitution
+- **Expression Evaluator**: Mathematical calculations and business logic
+- **Batch Processing**: Multi-document operations with progress tracking
+- **Workflow Engine**: Multi-step process orchestration
+- **Export System**: Professional output formats (PDF, DOCX, HTML)
+- **External Connectors**: Database, API, and file system integration
+
+## Quality Assurance Framework
+
+### **Testing Strategy**
+- **Unit Tests**: >95% coverage for all new components
+- **Integration Tests**: Comprehensive testing with existing systems
+- **Performance Tests**: Enterprise-scale performance validation
+- **Backward Compatibility**: Ensure all existing functionality preserved
+
+### **Validation Requirements**
+- **Template Validation**: Syntax checking and data schema validation
+- **Batch Validation**: Quality gates for large-scale operations
+- **Security Validation**: Enterprise-grade security testing
+- **Compliance Validation**: Audit trail and regulatory compliance testing
+
+## Risk Management
+
+### **Technical Risks** (Mitigated)
+- **Performance**: Caching and optimization designed from foundation
+- **Complexity**: Incremental implementation with continuous integration
+- **Integration**: Backward compatibility testing at each milestone
+- **Scalability**: Horizontal scaling architecture from the start
+
+### **Business Risks** (Addressed)
+- **User Adoption**: Comprehensive documentation and examples
+- **Learning Curve**: Gradual feature rollout with training materials
+- **Enterprise Requirements**: Security and compliance built-in
+- **Market Timing**: Phased delivery enables early value realization
+
+## Success Metrics
+
+### **Technical Metrics**
+- **Template Performance**: <100ms rendering for typical business documents
+- **Batch Performance**: 1000+ documents processed in <5 minutes
+- **Memory Efficiency**: <100MB additional memory footprint
+- **Error Handling**: <1% unrecoverable failures in production use
+
+### **Business Metrics**
+- **Use Case Coverage**: Support for all major business document types
+- **Enterprise Adoption**: Integration with common ERP/CRM systems
+- **Professional Output**: Publication-quality documents for business use
+- **Workflow Automation**: 80% reduction in manual document generation time
+
+## Next Steps
+
+### **Immediate Actions** (Next Session)
+1. **Begin Epic #64 Implementation**: Start with Issue #65 (Template Engine Foundation)
+2. **Requirements Validation**: Use requirements engineering agent for design validation
+3. **Interface Design**: Define template engine interfaces using compatibility checking
+4. **Test Architecture**: Design comprehensive testing strategy
+
+### **Development Commands**
+```bash
+# Start template engine development
+make tdd-start NUM=65
+
+# Validate requirements during development
+make validate-requirements
+make check-interface-compatibility INTERFACE="TemplateEngine"
+
+# Generate development checklists as needed
+make generate-dev-checklist FEATURE="Template Rendering Engine"
+```
+
+### **Success Validation**
+- **Epic #64 Success**: Generate professional invoice from examples/invoice_template.md
+- **Epic #65 Success**: Process 100+ invoices from customer database in batch
+- **Epic #66 Success**: Export styled PDF reports with external data integration
+
+## Strategic Impact
+
+**Transformation Completed**: MarkiTect evolves from document analysis tool to comprehensive business document automation platform, enabling real-world enterprise applications with professional-quality output and seamless business system integration.
+
+**Market Position**: Positions MarkiTect as enterprise-ready solution for document automation workflows, competing with commercial document generation platforms while maintaining open-source flexibility and markdown-native approach.
--- a/todo/ARCHITECTURAL_CHAOS_TESTING_ISSUE.md
+++ b/todo/ARCHITECTURAL_CHAOS_TESTING_ISSUE.md
@@ -0,0 +1,229 @@
+# Issue: Architectural Layer Independence Test Runner with Chaos Engineering
+
+## 🎯 Objective
+Create a sophisticated test runner that validates architectural layer independence through controlled error injection (chaos engineering). This tool will systematically inject failures into each layer and verify that only dependent layers fail, while independent layers remain unaffected.
+
+## 🧠 Motivation
+Our current architectural test organization ensures proper execution order, but doesn't validate that layers are truly independent. Hidden dependencies between layers can:
+- Create fragile architecture that breaks unexpectedly
+- Violate clean architecture principles
+- Make debugging and maintenance difficult
+- Reduce system resilience
+
+## 🏗️ Technical Design
+
+### Core Components
+
+#### 1. Chaos Injection Engine
+```python
+class ArchitecturalChaosInjector:
+    """Systematically inject controlled failures into architectural layers."""
+
+    def inject_layer_failure(self, layer: str, strategy: str) -> ContextManager
+    def restore_layer_state(self, layer: str) -> None
+    def validate_injection_safety(self, strategy: str) -> bool
+```
+
+#### 2. Dependency Validation Matrix
+```python
+LAYER_DEPENDENCY_MATRIX = {
+    "foundation": {
+        "should_fail_when_broken": ["infrastructure", "integration", "domain", "service", "application", "presentation"],
+        "should_remain_independent": [],
+        "failure_tolerance": 0  # Foundation failures are critical
+    },
+    "infrastructure": {
+        "should_fail_when_broken": ["service", "application", "presentation"],
+        "should_remain_independent": ["domain"],  # Domain should be infrastructure-agnostic
+        "failure_tolerance": 20  # Some infrastructure failures may be recoverable
+    },
+    # ... complete matrix for all layers
+}
+```
+
+#### 3. Error Injection Strategies
+
+| **Layer** | **Injection Strategy** | **Implementation** | **Safety Level** |
+|-----------|------------------------|-------------------|-------------------|
+| **Foundation** | Database corruption | Mock SQLite connection failures | High |
+| **Foundation** | File system errors | Temporary permission changes | Medium |
+| **Infrastructure** | Cache corruption | Corrupt cache file contents | High |
+| **Infrastructure** | Config errors | Inject invalid configuration values | High |
+| **Integration** | Network failures | Mock HTTP timeout responses | High |
+| **Integration** | API errors | Return error responses from Gitea API | High |
+| **Domain** | Business logic errors | Inject invalid model states | Medium |
+| **Service** | Coordination failures | Break service interface contracts | Medium |
+| **Application** | Workflow errors | Inject use case execution failures | High |
+| **Presentation** | CLI errors | Break command argument parsing | High |
+
+#### 4. Test Execution Pipeline
+```
+1. Baseline Run: Execute all tests normally (establish baseline)
+2. For each layer:
+   a. Inject controlled failure
+   b. Run all layer tests
+   c. Analyze failure patterns
+   d. Detect dependency violations
+   e. Restore clean state
+3. Generate comprehensive violation report
+4. Provide remediation recommendations
+```
+
+## 📊 Expected Outcomes
+
+### Success Metrics
+- **Zero Dependency Violations**: Only expected layers fail when dependencies break
+- **Complete Layer Isolation**: Independent layers remain unaffected by unrelated failures
+- **Predictable Failure Patterns**: Failures follow documented dependency graph
+
+### Violation Detection
+- **Upward Dependencies**: Lower layers depending on higher layers (architectural violation)
+- **Cross-Layer Dependencies**: Unexpected dependencies between parallel layers
+- **Shared State Issues**: Tests affecting each other through global state
+
+### Reporting
+```
+🏗️ Architectural Chaos Test Results
+=====================================
+
+Foundation Layer Injection:
+✅ Expected failures: Infrastructure(98), Service(24), Application(16), Presentation(1)
+❌ Unexpected failures: Domain(2) - VIOLATION DETECTED
+
+Infrastructure Layer Injection:
+✅ Expected failures: Service(24), Application(16), Presentation(1)
+✅ Independent layers: Foundation(10), Domain(14) - ARCHITECTURE SOUND
+
+Violations Found: 1
+- Domain layer has hidden dependency on Foundation layer
+- Recommendation: Review domain models for infrastructure coupling
+```
+
+## 🚧 Implementation Plan
+
+### Phase 1: MVP Framework (3-4 days)
+- [ ] Create basic chaos injection framework
+- [ ] Implement safe error injection for Foundation layer
+- [ ] Build test execution pipeline
+- [ ] Create simple violation detection
+
+### Phase 2: Comprehensive Injection (4-5 days)
+- [ ] Implement error injection for all 7 layers
+- [ ] Add multiple injection strategies per layer
+- [ ] Create sophisticated failure simulation
+- [ ] Add state restoration mechanisms
+
+### Phase 3: Advanced Analysis (3-4 days)
+- [ ] Build dependency violation detection algorithms
+- [ ] Create detailed failure pattern analysis
+- [ ] Implement remediation recommendations
+- [ ] Add performance impact assessment
+
+### Phase 4: Integration & Polish (2-3 days)
+- [ ] Integrate with existing test infrastructure
+- [ ] Add Makefile targets
+- [ ] Create comprehensive documentation
+- [ ] Add safety mechanisms and rollback features
+
+## 🎯 Acceptance Criteria
+
+### Functional Requirements
+- [ ] Inject controlled failures into all 7 architectural layers
+- [ ] Execute tests under failure conditions safely
+- [ ] Detect dependency violations automatically
+- [ ] Generate actionable violation reports
+- [ ] Restore clean state after each injection
+- [ ] Integrate with existing test framework
+
+### Quality Requirements
+- [ ] Zero permanent damage to test environment
+- [ ] Reproducible failure injection (seed-based)
+- [ ] Clear documentation and examples
+- [ ] Performance overhead < 50% of normal test execution
+- [ ] Comprehensive error handling and recovery
+
+### Integration Requirements
+- [ ] Makefile targets: `make test-chaos`, `make test-layer-independence`
+- [ ] CLI interface: `run_chaos_tests.py --layer foundation --strategy database-failure`
+- [ ] Reporting integration with existing test reporting
+- [ ] CI/CD pipeline integration capability
+
+## 🔧 Technical Challenges
+
+### High Risk Areas
+1. **State Safety**: Ensuring injected failures don't permanently corrupt test environment
+2. **Realistic Failures**: Creating failure scenarios that accurately represent real-world issues
+3. **Test Isolation**: Preventing chaos injection from affecting parallel test runs
+4. **Performance Impact**: Managing execution time overhead from multiple test iterations
+
+### Mitigation Strategies
+1. **Sandbox Environment**: Run chaos tests in isolated environment
+2. **Atomic Transactions**: Ensure all state changes are reversible
+3. **Failure Simulation**: Use mocking rather than actual system corruption
+4. **Incremental Implementation**: Start with safe, simple failures and build complexity
+
+## 📚 Research & References
+
+### Similar Tools
+- **Chaos Monkey** (Netflix) - Infrastructure chaos engineering
+- **Gremlin** - Failure injection for distributed systems
+- **LitmusChaos** - Kubernetes chaos engineering
+- **pytest-chaos** - Test-level chaos engineering
+
+### Architectural Patterns
+- **Circuit Breaker Pattern** - For graceful failure handling
+- **Bulkhead Pattern** - For layer isolation
+- **Dependency Injection** - For controllable failure injection
+
+## 🎮 Usage Examples
+
+```bash
+# Basic chaos testing
+make test-chaos
+
+# Test specific layer independence
+make test-layer-independence LAYER=domain
+
+# Comprehensive chaos analysis
+python run_chaos_tests.py --all-layers --strategies all --report-format detailed
+
+# Reproduce specific violation
+python run_chaos_tests.py --layer infrastructure --strategy cache-corruption --seed 12345
+```
+
+## 💡 Future Enhancements
+
+### Advanced Features
+- **Gradual Failure Injection**: Slowly degrade system rather than instant failure
+- **Recovery Testing**: Test system behavior during failure recovery
+- **Load-Based Chaos**: Inject failures under different load conditions
+- **Temporal Chaos**: Time-based failure injection patterns
+
+### Integration Opportunities
+- **CI/CD Integration**: Automated architectural validation on every commit
+- **Monitoring Integration**: Real-world failure pattern comparison
+- **Documentation Generation**: Auto-update architecture docs with dependency findings
+
+## 🏷️ Labels
+- `enhancement`
+- `testing`
+- `architecture`
+- `chaos-engineering`
+- `high-priority`
+- `complex-implementation`
+
+## 📈 Business Value
+- **Architecture Integrity**: Ensure clean architecture principles are maintained
+- **System Resilience**: Identify and fix hidden dependencies before production
+- **Developer Confidence**: Clear understanding of system boundaries and dependencies
+- **Maintenance Efficiency**: Easier debugging and modification of isolated components
+- **Quality Assurance**: Automated validation of architectural decisions
+
+---
+
+**Estimated Effort**: 12-16 days
+**Risk Level**: Medium-High
+**Business Value**: Very High
+**Technical Complexity**: High
+
+This sophisticated chaos engineering approach will significantly improve our architectural robustness and provide ongoing validation of clean architecture principles.
--- a/todo/NEXT_SESSION_BRIEFING.md
+++ b/todo/NEXT_SESSION_BRIEFING.md
@@ -0,0 +1,227 @@
+# Development Session Summary - Practical Use Cases & Strategic Roadmap
+
+**Date**: 2025-10-02
+**Session Focus**: Use case analysis and tooling gap identification
+**Outcome**: ✅ Complete analysis with strategic development roadmap
+
+## 🎯 Current Status: Foundation Complete, Strategic Expansion Ready
+
+**Recently Completed Issues:**
+- ✅ Issue #38: Complete MarkdownMatters CLI implementation - COMPLETED
+- ✅ Issue #41: TOML frontmatter support - COMPLETED
+- ✅ Issue #42: Contentmatter Commands (MMD Key-Value Processing) - COMPLETED
+- ✅ Issue #43: Tailmatter Commands (QA and Editorial Metadata Management) - COMPLETED
+- ✅ Issue #46: Schema generation outline mode with heading text capture - COMPLETED
+- ✅ Issue #50: Metaschema definition - COMPLETED
+- ✅ Issue #59: Issue management CLI tool with plugin system - COMPLETED
+
+**Current Achievement**: **Comprehensive MarkiTect Foundation Complete** with full document lifecycle management, quality assurance workflows, and multi-format support. Ready for practical business applications.
+
+---
+
+## 🔍 Use Case Analysis & Gap Discovery
+
+**Analysis Based On**: Issue #63 use case brainstorming
+**Method**: Practical examples with real-world business scenarios
+**Examples Created**: Invoice templates, design patterns, compliance documents
+
+### **MarkiTect Foundation Strengths** ✅
+- **Document Structure & Metadata**: Complete frontmatter/contentmatter/tailmatter support
+- **Quality Assurance**: QA checklists, editorial workflows, validation systems
+- **Analysis Capabilities**: AST parsing, schema generation, comprehensive statistics
+- **CLI Maturity**: 740 passing tests, robust command interface
+- **Multi-format Support**: YAML/JSON/TOML parsing, flexible output formats
+
+### **Critical Gaps Identified** 🎯
+
+#### **Gap 1: Template Engine & Dynamic Generation**
+**Problem**: Cannot generate documents from templates + data
+**Business Impact**: Unable to create invoices, letters, reports from templates
+**Example**: `{{customer.name}}` stays literal, no rendering to "Acme Corporation"
+
+#### **Gap 2: Calculation & Business Logic**
+**Problem**: No mathematical operations or formula evaluation
+**Business Impact**: Cannot compute totals, taxes, derived values
+**Example**: Cannot calculate `{{sum line_items 'total'}}` or `{{multiply subtotal tax_rate}}`
+
+#### **Gap 3: Batch Processing & Automation**
+**Problem**: No multi-document operations or workflow automation
+**Business Impact**: Cannot scale to mass generation, batch validation
+**Example**: Cannot process 100 invoices from customer database
+
+#### **Gap 4: External Data Integration**
+**Problem**: No connectivity to databases, APIs, external sources
+**Business Impact**: Manual data preparation, no business system integration
+**Example**: Cannot import customer data from CRM or ERP systems
+
+#### **Gap 5: Cross-Document Relationships**
+**Problem**: No document linking or reference validation
+**Business Impact**: Cannot maintain document hierarchies or dependencies
+**Example**: Cannot validate that referenced specifications actually exist
+
+#### **Gap 6: Advanced Output Formats**
+**Problem**: Limited professional output capabilities
+**Business Impact**: Cannot generate PDFs, styled documents for business use
+**Example**: Cannot create professional invoices or compliance reports
+
+---
+
+## 📋 Strategic Development Roadmap
+
+### **Phase 1: Core Business Engine** (Epic #64 - Template & Calculation System)
+**Priority**: Critical - Foundation for all business applications
+**Components**:
+- Template rendering engine with variable substitution
+- Mathematical expression evaluator for calculations
+- Conditional content and loop support
+- Integration with existing metadata systems
+
+**Business Value**: Enables invoice generation, report automation, dynamic documents
+
+### **Phase 2: Automation & Scale** (Epic #65 - Batch Processing & Workflows)
+**Priority**: High - Required for production business use
+**Components**:
+- Multi-document processing commands
+- Data-driven batch generation from CSV/JSON
+- Workflow orchestration and pipeline management
+- Batch validation and comprehensive reporting
+
+**Business Value**: Enables mass mailings, automated reporting, enterprise workflows
+
+### **Phase 3: Integration & Professional Output** (Epic #66 - External Systems & Export)
+**Priority**: Medium - Enhances business system integration
+**Components**:
+- External data source connectors (databases, APIs, files)
+- Advanced output format support (PDF, DOCX, HTML with styling)
+- Cross-document relationship management and validation
+- Professional template libraries and styling systems
+
+**Business Value**: Enables ERP integration, professional document generation, compliance workflows
+
+---
+
+## 🛠 Development Environment & Infrastructure
+
+### Working Directory
+```
+/mnt/c/Users/bernd.worsch/Documents/binky/2025/250915b-markitectAdvancedMarkdownEngine/markitect_project
+```
+
+### Current System Health
+- **Test Status**: 740 tests passing (100% success rate)
+- **CLI Commands**: Complete MarkdownMatters implementation
+- **Database**: SQLite with comprehensive document storage
+- **Git Status**: Clean working tree, ready for new development
+
+### Key Infrastructure Files
+- **USE_CASES_GAP_ANALYSIS.md**: Comprehensive analysis document
+- **examples/**: Practical use case examples (invoice, patterns)
+- **markitect/**: Complete CLI implementation with all command families
+- **tests/**: Comprehensive test suite with integration testing
+
+---
+
+## 🎮 Requirements Engineering Task Queue
+
+### **CRITICAL NEXT ACTIONS** 🚨
+
+#### **1. Epic Decomposition for Issue #64** (Template & Calculation System)
+**Task**: Use requirements engineering agent to break down Phase 1 epic
+**Components to Define**:
+- Template rendering engine requirements
+- Mathematical expression evaluator specifications
+- Variable substitution system design
+- Integration points with existing metadata systems
+- Testing strategy for dynamic content generation
+
+#### **2. Epic Decomposition for Issue #65** (Batch Processing & Workflows)
+**Task**: Use requirements engineering agent to break down Phase 2 epic
+**Components to Define**:
+- Multi-document processing architecture
+- Data source integration patterns
+- Workflow orchestration requirements
+- Batch operation error handling and reporting
+- Performance requirements for large-scale operations
+
+#### **3. Epic Decomposition for Issue #66** (External Systems & Export)
+**Task**: Use requirements engineering agent to break down Phase 3 epic
+**Components to Define**:
+- External data connector architecture
+- Output format conversion requirements
+- Document relationship modeling
+- Professional template system design
+- Security and access control for external integrations
+
+### **Requirements Engineering Workflow**
+```bash
+# Create epic issues in gitea
+python3 tddai_cli.py create-issue --title "Epic #64: Template & Calculation Engine" --epic
+python3 tddai_cli.py create-issue --title "Epic #65: Batch Processing & Workflows" --epic
+python3 tddai_cli.py create-issue --title "Epic #66: External Systems & Professional Export" --epic
+
+# Use requirements agent for decomposition
+make validate-requirements
+make generate-dev-checklist FEATURE="Template Engine"
+make check-interface-compatibility INTERFACE="TemplateRenderer"
+```
+
+---
+
+## 🧪 TDD8 Workflow Protocol
+
+### Enhanced for Business Applications
+1. **ISSUE** - Business requirements analysis with real use cases
+2. **TEST** - Test-driven development with practical examples
+3. **RED** - Verify tests fail before implementation
+4. **GREEN** - Implement minimal viable business functionality
+5. **REFACTOR** - Clean architecture with business logic separation
+6. **DOCUMENT** - Business-focused CLI help and user guides
+7. **REFINE** - Performance optimization for enterprise scale
+8. **PUBLISH** - Production-ready commits with business validation
+
+### Quality Standards for Business Applications
+- Business use case validation with real examples
+- Performance requirements for enterprise scale (1000+ documents)
+- Professional error handling and user feedback
+- Integration testing with external systems
+- Security considerations for business data
+
+---
+
+## 🚀 Immediate Next Steps
+
+### **For Requirements Engineering Agent**
+1. **Analyze** USE_CASES_GAP_ANALYSIS.md for technical requirements
+2. **Decompose** each epic into implementable issues (5-8 issues per epic)
+3. **Define** acceptance criteria with business validation scenarios
+4. **Plan** implementation sequence considering dependencies
+5. **Validate** requirements against existing architecture
+
+### **Success Criteria for Epic Development**
+- **Epic #64**: Generate professional invoice from template + customer data
+- **Epic #65**: Process 100+ documents in single batch operation
+- **Epic #66**: Export styled PDF reports with CRM data integration
+
+### **Starting Command for Requirements Work**
+```bash
+# Begin requirements engineering for template system
+make validate-requirements
+make generate-dev-checklist FEATURE="Template & Calculation Engine"
+```
+
+---
+
+## 📊 Strategic Impact
+
+**Before**: MarkiTect as document analysis and validation tool
+**After**: MarkiTect as comprehensive business document automation platform
+
+**Market Position**: Transform from developer tool to business application engine
+**Value Proposition**: Complete document lifecycle automation with professional output
+
+---
+
+*Updated: October 2, 2025*
+*Status: Foundation Complete - Strategic Expansion Ready*
+*Achievement: Comprehensive gap analysis with 3-phase development roadmap*
+*Next Target: Requirements engineering for business application epics*
--- a/todo/RelevantClaudeIssues.md
+++ b/todo/RelevantClaudeIssues.md
@@ -0,0 +1,75 @@
+# Relevant Claude Code Issues
+
+## Introduction
+
+This document tracks Claude Code issues that directly impact our development workflows for the MarkiTect project. Each issue section provides a clear problem description, affected workflows, related GitHub issues for monitoring, available workarounds, and resolution tracking information.
+
+**Purpose:**
+- Document blocking Claude Code issues affecting project development
+- Provide centralized tracking of GitHub issues to monitor for fixes
+- Maintain awareness of workarounds and their trade-offs
+- Enable quick assessment of when normal workflows can resume
+
+**Maintenance:**
+- Update when new blocking issues are discovered
+- Check GitHub issue status weekly and update resolution monitoring
+- Remove resolved issues after confirming fixes work in our environment
+- Maintained by the agent-claude-documentation subagent as part of issue tracking responsibilities
+
+**🎯 CRITICAL WORKFLOW REMINDER:**
+When discussing project issues (not Claude Code issues), ALWAYS fetch from Gitea first. Gitea is the source of truth for all issue assessment, feasibility evaluation, and implementation planning. Local files are insufficient for decision-making about issues. See ISSUE_WORKFLOW_REMINDER.md for complete workflow.
+
+---
+
+## Resolved Issues
+
+### ✅ RESOLVED: Custom Subagents Not Available
+
+### Problem Description (Historical)
+
+Custom subagents defined in `.claude/agents/` directory were not being detected or made available as `subagent_type` options in the Task tool. This prevented the intended workflow of using specialized subagents for domain-specific tasks like project management, documentation, or Claude Code expertise.
+
+The custom subagent system appeared completely broken, with agents not being recognized despite proper YAML frontmatter configuration.
+
+### Resolution Details
+
+**Resolved Date:** 2025-09-23
+**Resolution Method:** Issue appears to have been fixed in current Claude Code version
+**Verification:** Successfully tested the following subagents:
+- ✅ `general-purpose` - Full tool access for complex multi-step tasks
+- ✅ `agent-claude-documentation` - Specialized for Claude Code documentation and features
+- ✅ `agent-project-management` - Specialized for MarkiTect project status and development planning
+
+**Resolution Confirmation Steps:**
+1. ✅ Custom agents now appear as valid `subagent_type` options in Task tool
+2. ✅ Successfully invoked custom subagents for specialized tasks
+3. ✅ All intended multi-agent workflows are now functional
+4. ✅ No workarounds needed - normal operation restored
+
+### Impact of Resolution
+
+**Restored Workflows:**
+- **Specialized Task Delegation**: ✅ Custom subagents working for domain-specific tasks
+- **Project Management**: ✅ agent-project-management subagent functional for status tracking and planning
+- **Documentation Assistance**: ✅ agent-claude-documentation subagent operational for Claude Code expertise
+- **Task Decomposition**: ✅ Full subagent ecosystem available
+- **Workflow Automation**: ✅ Multi-agent collaborative workflows enabled
+
+**Workarounds No Longer Needed:**
+- No need to downgrade Claude Code versions
+- No need to use only built-in general-purpose agent
+- No need for manual role assignment
+
+### Related GitHub Issues (Historical Reference)
+
+- [#4623](https://github.com/anthropics/claude-code/issues/4623) - Custom agents not being detected
+- [#4728](https://github.com/anthropics/claude-code/issues/4728) - Agent discovery mechanism broken
+- [#4626](https://github.com/anthropics/claude-code/issues/4626) - Custom agents missing from UI
+- [#5185](https://github.com/anthropics/claude-code/issues/5185) - Agent configuration not working
+- [#4182](https://github.com/anthropics/claude-code/issues/4182) - Task tool limitations for nested agents
+
+---
+
+## Monitoring Schedule
+
+This document should be reviewed weekly to check for issue resolution and update status. The agent-claude-documentation subagent is responsible for maintaining this tracking and updating the project team when workflows can resume normal operation.