Fix critical template usage issues for CTO AI delegation

MAJOR FIXES:
- AGENT-LLM.MD: Add git init setup instructions for fresh repositories
- AGENT-LLM.MD: Replace clone workflow with template workflow
- AGENT-LLM.MD: Add deterministic command sequences for consistent AI outcomes
- WORKLOG-LLM.md: Convert to template with bracketed placeholders
- CURRENTWORK-LLM.md: Convert to template with structured sections
- Add TEMPLATE-README.md with complete setup instructions

DETERMINISTIC IMPROVEMENTS:
- Exact command sequences for AI agents
- Mandatory worklog maintenance patterns
- Specific commit message and tagging formats
- Clear CTO delegation principles and audit trails

Ready for milestone tag download and fresh git init usage.
This commit is contained in:
2025-09-05 07:47:32 -05:00
parent 44cdd6eb67
commit 711bcf20a1
4 changed files with 332 additions and 126 deletions

View File

@@ -1,65 +1,100 @@
# AI AGENT REFERENCE - LLM OPTIMIZED
# AI AGENT REFERENCE - TEMPLATE VERSION
**FOR: Gemini-CLI, Claude, OpenCode, all AI tools**
**FOR: Gemini-CLI, Claude, OpenCode, all AI tools working with CTO delegation template**
## CRITICAL SETUP (FIRST TIME ONLY)
**This template requires initial git setup:**
```bash
git init
git add .
git commit -m "Initial commit from CTO template"
git branch -M main
git remote add origin YOUR_REPO_URL
git push -u origin main
```
**Create required branches:**
```bash
git checkout -b INTEGRATION-WIP && git push -u origin INTEGRATION-WIP
git checkout -b RELEASE && git push -u origin RELEASE
git checkout main
```
## CRITICAL RULES
1. NEVER work on `main` branch
2. NEVER auto-delete feature branches
3. ALWAYS push before switching branches
4. Push every 10 commits max
5. Tag milestones
6. UPDATE WORKLOGS
1. NEVER work on `main` branch - Always use feature branches
2. NEVER auto-delete feature branches - Preserve all branches permanently
3. ALWAYS push before switching branches - Never lose work
4. Push every 10 commits max - Keep work backed up
5. Tag milestones - Mark completed stages/milestones
6. UPDATE WORKLOGS - Maintain both worklog files
## COMMANDS
## DETERMINISTIC COMMANDS
**New feature:**
**Start new feature (EXACT sequence):**
```bash
git checkout main && git pull origin main
git checkout -b feature/name
git checkout main
git pull origin main
git checkout -b feature/TASK-NAME
```
**Before switch:**
**Save work before switching (MANDATORY):**
```bash
git add . && git commit -m "msg"
git push origin current-branch
git add .
git commit -m "SPECIFIC_DESCRIPTION_OF_CHANGES"
git push origin CURRENT-BRANCH-NAME
```
**Tag milestone:**
**Tag completed milestone:**
```bash
git tag -a name -m "description"
git push origin name
git tag -a MILESTONE-NAME -m "DETAILED_DESCRIPTION_OF_COMPLETION"
git push origin MILESTONE-NAME
```
## BRANCHES
- `main` - stable, protected
- `LLMBOOTSTRAP` - initial setup
- `INTEGRATION-WIP` - auto-merge target
- `RELEASE` - manual PR target
- `feature/*` - all development
## BRANCH STRUCTURE (CREATE THESE)
- **`main`** - Stable, protected, no direct commits
- **`INTEGRATION-WIP`** - Auto-merge target for testing features
- **`RELEASE`** - Manual PR target for production releases
- **`feature/TASK-NAME`** - All development work (descriptive names)
## WORKFLOW
1. Create feature branch from main
2. Frequent commits (small, logical)
3. Push every ~10 commits or before switch
4. Auto-merge to INTEGRATION-WIP
5. Manual PR to RELEASE
6. NEVER delete branches
## DETERMINISTIC WORKFLOW
1. **Always start from main:** `git checkout main && git pull origin main`
2. **Create specific branch:** `git checkout -b feature/EXACT-TASK-NAME`
3. **Work in small chunks:** Commit every logical change
4. **Push frequently:** Every 5-10 commits or before any branch switch
5. **Never delete branches:** Preserve all feature branches permanently
6. **Tag milestones:** When features/stages complete
## TAGGING
**When:** milestone/stage/feature complete
**Format:** `bootstrap-complete`, `milestone-2025-09-05`, `auth-done`
**Command:** `git tag -a name -m "desc"`
## MILESTONE TAGGING (DETERMINISTIC)
**When to tag:**
- Feature completely implemented and tested
- Stage of project fully complete
- Major milestone achieved
## WORKLOGS
- **docs/WORKLOG-LLM.md** - status/progress
- **docs/CURRENTWORK-LLM.md** - detailed notes
**Pattern:** Start→update status, During→add notes, End→update completion
**Format (be specific):**
- `feature-auth-complete` (feature done)
- `milestone-YYYY-MM-DD-DESCRIPTION` (date+description)
- `stage-NAME-done` (stage complete)
## FILES
- Human: docs/GIT_WORKFLOW.MD, docs/AGENT.MD, docs/WORKLOG.md, docs/CURRENTWORK.md
- LLM: docs/*-LLM.MD (this file and others)
## WORKLOG MAINTENANCE (MANDATORY)
**Update these files every session:**
- **docs/WORKLOG-LLM.md** - Current status, progress, next actions
- **docs/CURRENTWORK-LLM.md** - Detailed notes, decisions, concerns
**Pattern (deterministic):**
1. Session start → Update current status in WORKLOG-LLM.md
2. During work → Add detailed notes to CURRENTWORK-LLM.md
3. Session end → Update completion status and next actions
## CTO DELEGATION PRINCIPLES
**Make outcomes deterministic:**
- Use specific commit messages describing exact changes
- Tag with descriptive names explaining what was accomplished
- Document all decisions and concerns in CURRENTWORK-LLM.md
- Follow exact command sequences above
- Never deviate from branch protection rules
## CONTEXT
- Platform: Gitea (not GitHub)
- Repo: /home/localuser/UKSRS/CTO
- Keep clean: docs in docs/ directory
- **Purpose:** Template for CTO AI delegation framework
- **Platform:** Any git hosting (GitHub, Gitea, GitLab)
- **Structure:** Keep docs in docs/ directory for clean repos
- **Philosophy:** Deterministic AI delegation with complete audit trail