Fix main branch README with dual-purpose sections and working links
CRITICAL FIXES: - Completely rewrote README for dual purpose (template users vs contributors) - Fixed all broken documentation links that referenced non-existent files on main - Clear separation: Section 1 for template users, Section 2 for developers - Added CONTRIBUTING.md with comprehensive development guidelines TEMPLATE USER SECTION: - Clear warning: Don't clone, download releases instead - Direct links to latest release artifacts - Quick start instructions for CTO delegation - Focus on template usage, not repository development DEVELOPER SECTION: - Instructions for contributing to framework itself - WORKONMAIN branch workflow explanation - Links to CONTRIBUTING.md for detailed guidelines - Clear branch purposes and development setup WORKING LINKS: - All links now point to files that exist on main branch - Release links use Gitea relative paths (../../releases/latest) - License link works (./LICENSE exists on main) - CONTRIBUTING.md link works (file created on main) Ready for clean template user experience with no broken links.
This commit is contained in:
284
CONTRIBUTING.md
Normal file
284
CONTRIBUTING.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user