# [PROJECT_NAME] - [SERVICE_DESCRIPTION] **STATUS: [IN DEVELOPMENT / READY FOR TESTING / PRODUCTION]** - Last Updated: [YYYY-MM-DD] ## Repository Information - **GitHub Repository**: [GITHUB_URL] - **Local Directory**: `[LOCAL_PATH]` - **Primary Purpose**: [PRIMARY_PURPOSE_DESCRIPTION] ## Important Context [PROJECT_SPECIFIC_CONTEXT - Replace with relevant background, history, or critical information about this project/service] ## Core Development Principles (MANDATORY) ### 1. KISS (Keep It Simple, Stupid) - Avoid over-complication and over-engineering - Choose simple solutions over complex ones - Question every abstraction layer - If a feature seems complex, ask: "Is there a simpler way?" ### 2. TDD (Test-Driven Development) - Write tests first - Run tests to ensure they fail (Red phase) - Write minimal code to pass tests (Green phase) - Refactor while keeping tests green - Never commit code without tests ### 3. Separation of Concerns (SOC) - Each module/component has a single, well-defined responsibility - Clear boundaries between different parts of the system - Services should be loosely coupled - Avoid mixing business logic with UI or data access code ### 4. DRY (Don't Repeat Yourself) - Eliminate code duplication - Extract common functionality into reusable components - Use configuration files for repeated settings - Create shared libraries for common operations ### 5. Documentation Standards - Always include the actual date when writing documentation - Use objective, factual language only - Avoid marketing terms like "production-ready", "world-class", "highly sophisticated", "cutting-edge", etc. - State current development status clearly - Document what IS, not what WILL BE ### 5.5. AI-Optimized Documentation **CRITICAL**: Documentation is structured data for both humans AND AI consumption **Added**: v1.5.0 | **Enhanced**: v1.5.1 **Purpose**: Enable AI assistants to effectively help during: - **Development** (now) - Building the system - **Deployment** (later) - Setting up and configuring - **Operations** (ongoing) - Monitoring, troubleshooting - **User Support** (ongoing) - Helping users use the system **The 7 Principles**: 1. **Structured Data Over Prose** - Use tables, JSON, YAML instead of paragraphs 2. **Explicit Context** - Never assume prior knowledge 3. **Cause-Effect Relationships** - Clear "if X then Y" statements 4. **Machine-Readable Formats** - Consistent, parseable metadata (dates, versions, status) 5. **Searchable Content** - Keywords, anchors, consistent terminology 6. **Version-Stamped** - Date all documentation updates 7. **Cross-Referenced** - Explicit links between related docs **Example** (Good AI-optimized documentation): ```markdown ## Database Configuration **Required Environment Variables**: | Variable | Format | Example | Required | |----------|--------|---------|----------| | DATABASE_URL | postgresql://... | postgresql://postgres:secret@localhost:5432/db | Yes | **Validation**: \```bash npm run db:test-connection # Expected output: "✅ Connected successfully" \``` ``` **Documentation Layers**: - **Layer 1**: Development Phase (AGENTS.md, Architecture docs, Phase plans) - **Layer 2**: Deployment Phase (DEPLOYMENT-GUIDE.md, OPERATIONS.md, API-REFERENCE.md) - **Layer 3**: User Phase (USER-GUIDE.md, TROUBLESHOOTING.md, Configuration patterns) --- **New in v1.5.1**: Comprehensive documentation standards and templates **Complete Standards**: See [DOCUMENTATION-STANDARDS.md](https://github.com/ydun-code-library/Ydun_ai_workflow/blob/main/templates/docs/DOCUMENTATION-STANDARDS.md) for comprehensive guidelines, best practices, and anti-patterns. **Quick Start** (for projects with >5 documentation files): 1. **Add AI Navigation Headers** to core documentation: ```bash # Download the template curl -sO https://raw.githubusercontent.com/ydun-code-library/Ydun_ai_workflow/main/templates/docs/doc-components/AI-NAVIGATION-HEADER.template # Add to top of AGENTS.md, CLAUDE.md, major guides # Fill all [FILL: ...] placeholders ``` 2. **Create Master Navigation Map**: ```bash # If project has >5 documentation files curl -so DOCS-MAP.md https://raw.githubusercontent.com/ydun-code-library/Ydun_ai_workflow/main/templates/docs/doc-components/DOCS-MAP.md.template # List all documentation files with priorities ``` 3. **Document Architecture Decisions**: ```bash # Create ADR directory mkdir -p docs/decisions curl -so docs/decisions/001-decision-name.md https://raw.githubusercontent.com/ydun-code-library/Ydun_ai_workflow/main/templates/docs/doc-components/ADR-TEMPLATE.md ``` **Available Templates** (from [Ydun_ai_workflow](https://github.com/ydun-code-library/Ydun_ai_workflow/tree/main/templates/docs/doc-components)): - [AI-NAVIGATION-HEADER.template](https://github.com/ydun-code-library/Ydun_ai_workflow/blob/main/templates/docs/doc-components/AI-NAVIGATION-HEADER.template) - Help AI know when to read files - [DOCS-MAP.md.template](https://github.com/ydun-code-library/Ydun_ai_workflow/blob/main/templates/docs/doc-components/DOCS-MAP.md.template) - Master documentation index - [ADR-TEMPLATE.md](https://github.com/ydun-code-library/Ydun_ai_workflow/blob/main/templates/docs/doc-components/ADR-TEMPLATE.md) - Architecture Decision Records - [METADATA-BLOCK.template](https://github.com/ydun-code-library/Ydun_ai_workflow/blob/main/templates/docs/doc-components/METADATA-BLOCK.template) - Machine-readable metadata **When to Apply**: - ✅ Projects with >5 documentation files (use full standards) - ✅ Multi-service platforms (essential for navigation) - ✅ Long-lived projects >3 months (worth the investment) - ⚠️ Optional for simple scripts (lightweight approach fine) **Validation** (requires [Ydun_ai_workflow](https://github.com/ydun-code-library/Ydun_ai_workflow) clone): ```bash # Check documentation quality (optional Check #8) # Run from inside your Ydun_ai_workflow clone: path/to/Ydun_ai_workflow/templates/tools/audit-project.sh --full ``` All documentation follows these principles to maximize AI assistant effectiveness. ### 6. Jimmy's Workflow v2.1 (Red/Green Checkpoints) **MANDATORY for all implementation tasks** Use the four-phase checkpoint system to prevent AI hallucination and ensure robust implementation: ``` 🔴 PRE-FLIGHT → 🔴 IMPLEMENT → 🟢 VALIDATE → 🔵 CHECKPOINT ``` - 🔴 **PRE-FLIGHT**: Verify context - do I have all files, requirements, dependencies? - 🔴 **IMPLEMENT**: Write code, build features, make changes - 🟢 **VALIDATE**: Run explicit validation with documented reasoning and confidence level - 🔵 **CHECKPOINT**: Mark completion with confidence level and validity conditions **Critical Rules:** - NEVER skip PRE-FLIGHT - always verify context first - NEVER proceed to IMPLEMENT if PRE-FLIGHT status is 🔴 BLOCKED or 🟡 GAPS - NEVER proceed to next checkpoint without GREEN passing - ALWAYS document WHY validation proves correctness (reasoning) - ALWAYS acknowledge what validation does NOT prove (weaknesses) - ALWAYS document rollback procedures and validity conditions - ALWAYS disclose when AI validates AI-generated code (COI) **Confidence Levels:** - **HIGH**: Proceed automatically - **MEDIUM**: Human spot-check recommended - **LOW**: Human validation required **Reference**: See **JIMMYS-WORKFLOW.md** for complete workflow system (v2.1) **Usage**: When working with AI assistants, say: *"Let's use Jimmy's Workflow to execute this plan"* **Benefits:** - Prevents "AI says done ≠ Actually done" problem - PRE-FLIGHT catches missing context before wasted effort - Confidence levels enable appropriate human involvement - Reasoning documentation combats circular AI validation - COI disclosure acknowledges AI blind spots - Provides clear rollback paths with validity conditions ### 7. YAGNI (You Ain't Gonna Need It) - Don't implement features until they're actually needed - Resist the urge to "future-proof" or add "might be useful later" code - Build for current requirements, not hypothetical future ones - Question every feature: "Do we need this NOW?" - Refactor when requirements change, don't pre-optimize - Every line of code is a liability - only write what's necessary **Why This Matters:** - Prevents scope creep and over-engineering - Reduces technical debt (unused code is still debt) - Speeds up development (focus on actual requirements) - Forces clear prioritization of features **AI Assistant Reminder:** Don't add "helpful" features like caching, abstraction layers, or config systems unless explicitly required by current needs. ### 8. Fix Now, Not Later - Fix vulnerabilities immediately when discovered (npm audit, security warnings) - Fix warnings immediately (don't suppress or accumulate) - Fix failing tests immediately (understand root cause, don't skip) - Fix linter errors immediately (don't disable rules without reason) - Address build errors and deprecation warnings as they appear - Don't use suppressions (@ts-ignore, eslint-disable, etc.) without documented justification **Exception Clause:** - If you MUST defer or bypass an issue: 1. Investigate the root cause thoroughly 2. Weigh multiple solution options 3. Make an explicit decision 4. DOCUMENT why (in code comments, KNOWN_ISSUES.md, or technical debt tracker) 5. Create a tracking issue/ticket **Why This Matters:** - Prevents technical debt accumulation - Keeps codebase healthy and maintainable - Vulnerabilities don't ship to production - Warnings don't become noise - Tests remain meaningful **AI Assistant Reminder:** Never suggest "we'll fix this later" or "skip for now". Always investigate root cause and fix immediately. If deferring is necessary, document comprehensively. ### 9. Measure Twice, Cut Once - Always verify your understanding before executing - Double-check file paths, command syntax, and target locations - Review the plan before implementation begins - Confirm assumptions with explicit checks (read the file, run the test) - When in doubt, investigate first - don't guess **Why This Matters:** - Prevents "oops, wrong file" disasters - Catches misunderstandings before they become bugs - Saves time by avoiding rework - Builds confidence in changes **AI Assistant Reminder:** Before making changes, explicitly verify: Is this the right file? Is this the right approach? Did I understand the requirement correctly? Run verification commands, don't assume. ### 10. No Shortcuts (Do It Right) - Complete the job properly - no half-arsed work - Don't skip steps to save time - Implement the full solution, not a "good enough" hack - If something needs 5 steps, do all 5 steps - Quality over speed - cutting corners creates debt **Why This Matters:** - Half-finished work creates more work later - Shortcuts compound into technical debt - "Quick fixes" become permanent problems - Professional work means complete work **AI Assistant Reminder:** Never say "we can skip this for now" or "this should be good enough". Complete the task fully. If scope needs reducing, discuss with user first - don't silently cut corners. ### 11. Rules Persist (Context Compression Immunity) - **ALL rules remain in effect after auto-compact/context summarization** - Core principles are NEVER optional, regardless of context length - If you can't remember a rule, re-read AGENTS.md - Summarization does not equal permission to skip validation - Jimmy's Workflow gates apply to EVERY task, not just "important" ones **Why This Matters:** - Context compression can cause AI to "forget" constraints - Long sessions drift from initial guidelines - Rules exist for good reasons - they don't expire - Consistency requires explicit reinforcement **AI Assistant Reminder:** After context summarization, you may feel "freer" - this is an illusion. Re-read AGENTS.md if uncertain. All 11 principles apply with full force regardless of conversation length. NEVER skip Jimmy's Workflow checkpoints just because "we've been doing this for a while". ## GitHub Workflow ### Use GitHub CLI (gh) for All GitHub Operations **Standard Tool**: Use `gh` CLI for all GitHub interactions (issues, PRs, CI/CD monitoring, releases) **Installation**: `gh` should already be installed. Verify with `gh --version` **Common Operations:** **Pull Requests:** ```bash gh pr create --title "Feature" --body "Description" gh pr list # View open PRs gh pr checks # Check CI/CD status gh pr view [number] # View PR details gh pr merge [number] # Merge PR ``` **CI/CD Monitoring:** ```bash gh run list # List workflow runs gh run view [id] # View run details gh run watch # Watch current run (live updates) gh workflow list # List workflows ``` **Issues:** ```bash gh issue create --title "Bug" --body "Description" gh issue list # View open issues gh issue view [number] # View issue details gh issue close [number] # Close issue ``` **Releases:** ```bash gh release create v1.0.0 # Create release gh release list # List releases gh release view [tag] # View release details ``` **Why GitHub CLI:** - ✅ Scriptable and automation-friendly - ✅ Consistent across all projects - ✅ Works seamlessly with AI assistants - ✅ Faster than web UI for most operations - ✅ Built-in CI/CD monitoring - ✅ Integrates with Jimmy's Workflow checkpoints **AI Assistant Note**: Always use `gh` commands instead of suggesting "check the GitHub web UI" or manual git operations for GitHub-specific tasks. ## Service Overview [SERVICE_OVERVIEW - Provide a comprehensive description of what this service/project does, its role in the larger system (if applicable), and key responsibilities] **Key Responsibilities:** - [Responsibility 1] - [Responsibility 2] - [Responsibility 3] **Important Distinctions:** [If applicable, clarify any terminology or concepts that might be confusing - e.g., Users vs Clients, Services vs Applications, etc.] ## Current Status [STATUS_EMOJI] **[STATUS_DESCRIPTION]** - [COMPLETION_PERCENTAGE] [List current implementation status with checkmarks] - ✅ [Completed feature/component] - 🔄 [In progress feature/component] - ⚪ [Not started feature/component] - ⚠️ [Feature with issues/blockers] ## Technology Stack ### [Frontend/Backend/Full-Stack - Choose Relevant Section] **Frontend:** - **Framework**: [e.g., React 18, Vue 3, Angular] - **Build Tool**: [e.g., Vite, Webpack, Parcel] - **Styling**: [e.g., SASS, Tailwind, CSS Modules] - **State Management**: [e.g., Context API, Redux, Pinia] - **Testing**: [e.g., Vitest, Jest, React Testing Library] **Backend:** - **Runtime**: [e.g., Node.js, Python, Go] - **Framework**: [e.g., Express, FastAPI, Gin] - **Database**: [e.g., PostgreSQL, MongoDB, Redis] - **Authentication**: [e.g., JWT, OAuth, Supabase Auth] - **Testing**: [e.g., Jest, pytest, go test] **Infrastructure:** - **Hosting**: [e.g., Vercel, AWS, Supabase] - **CI/CD**: [e.g., GitHub Actions, GitLab CI] - **Monitoring**: [e.g., Sentry, DataDog] ## Build & Test Commands ### Development ```bash # Install dependencies [INSTALL_COMMAND - e.g., npm install, pip install -r requirements.txt] # Start development server [DEV_COMMAND - e.g., npm run dev, python manage.py runserver] # Run tests [TEST_COMMAND - e.g., npm test, pytest] # Type checking [TYPECHECK_COMMAND - e.g., npm run typecheck, mypy .] # Linting [LINT_COMMAND - e.g., npm run lint, flake8 .] ``` ### Production ```bash # Build for production [BUILD_COMMAND - e.g., npm run build, docker build .] # Run production build locally [PREVIEW_COMMAND - e.g., npm run preview] # Deploy [DEPLOY_COMMAND - e.g., vercel deploy, git push heroku main] ``` ## Repository Structure ``` [PROJECT_ROOT]/ ├── src/ # Source code │ ├── components/ # [Framework] components │ ├── services/ # Business logic │ ├── utils/ # Utility functions │ ├── types/ # TypeScript types │ └── tests/ # Test files ├── public/ # Static assets ├── config/ # Configuration files ├── [OTHER_DIRECTORIES] # [Description] ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── AGENTS.md # AI assistant guidelines (this file) └── README.md # User-facing documentation ``` ## Development Workflow ### Starting Work on a Task 1. Read this AGENTS.md file for context 2. Check current implementation status above 3. Review known issues and TODOs below 4. **Use Jimmy's Workflow**: Plan → Implement → Validate → Checkpoint 5. Follow TDD approach - write tests first 6. Implement minimal code to pass tests 7. Refactor while maintaining green tests ### Before Committing Code 1. Run all tests: `[TEST_COMMAND]` 2. Check types: `[TYPECHECK_COMMAND]` 3. Run linter: `[LINT_COMMAND]` 4. Update documentation if needed 5. Ensure no credentials are exposed 6. Verify tests are passing 7. Use Jimmy's Workflow checkpoints to validate completeness ### Documentation Updates 1. Update README.md with any API changes 2. Add inline comments for complex logic 3. Update this AGENTS.md if development approach changes 4. Document all decisions with dates 5. Keep development diary current (if applicable) ## Known Issues & Technical Debt ### 🔴 Critical Issues [List critical issues that block progress or pose security risks] 1. [Issue description with link to ticket/issue if applicable] ### 🟡 Important Issues [List important but non-blocking issues] 1. [Issue description] ### 📝 Technical Debt [List areas that need refactoring or improvement] 1. [Technical debt item with estimated effort] ## Project-Specific Guidelines [Add any project-specific coding standards, conventions, or guidelines here] ### Code Style - [Naming conventions specific to this project] - [File organization preferences] - [Import ordering rules] - [Component/function size limits] ### Testing Requirements - [Coverage requirements] - [Required test types] - [Test data management] ### Security Considerations - [Project-specific security requirements] - [Sensitive data handling] - [Authentication/authorization patterns] ## Common Patterns & Examples ### [Pattern Name 1] [Description of common pattern used in this project] ```[language] // Example code ``` ### [Pattern Name 2] [Description of another common pattern] ```[language] // Example code ``` ## Dependencies & Integration ### External Services - **[Service Name 1]**: [Purpose and integration details] - **[Service Name 2]**: [Purpose and integration details] ### Related Services (if part of multi-service platform) - **[Related Service 1]**: [Relationship and dependencies] - **[Related Service 2]**: [Relationship and dependencies] ## Environment Variables ```bash # Required [REQUIRED_VAR_1]=[description] [REQUIRED_VAR_2]=[description] # Optional [OPTIONAL_VAR_1]=[description] # Default: [default_value] [OPTIONAL_VAR_2]=[description] # Default: [default_value] ``` ## Troubleshooting ### Common Issues **Issue**: [Common problem description] **Solution**: [How to fix it] **Issue**: [Another common problem] **Solution**: [How to fix it] ## Resources & References ### Documentation - [Link to main documentation] - [Link to API documentation] - [Link to architecture diagrams] ### External Resources - [Relevant external documentation] - [Tutorial or guide links] - [Community resources] ## Template Version Management **Current Template Version**: See `` comment at top of this file **This project uses versioned templates** from the [Ydun AI Workflow](https://github.com/ydun-code-library/Ydun_ai_workflow) repository. > **Note:** The tool scripts below live in the templates repo, not in your project. Clone it once and keep it alongside your projects: > ```bash > git clone https://github.com/ydun-code-library/Ydun_ai_workflow.git > ``` ### Check if Templates are Up to Date ```bash # Run from your Ydun_ai_workflow clone: Ydun_ai_workflow/templates/tools/check-version.sh ``` **What it does:** - Compares your AGENTS.md version with master template version - Exit code 0 = up to date ✅ - Exit code 1 = out of date ⚠️ ### View Template Changelog ```bash # In the Ydun_ai_workflow clone: cat Ydun_ai_workflow/CHANGELOG.md ``` See what's new in each version and migration instructions. ### Sync to Latest Version (Manual for now) ```bash # Run from your Ydun_ai_workflow clone: Ydun_ai_workflow/templates/tools/sync-templates.sh --dry-run # Preview changes Ydun_ai_workflow/templates/tools/sync-templates.sh # Apply changes (with confirmation) Ydun_ai_workflow/templates/tools/sync-templates.sh --auto # Auto-apply without confirmation ``` **What gets preserved during sync:** - ✅ All `` sections (your customizations) - ✅ All placeholder values (PROJECT_NAME, commands, etc.) - ✅ Custom additions to Known Issues, Technical Debt, etc. - ✅ Project-specific guidelines and patterns **What gets updated during sync:** - 🔄 Core Development Principles (if new ones added) - 🔄 Template structure improvements - 🔄 Standard sections and formatting - 🔄 Tool integrations (GitHub CLI, etc.) **Important Notes:** - Always review the diff before applying - Backups are created automatically in `.template-sync-backup/` - If sync fails, restore from backup - Commit template updates separately from feature work ### Template Compliance Checking **AI Assistant Behavior**: When user asks "check templates" or "are we up to date?", automatically: 1. Run the audit script from the Ydun_ai_workflow clone OR manually execute checks 2. Generate compliance report 3. Offer remediation based on findings **User can also run manually** (from the Ydun_ai_workflow clone): ```bash Ydun_ai_workflow/templates/tools/audit-project.sh # Full audit Ydun_ai_workflow/templates/tools/audit-project.sh --quick # Quick check ``` **Quick Manual Check:** ```bash # Are we up to date? Ydun_ai_workflow/templates/tools/check-version.sh # What's new? cat Ydun_ai_workflow/CHANGELOG.md ``` ## Important Reminders for AI Assistants 1. **Always use Jimmy's Workflow** for implementation tasks 2. **Follow TDD** - Write tests before implementation 3. **Keep it KISS** - Simplicity over complexity 4. **Apply YAGNI** - Only implement what's needed now, not future "might need" features 5. **Use GitHub CLI** - Use `gh` for all GitHub operations (PRs, issues, CI/CD monitoring) 6. **Fix Now** - Never defer fixes for vulnerabilities, warnings, or test failures. No suppressions without documented justification 7. **Document dates** - Include actual dates in all documentation 8. **Validate explicitly** - Run commands, don't assume 9. **Never skip checkpoints** - Each phase must complete before proceeding 10. **Update this file** - Keep AGENTS.md current as project evolves 11. **Measure Twice, Cut Once** - Verify before executing. Double-check paths, commands, and assumptions 12. **No Shortcuts** - Complete the job properly. No half-arsed work or "good enough" hacks 13. **Rules Persist** - ALL principles remain in effect after auto-compact. Re-read AGENTS.md if uncertain --- **This document follows the [agents.md](https://agents.md/) standard for AI coding assistants.** **Template Version**: 1.7.0 **Last Updated**: [YYYY-MM-DD]