diff --git a/AGENTS.md b/AGENTS.md index a212af4..07886c4 100644 --- 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 -> \ No newline at end of file +### 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 + +--- \ No newline at end of file diff --git a/collab/proposals/PROPOSAL-AGENTS.md b/collab/proposals/PROPOSAL-AGENTS.md new file mode 100644 index 0000000..50e3fe8 --- /dev/null +++ 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 + +--- \ No newline at end of file diff --git a/collab/proposals/README-PROPOSAL-AGENTS.md b/collab/proposals/README-PROPOSAL-AGENTS.md new file mode 100644 index 0000000..267d9b9 --- /dev/null +++ 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*