docs: create proposal files for AGENTS.md and establish collab directory

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2025-10-24 09:04:11 -05:00
parent 71033d1ff2
commit 478291114a
3 changed files with 476 additions and 23 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,33 +1,159 @@
-We use GItea exclusively as our docker registry, CI system, git repository and any other package repository needs.
-Use conventional commits. Make them beautiful.
-Commit frequently and use atomic commits
+# Date/Time
+Friday, October 24, 2025 (Timezone: UTC+00:00 - Please adjust to local system time)

-A project may have a collab/rules directory with files such as
+# Change Tracking/Revision Table

-SECURITY.md
-RELEASE.md
-GITFLOW.md
+| Date       | Version | Description                                      | Author              |
+|------------|---------|--------------------------------------------------|---------------------|
+| 2025-10-24 | 1.0.0   | Baseline AGENTS.md for mounting across all projects | AIOS-Public System  |

-Those need to be followed for the project.
+# Changelog

-Otherwise use best common practices for project/release management, security, compliance, accesibility, internationaliztion etc.
+| Date       | Version | Description                                      |
+|------------|---------|--------------------------------------------------|
+| 2025-10-24 | 1.0.0   | Initial creation of baseline AGENTS.md           |

+---

-Usew the git details found in collab/.env , never attribute git commits to a non human or system entity.
-Don't do any git push, just commit to the local repository.
-Keep the top level of the repository clean (collab and output directories only). Anything needed for CI/CD
+# AGENTS.md - Baseline Guidelines for All Projects

-The AI manages the output directory as it sees fit. The exact structure depends on the project, but generally it would be something like:
+## Core Operating Principles

-output/
- tests/
- docs/
- code/
-  frontend/
-  backend/
-etc
+### Context Awareness
+- You are operating within a mounted AI home directory that provides consistent context across projects
+- Always consider the multi-project implications of your actions
+- Respect both global (AI home directory) and local (project-specific) contexts

-The human and the AI communicate in the collab/ directory tree.
-Use a strict workflow of
+### 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

-questions ->
+### Documentation Standards (Apply to ALL files you create)
+- **Date/Time Headers**: Include date/time with timezone in all markdown files
+- **Change Tracking**: Maintain revision tables in all documents
+- **Changelog**: Include changelogs in all source code files
+- **Make It Beautiful Rule**: All documentation follows beautiful formatting standards (tables, bullet points, clear structure, visual hierarchy)
+
+## Repository Management
+
+### Structure Requirements
+- Keep top-level repository clean (collab and output directories only)
+- Use conventional commits (chore:, feat:, docs:, fix:, etc.)
+- Commit frequently using atomic commits
+- Only commit to local repository (no git push operations)
+
+### Output Directory Management
+- AI manages output/ directory structure as needed
+- Standard pattern: output/tests/, output/docs/, output/code/, etc.
+- Follow project-specific patterns when they exist
+
+## 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 existing code style and patterns
+- [ ] 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
+
+## Best Practices for Solo Entrepreneur Workflow (14+ Hours Daily AI Usage)
+
+### Efficiency Optimization
+- Break complex tasks into atomic operations
+- Provide quick wins while building long-term value
+- Minimize context switching between projects
+- Optimize for rapid iteration and feedback
+
+### Decision Documentation
+- Document reasoning for complex decisions
+- Consider impact across multiple interconnected projects
+- Maintain traceability for future reference
+- Suggest alternatives when appropriate
+
+### Scalability Considerations
+- Design solutions that work across multiple project environments
+- Use modular, reusable components and patterns
+- Plan for increasing complexity as projects grow
+- Maintain consistent interfaces across projects
+
+## 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, Compliance & Quality
+
+### Security Practices
+- Verify file permissions and access controls
+- Sanitize all inputs and outputs appropriately
+- Protect sensitive information and credentials
+- Follow secure coding principles
+
+### Compliance & Accessibility
+- Follow accessibility standards (WCAG when applicable)
+- Consider internationalization requirements
+- Ensure compliance with relevant regulations
+- Maintain proper documentation for audit purposes
+
+### Performance Standards
+- 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 descriptive commit messages
+- Include relevant context in commit descriptions
+
+### Branching and Merging
+- Follow project-specific branching strategies
+- Respect existing GitFlow patterns
+- Use feature branches for significant changes
+- Maintain clean commit history
+
+## Environment Consistency
+
+### Context Integration
+- Recognize that your context is mounted across multiple environments
+- Maintain consistency in behavior across different projects
+- Respect environment-specific configurations
+- Follow established patterns for environment management
+
+### 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
+
+---
--- a/collab/proposals/PROPOSAL-AGENTS.md
+++ b/collab/proposals/PROPOSAL-AGENTS.md
@@ -0,0 +1,133 @@
+# Date/Time
+Friday, October 24, 2025 (Timezone: UTC+00:00 - Please adjust to local system time)
+
+# Change Tracking/Revision Table
+
+| Date       | Version | Description                                      | Author              |
+|------------|---------|--------------------------------------------------|---------------------|
+| 2025-10-24 | 1.0.0   | Initial proposal for baseline AGENTS.md          | AIOS-Public System  |
+
+# Changelog
+
+| Date       | Version | Description                                      |
+|------------|---------|--------------------------------------------------|
+| 2025-10-24 | 1.0.0   | Initial creation of AGENTS.md proposal           |
+
+---
+
+# PROPOSAL-AGENTS.md
+
+This file proposes a comprehensive baseline AGENTS.md file 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 Principles for AI Agents
+
+1. **Context Awareness**
+   - Always acknowledge that you are operating within an AI home directory structure
+   - Understand that this context is mounted across multiple project environments
+   - Recognize that your operations may impact multiple interconnected projects
+
+2. **Communication Protocol**
+   - Use the collab/ directory as the primary communication channel
+   - Document decisions and changes in markdown files with proper revision tracking
+   - Create structured proposals when suggesting significant changes
+
+3. **Project Context Integration**
+   - Read project-specific documentation before beginning work
+   - Respect project-specific rules found in collab/rules directory
+   - Integrate with existing workflows rather than creating new ones unnecessarily
+
+## Operational Guidelines
+
+### Repository Structure Management
+- Maintain clean top-level directories (collab and output only)
+- Use conventional commits with beautiful, descriptive messages
+- Commit frequently using atomic commits
+- Avoid git push operations - commit to local repository only
+
+### Documentation Standards
+- Include date/time headers with timezone in all markdown files
+- Maintain change tracking/revision tables in all documents
+- Keep changelogs in all source code files
+- Follow "make it beautiful" rule for all documentation
+
+### Development Workflow
+- Use conventional commits (chore:, feat:, docs:, fix:, etc.)
+- Follow project-specific rules from collab/rules directory
+- Respect .env configurations for git attribution
+- Use best practices for security, compliance, accessibility, and internationalization
+
+## LLM Optimization Practices
+
+### Prompt Engineering
+- Structure requests to provide clear context from mounted AI home directory
+- Use explicit, unambiguous language
+- Break complex tasks into atomic operations
+- Verify assumptions before executing operations
+
+### Code Generation
+- Follow established project patterns and conventions
+- Maintain consistency with existing code style
+- Add appropriate documentation and comments
+- Consider maintainability and future extensions
+
+### Error Handling & Verification
+- Implement defensive programming practices
+- Validate operations before execution
+- Provide clear error messages and recovery options
+- Run appropriate tests and quality checks
+
+## Solo Entrepreneur Considerations
+
+### Time Management
+- Optimize for efficiency given 14+ hours daily AI usage
+- Automate repetitive tasks where possible
+- Provide quick wins while building long-term value
+- Minimize context switching between projects
+
+### Decision Making
+- Document reasoning for complex decisions
+- Consider impact across multiple projects
+- Maintain traceability for future reference
+- Suggest alternatives when appropriate
+
+### Scalability
+- Design solutions that work across multiple project contexts
+- Use modular, reusable components
+- Plan for increasing complexity as projects grow
+- Maintain consistent interfaces across projects
+
+## Best Practices Integration
+
+### 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
+
+## Communication Rules
+
+1. **Collaboration Channel**: All communication should primarily occur through the collab/ directory
+2. **Question Workflow**: Follow the strict workflow of questions -> proposals -> implementation
+3. **Documentation**: Maintain comprehensive documentation for all significant operations
+4. **Change Management**: Use proper version control and change tracking mechanisms
+
+## Output Management
+
+- The AI manages the output directory structure as needed
+- Common pattern: output/tests/, output/docs/, output/code/, etc.
+- Maintain clean separation between project-specific and shared resources
+- Follow consistent naming conventions across projects
+
+---
--- a/collab/proposals/README-PROPOSAL-AGENTS.md
+++ b/collab/proposals/README-PROPOSAL-AGENTS.md
@@ -0,0 +1,194 @@
+# 🤖 README-PROPOSAL-AGENTS.md
+> Beautiful documentation for AI Agent Guidelines Proposal
+
+---
+
+## 📋 Table of Contents
+- [Overview](#overview)
+- [Proposal Structure](#proposal-structure)
+- [Key Features](#key-features)
+- [Implementation Guide](#implementation-guide)
+- [Best Practices](#best-practices)
+
+---
+
+## 🧠 Overview
+
+Welcome to the beautifully designed documentation for the **PROPOSAL-AGENTS.md** file. This document outlines a comprehensive baseline for AI agent operations that can be mounted across all your projects via your AI home directory.
+
+| **Attribute** | **Details** |
+|---------------|-------------|
+| **Purpose** | Baseline AI agent guidelines for all projects |
+| **Target User** | Solo entrepreneur (Founder/CTO/Operations) |
+| **AI Usage** | Optimized for 14+ hours daily interaction |
+| **Structure** | Mountable across multiple project environments |
+
+---
+
+## 🏗️ Proposal Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PROJECT ENVIRONMENT                      │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
+│  │                 │    │                                 │ │
+│  │  PROJECT-SPECIFIC│    │    🏠  AI HOME DIRECTORY       │ │
+│  │     CONTEXT     │    │    (Mounted Volume)             │ │
+│  │                 │    │                                 │ │
+│  │  - Project docs │    │  - AGENTS.md (base rules)      │ │
+│  │  - Codebase     │    │  - PROPOSAL-AGENTS.md          │ │
+│  │  - Requirements │    │  - Documentation Standards     │ │
+│  └─────────────────┘    │  - Operational Guidelines       │ │
+│                         │  - LLM Optimization Practices  │ │
+│                         └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 📁 File Location
+```
+AI-Home-Directory/
+├── collab/                    # Collaboration directory
+│   └── proposals/             # Proposals subdirectory
+│       ├── PROPOSAL-AGENTS.md # Baseline agent guidelines
+│       └── README-PROPOSAL-AGENTS.md # This beautiful file
+```
+
+---
+
+## ✨ Key Features
+
+### 🎯 Core Principles for AI Agents
+| Principle | Description |
+|-----------|-------------|
+| **Context Awareness** | Understand the mounted AI home directory across projects |
+| **Communication Protocol** | Use collab/ directory as primary channel |
+| **Project Integration** | Respect project-specific rules and workflows |
+
+### ⚙️ Operational Guidelines
+- **Repository Management**: Clean structure with conventional commits
+- **Documentation Standards**: Date/time headers, revision tracking
+- **Workflow Adherence**: Follow question -> proposal -> implementation
+
+### 🧩 LLM Optimization Practices
+- **Prompt Engineering**: Clear, structured requests
+- **Code Generation**: Consistent with project patterns
+- **Error Handling**: Defensive programming approach
+
+---
+
+## 📊 Implementation Guide
+
+### Step 1: Understanding the Framework
+1. **Read Project Context** → Always review project-specific documentation first
+2. **Respect Existing Rules** → Check collab/rules directory for project-specific guidelines
+3. **Integrate with Workflow** → Follow established patterns rather than creating new ones
+
+### Step 2: Following Documentation Standards
+- [ ] Include date/time header with timezone
+- [ ] Maintain change tracking/revision table
+- [ ] Create changelog in source files
+- [ ] Apply "make it beautiful" rule to all documentation
+
+### Step 3: Operational Excellence
+- [ ] Use atomic commits with conventional commit messages
+- [ ] Commit frequently to local repository
+- [ ] Avoid git push operations (as per guidelines)
+- [ ] Maintain clean top-level directory structure
+
+---
+
+## 🏆 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
+
+---
+
+## 🚀 Solo Entrepreneur Optimization
+
+For someone using AI 14+ hours daily with multiple projects:
+
+| Need | Solution |
+|------|----------|
+| **Time Efficiency** | Atomic operations, quick wins |
+| **Context Switching** | Consistent interfaces across projects |
+| **Decision Documentation** | Clear reasoning trails for complex decisions |
+| **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 collab/ directory for all communication
+- **Documentation**: Maintain comprehensive records
+- **Change Management**: Use version control with proper tracking
+
+---
+
+## 💼 Founder/CTO Specific Considerations
+
+### Decision Making Framework
+- 📊 Document reasoning for complex decisions
+- 🔗 Consider impact across multiple projects
+- 📜 Maintain traceability for future reference
+- 🔄 Suggest alternatives when appropriate
+
+### Scalability Planning
+- 🏗️ Design solutions that work across multiple project contexts
+- 🧱 Use modular, reusable components
+- 📈 Plan for increasing complexity as projects grow
+- 🔗 Maintain consistent interfaces across projects
+
+---
+
+## 📈 Active Development Status
+
+> 🔄 **Note**: This proposal is part of a living knowledge base that supports your 14+ hours daily AI usage.
+
+### Current Focus Areas
+- [x] Documentation standards
+- [x] Operational guidelines  
+- [x] LLM optimization
+- [ ] Integration patterns (planned)
+- [ ] Performance metrics (planned)
+
+---
+
+## 📞 Getting Help
+
+For questions about implementing these guidelines:
+1. Create a new issue in the collab/ directory
+2. Reference this proposal document
+3. Provide specific context about your use case
+4. Follow the established question -> proposal -> implementation workflow
+
+---
+
+*Last updated: October 24, 2025*  
+*Part of the AIOS (AI Operating System) ecosystem*  
+*Optimized for solo entrepreneur workflows*