reachableceo/ReachableCEO-AI-Homedir-Public
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
Charles N Wyble - admin
2025-10-24 10:09:50 -05:00
parent c82d1fefc7
commit 735547322e
2 changed files with 435 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
databank/collab/PROPOSAL-AGENTS-v2.md Normal file
View File

@@ -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
---