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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Test git-native auto-merge
./setup-git-auto-merge.sh

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

### Dashboard Testing
```bash
# 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
```bash
# 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
```bash
# 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
```markdown
## 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
```bash
# 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
```bash
# 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.*