docs: create AGENTS.md proposal v2 to reflect current state\n\n- Create PROPOSAL-AGENTS-v2.md that aligns with current AGENTS.md v7.0.1\n- Update to reflect advanced databank/PMO structure with access rights\n- Include current authority structure with Charles in charge\n- Document filesystem as source of truth guidelines\n- Reflect 24-hour time format without seconds\n- Capture gorgeous commit message practices\n- Update collaboration model with databank/collab/ and databank/artifacts/\n- Create beautiful README-PROPOSAL-AGENTS-v2.md with comprehensive documentation\n- Align all content with current operational practices\n- Include decision hierarchy and when to stop and ask

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2025-10-24 10:09:50 -05:00
parent c82d1fefc7
commit 735547322e
2 changed files with 435 additions and 0 deletions
--- a/databank/collab/PROPOSAL-AGENTS-v2.md
+++ b/databank/collab/PROPOSAL-AGENTS-v2.md
@@ -0,0 +1,221 @@
+# Date/Time
+Friday October 24, 2025 09:43 CDT (UTC-05:00)
+
+# Change Tracking/Revision Table
+
+| Date/Time                        | Version | Description                                      | Author              |
+|----------------------------------|---------|--------------------------------------------------|---------------------|
+| 2025-10-24 09:43 CDT (UTC-05:00) | 2.0.0   | Update proposal to reflect current AGENTS.md state | Charles N Wyble (@ReachableCEO) |
+| 2025-10-24 09:43 CDT (UTC-05:00) | 1.0.0   | Initial proposal for baseline AGENTS.md          | Charles N Wyble (@ReachableCEO) |
+
+# Changelog
+
+| Date/Time                        | Version | Description                                      |
+|----------------------------------|---------|--------------------------------------------------|
+| 2025-10-24 09:43 CDT (UTC-05:00) | 2.0.0   | Updated proposal to reflect current AGENTS.md state |
+| 2025-10-24 09:43 CDT (UTC-05:00) | 1.0.0   | Initial creation of AGENTS.md proposal           |
+
+---
+
+# PROPOSAL-AGENTS.md - v2
+
+This file proposes an updated comprehensive baseline AGENTS.md file that reflects the current state after multiple iterations and optimizations. It serves as a guide that can be used across all projects via mounting in the AI home directory. It optimizes for LLM consumption and addresses the needs of a solo entrepreneur in a founder/CTO role covering operations tasks with 14+ hours daily AI usage.
+
+## Core Operating Principles for AI Agents
+
+### Context Awareness
+- You are operating within a mounted AI home directory with separated databank (readonly) and PMO (read-write)
+- **Databank** (`/ai-home/databank/`): Contains readonly context, guidelines, and personal information
+- **PMO** (`/ai-home/pmo/`): Contains project management functionality where updates are allowed
+- Always consider the multi-project implications of your actions
+- Respect the readonly nature of the databank and only update PMO when appropriate
+
+### Communication Protocol
+- Primary communication channel: collab/ directory in mounted AI home directory
+- Use question -> proposal -> implementation workflow
+- Document all significant decisions and changes with proper revision tracking
+
+### Documentation Standards (Apply to ALL files you create)
+- **Date/Time Headers**: Include full date/time with timezone in all markdown files (date, time, timezone format)
+- **Change Tracking**: Maintain revision tables in all documents with full date/time/timezone
+- **Changelog**: Include changelogs in all source code files with full date/time/timezone
+- **Make It Beautiful Rule**: All documentation follows beautiful formatting standards (tables, bullet points, clear structure, visual hierarchy)
+
+## Repository Management
+
+### Structure Requirements
+- **Databank**: Readonly context (do not modify except in designated areas)
+  - `databank/personal/` - Personal information
+  - `databank/agents/` - Agent guidelines and tools
+  - `databank/context/` - General context information
+  - `databank/operations/` - Operational environment information
+  - `databank/templates/` - Template files for projects
+  - `databank/collab/` - Human/AI interaction space (read/write for interaction)
+  - `databank/artifacts/` - AI-managed content (fully managed by AI)
+- **PMO**: Read-write project management (updates allowed here)
+  - `pmo/artifacts/dashboard/` - Dashboard views
+  - `pmo/artifacts/projects/` - Project registry and tracking
+  - `pmo/artifacts/reports/` - Status reports
+  - `pmo/artifacts/resources/` - Resource management
+  - `pmo/artifacts/config/` - Configuration
+  - `pmo/artifacts/docs/` - Documentation
+  - `pmo/collab/` - PMO-specific collaboration
+- Keep top-level repository clean (databank and pmo directories only)
+- Use conventional commits (chore:, feat:, docs:, fix:, etc.)
+- Commit frequently using atomic commits
+- Only commit to local repository (no git push operations)
+
+### Access Rights
+- **Databank (readonly)**: Access only for most content, with exceptions for `databank/collab/` and `databank/artifacts/`
+- **PMO (read-write)**: Only update when project milestones reached or status updates needed
+- **Collab (readonly)**: Access for reference, no modifications in active projects
+
+## Development Workflow
+
+### Pre-Work Checklist
+- [ ] Read project-specific documentation first
+- [ ] Check collab/rules directory for project-specific guidelines (SECURITY.md, RELEASE.md, GITFLOW.md, etc.)
+- [ ] Review databank context for consistent understanding
+- [ ] Understand project dependencies and constraints
+
+### Implementation Standards
+- Follow conventional commits with beautiful, descriptive messages
+- Maintain consistency with existing codebase
+- Add appropriate documentation and comments
+- Consider maintainability and future extensions
+
+### Verification Process
+- Validate operations before execution
+- Run appropriate tests and quality checks
+- Verify outputs against expected outcomes
+- Implement defensive programming practices
+
+## PMO Update Guidelines
+
+### When to Update PMO
+- When project milestones are reached
+- When project status changes significantly
+- When new projects are initiated
+- When projects are completed or paused
+- When resource allocation changes
+
+### What to Update in PMO
+- Project registry in `pmo/artifacts/projects/`
+- Dashboard information in `pmo/artifacts/dashboard/`
+- Status reports in `pmo/artifacts/reports/`
+- Resource tracking in `pmo/artifacts/resources/`
+- Configuration in `pmo/artifacts/config/`
+
+### What NOT to Update
+- **Never modify general databank files** - they are readonly
+- Do not create new top-level directories
+- Do not modify collab files in active projects without explicit permission
+- Do not add audit logs to this repository (audit logs belong in projects)
+
+## Authority and Decision Making Guidelines
+
+### Authority Structure
+- Charles N Wyble (@ReachableCEO) is in charge at all times
+- If something is adrift between docs and filesystem/code, stop and ask Charles to resolve the issue
+- Especially if discrepancy isn't reflected in git or conversation history, ask for clarification
+- When Charles modifies filesystem manually (vs having AI do it), Charles will ensure AI integrates the changes into mental model
+- Do not create or modify things that Charles hasn't explicitly instructed
+- The filesystem is the source of truth
+- If you notice discrepancies between documentation and actual filesystem, ask Charles to resolve
+
+### Decision Documentation
+- Document reasoning for complex decisions
+- Consider impact across multiple interconnected projects
+- Maintain traceability for future reference
+- Suggest alternatives when appropriate
+
+## Best Practices Integration
+
+### LLM Optimization Practices
+#### Prompt Engineering
+- Structure requests with clear context from mounted AI home directory
+- Use explicit, unambiguous language
+- Provide sufficient context without unnecessary verbosity
+- Break multi-step processes into clear, sequential instructions
+
+#### Code Generation
+- Follow established project patterns and conventions
+- Maintain consistency with existing code style
+- Add appropriate error handling and validation
+- Consider performance implications
+
+#### Quality Assurance
+- Implement appropriate testing strategies
+- Ensure code quality and maintainability
+- Perform validation against requirements
+- Include appropriate logging and monitoring
+
+### Security Practices
+- Verify file permissions and access controls
+- Sanitize all inputs and outputs appropriately
+- Protect sensitive information and credentials
+- Follow secure coding principles
+
+### Performance Considerations
+- Optimize for efficient processing
+- Consider resource usage and constraints
+- Implement appropriate caching strategies
+- Monitor and optimize for performance
+
+## Git and Version Control
+
+### Commit Standards
+- Use conventional commits with semantic meaning
+- Make commits atomic (one logical change per commit)
+- Write gorgeous, verbose commit messages when needed
+- Include comprehensive context and detailed descriptions
+- Follow the aesthetic principles of beautiful commits
+
+### Guidelines for Gorgeous Commit Messages
+- Be verbose and comprehensive when it adds value
+- Include context about why the change was made
+- Explain the impact of the changes when relevant
+- Use clear, descriptive language that future-you will understand
+- Follow the format: "type(scope): short description" for the first line
+- Add a blank line followed by detailed explanation when needed
+- Include any relevant references (issues, discussions, etc.)
+- Aim for beauty in both form and function
+- Think of commit messages as documentation for the changes
+
+### Branching and Merging
+- Follow project-specific branching strategies
+- Respect existing GitFlow patterns
+- Use feature branches for significant changes
+- Maintain clean commit history
+
+## Environment Management
+
+### Context Integration
+- Recognize that databank is mounted readonly across multiple environments
+- PMO is mounted read-write for project tracking
+- Maintain consistency in behavior across different projects
+- Respect environment-specific configurations
+
+### Collaboration and Artifacts
+- Use `databank/collab/` for human/AI interaction and communication
+- Use `databank/artifacts/` for AI-managed content (docs, code, config, templates)
+- AI has full management control over `databank/artifacts/` directory
+- Human interaction primarily occurs in `databank/collab/` directory
+- The AI manages the `databank/artifacts/` directory structure as needed
+- Common pattern: `databank/artifacts/docs/`, `databank/artifacts/code/`, `databank/artifacts/config/`, etc.
+- Maintain clean separation between human-managed and AI-managed resources
+- Follow consistent naming conventions across artifacts
+
+### Tool Integration
+- Work with existing development tools and workflows
+- Maintain compatibility with CI/CD pipelines
+- Use project-appropriate build and deployment processes
+- Respect project-specific dependencies and versions
+
+### AI Tool Context (for agents working in this environment)
+- **Codex** - Primary daily driver (subscription-based), best for code generation and completion
+- **Qwen** - Heavy system orchestration, excels at shell/Docker operations
+- **Gemini** - Primarily used for audits and analysis
+- **Claude** - Used occasionally for specific tasks
+
+---
--- a/databank/collab/README-PROPOSAL-AGENTS-v2.md
+++ b/databank/collab/README-PROPOSAL-AGENTS-v2.md
@@ -0,0 +1,214 @@
+# 🤖 README-PROPOSAL-AGENTS-v2.md
+> Beautiful documentation for updated AI Agent Guidelines Proposal
+
+---
+
+## 📋 Table of Contents
+- [Overview](#overview)
+- [Current State Alignment](#current-state-alignment)
+- [Key Features](#key-features)
+- [Implementation Guide](#implementation-guide)
+- [Best Practices](#best-practices)
+- [Authority Structure](#authority-structure)
+
+---
+
+## 🧠 Overview
+
+Welcome to the beautifully designed documentation for the **PROPOSAL-AGENTS-v2.md** file. This document represents an updated comprehensive baseline for AI agent operations that aligns with the current state of AGENTS.md after multiple iterations. It can be mounted across all your projects via your AI home directory.
+
+| **Attribute** | **Details** |
+|---------------|-------------|
+| **Purpose** | Updated baseline AI agent guidelines for all projects |
+| **Current State** | Aligns with v7.0.1 of AGENTS.md |
+| **Target User** | Solo entrepreneur (Founder/CTO/Operations) |
+| **AI Usage** | Optimized for 14+ hours daily interaction |
+| **Structure** | Mountable across multiple project environments |
+
+---
+
+## 🔄 Current State Alignment
+
+This v2 proposal reflects the current AGENTS.md state including:
+
+### Recent Updates
+- ✅ **Date/Time Format**: Full date, time, timezone without seconds (HH:MM format)
+- ✅ **Authority Structure**: Charles N Wyble (@ReachableCEO) is in charge at all times
+- ✅ **Filesystem Truth**: Filesystem is source of truth; check with Charles for discrepancies
+- ✅ **Databank/PMO Structure**: Clear separation with specific access rights
+- ✅ **Gorgeous Commits**: Verbose, detailed commit messages as standard
+- ✅ **Collaboration Model**: Clear distinction between `databank/collab/` and `databank/artifacts/`
+- ✅ **Versioning**: Minor increments for non-major changes (e.g., 7.0.0 to 7.0.1)
+
+### Key Changes from v1
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    EVOLUTION FROM V1 TO V2                  │
+├─────────────────────────────────────────────────────────────┤
+│  BEFORE (v1)                    │  AFTER (v2)               │
+│  - Basic collab/output model     │  - Advanced databank/PMO  │
+│  - Simple authority structure    │  - Clear authority rules  │
+│  - Basic date format             │  - 24-hour time format    │
+│  - No explicit truth rules       │  - Filesystem source truth│
+│  - Output directory reference    │  - Artifacts model        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ✨ Key Features
+
+### 🎯 Core Operating Principles
+| Principle | Current Implementation |
+|-----------|------------------------|
+| **Context Awareness** | Databank/PMO separation with specific access rights |
+| **Communication Protocol** | Questions -> proposals -> implementation workflow |
+| **Documentation Standards** | Beautiful formatting with date/time/timezone |
+
+### ⚙️ Operational Guidelines
+- **Repository Management**: Clean structure with conventional commits
+- **Documentation Standards**: Date/time headers, revision tracking, changelogs
+- **Workflow Adherence**: Follow question -> proposal -> implementation
+
+### 🧩 LLM Optimization Practices
+- **Prompt Engineering**: Clear, structured requests with context
+- **Code Generation**: Consistent with project patterns
+- **Quality Assurance**: Comprehensive validation and testing
+
+---
+
+## 📊 Implementation Guide
+
+### Step 1: Understanding the Current Framework
+1. **Databank Context** → Readonly access except for designated areas
+2. **PMO Updates** → Read-write access for project tracking when appropriate
+3. **Authority Model** → Charles in charge at all times
+
+### Step 2: Following Documentation Standards
+- [ ] Include full date/time header with timezone (HH:MM format, 24-hour)
+- [ ] Maintain change tracking/revision table with full date/time
+- [ ] Create changelog in source files with full date/time
+- [ ] Apply "make it beautiful" rule to all documentation
+
+### Step 3: Operational Excellence
+- [ ] Use atomic commits with conventional commit messages
+- [ ] Write gorgeous, verbose commit messages when needed
+- [ ] Commit frequently to local repository
+- [ ] Respect file access permissions (readonly vs read-write)
+
+---
+
+## 🏆 Best Practices
+
+### 🛡️ Security Practices
+- 🔐 Verify file permissions and access controls
+- 🛡️ Sanitize inputs and outputs appropriately  
+- 🔐 Protect sensitive information and credentials
+- 🔒 Follow secure coding principles
+
+### 📈 Quality Assurance
+- ✅ Implement appropriate testing strategies
+- ✅ Ensure code quality and maintainability
+- ✅ Perform regular documentation updates
+- ✅ Validate outputs against expected outcomes
+
+### ⚡ Performance Considerations
+- ⚡ Optimize for efficient processing
+- 💾 Minimize resource usage where possible
+- 📊 Consider impact on system performance
+- 🔄 Implement caching strategies when appropriate
+
+---
+
+## 👑 Authority Structure
+
+### Decision Hierarchy
+| Level | Authority | Responsibilities |
+|-------|-----------|------------------|
+| **Primary** | Charles N Wyble (@ReachableCEO) | Final decision maker on all matters |
+| **Implementation** | AI Agents | Execute within defined guidelines |
+| **Review** | Charles | Validate all major changes |
+
+### When to Stop and Ask
+- [ ] When docs and filesystem conflict
+- [ ] When discrepancy isn't in git history
+- [ ] When Charles manually modifies filesystem
+- [ ] When unsure about file access permissions
+
+---
+
+## 🚀 Solo Entrepreneur Optimization
+
+For someone using AI 14+ hours daily with multiple projects:
+
+| Need | Current Solution |
+|------|------------------|
+| **Time Efficiency** | Atomic operations with clear authority structure |
+| **Context Switching** | Consistent interfaces across projects |
+| **Decision Documentation** | Clear reasoning trails with proper attribution |
+| **Multi-Project Impact** | Considerations for interconnected projects |
+
+---
+
+## 🤝 Communication Workflow
+
+```
+┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
+│   Question  │ -> │   Proposal   │ -> │ Implementation  │
+│             │    │              │    │                 │
+│ What to do? │    │ How to do it?│    │ Execute & Test  │
+└─────────────┘    └──────────────┘    └─────────────────┘
+```
+
+### Primary Channels
+- **Collaboration**: Use `databank/collab/` directory for human/AI interaction
+- **Documentation**: Maintain comprehensive records with proper date/time
+- **Change Management**: Use version control with proper tracking
+
+---
+
+## 💼 Founder/CTO Specific Considerations
+
+### Decision Making Framework
+- 📊 Document reasoning for complex decisions with full context
+- 🔗 Consider impact across multiple projects with clear attribution
+- 📜 Maintain traceability for future reference with proper versioning
+- 🔄 Suggest alternatives when appropriate with complete information
+
+### Scalability Planning
+- 🏗️ Design solutions that work across multiple project contexts
+- 🧱 Use modular, reusable components with proper documentation
+- 📈 Plan for increasing complexity as projects grow
+- 🔗 Maintain consistent interfaces across projects
+
+---
+
+## 📈 Active Development Status
+
+> 🔄 **Note**: This proposal reflects the current living knowledge base that supports your 14+ hours daily AI usage.
+
+### Current Focus Areas
+- [x] Documentation standards
+- [x] Operational guidelines  
+- [x] LLM optimization
+- [x] Authority structure
+- [x] Versioning approach
+- [ ] Integration patterns (planned)
+- [ ] Performance metrics (planned)
+
+---
+
+## 📞 Getting Help
+
+For questions about implementing these guidelines:
+1. Create a new issue in the `databank/collab/` directory
+2. Reference this proposal document
+3. Provide specific context about your use case
+4. Follow the established question -> proposal -> implementation workflow
+5. Ask Charles if documentation conflicts with filesystem
+
+---
+
+*Last updated: October 24, 2025 09:43 CDT*  
+*Part of the AIOS (AI Operating System) ecosystem*  
+*Optimized for solo entrepreneur workflows*