CTO/CONTRIBUTING.md

Contributing to CTO AI Delegation Framework

Welcome to the CTO AI Delegation Framework development! This guide is for developers who want to contribute to the framework itself, not for users of the template.

---

🎯 Quick Start for Contributors

Development Setup

# Clone the repository
git clone git@git.knownelement.com:UKRRS/CTO.git
cd CTO

# Switch to main development branch
git checkout WORKONMAIN

# Explore the full framework
ls docs/

Understanding the Repository Structure

Branch	Purpose	When to Use
main	Clean template baseline for end users	Never (except for README/LICENSE updates)
WORKONMAIN	Main development branch	Most framework development
LLMBOOTSTRAP	Feature development branch	Experimental features

---

🛠️ Development Workflow

For Framework Improvements

# Start from WORKONMAIN
git checkout WORKONMAIN
git pull origin WORKONMAIN

# Create feature branch for your improvement
git checkout -b feature/your-improvement

# Make changes, test, commit
git add .
git commit -m "Add your improvement"
git push origin feature/your-improvement

# Create pull request to WORKONMAIN

For Main Branch Updates (Rare)

# Only for README, LICENSE, or critical template baseline changes
git checkout WORKONMAIN  # Start from full development context

# Create WORKONMAIN → main PR when approved by maintainer
# (This bypasses normal "human-only main" rule for framework development)

---

📋 Development Guidelines

Code Standards

• Scripts must be executable: chmod +x script.sh
• Gitea-exclusive platform: No GitHub/GitLab references
• Git-native solutions preferred: Avoid external dependencies
• Dual documentation: Maintain both human and LLM-optimized versions

Documentation Standards

• Update both versions: docs/FILE.md and docs/FILE-LLM.md
• Test all links: Ensure Gitea web interface compatibility
• Keep deterministic: AI instructions must be exact command sequences
• Platform consistency: All references must be Gitea-specific

Testing Requirements

# Test your changes
./test-bootstrap.sh

# Test integration automation  
./setup-git-auto-merge.sh

# Generate progress dashboard
./generate-progress-dashboard.sh

# Validate all scripts work

---

🧪 Testing Framework

Bootstrap Testing

# Run comprehensive bootstrap validation
./test-bootstrap.sh

# Expected: 8 tests passing
# - Template file presence
# - Git initialization  
# - Branch creation
# - Template placeholders
# - AI agent instructions
# - Milestone tagging
# - Automation script validation
# - Integration setup

Integration Testing

# Test git-native auto-merge
./setup-git-auto-merge.sh

# Create test commits on feature branches
# Verify INTEGRATION-WIP auto-merge works

Dashboard Testing

# Generate dashboard with current data
./generate-progress-dashboard.sh

# Check generated files
ls docs/dashboard/
open docs/dashboard/index.html

---

📚 Documentation Maintenance

Key Files to Update

When making changes, consider updating:

Core Documentation:

• docs/AGENT-LLM.MD - Primary AI agent instructions
• docs/GIT_WORKFLOW.MD - Comprehensive workflow guide
• docs/INTEGRATION-AUTOMATION.md - Integration setup guide

Tracking Files:

• TODO.md + TODO-LLM.md - Project roadmap
• RETROSPECTIVE.md + RETROSPECTIVE-LLM.md - Project analysis
• PLATFORM-REQUIREMENTS.md - Platform constraints

Template Files:

• docs/WORKLOG-LLM.md - Template progress tracking
• docs/CURRENTWORK-LLM.md - Template session logging

Documentation Sync

# After updating human-readable docs, update LLM versions
# Example: Update AGENT.MD → also update AGENT-LLM.MD

# Keep content aligned but optimize format for target audience
# Human: Comprehensive, contextual, explanatory
# LLM: Concise, command-focused, deterministic

---

🏷️ Release Process

Creating Releases

# When ready to release improvements
git checkout WORKONMAIN

# Create milestone tag
git tag -a framework-v1.x.x -m "Framework improvements: [describe changes]"
git push origin framework-v1.x.x

# Maintainer creates GitHub/Gitea release from tag
# Users download release artifacts as templates

Tag Naming Convention

• framework-v1.x.x - Framework improvements
• phase-N-complete - Major phase completions
• milestone-YYYY-MM-DD - Date-based milestones
• feature-NAME-complete - Specific feature completions

---

🔍 Code Review Guidelines

What Reviewers Look For

1. Gitea Compatibility - Works exclusively with Gitea
2. Git-Native Solutions - Prefers git over external tools
3. Deterministic Instructions - AI agents get exact commands
4. Documentation Completeness - Both human and LLM versions updated
5. Testing Coverage - Changes include appropriate tests

Pull Request Template

## Changes Made
- [Brief description of changes]

## Testing Done  
- [ ] Bootstrap testing passes (`./test-bootstrap.sh`)
- [ ] Integration testing works (`./setup-git-auto-merge.sh`) 
- [ ] Documentation updated (both human and LLM versions)
- [ ] Scripts are executable and work in clean environment

## Breaking Changes
- [Any breaking changes for template users]

## Documentation Updates
- [ ] Updated relevant docs in `docs/` directory
- [ ] Updated TODO.md if roadmap changed
- [ ] Updated RETROSPECTIVE.md if architecture changed

---

🚨 Important Constraints

Platform Requirements

• Gitea Exclusive: No GitHub or GitLab references anywhere
• Git-Native Preferred: Avoid workflow-based solutions when git hooks work
• No External Dependencies: Framework should work with just git + bash

Branch Protection Rules

• Main Branch: Minimal, clean baseline for template users
• WORKONMAIN: Where framework development happens
• Human Oversight: All merges to main require explicit approval

Template User Focus

• Don't Break Template Usage: Changes shouldn't affect template download/usage
• Maintain Simplicity: Template users want simple bootstrap process
• Preserve Determinism: AI delegation must remain predictable

---

💡 Development Tips

Environment Setup

# Work in isolated test directories
mkdir /tmp/cto-test && cd /tmp/cto-test

# Extract current template to test changes
cp -r /path/to/CTO/* .
rm -rf .git

# Test bootstrap process in clean environment
./start-ai-delegation.sh  # or manual bootstrap process

Common Pitfalls

• Broken links on main branch: Test README links work in Gitea web UI
• Platform references: Scan for any GitHub/GitLab mentions
• Missing LLM docs: Always update both human and LLM versions
• Non-executable scripts: Check chmod +x on all shell scripts

Debugging

# Enable debug mode for scripts
export DEBUG=1

# Run with verbose output
./test-bootstrap.sh --debug
./generate-progress-dashboard.sh --check-sources

---

📞 Getting Help

Resources

• Current Documentation: Browse docs/ directory on WORKONMAIN branch
• Project Roadmap: See TODO.md and TODO-LLM.md
• Architecture Decisions: Review RETROSPECTIVE.md

Communication

• Issues: Use repository issue tracker
• Discussions: Repository discussions or maintainer contact
• Pull Requests: Follow PR template and guidelines above

---

Thank you for contributing to the CTO AI Delegation Framework!

Your improvements help founder CTOs delegate more effectively to AI teams.