{"id":44190141,"url":"https://github.com/oliguo/vibe-coding-instructions","last_synced_at":"2026-02-09T17:01:18.400Z","repository":{"id":304299960,"uuid":"1018360074","full_name":"oliguo/vibe-coding-instructions","owner":"oliguo","description":"Vibe Coding Instructions - AI-Optimized TDD Framework","archived":false,"fork":false,"pushed_at":"2025-07-16T03:35:05.000Z","size":72,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-24T11:31:01.166Z","etag":null,"topics":["vibe-coding"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oliguo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-12T05:17:45.000Z","updated_at":"2025-07-16T03:35:09.000Z","dependencies_parsed_at":"2025-07-12T08:32:28.180Z","dependency_job_id":"b4a2a34b-afd5-49f0-bf7c-0831b45a46ff","html_url":"https://github.com/oliguo/vibe-coding-instructions","commit_stats":null,"previous_names":["oliguo/vibe-coding-instructions"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oliguo/vibe-coding-instructions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliguo%2Fvibe-coding-instructions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliguo%2Fvibe-coding-instructions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliguo%2Fvibe-coding-instructions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliguo%2Fvibe-coding-instructions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oliguo","download_url":"https://codeload.github.com/oliguo/vibe-coding-instructions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliguo%2Fvibe-coding-instructions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29273139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T13:47:44.167Z","status":"ssl_error","status_checked_at":"2026-02-09T13:47:43.721Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["vibe-coding"],"created_at":"2026-02-09T17:00:49.563Z","updated_at":"2026-02-09T17:01:18.358Z","avatar_url":"https://github.com/oliguo.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vibe Coding Instructions - AI-Optimized TDD Framework\n\n**Version**: 2.0  \n**Framework**: Kent Beck TDD + AI-Optimized Development  \n**Compatible**: Cursor, Windsurf, VS Code + AI Extensions\n\n## Credits \u0026 Methodology\n\nThis framework integrates **Kent Beck's Test-Driven Development (TDD)** and **Tidy First** methodologies with AI-optimized development practices.\n\n**TDD Methodology Credit**: [Kent Beck](https://github.com/KentBeck/BPlusTree3/blob/main/rust/docs/CLAUDE.md) - Original TDD principles and Red-Green-Refactor cycle\n\n**Core Principles Applied**:\n\n```mermaid\ngraph LR\n    A[TDD Cycle] --\u003e B[Red: Failing Test]\n    B --\u003e C[Green: Minimal Code]\n    C --\u003e D[Refactor: Tidy First]\n    D --\u003e B\n    \n    E[AI Optimization] --\u003e F[≤25 LOC Functions]\n    E --\u003e G[≤3 Parameters]\n    E --\u003e H[Single Responsibility]\n    \n    I[Quality Gates] --\u003e J[All Tests Pass]\n    I --\u003e K[No Compiler Warnings]\n    I --\u003e L[AI Readability]\n    \n    style A fill:#ffcdd2\n    style E fill:#c8e6c9\n    style I fill:#bbdefb\n```\n\n- Always follow the TDD cycle: Red → Green → Refactor\n- Write the simplest failing test first\n- Implement minimum code needed to make tests pass\n- Separate structural changes from behavioral changes (Tidy First)\n- Maintain high code quality throughout development\n\n## Project Structure Overview\n\n```mermaid\ngraph TD\n    A[Vibe Coding Instructions Framework] --\u003e B[Source Code]\n    A --\u003e C[Requirements]\n    A --\u003e D[Documentation]\n    A --\u003e E[AI Optimization: ai-ide-instructions.md]\n    \n    B --\u003e B1[≤300 LOC per file]\n    B --\u003e B2[≤25 LOC per function]\n    B --\u003e B3[≤3 parameters per function]\n    \n    C --\u003e C1[PRD.md]\n    C --\u003e C2[Technical Specs]\n    C --\u003e C3[Product Requirements]\n    \n    D --\u003e D1[knowledge.md - Central Knowledge Base]\n    D --\u003e D2[plan.md - TDD Test Roadmap]\n    D --\u003e D3[todo.md - Master Task Tracking]\n    D --\u003e D4[step_plan.md - Implementation Plans]\n    D --\u003e D5[Role Guidelines]\n    D --\u003e D6[Individual Tasks: todos/]\n    D --\u003e D7[Detailed Plans: step_plans/]\n    \n    D5 --\u003e D5A[programmer-guidelines.md]\n    D5 --\u003e D5B[designer-guidelines.md]\n    D5 --\u003e D5C[tester-guidelines.md]\n    \n    E --\u003e E1[F-LEN: ≤25 LOC]\n    E --\u003e E2[F-PARAM: ≤3 params]\n    E --\u003e E3[F-RESP: Single responsibility]\n    E --\u003e E4[M-SIZE: ≤300 LOC files]\n    \n    style A fill:#e1f5fe\n    style B fill:#f3e5f5\n    style C fill:#e8f5e8\n    style D fill:#fff3e0\n    style E fill:#fce4ec\n```\n\n### Directory Structure\n```\n├── @/app/                   # Source code (≤300 LOC per file, ≤25 LOC per function)\n├── @/ideas/                 # Requirements and project concepts\n├── @/doc/                   # Documentation and guidelines\n│   ├── knowledge.md         # Central knowledge base (use MCP Context7)\n│   ├── plan.md             # TDD test roadmap (20 tests ready)\n│   ├── todo.md             # Master task tracking\n│   ├── step_plan.md        # Master step plan index\n│   ├── programmer-guidelines.md    # TDD + AI development workflow\n│   ├── designer-guidelines.md      # AI-optimized design patterns\n│   ├── tester-guidelines.md        # Quality assurance strategy\n│   ├── todos/              # Individual task files (YYYYMMDD_HHMMSS format)\n│   └── step_plans/         # Detailed implementation plans\n└── ai-ide-instructions.md  # Core AI optimization principles\n```\n\n---\n\n## 🚀 New Requirements \u0026 AI Startup Workflow\n\n```mermaid\nflowchart TD\n    A[Add PRD.md to ideas folder] --\u003e B[Phase 1: Requirements Analysis]\n    B --\u003e C[Phase 2: Security \u0026 Structure Setup]\n    C --\u003e D[Phase 3: Development Cycle Kickoff]\n    D --\u003e E[Phase 4: Task Management]\n    \n    B --\u003e B1[Step 1: Analyze Requirements\u003cbr/\u003eAI Prompt: Extract tech requirements]\n    B --\u003e B2[Step 2: Update Knowledge Base\u003cbr/\u003eUse Context7 + consolidate insights]\n    \n    C --\u003e C1[Step 3: Security Validation\u003cbr/\u003eValidate .gitignore, .dockerignore]\n    C --\u003e C2[Step 4: Map to TDD Tests\u003cbr/\u003eLink requirements to plan.md]\n    \n    D --\u003e D1[Step 5: Start TDD Cycle\u003cbr/\u003ego command + Red phase]\n    D --\u003e D2[Step 6: Green Implementation\u003cbr/\u003e≤25 LOC, ≤3 params]\n    D --\u003e D3[Step 7: Refactor\u003cbr/\u003eTidy First principles]\n    \n    E --\u003e E1[Step 8: Create Task Files\u003cbr/\u003eYYYYMMDD_HHMMSS format]\n    E --\u003e E2[Step 9: Generate Step Plans\u003cbr/\u003eAtomic implementation steps]\n    \n    E --\u003e F[Continue TDD Cycles]\n    F --\u003e D1\n    \n    style A fill:#e8f5e8\n    style B fill:#e3f2fd\n    style C fill:#fff3e0\n    style D fill:#f3e5f5\n    style E fill:#fce4ec\n    style F fill:#e0f2f1\n```\n\n## 🔄 Complete Document Integration Workflow\n\n```mermaid\ngraph TD\n    subgraph \"Input Documents\"\n        A[PRD.md in ideas folder]\n        B[PR.md - Pull Request]\n        C[Technical Specs]\n    end\n    \n    subgraph \"Document Processing Pipeline\"\n        D[Step 1: Document Analysis]\n        E[Step 2: Knowledge Integration]\n        F[Step 3: Task Generation]\n        G[Step 4: Implementation Planning]\n    end\n    \n    subgraph \"Framework Documents\"\n        H[ai-ide-instructions.md]\n        I[knowledge.md]\n        J[plan.md - 20 TDD Tests]\n        K[todo.md - Task Tracking]\n        L[step_plan.md - Plans Index]\n    end\n    \n    subgraph \"Role Guidelines\"\n        M[programmer-guidelines.md]\n        N[designer-guidelines.md]\n        O[tester-guidelines.md]\n    end\n    \n    subgraph \"Implementation Outputs\"\n        P[Individual TODO Files]\n        Q[Step Plan Files]\n        R[Source Code in app/]\n        S[Test Implementation]\n    end\n    \n    A --\u003e D\n    B --\u003e D\n    C --\u003e D\n    \n    D --\u003e E\n    E --\u003e F\n    F --\u003e G\n    \n    H --\u003e E\n    I --\u003e E\n    J --\u003e F\n    K --\u003e F\n    L --\u003e G\n    \n    M --\u003e G\n    N --\u003e G\n    O --\u003e G\n    \n    G --\u003e P\n    G --\u003e Q\n    P --\u003e R\n    Q --\u003e S\n    \n    style A fill:#e8f5e8\n    style B fill:#ffe0b2\n    style H fill:#fce4ec\n    style I fill:#fff3e0\n    style R fill:#f3e5f5\n```\n\n### **Complete Integration Workflow: From Requirements to Code**\n\nWhen you add requirements documents (PRD.md, PR.md, technical specs, etc.) to the [`@/ideas/`](ideas) folder, follow this systematic integration workflow that connects all framework documents:\n\n### **Phase 1: Document Analysis \u0026 Requirements Processing**\n\n```mermaid\nsequenceDiagram\n    participant User as User\n    participant AI as AI Assistant\n    participant Ideas as ideas/ folder\n    participant AiInst as ai-ide-instructions.md\n    participant Know as knowledge.md\n    participant Context as MCP Context7\n    \n    User-\u003e\u003eIdeas: Add PRD.md or PR.md\n    User-\u003e\u003eAI: Analyze new requirements\n    AI-\u003e\u003eIdeas: Read all requirement documents\n    AI-\u003e\u003eAiInst: Apply AI optimization principles\n    AI--\u003e\u003eUser: Requirements analysis complete\n    \n    User-\u003e\u003eContext: Use Context7\n    Context-\u003e\u003eKnow: Update knowledge base\n    AI-\u003e\u003eKnow: Consolidate insights with framework\n    AI--\u003e\u003eUser: Knowledge base updated\n    \n    Note over User,Know: Phase 1 Complete: Requirements understood\n```\n\n#### **Step 1: Requirements Analysis with Framework Integration**\n```bash\n# AI Prompt for Comprehensive Requirements Analysis\n/agent analyze new requirements from @/ideas/ folder\nApply framework principles from @/ai-ide-instructions.md:\n- F-LEN: Break features into ≤25 LOC functions\n- F-PARAM: Design APIs with ≤3 parameters\n- F-RESP: Single responsibility per component\n- M-SIZE: Keep modules ≤300 LOC\n\nExtract and document:\n- UI/UX requirements mapping to @/doc/designer-guidelines.md\n- Technical implementation following @/doc/programmer-guidelines.md\n- Testing strategy aligned with @/doc/tester-guidelines.md\n- Maintainability considerations for long-term AI assistance\n\nUpdate @/doc/knowledge.md with consolidated analysis\n```\n\n#### **Step 2: Knowledge Base Integration**\n```bash\n# MCP Context7 Integration\nUse Context7\n\n# AI Knowledge Consolidation Prompt\n/agent update @/doc/knowledge.md with comprehensive integration\nCross-reference with existing framework documents:\n- Validate against established patterns in @/doc/plan.md\n- Check consistency with @/doc/todo.md priorities\n- Align with @/doc/step_plan.md methodology\n- Ensure compatibility with role-specific guidelines\n\nDocument integration points and dependencies\nIdentify potential conflicts with existing architecture\n```\n\n#### **Phase 1: Requirements Analysis \u0026 Knowledge Base Setup**\n\n**Step 1: Analyze Requirements**\n```bash\n# AI Prompt for Requirements Analysis\n/agent analyze requirements from @/ideas/ folder\nApply AI coding standards from @/ai-ide-instructions.md\nFocus on F-LEN (≤25 LOC), F-PARAM (≤3 params), single responsibility\nExtract UI/UX requirements, technical feasibility, maintainability considerations\nDocument findings in @/doc/knowledge.md following ≤300 LOC sections\n```\n\n**Step 2: Update Knowledge Base with MCP Context7**\n```bash\n# Command to refresh AI context\nUse Context7\n\n# Follow-up AI Prompt\n/agent update @/doc/knowledge.md with MCP Context7 insights\nConsolidate requirements analysis with:\n- Best UI/UX practices for AI readability\n- Long-term maintainability (≤25 LOC functions)\n- Code readability (descriptive names, clear structure)\n- Technical feasibility (AI IDE compatibility)\n```\n\n### **Phase 2: Task Generation \u0026 Planning Integration**\n\n```mermaid\nsequenceDiagram\n    participant Know as knowledge.md\n    participant Plan as plan.md\n    participant Todo as todo.md\n    participant StepPlan as step_plan.md\n    participant AI as AI Assistant\n    participant Guidelines as Role Guidelines\n    \n    Know-\u003e\u003eAI: Requirements consolidated\n    AI-\u003e\u003ePlan: Map to TDD test roadmap\n    Plan-\u003e\u003eTodo: Generate specific tasks\n    Todo-\u003e\u003eStepPlan: Create implementation plans\n    \n    AI-\u003e\u003eGuidelines: Apply role-specific patterns\n    Guidelines--\u003e\u003eStepPlan: Validate against constraints\n    \n    Note over Know,Guidelines: Phase 2 Complete: Tasks planned\n```\n\n#### **Step 3: TDD Test Mapping \u0026 Integration**\n```bash\n# AI Test Integration Prompt\n/agent analyze @/doc/plan.md 20-test roadmap\nMap new requirements from @/ideas/ to existing test framework:\n- Cross-reference with @/doc/programmer-guidelines.md TDD methodology\n- Cross-reference with @/doc/tester-guidelines.md quality standards\n- Cross-reference with @/doc/designer-guidelines.md testable components\n\nFor each requirement:\n- Identify which existing tests cover new functionality\n- Create additional tests if needed (following TDD Red-Green-Refactor)\n- Prioritize tests based on:\n  * Core functionality importance\n  * Risk assessment from requirements\n  * Dependencies between features\n  * Integration with existing @/doc/todo.md priorities\n\nUpdate plan.md with new test scenarios\nEnsure each test follows ≤25 LOC constraint\nValidate test names follow shouldDoSomething pattern\nCross-reference with all role guidelines for comprehensive coverage\n```\n\n#### **Step 4: Comprehensive Task Decomposition**\n```bash\n# AI Task Generation Prompt (Framework-Integrated)\n/agent create comprehensive task breakdown\nBased on updated @/doc/plan.md and @/doc/knowledge.md\nIntegrate with ALL framework documents:\n\nFor each requirement, generate tasks using role guidelines:\n\nPROGRAMMER TASKS (apply @/doc/programmer-guidelines.md):\n- TDD implementation tasks (Red-Green-Refactor cycles)\n- Code structure following F-LEN (≤25 LOC), F-PARAM (≤3 params)\n- AI integration points for code generation\n- Security validation tasks\n\nDESIGNER TASKS (apply @/doc/designer-guidelines.md):\n- Component design with ≤3 props (F-PARAM mapping)\n- Atomic design system integration\n- Testable UI specification\n- AI assistance for design token generation\n\nTESTER TASKS (apply @/doc/tester-guidelines.md):\n- Test strategy aligned with TDD cycles\n- Quality gate validation\n- AI-assisted test case generation\n- Performance and accessibility validation\n\nEach task file: YYYYMMDD_HHMMSS_todo_taskname.md must include:\n- Single responsibility description\n- Acceptance criteria (≤10 items, measurable)\n- Dependencies linking to framework documents\n- AI integration points (TODO(ai) markers)\n- Role assignment and cross-role dependencies\n\nUpdate @/doc/todo.md with complete integrated task index\n```\n\n### **Phase 3: Implementation Planning \u0026 Role Integration**\n\n```mermaid\nflowchart TD\n    A[Tasks from todo.md] --\u003e B[Role Assignment Matrix]\n    \n    B --\u003e C[Programmer Tasks]\n    B --\u003e D[Designer Tasks]\n    B --\u003e E[Tester Tasks]\n    \n    C --\u003e C1[programmer-guidelines.md]\n    D --\u003e D1[designer-guidelines.md]\n    E --\u003e E1[tester-guidelines.md]\n    \n    C1 --\u003e F[Cross-Role Integration]\n    D1 --\u003e F\n    E1 --\u003e F\n    \n    F --\u003e G[Unified Step Plans]\n    G --\u003e H[YYYYMMDD_HHMMSS_steps_plan_*.md]\n    H --\u003e I[step_plan.md Index Update]\n    \n    I --\u003e J[TDD Implementation Ready]\n    J --\u003e K[go command execution]\n    \n    style A fill:#fff3e0\n    style C fill:#f3e5f5\n    style D fill:#e8f5e8\n    style E fill:#e3f2fd\n    style F fill:#ffecb3\n    style K fill:#e0f2f1\n```\n\n#### **Step 5: Integrated Step Planning**\n```bash\n# AI Step Plan Generation (Cross-Role Integration)\n/agent create detailed step plans with framework integration\nFollowing ALL role-specific guidelines with cross-dependencies:\n\nFor each task, create unified step plan that integrates:\n\nTECHNICAL IMPLEMENTATION (programmer-guidelines.md):\n- TDD Red-Green-Refactor methodology\n- Function constraints: ≤25 LOC, ≤3 parameters\n- Atomic commits (structural vs behavioral)\n- AI assistance points for code generation\n- Security validation checkpoints\n\nUI/UX IMPLEMENTATION (designer-guidelines.md):\n- Atomic design principles\n- Component specs with ≤3 props (F-PARAM mapping)\n- Design-to-code AI generation points\n- Testability considerations for development\n\nQUALITY ASSURANCE (tester-guidelines.md):\n- Test integration with TDD cycles\n- Quality gates and automation\n- AI-assisted test generation\n- Cross-browser and accessibility validation\n\nCROSS-ROLE DEPENDENCIES:\n- Designer → Programmer: Component specs for implementation\n- Programmer → Tester: Code structure for test design\n- Tester → Designer: Accessibility feedback for design\n- All roles → knowledge.md: Consolidated learnings\n\nEach step plan file: YYYYMMDD_HHMMSS_steps_plan_taskname.md\nInclude comprehensive resource requirements and validation criteria\nUpdate @/doc/step_plan.md with integrated index\n```\n\n#### **Phase 4: Security Validation \u0026 Project Setup**\n\n**Step 6: Security Validation (CRITICAL FIRST)**\n```bash\n# AI Security Audit Prompt\n/agent validate project security setup\nConfirm .gitignore, .dockerignore, .env.example are comprehensive\nAudit for any sensitive data in repository\nCreate language-specific ignore patterns if needed\nValidate no API keys, passwords, or secrets in code\n```\n\n### **Phase 5: TDD Implementation \u0026 Continuous Integration**\n\n```mermaid\ngraph TD\n    A[All Phases Complete] --\u003e B[go Command]\n    B --\u003e C[First TDD Cycle]\n    \n    subgraph \"TDD Implementation\"\n        C --\u003e D[Red Phase: Write Failing Test]\n        D --\u003e E[Green Phase: Minimal Implementation]\n        E --\u003e F[Refactor Phase: Tidy First]\n        F --\u003e G[Documentation Update]\n        G --\u003e H[Next Test Selection]\n        H --\u003e D\n    end\n    \n    subgraph \"PR Integration\"\n        I[PR.md Created] --\u003e J[Link to Implementation]\n        J --\u003e K[Testing \u0026 Verification]\n        K --\u003e L[Documentation Updates]\n        L --\u003e M[Ready for Review]\n    end\n    \n    G --\u003e I\n    M --\u003e N[Deployment Ready]\n    \n    style A fill:#e0f2f1\n    style B fill:#ffcdd2\n    style N fill:#c8e6c9\n```\n\n#### **Step 7: TDD Implementation Launch**\n```bash\n# Command to start implementation\ngo\n\n# This triggers the first test from plan.md following complete integration:\n/agent implement failing test for [first behavior from updated plan.md]\nApply framework integration:\n- Use knowledge.md context for implementation approach\n- Follow programmer-guidelines.md for TDD Red phase\n- Consider designer-guidelines.md for UI-related tests\n- Integrate tester-guidelines.md quality standards\n\nTest implementation must:\n- Follow ≤25 LOC constraint (ai-ide-instructions.md)\n- Use descriptive shouldDoSomething naming pattern\n- Include single behavior validation\n- Reference framework documentation in test comments\n```\n\n#### **Step 8: Pull Request Integration (PR.md)**\nWhen creating PR.md documents, integrate with framework:\n\n```bash\n# AI PR Integration Prompt\n/agent create PR.md following framework standards\nBased on completed implementation and framework documents:\n\n## Background (Why) - Reference Framework Docs\n- Link to original requirements in @/ideas/\n- Reference decisions documented in @/doc/knowledge.md\n- Cross-reference with @/doc/plan.md test implementations\n\n## Implementation Approach (How) - Framework Compliance\n- Validate against @/ai-ide-instructions.md constraints:\n  * Functions ≤25 LOC (F-LEN compliance)\n  * Parameters ≤3 (F-PARAM compliance)\n  * Single responsibility (F-RESP compliance)\n- Reference @/doc/programmer-guidelines.md TDD methodology\n- Include @/doc/designer-guidelines.md design decisions (if UI)\n- Document @/doc/tester-guidelines.md quality validations\n\n## Actual Changes (What was done) - Cross-Reference Tasks\n- Link to completed tasks in @/doc/todo.md\n- Reference step plans in @/doc/step_plan.md\n- Update @/doc/knowledge.md with implementation insights\n\n## Testing \u0026 Verification - Framework Integration\n- Validate all tests from @/doc/plan.md pass\n- Confirm @/doc/tester-guidelines.md standards met\n- Include AI assistance effectiveness metrics\n- Document any framework constraint violations and resolutions\n\n## Framework Compliance Checklist:\n- [ ] All functions ≤25 LOC (F-LEN)\n- [ ] All functions ≤3 parameters (F-PARAM)\n- [ ] TDD Red-Green-Refactor cycle followed\n- [ ] Documentation updated in knowledge.md\n- [ ] Tasks marked complete in todo.md\n- [ ] Cross-role guidelines followed\n- [ ] AI optimization maintained\n```\n\n### **Continuous Framework Integration**\n\n```mermaid\nsequenceDiagram\n    participant Dev as Developer\n    participant Framework as Framework Docs\n    participant AI as AI Assistant\n    participant Quality as Quality Gates\n    \n    loop Every Commit\n        Dev-\u003e\u003eFramework: Check compliance\n        Framework-\u003e\u003eAI: Apply constraints\n        AI-\u003e\u003eDev: Validate implementation\n        Dev-\u003e\u003eQuality: Run quality gates\n        Quality--\u003e\u003eDev: Pass/Fail feedback\n    end\n    \n    loop Weekly Review\n        Dev-\u003e\u003eFramework: Update learnings\n        Framework-\u003e\u003eAI: Refresh context\n        AI-\u003e\u003eFramework: Suggest improvements\n    end\n    \n    Note over Dev,Quality: Continuous Integration with Framework\n```\n\n### **Complete Integration Checklist**\n\nBefore considering any feature complete, validate integration across ALL framework documents:\n\n#### **Document Integration Validation**\n```bash\n# AI Integration Validation Prompt\n/agent validate complete framework integration\nCheck all document cross-references and consistency:\n\nREQUIREMENTS INTEGRATION:\n- [ ] @/ideas/ documents fully processed\n- [ ] @/doc/knowledge.md updated with all insights\n- [ ] Requirements mapped to @/doc/plan.md tests\n\nROLE INTEGRATION:\n- [ ] @/doc/programmer-guidelines.md patterns followed\n- [ ] @/doc/designer-guidelines.md principles applied\n- [ ] @/doc/tester-guidelines.md standards met\n\nTASK INTEGRATION:\n- [ ] All tasks created in @/doc/todo.md\n- [ ] Step plans generated in @/doc/step_plan.md\n- [ ] Cross-dependencies documented\n\nAI OPTIMIZATION INTEGRATION:\n- [ ] @/ai-ide-instructions.md rules enforced\n- [ ] Function constraints validated (≤25 LOC, ≤3 params)\n- [ ] AI readability patterns maintained\n\nTDD INTEGRATION:\n- [ ] Red-Green-Refactor cycles completed\n- [ ] All tests in @/doc/plan.md implemented\n- [ ] Quality gates passing\n\nDOCUMENTATION INTEGRATION:\n- [ ] Knowledge base current and comprehensive\n- [ ] All TODO(ai) markers addressed\n- [ ] Framework compliance documented\n```\n\n### **Sample Complete Integration: PRD → Running Code → PR**\n\n```bash\n# Complete End-to-End Example\n# 1. Add PRD.md to ideas/\necho \"New user authentication feature\" \u003e ideas/PRD_user_auth.md\n\n# 2. Run complete integration workflow\n/agent analyze requirements from @/ideas/PRD_user_auth.md\nApply @/ai-ide-instructions.md principles\nCross-reference ALL @/doc/ guidelines\nUpdate @/doc/knowledge.md with integrated analysis\n\n# 3. Generate integrated tasks and plans\n/agent create tasks following framework integration\nReference @/doc/programmer-guidelines.md for TDD tasks\nReference @/doc/designer-guidelines.md for UI tasks\nReference @/doc/tester-guidelines.md for QA tasks\nUpdate @/doc/todo.md and @/doc/step_plan.md\n\n# 4. Start TDD implementation\ngo\n/agent implement first failing test\nFollow complete framework integration\n\n# 5. Create PR with framework compliance\n/agent create PR.md with framework documentation\nInclude compliance checklist and cross-references\nDocument framework integration points\n```\n\nThis integration ensures that when AI assistants receive new PRD.md or PR.md documents, they follow a systematic approach that leverages ALL framework documents, maintains strong connections between them, and produces consistently high-quality, maintainable code that follows TDD principles and AI optimization constraints.\n\n#### **Phase 3: Development Cycle Kickoff**\n\n**Step 5: Start First TDD Cycle**\n```bash\n# Command to begin development\ngo\n\n# AI Implementation Prompt\n/agent implement failing test for [first behavior from plan.md]\nFollow TDD Red phase:\n- Test name: shouldDoSomething pattern (≤25 LOC)\n- Single behavior validation\n- Descriptive assertions\n- No implementation code yet\n```\n\n**Step 6: Minimal Implementation (Green Phase)**\n```bash\n# AI Green Phase Prompt\n/agent write minimal code to pass current failing test\nFollow F-LEN (≤25 LOC), F-PARAM (≤3 params), F-RESP (single responsibility)\nNo over-engineering, just enough to make test pass\nMaintain AI readability patterns from @/ai-ide-instructions.md\n```\n\n**Step 7: Refactoring (Tidy First)**\n```bash\n# AI Refactoring Prompt\n/agent refactor following Tidy First principles\nSeparate structural from behavioral changes:\n1. Structural: extract helpers, rename variables, reorganize imports\n2. Behavioral: new features, logic changes\nCommit each type separately with proper prefixes (structural: / feat:)\n```\n\n#### **Phase 4: Task Management \u0026 Documentation**\n\n**Step 8: Create Task Files**\n```bash\n# AI Task Creation Prompt\n/agent create todo task file for [specific feature]\nUse naming: YYYYMMDD_HHMMSS_todo_featurename.md\nInclude:\n- Task description (single responsibility)\n- Acceptance criteria (≤10 items, measurable)\n- Dependencies (explicit prerequisites)\n- AI integration points (TODO(ai) markers)\nUpdate @/doc/todo.md with new task entry\n```\n\n**Step 9: Generate Detailed Step Plans**\n```bash\n# AI Step Planning Prompt\n/agent create step plan for [todo task]\nUse naming: YYYYMMDD_HHMMSS_steps_plan_featurename.md\nStructure with:\n- Overview (≤3 paragraphs)\n- Detailed steps (≤10 per phase, atomic ≤25 LOC implementations)\n- Resource requirements (explicit tools, skills, dependencies)\n- Risk assessment (with AI-assisted mitigation strategies)\n- Validation criteria (automatable where possible)\nUpdate @/doc/step_plan.md index\n```\n\n### **Sample Complete Workflow: From PRD to Running Code**\n\n```bash\n# 1. Process Requirements\n/agent analyze requirements from @/ideas/PRD.md\nApply AI coding standards, extract technical requirements\n\n# 2. Update Knowledge Base\nUse Context7\n/agent update @/doc/knowledge.md with consolidated insights\n\n# 3. Security Check\n/agent validate comprehensive security setup\n\n# 4. Plan Tests\n/agent map PRD requirements to @/doc/plan.md TDD tests\n\n# 5. Start Development\ngo\n/agent implement failing test for user authentication\n\n# 6. Implement Minimal Code\n/agent write minimal code to pass authentication test\n\n# 7. Refactor \u0026 Clean\n/agent refactor following Tidy First principles\n\n# 8. Create Tasks\n/agent create todo task for dashboard component\n\n# 9. Continue Cycle\n# Select next test from plan.md and repeat\n```\n\n### **Daily AI-Assisted Development Routine**\n\n```bash\n# Morning Standup (≤5 minutes)\n/agent daily standup analysis\nCheck @/doc/todo.md for today's priorities\nReview @/doc/knowledge.md for overnight updates\nSelect next unmarked test from @/doc/plan.md\nValidate AI-optimization compliance (F-LEN, F-PARAM, F-RESP)\n\n# Development Cycle\n/agent implement next TDD cycle\nFollow Red-Green-Refactor methodology\nMaintain ≤25 LOC functions, ≤3 parameters\nUpdate documentation with learnings\n\n# End of Day\n/agent update progress tracking\nMark completed tasks in @/doc/todo.md\nUpdate @/doc/knowledge.md with insights\nPrepare tomorrow's priorities\n```\n\n---\n\n## 🚀 Project Initialization (New Team Members)\n\n```mermaid\ngraph TD\n    A[New Team Member] --\u003e B{What's Your Role?}\n    \n    B --\u003e C[Project Leader/CTO]\n    B --\u003e D[Developer]\n    B --\u003e E[Designer]\n    B --\u003e F[Tester/QA]\n    \n    C --\u003e C1[Read Framework Docs]\n    C --\u003e C2[Use Context7]\n    C --\u003e C3[Assign Team Roles]\n    \n    D --\u003e D1[Read AI Optimization Rules]\n    D --\u003e D2[Setup IDE + AI Extensions]\n    D --\u003e D3[SECURITY FIRST: Create Ignore Files]\n    D --\u003e D4[Start TDD Cycle: go command]\n    \n    E --\u003e E1[Read Design Guidelines]\n    E --\u003e E2[Setup Design System]\n    E --\u003e E3[Create Component Specs]\n    \n    F --\u003e F1[Read Testing Strategy]\n    F --\u003e F2[Setup Test Environment]\n    F --\u003e F3[Join TDD Cycle]\n    \n    C1 --\u003e C1A[ai-ide-instructions.md]\n    C1 --\u003e C1B[doc/knowledge.md]\n    C1 --\u003e C1C[doc/plan.md]\n    \n    D1 --\u003e D1A[≤25 LOC functions]\n    D1 --\u003e D1B[≤3 parameters]\n    D1 --\u003e D1C[Single responsibility]\n    \n    D3 --\u003e D3A[.gitignore]\n    D3 --\u003e D3B[.dockerignore]\n    D3 --\u003e D3C[.env.example]\n    \n    E2 --\u003e E2A[Design tokens → code constants]\n    E2 --\u003e E2B[≤3 props per component]\n    E2 --\u003e E2C[Testable interactions]\n    \n    F2 --\u003e F2A[Test frameworks]\n    F2 --\u003e F2B[Coverage reporting]\n    F2 --\u003e F2C[CI integration]\n    \n    style C fill:#e1f5fe\n    style D fill:#f3e5f5\n    style E fill:#e8f5e8\n    style F fill:#fff3e0\n```\n\n### **For Project Leaders/CTOs**\n```bash\n# 1. Read core framework\n📖 Read: @/ai-ide-instructions.md (AI optimization principles)\n📖 Read: @/doc/knowledge.md (project knowledge base)\n📖 Read: @/doc/plan.md (TDD roadmap with 20 tests)\n\n# 2. Update knowledge base\n💡 Command: \"Use Context7\" (MCP server integration)\n📝 Update: @/doc/knowledge.md with project requirements from @/ideas/\n\n# 3. Assign roles and review guidelines\n👥 Team: Review role-specific guidelines in @/doc/\n🎯 Next: Choose starting point based on team composition\n```\n\n### **For Developers (First Time)**\n```bash\n# 1. Understand the framework\n📖 Read: @/ai-ide-instructions.md (Function rules: ≤25 LOC, ≤3 params)\n📖 Read: @/doc/programmer-guidelines.md (TDD workflow)\n📖 Read: @/doc/plan.md (Available tests to implement)\n\n# 2. Setup development environment\n⚙️ Configure: IDE with AI extensions (Cursor/Windsurf/VS Code)\n⚙️ Setup: Testing framework and linting rules\n⚙️ Validate: F-LEN, F-PARAM compliance in IDE\n\n# 3. Create security and ignore files (CRITICAL FIRST STEP)\n🔒 Create: .gitignore (prevent sensitive files in git)\n🔒 Create: .dockerignore (optimize docker builds)\n🔒 Create: .env.example (template for environment variables)\n🔒 Setup: IDE-specific ignore patterns\n🔒 Validate: No sensitive data in repository\n\n# 4. Start TDD cycle\n🔴 Command: \"go\" (Implements first test from plan.md)\n🟢 Follow: Red-Green-Refactor methodology\n📝 Update: @/doc/knowledge.md with learnings\n```\n\n### **For Designers (First Time)**\n```bash\n# 1. Understand design constraints\n📖 Read: @/doc/designer-guidelines.md (Atomic design + TDD)\n📖 Read: @/ai-ide-instructions.md (AI-optimized patterns)\n📖 Review: Component size limits (≤25 LOC implementation)\n\n# 2. Setup design system\n🎨 Create: Design tokens mapping to code constants\n🎨 Plan: Components with ≤3 props (F-PARAM rule)\n🎨 Document: Testable interaction specifications\n\n# 3. Collaborate with development\n🤝 Review: @/doc/plan.md for UI-related tests\n📝 Create: Component specs following guidelines\n✅ Validate: Designs support automated testing\n```\n\n### **For Testers/QA (First Time)**\n```bash\n# 1. Understand testing strategy\n📖 Read: @/doc/tester-guidelines.md (TDD integration)\n📖 Read: @/doc/plan.md (20 tests ready for implementation)\n📖 Review: Quality gates and validation criteria\n\n# 2. Setup testing environment\n⚙️ Configure: Test frameworks and automation tools\n⚙️ Setup: Coverage reporting and CI integration\n⚙️ Prepare: Test data fixtures and mocks\n\n# 3. Join TDD cycle\n🔴 Collaborate: Help write meaningful failing tests\n🟢 Validate: Minimal implementations meet requirements\n🔧 Ensure: Structural changes don't break functionality\n```\n\n---\n\n## 🔄 Project Continuation (Daily/Weekly Work)\n\n```mermaid\nsequenceDiagram\n    participant D as Developer\n    participant T as Tester\n    participant Des as Designer\n    participant AI as AI Assistant\n    participant K as Knowledge Base\n    \n    Note over D,K: Daily Workflow (≤5 minutes setup)\n    \n    D-\u003e\u003eK: Check todo.md priorities\n    D-\u003e\u003eK: Review knowledge.md updates\n    D-\u003e\u003eAI: Select next test from plan.md\n    \n    Note over D,AI: TDD Red-Green-Refactor Cycle\n    \n    D-\u003e\u003eAI: /agent implement failing test\n    AI--\u003e\u003eD: Test code ≤25 LOC\n    D-\u003e\u003eAI: /agent write minimal implementation\n    AI--\u003e\u003eD: Code ≤25 LOC, ≤3 params\n    \n    T-\u003e\u003eAI: /agent validate test quality\n    AI--\u003e\u003eT: Coverage + quality metrics\n    \n    Des-\u003e\u003eAI: /agent design component specs\n    AI--\u003e\u003eDes: ≤3 props, testable states\n    \n    D-\u003e\u003eAI: /agent refactor following Tidy First\n    AI--\u003e\u003eD: Structural vs behavioral separation\n    \n    Note over D,K: End of Day\n    D-\u003e\u003eK: Update progress in todo.md\n    D-\u003e\u003eK: Document insights in knowledge.md\n    \n    Note over D,K: Weekly Review\n    rect rgb(240, 248, 255)\n        D-\u003e\u003eAI: /agent weekly progress review\n        AI--\u003e\u003eD: Compliance metrics + suggestions\n        D-\u003e\u003eK: Update team learnings\n    end\n```\n\n### **Daily Standup Prompt**\n```bash\n# Morning routine (≤5 minutes)\n📋 Check: @/doc/todo.md for today's priorities\n📖 Review: @/doc/knowledge.md for overnight updates\n🎯 Select: Next unmarked test from @/doc/plan.md (if developing)\n⚡ Command: \"Use Context7\" (if major changes occurred)\n\n# Role-specific daily prep\n👨‍💻 Developers: Review @/doc/programmer-guidelines.md TDD cycle\n🎨 Designers: Check @/doc/designer-guidelines.md for component work\n🧪 Testers: Review @/doc/tester-guidelines.md for validation tasks\n```\n\n### **Weekly Progress Review**\n```bash\n# Team lead review (≤15 minutes)\n📊 Analyze: @/doc/todo.md completion rates\n📈 Review: @/doc/plan.md test implementation progress\n🔍 Validate: AI-optimization compliance across codebase\n📝 Update: @/doc/knowledge.md with team learnings\n\n# Quality assurance check\n✅ Verify: Functions ≤25 LOC, ≤3 parameters\n✅ Confirm: TDD Red-Green-Refactor cycles followed\n✅ Check: Documentation consistency across @/doc/\n✅ Validate: AI readability patterns maintained\n```\n\n---\n\n## 🎶 Security \u0026 Project Setup (CRITICAL FIRST STEP)\n\n### **When Starting Any New Project**\n```bash\n# Security and ignore files setup (BEFORE any code commits)\n🔒 Create: Standard ignore files to prevent data leaks\n📁 Setup: Project structure with security best practices\n🛡️ Validate: No sensitive information in version control\n⚙️ Configure: Environment variable templates\n```\n\n### **Essential Ignore Files to Create**\n\n#### 1. .gitignore (Universal - Always Required)\n```bash\n# AI Development Environment\n.cursor/\n.windsurf/\n.vscode/settings.json\n.vscode/launch.json\n\n# Dependencies\nnode_modules/\nvenv/\nenv/\n.env\n.env.local\n.env.development\n.env.production\n\n# Build outputs\ndist/\nbuild/\ntarget/\nout/\n*.log\n*.tmp\n\n# OS generated files\n.DS_Store\n.DS_Store?\n._*\n.Spotlight-V100\n.Trashes\nehthumbs.db\nThumbs.db\n\n# IDE files\n*.swp\n*.swo\n*~\n.idea/\n.vscode/\n*.sublime-project\n*.sublime-workspace\n\n# Test coverage\ncoverage/\n.nyc_output/\n.coverage\nhtmlcov/\n\n# Cache directories\n.cache/\n.npm/\n.yarn/cache/\n__pycache__/\n*.pyc\n*.pyo\n*.pyd\n\n# Database files\n*.db\n*.sqlite\n*.sqlite3\n\n# API keys and secrets\nconfig/secrets/\n.env*\n!.env.example\nsecrets.json\ncredentials.json\nservice-account-key.json\n\n# AI model files (often large)\n*.h5\n*.pkl\n*.joblib\nmodels/\ncheckpoints/\n\n# Documentation builds\ndocs/_build/\nsite/\n```\n\n#### 2. .dockerignore (For Docker Projects)\n```bash\n# Version control\n.git\n.gitignore\n\n# Documentation\nREADME.md\ndocs/\n*.md\n\n# Development files\n.env*\n!.env.example\n.vscode/\n.cursor/\n.windsurf/\n\n# Dependencies (install fresh in container)\nnode_modules/\nvenv/\nenv/\n\n# Build artifacts\ndist/\nbuild/\ntarget/\n*.log\n\n# OS files\n.DS_Store\nThumbs.db\n\n# Test files\ntests/\n**/*.test.*\ncoverage/\n\n# CI/CD files\n.github/\n.gitlab-ci.yml\nJenkinsfile\n```\n\n#### 3. .env.example (Environment Template)\n```bash\n# Database Configuration\nDATABASE_URL=postgresql://user:password@localhost:5432/dbname\nDATABASE_HOST=localhost\nDATABASE_PORT=5432\nDATABASE_NAME=your_database_name\n\n# API Keys (Use actual keys in .env file, never commit)\nAPI_KEY=your_api_key_here\nSECRET_KEY=your_secret_key_here\nJWT_SECRET=your_jwt_secret_here\n\n# AI Service Configuration\nOPENAI_API_KEY=your_openai_key_here\nANTHROPIC_API_KEY=your_anthropic_key_here\n\n# Application Settings\nNODE_ENV=development\nPORT=3000\nDEBUG=true\n\n# External Services\nREDIS_URL=redis://localhost:6379\nELASTICSEARCH_URL=http://localhost:9200\n\n# Email Configuration\nSMTP_HOST=smtp.example.com\nSMTP_PORT=587\nSMTP_USER=your_email@example.com\nSMTP_PASS=your_email_password\n```\n\n#### 4. Language-Specific Ignore Patterns\n\n**For Python Projects:**\n```bash\n# Add to .gitignore\n__pycache__/\n*.py[cod]\n*$py.class\n*.so\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\npip-wheel-metadata/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n```\n\n**For Node.js Projects:**\n```bash\n# Add to .gitignore\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\nlerna-debug.log*\n.pnpm-debug.log*\n.npm\n.eslintcache\n.yarn-integrity\n.yarn/cache/\n.yarn/unplugged/\n.yarn/build-state.yml\n.yarn/install-state.gz\n.pnp.*\n```\n\n**For AI/ML Projects:**\n```bash\n# Add to .gitignore\n# Jupyter Notebook\n.ipynb_checkpoints\n*.ipynb\n\n# Data files (often large/sensitive)\ndata/\ndatasets/\n*.csv\n*.json\n*.parquet\n\n# Model artifacts\nmodels/\nweights/\ncheckpoints/\n*.h5\n*.pkl\n*.joblib\n*.onnx\n\n# Experiment tracking\nmlruns/\n.mlflow/\nwandb/\n```\n\n### **Security Validation Checklist**\n```bash\n# Before first commit, verify:\n✅ .gitignore created and comprehensive\n✅ .env.example created (template only, no real secrets)\n✅ .env added to .gitignore\n✅ No API keys, passwords, or secrets in code\n✅ Database files ignored\n✅ Build artifacts ignored\n✅ OS-specific files ignored\n✅ IDE-specific files ignored\n✅ Large binary files ignored\n✅ AI model files ignored (if applicable)\n```\n\n### **AI Programming Security Commands**\n```bash\n# Security validation prompts for AI assistants\n🔒 \"/agent create comprehensive .gitignore for [language/framework]\"\n🔒 \"/agent validate no sensitive data in repository\"\n🔒 \"/agent create .env.example template for project dependencies\"\n🔒 \"/agent setup .dockerignore optimized for [project type]\"\n🔒 \"/agent audit codebase for hardcoded secrets or credentials\"\n```\n\n### **Post-Setup Validation**\n```bash\n# After creating ignore files, run these commands:\ngit status                    # Verify sensitive files not tracked\ngit check-ignore -v file.env  # Test ignore patterns work\ndocker build . --dry-run     # Verify dockerignore effectiveness (if using Docker)\n```\n\n## 💻 Development Phase Prompts\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e Planning: New Feature Request\n    \n    Planning --\u003e Red: Feature Planned\n    Planning --\u003e Planning: Refine Requirements\n    \n    state Red {\n        [*] --\u003e WriteTest: Start TDD Cycle\n        WriteTest --\u003e ValidateTest: Test Written ≤25 LOC\n        ValidateTest --\u003e TestFails: Run Test\n        TestFails --\u003e [*]: Red Phase Complete\n    }\n    \n    Red --\u003e Green: Test Failing\n    \n    state Green {\n        [*] --\u003e WriteCode: Implement Minimal Code\n        WriteCode --\u003e ValidateCode: Code ≤25 LOC, ≤3 params\n        ValidateCode --\u003e TestPasses: Run All Tests\n        TestPasses --\u003e [*]: Green Phase Complete\n    }\n    \n    Green --\u003e Refactor: Tests Passing\n    \n    state Refactor {\n        [*] --\u003e StructuralChanges: Tidy First Approach\n        StructuralChanges --\u003e BehavioralChanges: Separate Commits\n        BehavioralChanges --\u003e ValidateRefactor: Maintain Test Coverage\n        ValidateRefactor --\u003e [*]: Refactor Complete\n    }\n    \n    Refactor --\u003e Documentation: Code Clean\n    \n    state Documentation {\n        [*] --\u003e UpdateKnowledge: Document Insights\n        UpdateKnowledge --\u003e UpdateTodos: Track Progress\n        UpdateTodos --\u003e [*]: Documentation Complete\n    }\n    \n    Documentation --\u003e Planning: Next Feature\n    Documentation --\u003e [*]: Feature Complete\n    \n    state AI_Assistant {\n        RedPhase: /agent implement failing test\n        GreenPhase: /agent write minimal code\n        RefactorPhase: /agent refactor following Tidy First\n        ValidatePhase: /agent validate compliance\n    }\n    \n    Red --\u003e AI_Assistant\n    Green --\u003e AI_Assistant\n    Refactor --\u003e AI_Assistant\n```\n\n### **AI-Optimized TDD Cycle**\n\n```mermaid\nflowchart TD\n    A[🔴 RED PHASE] --\u003e A1[Write Failing Test]\n    A1 --\u003e A2[≤25 LOC per test]\n    A2 --\u003e A3[Single behavior validation]\n    A3 --\u003e A4[Descriptive test name]\n    A4 --\u003e A5[Run test - must fail]\n    \n    A5 --\u003e B[🟢 GREEN PHASE]\n    B --\u003e B1[Write minimal code]\n    B1 --\u003e B2[≤25 LOC functions]\n    B2 --\u003e B3[≤3 parameters]\n    B3 --\u003e B4[Single responsibility]\n    B4 --\u003e B5[Run tests - all pass]\n    \n    B5 --\u003e C[🔧 REFACTOR PHASE]\n    C --\u003e C1[Structural changes first]\n    C1 --\u003e C2[Extract helpers]\n    C2 --\u003e C3[Rename for clarity]\n    C3 --\u003e C4[Reorganize imports]\n    C4 --\u003e C5[Behavioral changes second]\n    C5 --\u003e C6[Separate commits]\n    \n    C6 --\u003e D[📝 DOCUMENT]\n    D --\u003e D1[Update knowledge.md]\n    D1 --\u003e D2[Update todo progress]\n    D2 --\u003e D3[Add AI markers]\n    \n    D3 --\u003e E{Next Test?}\n    E --\u003e|Yes| A\n    E --\u003e|No| F[Feature Complete]\n    \n    style A fill:#ffcdd2\n    style B fill:#c8e6c9\n    style C fill:#bbdefb\n    style D fill:#fff3e0\n```\n\n### **When Starting New Features**\n```bash\n# Feature planning\n📖 Read: @/doc/knowledge.md for context\n📝 Create: New todo file using YYYYMMDD_HHMMSS_todo_featurename.md\n📋 Plan: Break feature into ≤25 LOC functions\n🎯 Add: Test to @/doc/plan.md following TDD pattern\n\n# TDD implementation\n🔴 Red: Write failing test (≤25 LOC)\n🟢 Green: Implement minimal code to pass\n🔧 Refactor: Apply Tidy First principles\n📝 Document: Update @/doc/knowledge.md with insights\n```\n\n### **When Debugging Issues**\n```bash\n# Debugging workflow\n📖 Review: @/doc/programmer-guidelines.md error handling\n🔍 Check: @/doc/plan.md for related tests\n🧪 Add: Failing test that reproduces the bug (TDD approach)\n🔧 Fix: Minimal code to make tests pass\n📝 Update: @/doc/knowledge.md with root cause analysis\n```\n\n### **When Adding Dependencies**\n```bash\n# Dependency validation\n📖 Check: @/ai-ide-instructions.md for dependency guidelines\n🔍 Validate: Library supports ≤25 LOC integration patterns\n🧪 Test: Integration following @/doc/tester-guidelines.md\n📝 Document: Update @/doc/knowledge.md with integration notes\n```\n\n---\n\n## 🎨 Design Phase Prompts\n\n### **When Creating New Components**\n```bash\n# Component design workflow\n📖 Read: @/doc/designer-guidelines.md atomic design principles\n🎯 Plan: Component with ≤3 props (F-PARAM rule)\n📝 Specify: Testable states and interactions\n🧪 Document: Test scenarios for developers\n✅ Validate: Design supports ≤25 LOC implementation\n```\n\n### **When Updating Design System**\n```bash\n# Design system evolution\n📖 Review: @/doc/designer-guidelines.md for patterns\n🔍 Analyze: @/app/ for implementation constraints\n🎨 Update: Design tokens mapping to code constants\n📝 Document: Changes in @/doc/knowledge.md\n🤝 Coordinate: With developers for TDD integration\n```\n\n---\n\n## 🧪 Testing Phase Prompts\n\n### **When Writing Tests**\n```bash\n# Test creation workflow\n📖 Follow: @/doc/tester-guidelines.md TDD patterns\n🔴 Write: One failing test per behavior (≤25 LOC)\n📝 Name: Descriptive test names (shouldDoSomething pattern)\n🎯 Focus: Single responsibility per test\n✅ Validate: Test covers edge cases and errors\n```\n\n### **When Validating Quality**\n```bash\n# Quality assurance workflow\n📊 Run: Full test suite (≤2 min execution time)\n📈 Check: Coverage metrics (≥85% target)\n🔍 Validate: All functions ≤25 LOC, ≤3 parameters\n📝 Review: @/doc/plan.md for test completion status\n🚀 Approve: Ready for deployment if all gates pass\n```\n\n---\n\n## 🚀 Deployment Phase Prompts\n\n### **When Preparing for Release**\n```bash\n# Pre-deployment checklist\n✅ Verify: All tests in @/doc/plan.md implemented\n✅ Confirm: @/doc/knowledge.md is up-to-date\n✅ Validate: AI-optimization compliance across @/app/\n✅ Check: Performance benchmarks within limits\n📝 Document: Release notes and deployment guide\n```\n\n### **When Monitoring Production**\n```bash\n# Post-deployment monitoring\n📊 Monitor: Performance metrics vs benchmarks\n🔍 Track: Error rates and user feedback\n📝 Update: @/doc/knowledge.md with production insights\n🔄 Plan: Next iteration based on learnings\n```\n\n---\n\n## 🤖 AI Integration Commands \u0026 Troubleshooting\n\n### **Context Management**\n```bash\n# Knowledge base updates\n💡 \"Use Context7\" - Update knowledge base with MCP server\n📝 Update @/doc/knowledge.md after major requirement changes\n🔄 Refresh AI context when switching between projects\n```\n\n### **AI-Assisted Development**\n```bash\n# Effective AI prompts\n🔴 \"/agent implement failing test for [behavior] following TDD Red phase\"\n🟢 \"/agent write minimal code to pass test, ≤25 LOC, ≤3 params\"\n🔧 \"/agent refactor following Tidy First principles\"\n📝 \"/agent update documentation following AI-readable patterns\"\n\n# Security-focused AI prompts\n🔒 \"/agent create comprehensive .gitignore for [language/framework]\"\n🔒 \"/agent validate no sensitive data in repository\"\n🔒 \"/agent audit codebase for hardcoded secrets or credentials\"\n🔒 \"/agent setup environment variable management securely\"\n```\n\n### **Role-Specific AI Prompts**\n\n#### **For Designers:**\n```bash\n# Component Design Prompts\n/agent design component following @/doc/designer-guidelines.md\nCreate atomic component with:\n- Single responsibility purpose\n- ≤3 props (maps to F-PARAM rule)\n- Testable states (default, hover, error, disabled)\n- AI-readable structure for code generation\nDocument component specification with implementation notes\n\n# Design System Prompts\n/agent generate design tokens following atomic design principles\nMap design constants to code variables\nEnsure ≤25 LOC implementation per component\nCreate testable interaction specifications\n```\n\n#### **For Testers:**\n```bash\n# Test Strategy Prompts\n/agent create test strategy following @/doc/tester-guidelines.md\nDesign tests for:\n- Unit tests (≤25 LOC per test, single behavior)\n- Integration tests (API, workflows, data)\n- Performance tests (≤2 sec unit tests, ≤30 sec integration)\n- Accessibility tests (WCAG 2.1 AA compliance)\nUse TODO(ai) markers for AI-assisted test generation\n\n# Quality Assurance Prompts\n/agent validate quality gates for deployment readiness\nCheck coverage metrics (≥85% target)\nVerify all functions ≤25 LOC, ≤3 parameters\nValidate TDD Red-Green-Refactor cycle compliance\nGenerate test reports with AI effectiveness metrics\n```\n\n#### **For Programmers:**\n```bash\n# TDD Cycle Prompts\n/agent apply house rules from @/ai-ide-instructions.md\nFocus on F-LEN (≤25 LOC), F-RESP (single responsibility), F-PARAM (≤3 params)\nSplit any function \u003e25 LOC into pure helpers\nKeep behavior identical, validate with tests\n\n# Code Review Prompts\n/agent review code for AI optimization compliance\nCheck function length, parameter count, cyclomatic complexity\nSuggest refactoring opportunities following Tidy First\nValidate descriptive naming conventions (4-6 words)\n```\n\n### **Emergency AI Troubleshooting Prompts**\n\n#### **When Tests Fail:**\n```bash\n/agent debug failing test following @/doc/programmer-guidelines.md\n1. Verify test exercises correct code path\n2. Check if test is too complex (split if \u003e25 LOC)\n3. Apply single responsibility to implementation\n4. Add failing test that reproduces bug (TDD approach)\n5. Fix with minimal code to pass tests\n```\n\n#### **When AI Suggestions Are Poor:**\n```bash\n/agent improve AI context for better suggestions\n1. Improve TODO(ai) markers with specific context\n2. Break large functions into ≤25 LOC units\n3. Use descriptive 4-6 word naming patterns\n4. Verify compliance with @/ai-ide-instructions.md\n5. Update @/doc/knowledge.md with clearer requirements\n```\n\n#### **When Code Becomes Complex:**\n```bash\n/agent simplify complex code following framework rules\nApply F-LEN rule: split functions \u003e25 LOC\nApply F-PARAM rule: use DTOs for \u003e3 parameters\nApply F-NEST rule: reduce nesting to ≤3 levels\nApply Tidy First: separate structural from behavioral changes\nMaintain test coverage throughout refactoring\n```\n\n### **Weekly AI-Assisted Reviews**\n```bash\n# Progress Analysis\n/agent weekly progress review\nAnalyze @/doc/todo.md completion rates\nReview @/doc/plan.md test implementation progress\nValidate AI-optimization compliance across codebase:\n- Functions ≤25 LOC (F-LEN)\n- Parameters ≤3 (F-PARAM)\n- Files ≤300 LOC (M-SIZE)\n- Cyclomatic complexity ≤10\nUpdate @/doc/knowledge.md with team learnings\n\n# Quality Metrics Review\n/agent generate quality metrics report\nTrack test coverage, code complexity, AI assistance effectiveness\nIdentify patterns in bugs, performance issues, technical debt\nSuggest improvements for next iteration\nPlan refactoring priorities using Tidy First principles\n```\n\n---\n\n## 📚 Quick Reference Guide\n\n### **Framework Knowledge Flow**\n\n```mermaid\ngraph TB\n    subgraph \"Input Layer\"\n        A[PRD.md in ideas folder]\n        B[Technical Specs]\n        C[Product Requirements]\n    end\n    \n    subgraph \"AI Processing Layer\"\n        D[MCP Context7]\n        E[AI Analysis Engine]\n        F[Requirement Processor]\n    end\n    \n    subgraph \"Knowledge Base Layer\"\n        G[knowledge.md]\n        H[plan.md - 20 TDD Tests]\n        I[todo.md - Task Tracking]\n        J[step_plan.md - Implementation Plans]\n    end\n    \n    subgraph \"Guidelines Layer\"\n        K[ai-ide-instructions.md]\n        L[programmer-guidelines.md]\n        M[designer-guidelines.md]\n        N[tester-guidelines.md]\n    end\n    \n    subgraph \"Implementation Layer\"\n        O[App Source Code]\n        P[Individual Tasks]\n        Q[Step Plans]\n    end\n    \n    subgraph \"Quality Gates\"\n        R[≤25 LOC Functions]\n        S[≤3 Parameters]\n        T[TDD Compliance]\n        U[AI Readability]\n    end\n    \n    A --\u003e D\n    B --\u003e D\n    C --\u003e D\n    \n    D --\u003e E\n    E --\u003e F\n    F --\u003e G\n    \n    G --\u003e H\n    G --\u003e I\n    G --\u003e J\n    \n    K --\u003e L\n    K --\u003e M\n    K --\u003e N\n    \n    H --\u003e O\n    I --\u003e P\n    J --\u003e Q\n    \n    L --\u003e O\n    M --\u003e O\n    N --\u003e O\n    \n    O --\u003e R\n    O --\u003e S\n    O --\u003e T\n    O --\u003e U\n    \n    R --\u003e V[Production Ready Code]\n    S --\u003e V\n    T --\u003e V\n    U --\u003e V\n    \n    style A fill:#e8f5e8\n    style D fill:#e3f2fd\n    style G fill:#fff3e0\n    style K fill:#fce4ec\n    style O fill:#f3e5f5\n    style V fill:#e0f2f1\n```\n\n### **Phase Reference Table**\n\n| Phase | Primary Files | Key Commands | Success Criteria |\n|-------|---------------|--------------|------------------|\n| **Security Setup** | .gitignore, .dockerignore, .env.example | Create ignore files | No sensitive data tracked |\n| **Init** | ai-ide-instructions.md, knowledge.md | \"Use Context7\" | Framework understood |\n| **Plan** | plan.md, todo.md | Select next test | Clear roadmap |\n| **Design** | designer-guidelines.md | Create component specs | Testable designs |\n| **Develop** | programmer-guidelines.md | \"go\" command | TDD cycle complete |\n| **Test** | tester-guidelines.md | Run test suite | All quality gates pass |\n| **Deploy** | All docs updated | Validate compliance | Production ready |\n\n### **AI Optimization Quick Check**\n\n```mermaid\npie title AI Compliance Metrics\n    \"Functions ≤25 LOC\" : 25\n    \"Parameters ≤3\" : 20\n    \"Single Responsibility\" : 20\n    \"Files ≤300 LOC\" : 15\n    \"Cyclomatic Complexity ≤10\" : 10\n    \"AI Readability Patterns\" : 10\n```\n\n### **Emergency Commands**\n| Issue | Command | Expected Outcome |\n|-------|---------|------------------|\n| **Tests Failing** | `/agent debug failing test following @/doc/programmer-guidelines.md` | Root cause identified, minimal fix applied |\n| **Poor AI Suggestions** | `/agent improve AI context for better suggestions` | Enhanced TODO(ai) markers, clearer requirements |\n| **Code Too Complex** | `/agent simplify complex code following framework rules` | Functions split to ≤25 LOC, reduced complexity |\n| **Security Concerns** | `/agent audit codebase for hardcoded secrets or credentials` | No sensitive data in repository |\n| **Performance Issues** | `/agent weekly progress review` | Compliance metrics, improvement suggestions |\n\n---\n\n**🎯 Ready to Start?** Choose your role above and follow the corresponding prompts. Remember: this framework combines Kent Beck's TDD with AI-optimization for maximum development effectiveness.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foliguo%2Fvibe-coding-instructions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foliguo%2Fvibe-coding-instructions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foliguo%2Fvibe-coding-instructions/lists"}