UKRRS/CTO
2
0
Fork 0
Code Pull Requests Actions Packages Releases Wiki Activity

Compare commits

base: UKRRS:main
Branches Tags
UKRRS:main UKRRS:WORKONMAIN UKRRS:LLMBOOTSTRAP UKRRS:INTEGRATION-WIP UKRRS:RELEASE
UKRRS:phase-2-enhancements-complete UKRRS:bootstrap-framework-complete UKRRS:template-ready UKRRS:docs-reorganized UKRRS:bootstrap-complete
..
compare: UKRRS:bootstrap-complete
Branches Tags
UKRRS:WORKONMAIN UKRRS:main UKRRS:LLMBOOTSTRAP UKRRS:INTEGRATION-WIP UKRRS:RELEASE
UKRRS:phase-2-enhancements-complete UKRRS:bootstrap-framework-complete UKRRS:template-ready UKRRS:docs-reorganized UKRRS:bootstrap-complete

1 Commits
main ... bootstrap-

Author SHA1 Message Date
ReachableCEO
57685f333b Add comprehensive git workflow with tagging guidelines and DO/DON'T examples 2025-09-05 07:29:52 -05:00
4 changed files with 204 additions and 386 deletions
Expand all files Collapse all files

28
AGENT.MD Normal file
View File

@@ -0,0 +1,28 @@
# Agent Guidelines
This document provides guidelines for AI agents working on this repository.
## Git Workflow
All agents must follow the established git workflow documented in [GIT_WORKFLOW.MD](./GIT_WORKFLOW.MD).
## Key Principles
1. **Never work on the main branch** - All development must occur on feature branches
2. **Follow the branch structure** as defined in the workflow documentation
3. **Respect the integration and release processes** outlined in the workflow
## Required Reading
Before making any commits or branches, agents must review:
- [Git Workflow Documentation](./GIT_WORKFLOW.MD)
## Branch Usage
- Use `LLMBOOTSTRAP` for initial setup and bootstrap tasks
- Create new feature branches for specific development tasks
- Ensure all work follows the integration and release pipeline
## Repository Context
This repository uses Gitea (not GitHub) for version control and collaboration.

284
CONTRIBUTING.md
View File

@@ -1,284 +0,0 @@
# 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.*

174
GIT_WORKFLOW.MD Normal file
View File

@@ -0,0 +1,174 @@
# Git Workflow
This document outlines the git workflow for this repository, designed for use with Gitea.
## Branch Structure
### Main Branches
- **`main`** - The primary stable branch. Direct work should NOT be done on this branch.
- **`RELEASE`** - Production-ready code. Only accepts pull requests that have been manually reviewed and approved.
- **`INTEGRATION-WIP`** - Integration branch where all feature branches are automatically merged for testing and integration.
### Feature Branches
- **`LLMBOOTSTRAP`** - Initial bootstrap feature branch for LLM-assisted development setup.
- Additional feature branches should follow naming conventions like `feature/description` or `task/description`.
## Workflow Rules
1. **Never work directly on `main`** - All work must be done on feature branches.
2. **Feature Development Flow:**
- Create feature branches from `main`
- Develop features in isolation on these branches
- Feature branches automatically merge to `INTEGRATION-WIP` for continuous integration testing
3. **Integration Testing:**
- `INTEGRATION-WIP` branch serves as the integration environment
- All feature branches are automatically merged here
- Used for testing compatibility between different features
4. **Release Process:**
- Only manually reviewed pull requests are merged to `RELEASE`
- `RELEASE` branch represents production-ready code
- Requires explicit approval before merging
## Branch Protection
- `main` - Protected, no direct commits allowed
- `RELEASE` - Protected, only manual PR merges allowed
- `INTEGRATION-WIP` - Accepts automatic merges from feature branches
## Feature Branch Management
### **CRITICAL: Branch Preservation**
- **NEVER automatically delete feature branches** under any circumstances
- Feature branches must be preserved for historical reference and potential future work
- Branch deletion should only occur through explicit manual action after careful consideration
### **Commit and Push Frequency**
- **Commit frequently** - Make small, logical commits as you work
- **Push every 10 commits maximum** - Don't let local commits accumulate
- **ALWAYS push before switching branches** - Ensure work is backed up remotely
- **Push immediately before any branch operations** (merge, rebase, etc.)
### **Tagging for Milestones**
- **Create tags when interim stages or milestones are completed**
- **Push tags immediately after creation** to preserve milestone markers
- **Tag naming conventions:**
- Date-based: `milestone-YYYY-MM-DD` or `stage-YYYY-MM-DD-HHMM`
- Stage-based: `bootstrap-complete`, `auth-module-done`, `integration-ready`
- Plan-based: Use milestone names from planning documents
- **Always annotate tags** with meaningful descriptions of what was accomplished
## Best Practices
- Keep feature branches focused and small
- Use descriptive branch names
- Regularly sync feature branches with `main`
- Test thoroughly in `INTEGRATION-WIP` before requesting merge to `RELEASE`
- Write clear commit messages and PR descriptions
- Follow the commit/push frequency rules above
## Examples: DO and DON'T
### ✅ **DO Examples**
```bash
# DO: Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/user-authentication
# DO: Commit frequently with descriptive messages
git add .
git commit -m "Add user login form validation"
git commit -m "Implement password hashing utility"
git commit -m "Add user session management"
# DO: Push after every 10 commits or before switching branches
git push origin feature/user-authentication
# DO: Push before switching to another branch
git push origin feature/user-authentication
git checkout feature/payment-system
# DO: Sync feature branch with main regularly
git checkout main
git pull origin main
git checkout feature/user-authentication
git merge main
# DO: Tag milestones with descriptive annotations
git tag -a bootstrap-complete -m "Initial project structure and workflow setup completed"
git push origin bootstrap-complete
# DO: Use date-based tags for interim stages
git tag -a stage-2025-09-05-1430 -m "Authentication module implementation complete"
git push origin stage-2025-09-05-1430
```
### ❌ **DON'T Examples**
```bash
# DON'T: Work directly on main
git checkout main
git add .
git commit -m "Fix user auth bug" # ❌ NEVER DO THIS
# DON'T: Delete feature branches automatically
git branch -d feature/user-authentication # ❌ NEVER DO THIS
git push origin --delete feature/user-authentication # ❌ NEVER DO THIS
# DON'T: Let commits accumulate without pushing
git log --oneline # Shows 15+ unpushed commits # ❌ Should have pushed earlier
# DON'T: Switch branches without pushing current work
git checkout feature/payment-system # ❌ Without pushing current branch first
# DON'T: Make massive commits
git add .
git commit -m "Complete entire user system" # ❌ Too broad, break it down
# DON'T: Create tags without annotations
git tag milestone-1 # ❌ No description of what was accomplished
git push origin milestone-1
# DON'T: Forget to push tags
git tag -a bootstrap-complete -m "Setup complete"
# ❌ Missing: git push origin bootstrap-complete
```
### 🔧 **Workflow Examples**
**Starting new feature:**
```bash
git checkout main
git pull origin main
git checkout -b feature/shopping-cart
# Work, commit frequently, push every ~10 commits
```
**Switching between features:**
```bash
# Currently on feature/shopping-cart
git add .
git commit -m "Add item quantity validation"
git push origin feature/shopping-cart # ✅ Push before switching
git checkout feature/user-profile
```
**Preparing for integration:**
```bash
git checkout feature/shopping-cart
git push origin feature/shopping-cart
# Feature automatically merges to INTEGRATION-WIP
```
## Gitea Integration
This workflow is optimized for Gitea and utilizes:
- Branch protection rules
- Automatic merge capabilities for integration testing
- Manual review processes for production releases

104
README.md
View File

@@ -1,103 +1,3 @@
# CTO AI Delegation Framework
# CTO
**Prompts and code for founder CTOs who want to delegate to AI as an entire team.**
---
## 🎯 **For CTO Template Users (Most Users)**
**If you want to use this CTO AI delegation template for your project:**
### ⚠️ **Don't Clone This Repository!**
Instead, download the latest release as a template:
1. **Download Latest Release:** [📦 Latest Release](../../releases/latest)
2. **Extract** the downloaded zip to your project directory
3. **Run Setup:** `./start-ai-delegation.sh` (or follow instructions in extracted files)
4. **Start Delegating:** AI agents will read the included documentation automatically
### 🚀 **Quick Start for Template Users**
```bash
# After extracting the release:
cd your-project-directory
./start-ai-delegation.sh
# Follow the prompts to set up your CTO AI delegation workflow
```
**What You Get:**
- ✅ Complete AI delegation framework
- ✅ Deterministic workflows for AI agents
- ✅ Professional git workflow with branch protection
- ✅ Real-time progress tracking and dashboards
- ✅ Comprehensive documentation (human + AI optimized)
---
## 🛠️ **For Framework Developers (Repository Contributors)**
**If you want to contribute to the CTO delegation framework itself:**
### Development Setup
```bash
# Clone the repository for development
git clone git@git.knownelement.com:UKRRS/CTO.git
cd CTO
# Switch to development branch (has all the features)
git checkout WORKONMAIN
# See full documentation and development environment
ls docs/
```
### Development Workflow
- **WORKONMAIN** - Long-lived development branch for framework improvements
- **LLMBOOTSTRAP** - Feature development branch
- **main** - Template baseline (minimal, clean for end users)
### Contributing Guidelines
See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed development instructions.
---
## 📊 **Repository Information**
### Branch Structure
| Branch | Purpose | Who Uses It |
|--------|---------|-------------|
| **`main`** | Clean template baseline | Template users browsing |
| **`WORKONMAIN`** | Framework development | Contributors |
| **`LLMBOOTSTRAP`** | Feature development | Contributors |
### Latest Releases
| Release | Date | Description |
|---------|------|-------------|
| [phase-2-enhancements-complete](../../releases/tag/phase-2-enhancements-complete) | 2025-09-05 | Full framework with testing, dashboards, git-native integration |
| [bootstrap-framework-complete](../../releases/tag/bootstrap-framework-complete) | 2025-09-05 | Core bootstrap framework |
### Platform Information
- **Git Platform:** Gitea (optimized exclusively)
- **AI Compatibility:** Claude, Gemini-CLI, OpenCode
- **Architecture:** Git-native automation, no external dependencies
- **License:** [View License](./LICENSE)
---
## 🤖 **Framework Features**
- **Deterministic AI Instructions** - Exact command sequences for consistent results
- **Git-Native Automation** - Auto-merge integration via git hooks
- **Progress Dashboards** - Real-time CTO oversight and metrics
- **Bootstrap Testing** - Comprehensive validation framework
- **Dual Documentation** - Human-readable + AI-optimized versions
- **Branch Protection** - Main branch human-only policy
- **Milestone Tracking** - Complete audit trail and progress markers
---
**Need Help?**
- **Template Users:** Check the documentation in your downloaded release
- **Developers:** See [CONTRIBUTING.md](./CONTRIBUTING.md) or browse the [WORKONMAIN branch](../../tree/WORKONMAIN)
*Professional AI team delegation framework - Built for founder CTOs*
Prompts and code for founder CTO who want to delegate to AI as an entire team.