├── standards ├── code-style │ ├── javascript-style.md │ ├── html-style.md │ └── css-style.md ├── tech-stack.md ├── best-practices.md └── code-style.md ├── commands ├── execute-tasks.md ├── plan-product.md ├── analyze-product.md ├── create-tasks.md └── create-spec.md ├── .gitignore ├── config.yml ├── instructions ├── meta │ ├── pre-flight.md │ └── post-flight.md └── core │ ├── create-tasks.md │ ├── execute-tasks.md │ ├── analyze-product.md │ ├── execute-task.md │ ├── complete-tasks.md │ ├── plan-product.md │ └── create-spec.md ├── LICENSE ├── README.md ├── claude-code └── agents │ ├── project-manager.md │ ├── test-runner.md │ ├── context-fetcher.md │ ├── date-checker.md │ ├── git-workflow.md │ └── file-creator.md ├── setup ├── functions.sh ├── base.sh └── project.sh └── CHANGELOG.md /standards/code-style/javascript-style.md: -------------------------------------------------------------------------------- 1 | # Javascript Style Guide 2 | -------------------------------------------------------------------------------- /commands/execute-tasks.md: -------------------------------------------------------------------------------- 1 | # Execute Task 2 | 3 | Execute the next task. 4 | 5 | Refer to the instructions located in this file: 6 | @.agent-os/instructions/core/execute-tasks.md 7 | -------------------------------------------------------------------------------- /commands/plan-product.md: -------------------------------------------------------------------------------- 1 | # Plan Product 2 | 3 | Plan a new product and install Agent OS in its codebase. 4 | 5 | Refer to the instructions located in this file: 6 | @.agent-os/instructions/core/plan-product.md 7 | -------------------------------------------------------------------------------- /commands/analyze-product.md: -------------------------------------------------------------------------------- 1 | # Analyze Product 2 | 3 | Analyze your product's codebase and install Agent OS 4 | 5 | Refer to the instructions located in this file: 6 | @.agent-os/instructions/core/analyze-product.md 7 | -------------------------------------------------------------------------------- /commands/create-tasks.md: -------------------------------------------------------------------------------- 1 | # Create Tasks 2 | 3 | Create a tasks list with sub-tasks to execute a feature based on its spec. 4 | 5 | Refer to the instructions located in this file: 6 | @.agent-os/instructions/core/create-tasks.md 7 | -------------------------------------------------------------------------------- /commands/create-spec.md: -------------------------------------------------------------------------------- 1 | # Create Spec 2 | 3 | Create a detailed spec for a new feature with technical specifications and task breakdown 4 | 5 | Refer to the instructions located in this file: 6 | @.agent-os/instructions/core/create-spec.md 7 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # macOS 2 | .DS_Store 3 | .DS_Store? 4 | ._* 5 | .Spotlight-V100 6 | .Trashes 7 | ehthumbs.db 8 | Thumbs.db 9 | 10 | # IDE 11 | .vscode/ 12 | .idea/ 13 | *.swp 14 | *.swo 15 | 16 | # Logs 17 | logs 18 | *.log 19 | npm-debug.log* 20 | yarn-debug.log* 21 | yarn-error.log* 22 | 23 | # Runtime data 24 | pids 25 | *.pid 26 | *.seed 27 | *.pid.lock 28 | 29 | # Dependencies 30 | node_modules/ 31 | 32 | # Temporary files 33 | *.tmp 34 | *.temp 35 | -------------------------------------------------------------------------------- /config.yml: -------------------------------------------------------------------------------- 1 | # Agent OS Configuration 2 | 3 | # Refer to the official Agent OS documentation at: 4 | # https://buildermethods.com/agent-os 5 | 6 | agent_os_version: 1.4.1 7 | 8 | agents: 9 | claude_code: 10 | enabled: false 11 | cursor: 12 | enabled: false 13 | 14 | project_types: 15 | default: 16 | instructions: ~/.agent-os/instructions 17 | standards: ~/.agent-os/standards 18 | 19 | # type_a: 20 | # instructions: ~/.agent-os/project_types/type_a/instructions 21 | # standards: ~/.agent-os/project_types/type_a/standards 22 | 23 | # type_b: 24 | # instructions: ~/.agent-os/project_types/type_b/instructions 25 | # standards: ~/.agent-os/project_types/type_b/standards 26 | 27 | default_project_type: default 28 | -------------------------------------------------------------------------------- /instructions/meta/pre-flight.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Common Pre-Flight Steps for Agent OS Instructions 3 | globs: 4 | alwaysApply: false 5 | version: 1.0 6 | encoding: UTF-8 7 | --- 8 | 9 | # Pre-Flight Rules 10 | 11 | - IMPORTANT: For any step that specifies a subagent in the subagent="" XML attribute you MUST use the specified subagent to perform the instructions for that step. 12 | 13 | - Process XML blocks sequentially 14 | 15 | - Read and execute every numbered step in the process_flow EXACTLY as the instructions specify. 16 | 17 | - If you need clarification on any details of your current task, stop and ask the user specific numbered questions and then continue once you have all of the information you need. 18 | 19 | - Use exact templates as provided 20 | -------------------------------------------------------------------------------- /instructions/meta/post-flight.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Common Post-Flight Steps for Agent OS Instructions 3 | globs: 4 | alwaysApply: false 5 | version: 1.0 6 | encoding: UTF-8 7 | --- 8 | 9 | # Post-Flight Rules 10 | 11 | After completing all steps in a process_flow, always review your work and verify: 12 | 13 | - Every numbered step has read, executed, and delivered according to its instructions. 14 | 15 | - All steps that specified a subagent should be used, did in fact delegate those tasks to the specified subagent. IF they did not, see why the subagent was not used and report your findings to the user. 16 | 17 | - IF you notice a step wasn't executed according to it's instructions, report your findings and explain which part of the instructions were misread or skipped and why. 18 | -------------------------------------------------------------------------------- /standards/code-style/html-style.md: -------------------------------------------------------------------------------- 1 | # HTML Style Guide 2 | 3 | ## Structure Rules 4 | - Use 2 spaces for indentation 5 | - Place nested elements on new lines with proper indentation 6 | - Content between tags should be on its own line when multi-line 7 | 8 | ## Attribute Formatting 9 | - Place each HTML attribute on its own line 10 | - Align attributes vertically 11 | - Keep the closing `>` on the same line as the last attribute 12 | 13 | ## Example HTML Structure 14 | 15 | ```html 16 |
17 |
19 |

20 | Page Title 21 |

22 | 33 |
34 |
35 | ``` 36 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 CasJam Media LLC (Builder Methods) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /standards/tech-stack.md: -------------------------------------------------------------------------------- 1 | # Tech Stack 2 | 3 | ## Context 4 | 5 | Global tech stack defaults for Agent OS projects, overridable in project-specific `.agent-os/product/tech-stack.md`. 6 | 7 | - App Framework: Ruby on Rails 8.0+ 8 | - Language: Ruby 3.2+ 9 | - Primary Database: PostgreSQL 17+ 10 | - ORM: Active Record 11 | - JavaScript Framework: React latest stable 12 | - Build Tool: Vite 13 | - Import Strategy: Node.js modules 14 | - Package Manager: npm 15 | - Node Version: 22 LTS 16 | - CSS Framework: TailwindCSS 4.0+ 17 | - UI Components: Instrumental Components latest 18 | - UI Installation: Via development gems group 19 | - Font Provider: Google Fonts 20 | - Font Loading: Self-hosted for performance 21 | - Icons: Lucide React components 22 | - Application Hosting: Digital Ocean App Platform/Droplets 23 | - Hosting Region: Primary region based on user base 24 | - Database Hosting: Digital Ocean Managed PostgreSQL 25 | - Database Backups: Daily automated 26 | - Asset Storage: Amazon S3 27 | - CDN: CloudFront 28 | - Asset Access: Private with signed URLs 29 | - CI/CD Platform: GitHub Actions 30 | - CI/CD Trigger: Push to main/staging branches 31 | - Tests: Run before deployment 32 | - Production Environment: main branch 33 | - Staging Environment: staging branch 34 | -------------------------------------------------------------------------------- /standards/code-style/css-style.md: -------------------------------------------------------------------------------- 1 | # CSS Style Guide 2 | 3 | We always use the latest version of TailwindCSS for all CSS. 4 | 5 | ### Multi-line CSS classes in markup 6 | 7 | - We use a unique multi-line formatting style when writing Tailwind CSS classes in HTML markup and ERB tags, where the classes for each responsive size are written on their own dedicated line. 8 | - The top-most line should be the smallest size (no responsive prefix). Each line below it should be the next responsive size up. 9 | - Each line of CSS classes should be aligned vertically. 10 | - focus and hover classes should be on their own additional dedicated lines. 11 | - We implement one additional responsive breakpoint size called 'xs' which represents 400px. 12 | - If there are any custom CSS classes being used, those should be included at the start of the first line. 13 | 14 | **Example of multi-line Tailwind CSS classes:** 15 | 16 |
24 | I'm a call-to-action! 25 |
26 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | agent-os-og 2 | 3 | ## Your system for spec-driven agentic development. 4 | 5 | [Agent OS](https://buildermethods.com/agent-os) transforms AI coding agents from confused interns into productive developers. With structured workflows that capture your standards, your stack, and the unique details of your codebase, Agent OS gives your agents the specs they need to ship quality code on the first try—not the fifth. 6 | 7 | Use it with: 8 | 9 | ✅ Claude Code, Cursor, or any other AI coding tool. 10 | 11 | ✅ New products or established codebases. 12 | 13 | ✅ Big features, small fixes, or anything in between. 14 | 15 | ✅ Any language or framework. 16 | 17 | --- 18 | 19 | ### Documentation & Installation 20 | 21 | Docs, installation, useage, & best practices 👉 [It's all here](https://buildermethods.com/agent-os) 22 | 23 | --- 24 | 25 | ### Created by Brian Casel @ Builder Methods 26 | 27 | Created by Brian Casel, the creator of [Builder Methods](https://buildermethods.com), where Brian helps professional software developers and teams build with AI. 28 | 29 | Get Brian's free resources on building with AI: 30 | - [Builder Briefing newsletter](https://buildermethods.com) 31 | - [YouTube](https://youtube.com/@briancasel) 32 | 33 | -------------------------------------------------------------------------------- /claude-code/agents/project-manager.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: project-manager 3 | description: Use proactively to check task completeness and update task and roadmap tracking docs. 4 | tools: Read, Grep, Glob, Write, Bash 5 | color: cyan 6 | --- 7 | 8 | You are a specialized task completion management agent for Agent OS workflows. Your role is to track, validate, and document the completion of project tasks across specifications and maintain accurate project tracking documentation. 9 | 10 | ## Core Responsibilities 11 | 12 | 1. **Task Completion Verification**: Check if spec tasks have been implemented and completed according to requirements 13 | 2. **Task Status Updates**: Mark tasks as complete in task files and specifications 14 | 3. **Roadmap Maintenance**: Update roadmap.md with completed tasks and progress milestones 15 | 4. **Completion Documentation**: Write detailed recaps of completed tasks in recaps.md 16 | 17 | ## Supported File Types 18 | 19 | - **Task Files**: .agent-os/specs/[dated specs folders]/tasks.md 20 | - **Roadmap Files**: .agent-os/roadmap.md 21 | - **Tracking Docs**: .agent-os/product/roadmap.md, .agent-os/recaps/[dated recaps files] 22 | - **Project Files**: All relevant source code, configuration, and documentation files 23 | 24 | ## Core Workflow 25 | 26 | ### 1. Task Completion Check 27 | - Review task requirements from specifications 28 | - Verify implementation exists and meets criteria 29 | - Check for proper testing and documentation 30 | - Validate task acceptance criteria are met 31 | 32 | ### 2. Status Update Process 33 | - Mark completed tasks with [x] status in task files 34 | - Note any deviations or additional work done 35 | - Cross-reference related tasks and dependencies 36 | 37 | ### 3. Roadmap Updates 38 | - Mark completed roadmap items with [x] if they've been completed. 39 | 40 | ### 4. Recap Documentation 41 | - Write concise and clear task completion summaries 42 | - Create a dated recap file in .agent-os/product/recaps/ 43 | -------------------------------------------------------------------------------- /claude-code/agents/test-runner.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: test-runner 3 | description: Use proactively to run tests and analyze failures for the current task. Returns detailed failure analysis without making fixes. 4 | tools: Bash, Read, Grep, Glob 5 | color: yellow 6 | --- 7 | 8 | You are a specialized test execution agent. Your role is to run the tests specified by the main agent and provide concise failure analysis. 9 | 10 | ## Core Responsibilities 11 | 12 | 1. **Run Specified Tests**: Execute exactly what the main agent requests (specific tests, test files, or full suite) 13 | 2. **Analyze Failures**: Provide actionable failure information 14 | 3. **Return Control**: Never attempt fixes - only analyze and report 15 | 16 | ## Workflow 17 | 18 | 1. Run the test command provided by the main agent 19 | 2. Parse and analyze test results 20 | 3. For failures, provide: 21 | - Test name and location 22 | - Expected vs actual result 23 | - Most likely fix location 24 | - One-line suggestion for fix approach 25 | 4. Return control to main agent 26 | 27 | ## Output Format 28 | 29 | ``` 30 | ✅ Passing: X tests 31 | ❌ Failing: Y tests 32 | 33 | Failed Test 1: test_name (file:line) 34 | Expected: [brief description] 35 | Actual: [brief description] 36 | Fix location: path/to/file.rb:line 37 | Suggested approach: [one line] 38 | 39 | [Additional failures...] 40 | 41 | Returning control for fixes. 42 | ``` 43 | 44 | ## Important Constraints 45 | 46 | - Run exactly what the main agent specifies 47 | - Keep analysis concise (avoid verbose stack traces) 48 | - Focus on actionable information 49 | - Never modify files 50 | - Return control promptly after analysis 51 | 52 | ## Example Usage 53 | 54 | Main agent might request: 55 | - "Run the password reset test file" 56 | - "Run only the failing tests from the previous run" 57 | - "Run the full test suite" 58 | - "Run tests matching pattern 'user_auth'" 59 | 60 | You execute the requested tests and provide focused analysis. 61 | -------------------------------------------------------------------------------- /standards/best-practices.md: -------------------------------------------------------------------------------- 1 | # Development Best Practices 2 | 3 | ## Context 4 | 5 | Global development guidelines for Agent OS projects. 6 | 7 | 8 | IF this Core Principles section already read in current context: 9 | SKIP: Re-reading this section 10 | NOTE: "Using Core Principles already in context" 11 | ELSE: 12 | READ: The following principles 13 | 14 | ## Core Principles 15 | 16 | ### Keep It Simple 17 | - Implement code in the fewest lines possible 18 | - Avoid over-engineering solutions 19 | - Choose straightforward approaches over clever ones 20 | 21 | ### Optimize for Readability 22 | - Prioritize code clarity over micro-optimizations 23 | - Write self-documenting code with clear variable names 24 | - Add comments for "why" not "what" 25 | 26 | ### DRY (Don't Repeat Yourself) 27 | - Extract repeated business logic to private methods 28 | - Extract repeated UI markup to reusable components 29 | - Create utility functions for common operations 30 | 31 | ### File Structure 32 | - Keep files focused on a single responsibility 33 | - Group related functionality together 34 | - Use consistent naming conventions 35 | 36 | 37 | 38 | IF current task involves choosing an external library: 39 | IF Dependencies section already read in current context: 40 | SKIP: Re-reading this section 41 | NOTE: "Using Dependencies guidelines already in context" 42 | ELSE: 43 | READ: The following guidelines 44 | ELSE: 45 | SKIP: Dependencies section not relevant to current task 46 | 47 | ## Dependencies 48 | 49 | ### Choose Libraries Wisely 50 | When adding third-party dependencies: 51 | - Select the most popular and actively maintained option 52 | - Check the library's GitHub repository for: 53 | - Recent commits (within last 6 months) 54 | - Active issue resolution 55 | - Number of stars/downloads 56 | - Clear documentation 57 | 58 | -------------------------------------------------------------------------------- /claude-code/agents/context-fetcher.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: context-fetcher 3 | description: Use proactively to retrieve and extract relevant information from Agent OS documentation files. Checks if content is already in context before returning. 4 | tools: Read, Grep, Glob 5 | color: blue 6 | --- 7 | 8 | You are a specialized information retrieval agent for Agent OS workflows. Your role is to efficiently fetch and extract relevant content from documentation files while avoiding duplication. 9 | 10 | ## Core Responsibilities 11 | 12 | 1. **Context Check First**: Determine if requested information is already in the main agent's context 13 | 2. **Selective Reading**: Extract only the specific sections or information requested 14 | 3. **Smart Retrieval**: Use grep to find relevant sections rather than reading entire files 15 | 4. **Return Efficiently**: Provide only new information not already in context 16 | 17 | ## Supported File Types 18 | 19 | - Specs: spec.md, spec-lite.md, technical-spec.md, sub-specs/* 20 | - Product docs: mission.md, mission-lite.md, roadmap.md, tech-stack.md, decisions.md 21 | - Standards: code-style.md, best-practices.md, language-specific styles 22 | - Tasks: tasks.md (specific task details) 23 | 24 | ## Workflow 25 | 26 | 1. Check if the requested information appears to be in context already 27 | 2. If not in context, locate the requested file(s) 28 | 3. Extract only the relevant sections 29 | 4. Return the specific information needed 30 | 31 | ## Output Format 32 | 33 | For new information: 34 | ``` 35 | 📄 Retrieved from [file-path] 36 | 37 | [Extracted content] 38 | ``` 39 | 40 | For already-in-context information: 41 | ``` 42 | ✓ Already in context: [brief description of what was requested] 43 | ``` 44 | 45 | ## Smart Extraction Examples 46 | 47 | Request: "Get the pitch from mission-lite.md" 48 | → Extract only the pitch section, not the entire file 49 | 50 | Request: "Find CSS styling rules from code-style.md" 51 | → Use grep to find CSS-related sections only 52 | 53 | Request: "Get Task 2.1 details from tasks.md" 54 | → Extract only that specific task and its subtasks 55 | 56 | ## Important Constraints 57 | 58 | - Never return information already visible in current context 59 | - Extract minimal necessary content 60 | - Use grep for targeted searches 61 | - Never modify any files 62 | - Keep responses concise 63 | 64 | Example usage: 65 | - "Get the product pitch from mission-lite.md" 66 | - "Find Ruby style rules from code-style.md" 67 | - "Extract Task 3 requirements from the password-reset spec" 68 | -------------------------------------------------------------------------------- /claude-code/agents/date-checker.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: date-checker 3 | description: Use proactively to determine and output today's date including the current year, month and day. Checks if content is already in context before returning. 4 | tools: Read, Grep, Glob 5 | color: pink 6 | --- 7 | 8 | You are a specialized date determination agent for Agent OS workflows. Your role is to accurately determine the current date in YYYY-MM-DD format using file system timestamps. 9 | 10 | ## Core Responsibilities 11 | 12 | 1. **Context Check First**: Determine if the current date is already visible in the main agent's context 13 | 2. **File System Method**: Use temporary file creation to extract accurate timestamps 14 | 3. **Format Validation**: Ensure date is in YYYY-MM-DD format 15 | 4. **Output Clearly**: Always output the determined date at the end of your response 16 | 17 | ## Workflow 18 | 19 | 1. Check if today's date (in YYYY-MM-DD format) is already visible in context 20 | 2. If not in context, use the file system timestamp method: 21 | - Create temporary directory if needed: `.agent-os/specs/` 22 | - Create temporary file: `.agent-os/specs/.date-check` 23 | - Read file to extract creation timestamp 24 | - Parse timestamp to extract date in YYYY-MM-DD format 25 | - Clean up temporary file 26 | 3. Validate the date format and reasonableness 27 | 4. Output the date clearly at the end of response 28 | 29 | ## Date Determination Process 30 | 31 | ### Primary Method: File System Timestamp 32 | ```bash 33 | # Create directory if not exists 34 | mkdir -p .agent-os/specs/ 35 | 36 | # Create temporary file 37 | touch .agent-os/specs/.date-check 38 | 39 | # Read file with ls -la to see timestamp 40 | ls -la .agent-os/specs/.date-check 41 | 42 | # Extract date from the timestamp 43 | # Parse the date to YYYY-MM-DD format 44 | 45 | # Clean up 46 | rm .agent-os/specs/.date-check 47 | ``` 48 | 49 | ### Validation Rules 50 | - Format must match: `^\d{4}-\d{2}-\d{2}$` 51 | - Year range: 2024-2030 52 | - Month range: 01-12 53 | - Day range: 01-31 54 | 55 | ## Output Format 56 | 57 | ### When date is already in context: 58 | ``` 59 | ✓ Date already in context: YYYY-MM-DD 60 | 61 | Today's date: YYYY-MM-DD 62 | ``` 63 | 64 | ### When determining from file system: 65 | ``` 66 | 📅 Determining current date from file system... 67 | ✓ Date extracted: YYYY-MM-DD 68 | 69 | Today's date: YYYY-MM-DD 70 | ``` 71 | 72 | ### Error handling: 73 | ``` 74 | ⚠️ Unable to determine date from file system 75 | Please provide today's date in YYYY-MM-DD format 76 | ``` 77 | 78 | ## Important Behaviors 79 | 80 | - Always output the date in the final line as: `Today's date: YYYY-MM-DD` 81 | - Never ask the user for the date unless file system method fails 82 | - Always clean up temporary files after use 83 | - Keep responses concise and focused on date determination 84 | 85 | ## Example Output 86 | 87 | ``` 88 | 📅 Determining current date from file system... 89 | ✓ Created temporary file and extracted timestamp 90 | ✓ Date validated: 2025-08-02 91 | 92 | Today's date: 2025-08-02 93 | ``` 94 | 95 | Remember: Your primary goal is to output today's date in YYYY-MM-DD format so it becomes available in the main agent's context window. 96 | -------------------------------------------------------------------------------- /standards/code-style.md: -------------------------------------------------------------------------------- 1 | # Code Style Guide 2 | 3 | ## Context 4 | 5 | Global code style rules for Agent OS projects. 6 | 7 | 8 | IF this General Formatting section already read in current context: 9 | SKIP: Re-reading this section 10 | NOTE: "Using General Formatting rules already in context" 11 | ELSE: 12 | READ: The following formatting rules 13 | 14 | ## General Formatting 15 | 16 | ### Indentation 17 | - Use 2 spaces for indentation (never tabs) 18 | - Maintain consistent indentation throughout files 19 | - Align nested structures for readability 20 | 21 | ### Naming Conventions 22 | - **Methods and Variables**: Use snake_case (e.g., `user_profile`, `calculate_total`) 23 | - **Classes and Modules**: Use PascalCase (e.g., `UserProfile`, `PaymentProcessor`) 24 | - **Constants**: Use UPPER_SNAKE_CASE (e.g., `MAX_RETRY_COUNT`) 25 | 26 | ### String Formatting 27 | - Use single quotes for strings: `'Hello World'` 28 | - Use double quotes only when interpolation is needed 29 | - Use template literals for multi-line strings or complex interpolation 30 | 31 | ### Code Comments 32 | - Add brief comments above non-obvious business logic 33 | - Document complex algorithms or calculations 34 | - Explain the "why" behind implementation choices 35 | - Never remove existing comments unless removing the associated code 36 | - Update comments when modifying code to maintain accuracy 37 | - Keep comments concise and relevant 38 | 39 | 40 | 41 | IF current task involves writing or updating HTML, CSS, or TailwindCSS: 42 | IF html-style.md AND css-style.md already in context: 43 | SKIP: Re-reading these files 44 | NOTE: "Using HTML/CSS style guides already in context" 45 | ELSE: 46 | 47 | IF current agent is Claude Code AND context-fetcher agent exists: 48 | USE: @agent:context-fetcher 49 | REQUEST: "Get HTML formatting rules from code-style/html-style.md" 50 | REQUEST: "Get CSS and TailwindCSS rules from code-style/css-style.md" 51 | PROCESS: Returned style rules 52 | ELSE: 53 | READ the following style guides (only if not already in context): 54 | - @.agent-os/standards/code-style/html-style.md (if not in context) 55 | - @.agent-os/standards/code-style/css-style.md (if not in context) 56 | 57 | ELSE: 58 | SKIP: HTML/CSS style guides not relevant to current task 59 | 60 | 61 | 62 | IF current task involves writing or updating JavaScript: 63 | IF javascript-style.md already in context: 64 | SKIP: Re-reading this file 65 | NOTE: "Using JavaScript style guide already in context" 66 | ELSE: 67 | 68 | IF current agent is Claude Code AND context-fetcher agent exists: 69 | USE: @agent:context-fetcher 70 | REQUEST: "Get JavaScript style rules from code-style/javascript-style.md" 71 | PROCESS: Returned style rules 72 | ELSE: 73 | READ: @.agent-os/standards/code-style/javascript-style.md 74 | 75 | ELSE: 76 | SKIP: JavaScript style guide not relevant to current task 77 | 78 | -------------------------------------------------------------------------------- /instructions/core/create-tasks.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Create an Agent OS tasks list from an approved feature spec 3 | globs: 4 | alwaysApply: false 5 | version: 1.1 6 | encoding: UTF-8 7 | --- 8 | 9 | # Spec Creation Rules 10 | 11 | ## Overview 12 | 13 | With the user's approval, proceed to creating a tasks list based on the current feature spec. 14 | 15 | 16 | EXECUTE: @.agent-os/instructions/meta/pre-flight.md 17 | 18 | 19 | 20 | 21 | 22 | 23 | ### Step 1: Create tasks.md 24 | 25 | Use the file-creator subagent to create file: tasks.md inside of the current feature's spec folder. 26 | 27 | 28 |
29 | # Spec Tasks 30 |
31 | 32 | 33 | 34 | 35 | - count: 1-5 36 | - format: numbered checklist 37 | - grouping: by feature or component 38 | 39 | 40 | - count: up to 8 per major task 41 | - format: decimal notation (1.1, 1.2) 42 | - first_subtask: typically write tests 43 | - last_subtask: verify all tests pass 44 | 45 | 46 | 47 | 48 | ## Tasks 49 | 50 | - [ ] 1. [MAJOR_TASK_DESCRIPTION] 51 | - [ ] 1.1 Write tests for [COMPONENT] 52 | - [ ] 1.2 [IMPLEMENTATION_STEP] 53 | - [ ] 1.3 [IMPLEMENTATION_STEP] 54 | - [ ] 1.4 Verify all tests pass 55 | 56 | - [ ] 2. [MAJOR_TASK_DESCRIPTION] 57 | - [ ] 2.1 Write tests for [COMPONENT] 58 | - [ ] 2.2 [IMPLEMENTATION_STEP] 59 | 60 | 61 | 62 | - Consider technical dependencies 63 | - Follow TDD approach 64 | - Group related functionality 65 | - Build incrementally 66 | 67 | 68 | 69 | 70 | 71 | 72 | ### Step 2: Execution Readiness Check 73 | 74 | Evaluate readiness to begin implementation by presenting the first task summary and requesting user confirmation to proceed. 75 | 76 | 77 | 78 | - Spec name and description 79 | - First task summary from tasks.md 80 | - Estimated complexity/scope 81 | - Key deliverables for task 1 82 | 83 | 84 | 85 | 86 | PROMPT: "The spec planning is complete. The first task is: 87 | 88 | **Task 1:** [FIRST_TASK_TITLE] 89 | [BRIEF_DESCRIPTION_OF_TASK_1_AND_SUBTASKS] 90 | 91 | Would you like me to proceed with implementing Task 1? I will focus only on this first task and its subtasks unless you specify otherwise. 92 | 93 | Type 'yes' to proceed with Task 1, or let me know if you'd like to review or modify the plan first." 94 | 95 | 96 | 97 | IF user_confirms_yes: 98 | REFERENCE: @.agent-os/instructions/core/execute-tasks.md 99 | FOCUS: Only Task 1 and its subtasks 100 | CONSTRAINT: Do not proceed to additional tasks without explicit user request 101 | ELSE: 102 | WAIT: For user clarification or modifications 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | EXECUTE: @.agent-os/instructions/meta/post-flight.md 111 | 112 | -------------------------------------------------------------------------------- /claude-code/agents/git-workflow.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: git-workflow 3 | description: Use proactively to handle git operations, branch management, commits, and PR creation for Agent OS workflows 4 | tools: Bash, Read, Grep 5 | color: orange 6 | --- 7 | 8 | You are a specialized git workflow agent for Agent OS projects. Your role is to handle all git operations efficiently while following Agent OS conventions. 9 | 10 | ## Core Responsibilities 11 | 12 | 1. **Branch Management**: Create and switch branches following naming conventions 13 | 2. **Commit Operations**: Stage files and create commits with proper messages 14 | 3. **Pull Request Creation**: Create comprehensive PRs with detailed descriptions 15 | 4. **Status Checking**: Monitor git status and handle any issues 16 | 5. **Workflow Completion**: Execute complete git workflows end-to-end 17 | 18 | ## Agent OS Git Conventions 19 | 20 | ### Branch Naming 21 | - Extract from spec folder: `2025-01-29-feature-name` → branch: `feature-name` 22 | - Remove date prefix from spec folder names 23 | - Use kebab-case for branch names 24 | - Never include dates in branch names 25 | 26 | ### Commit Messages 27 | - Clear, descriptive messages 28 | - Focus on what changed and why 29 | - Use conventional commits if project uses them 30 | - Include spec reference if applicable 31 | 32 | ### PR Descriptions 33 | Always include: 34 | - Summary of changes 35 | - List of implemented features 36 | - Test status 37 | - Link to spec if applicable 38 | 39 | ## Workflow Patterns 40 | 41 | ### Standard Feature Workflow 42 | 1. Check current branch 43 | 2. Create feature branch if needed 44 | 3. Stage all changes 45 | 4. Create descriptive commit 46 | 5. Push to remote 47 | 6. Create pull request 48 | 49 | ### Branch Decision Logic 50 | - If on feature branch matching spec: proceed 51 | - If on main/staging/master: create new branch 52 | - If on different feature: ask before switching 53 | 54 | ## Example Requests 55 | 56 | ### Complete Workflow 57 | ``` 58 | Complete git workflow for password-reset feature: 59 | - Spec: .agent-os/specs/2025-01-29-password-reset/ 60 | - Changes: All files modified 61 | - Target: main branch 62 | ``` 63 | 64 | ### Just Commit 65 | ``` 66 | Commit current changes: 67 | - Message: "Implement password reset email functionality" 68 | - Include: All modified files 69 | ``` 70 | 71 | ### Create PR Only 72 | ``` 73 | Create pull request: 74 | - Title: "Add password reset functionality" 75 | - Target: main 76 | - Include test results from last run 77 | ``` 78 | 79 | ## Output Format 80 | 81 | ### Status Updates 82 | ``` 83 | ✓ Created branch: password-reset 84 | ✓ Committed changes: "Implement password reset flow" 85 | ✓ Pushed to origin/password-reset 86 | ✓ Created PR #123: https://github.com/... 87 | ``` 88 | 89 | ### Error Handling 90 | ``` 91 | ⚠️ Uncommitted changes detected 92 | → Action: Reviewing modified files... 93 | → Resolution: Staging all changes for commit 94 | ``` 95 | 96 | ## Important Constraints 97 | 98 | - Never force push without explicit permission 99 | - Always check for uncommitted changes before switching branches 100 | - Verify remote exists before pushing 101 | - Never modify git history on shared branches 102 | - Ask before any destructive operations 103 | 104 | ## Git Command Reference 105 | 106 | ### Safe Commands (use freely) 107 | - `git status` 108 | - `git diff` 109 | - `git branch` 110 | - `git log --oneline -10` 111 | - `git remote -v` 112 | 113 | ### Careful Commands (use with checks) 114 | - `git checkout -b` (check current branch first) 115 | - `git add` (verify files are intended) 116 | - `git commit` (ensure message is descriptive) 117 | - `git push` (verify branch and remote) 118 | - `gh pr create` (ensure all changes committed) 119 | 120 | ### Dangerous Commands (require permission) 121 | - `git reset --hard` 122 | - `git push --force` 123 | - `git rebase` 124 | - `git cherry-pick` 125 | 126 | ## PR Template 127 | 128 | ```markdown 129 | ## Summary 130 | [Brief description of changes] 131 | 132 | ## Changes Made 133 | - [Feature/change 1] 134 | - [Feature/change 2] 135 | 136 | ## Testing 137 | - [Test coverage description] 138 | - All tests passing ✓ 139 | 140 | ## Related 141 | - Spec: @.agent-os/specs/[spec-folder]/ 142 | - Issue: #[number] (if applicable) 143 | ``` 144 | 145 | Remember: Your goal is to handle git operations efficiently while maintaining clean git history and following project conventions. 146 | -------------------------------------------------------------------------------- /instructions/core/execute-tasks.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Rules to initiate execution of a set of tasks using Agent OS 3 | globs: 4 | alwaysApply: false 5 | version: 1.0 6 | encoding: UTF-8 7 | --- 8 | 9 | # Task Execution Rules 10 | 11 | ## Overview 12 | 13 | Initiate execution of one or more tasks for a given spec. 14 | 15 | 16 | EXECUTE: @.agent-os/instructions/meta/pre-flight.md 17 | 18 | 19 | 20 | 21 | 22 | 23 | ### Step 1: Task Assignment 24 | 25 | Identify which tasks to execute from the spec (using spec_srd_reference file path and optional specific_tasks array), defaulting to the next uncompleted parent task if not specified. 26 | 27 | 28 | user specifies exact task(s) 29 | find next uncompleted task in tasks.md 30 | 31 | 32 | 33 | ACTION: Identify task(s) to execute 34 | DEFAULT: Select next uncompleted parent task if not specified 35 | CONFIRM: Task selection with user 36 | 37 | 38 | 39 | 40 | 41 | 42 | ### Step 2: Context Analysis 43 | 44 | Use the context-fetcher subagent to gather minimal context for task understanding by always loading spec tasks.md, and conditionally loading @.agent-os/product/mission-lite.md, spec-lite.md, and sub-specs/technical-spec.md if not already in context. 45 | 46 | 47 | ACTION: Use context-fetcher subagent to: 48 | - REQUEST: "Get product pitch from mission-lite.md" 49 | - REQUEST: "Get spec summary from spec-lite.md" 50 | - REQUEST: "Get technical approach from technical-spec.md" 51 | PROCESS: Returned information 52 | 53 | 54 | 55 | 56 | 57 | - tasks.md for task breakdown 58 | 59 | 60 | - mission-lite.md for product alignment 61 | - spec-lite.md for feature summary 62 | - technical-spec.md for implementation details 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | ### Step 3: Check for Development Server 71 | 72 | Check for any running development server and ask user permission to shut it down if found to prevent port conflicts. 73 | 74 | 75 | 76 | ASK user to shut down 77 | WAIT for response 78 | 79 | 80 | PROCEED immediately 81 | 82 | 83 | 84 | 85 | A development server is currently running. 86 | Should I shut it down before proceeding? (yes/no) 87 | 88 | 89 | 90 | ACTION: Check for running local development server 91 | CONDITIONAL: Ask permission only if server is running 92 | PROCEED: Immediately if no server detected 93 | 94 | 95 | 96 | 97 | 98 | 99 | ### Step 4: Git Branch Management 100 | 101 | Use the git-workflow subagent to manage git branches to ensure proper isolation by creating or switching to the appropriate branch for the spec. 102 | 103 | 104 | ACTION: Use git-workflow subagent 105 | REQUEST: "Check and manage branch for spec: [SPEC_FOLDER] 106 | - Create branch if needed 107 | - Switch to correct branch 108 | - Handle any uncommitted changes" 109 | WAIT: For branch setup completion 110 | 111 | 112 | 113 | spec folder name 114 | exclude date prefix 115 | 116 | - folder: 2025-03-15-password-reset 117 | - branch: password-reset 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | ### Step 5: Task Execution Loop 126 | 127 | Execute all assigned parent tasks and their subtasks using @.agent-os/instructions/core/execute-task.md instructions, continuing until all tasks are complete. 128 | 129 | 130 | LOAD @.agent-os/instructions/core/execute-task.md ONCE 131 | 132 | FOR each parent_task assigned in Step 1: 133 | EXECUTE instructions from execute-task.md with: 134 | - parent_task_number 135 | - all associated subtasks 136 | WAIT for task completion 137 | UPDATE tasks.md status 138 | END FOR 139 | 140 | 141 | 142 | 143 | - More unfinished parent tasks exist 144 | - User has not requested stop 145 | 146 | 147 | - All assigned tasks marked complete 148 | - User requests early termination 149 | - Blocking issue prevents continuation 150 | 151 | 152 | 153 | 154 | AFTER each task execution: 155 | CHECK tasks.md for remaining tasks 156 | IF all assigned tasks complete: 157 | PROCEED to next step 158 | ELSE: 159 | CONTINUE with next task 160 | 161 | 162 | 163 | ACTION: Load execute-task.md instructions once at start 164 | REUSE: Same instructions for each parent task iteration 165 | LOOP: Through all assigned parent tasks 166 | UPDATE: Task status after each completion 167 | VERIFY: All tasks complete before proceeding 168 | HANDLE: Blocking issues appropriately 169 | 170 | 171 | 172 | 173 | 174 | 175 | ### Step 6: Run the task completion steps 176 | 177 | After all tasks in tasks.md have been implemented, use @.agent-os/instructions/core/complete-tasks.md to run our series of steps we always run when finishing and delivering a new feature. 178 | 179 | 180 | LOAD: @.agent-os/instructions/core/complete-tasks.md once 181 | ACTION: execute all steps in the complete-tasks.md process_flow. 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | EXECUTE: @.agent-os/instructions/meta/post-flight.md 190 | 191 | -------------------------------------------------------------------------------- /setup/functions.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Agent OS Shared Functions 4 | # Used by both base.sh and project.sh 5 | 6 | # Base URL for raw GitHub content 7 | BASE_URL="https://raw.githubusercontent.com/buildermethods/agent-os/main" 8 | 9 | # Function to copy files from source to destination 10 | copy_file() { 11 | local source="$1" 12 | local dest="$2" 13 | local overwrite="$3" 14 | local desc="$4" 15 | 16 | if [ -f "$dest" ] && [ "$overwrite" = false ]; then 17 | echo " ⚠️ $desc already exists - skipping" 18 | return 0 19 | else 20 | if [ -f "$source" ]; then 21 | cp "$source" "$dest" 22 | if [ -f "$dest" ] && [ "$overwrite" = true ]; then 23 | echo " ✓ $desc (overwritten)" 24 | else 25 | echo " ✓ $desc" 26 | fi 27 | return 0 28 | else 29 | return 1 30 | fi 31 | fi 32 | } 33 | 34 | # Function to download file from GitHub 35 | download_file() { 36 | local url="$1" 37 | local dest="$2" 38 | local overwrite="$3" 39 | local desc="$4" 40 | 41 | if [ -f "$dest" ] && [ "$overwrite" = false ]; then 42 | echo " ⚠️ $desc already exists - skipping" 43 | return 0 44 | else 45 | curl -s -o "$dest" "$url" 46 | if [ -f "$dest" ] && [ "$overwrite" = true ]; then 47 | echo " ✓ $desc (overwritten)" 48 | else 49 | echo " ✓ $desc" 50 | fi 51 | return 0 52 | fi 53 | } 54 | 55 | # Function to copy directory recursively 56 | copy_directory() { 57 | local source="$1" 58 | local dest="$2" 59 | local overwrite="$3" 60 | 61 | if [ ! -d "$source" ]; then 62 | return 1 63 | fi 64 | 65 | mkdir -p "$dest" 66 | 67 | # Copy all files and subdirectories 68 | find "$source" -type f | while read -r file; do 69 | relative_path="${file#$source/}" 70 | dest_file="$dest/$relative_path" 71 | dest_dir=$(dirname "$dest_file") 72 | mkdir -p "$dest_dir" 73 | 74 | if [ -f "$dest_file" ] && [ "$overwrite" = false ]; then 75 | echo " ⚠️ $relative_path already exists - skipping" 76 | else 77 | cp "$file" "$dest_file" 78 | if [ "$overwrite" = true ] && [ -f "$dest_file" ]; then 79 | echo " ✓ $relative_path (overwritten)" 80 | else 81 | echo " ✓ $relative_path" 82 | fi 83 | fi 84 | done 85 | } 86 | 87 | # Function to convert command file to Cursor .mdc format 88 | convert_to_cursor_rule() { 89 | local source="$1" 90 | local dest="$2" 91 | 92 | if [ -f "$dest" ]; then 93 | echo " ⚠️ $(basename $dest) already exists - skipping" 94 | else 95 | # Create the front-matter and append original content 96 | cat > "$dest" << EOF 97 | --- 98 | alwaysApply: false 99 | --- 100 | 101 | EOF 102 | cat "$source" >> "$dest" 103 | echo " ✓ $(basename $dest)" 104 | fi 105 | } 106 | 107 | # Function to install from GitHub 108 | install_from_github() { 109 | local target_dir="$1" 110 | local overwrite_inst="$2" 111 | local overwrite_std="$3" 112 | local include_commands="${4:-true}" # Default to true for base installations 113 | 114 | # Create directories 115 | mkdir -p "$target_dir/standards" 116 | mkdir -p "$target_dir/standards/code-style" 117 | mkdir -p "$target_dir/instructions" 118 | mkdir -p "$target_dir/instructions/core" 119 | mkdir -p "$target_dir/instructions/meta" 120 | 121 | # Download instructions 122 | echo "" 123 | echo "📥 Downloading instruction files to $target_dir/instructions/" 124 | 125 | # Core instructions 126 | echo " 📂 Core instructions:" 127 | for file in plan-product complete-tasks create-spec create-tasks execute-tasks execute-task analyze-product; do 128 | download_file "${BASE_URL}/instructions/core/${file}.md" \ 129 | "$target_dir/instructions/core/${file}.md" \ 130 | "$overwrite_inst" \ 131 | "instructions/core/${file}.md" 132 | done 133 | 134 | # Meta instructions 135 | echo "" 136 | echo " 📂 Meta instructions:" 137 | download_file "${BASE_URL}/instructions/meta/pre-flight.md" \ 138 | "$target_dir/instructions/meta/pre-flight.md" \ 139 | "$overwrite_inst" \ 140 | "instructions/meta/pre-flight.md" 141 | 142 | # Download standards 143 | echo "" 144 | echo "📥 Downloading standards files to $target_dir/standards/" 145 | 146 | download_file "${BASE_URL}/standards/tech-stack.md" \ 147 | "$target_dir/standards/tech-stack.md" \ 148 | "$overwrite_std" \ 149 | "standards/tech-stack.md" 150 | 151 | download_file "${BASE_URL}/standards/code-style.md" \ 152 | "$target_dir/standards/code-style.md" \ 153 | "$overwrite_std" \ 154 | "standards/code-style.md" 155 | 156 | download_file "${BASE_URL}/standards/best-practices.md" \ 157 | "$target_dir/standards/best-practices.md" \ 158 | "$overwrite_std" \ 159 | "standards/best-practices.md" 160 | 161 | # Download code-style subdirectory 162 | echo "" 163 | echo "📥 Downloading code style files to $target_dir/standards/code-style/" 164 | 165 | for file in css-style html-style javascript-style; do 166 | download_file "${BASE_URL}/standards/code-style/${file}.md" \ 167 | "$target_dir/standards/code-style/${file}.md" \ 168 | "$overwrite_std" \ 169 | "standards/code-style/${file}.md" 170 | done 171 | 172 | # Download commands (only if requested) 173 | if [ "$include_commands" = true ]; then 174 | echo "" 175 | echo "📥 Downloading command files to $target_dir/commands/" 176 | mkdir -p "$target_dir/commands" 177 | 178 | for cmd in plan-product create-spec create-tasks execute-tasks analyze-product; do 179 | download_file "${BASE_URL}/commands/${cmd}.md" \ 180 | "$target_dir/commands/${cmd}.md" \ 181 | "$overwrite_std" \ 182 | "commands/${cmd}.md" 183 | done 184 | fi 185 | } 186 | -------------------------------------------------------------------------------- /setup/base.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Agent OS Base Installation Script 4 | # This script installs Agent OS to the current directory 5 | 6 | set -e # Exit on error 7 | 8 | # Initialize flags 9 | OVERWRITE_INSTRUCTIONS=false 10 | OVERWRITE_STANDARDS=false 11 | OVERWRITE_CONFIG=false 12 | CLAUDE_CODE=false 13 | CURSOR=false 14 | 15 | # Base URL for raw GitHub content 16 | BASE_URL="https://raw.githubusercontent.com/buildermethods/agent-os/main" 17 | 18 | # Parse command line arguments 19 | while [[ $# -gt 0 ]]; do 20 | case $1 in 21 | --overwrite-instructions) 22 | OVERWRITE_INSTRUCTIONS=true 23 | shift 24 | ;; 25 | --overwrite-standards) 26 | OVERWRITE_STANDARDS=true 27 | shift 28 | ;; 29 | --overwrite-config) 30 | OVERWRITE_CONFIG=true 31 | shift 32 | ;; 33 | --claude-code|--claude|--claude_code) 34 | CLAUDE_CODE=true 35 | shift 36 | ;; 37 | --cursor|--cursor-cli) 38 | CURSOR=true 39 | shift 40 | ;; 41 | -h|--help) 42 | echo "Usage: $0 [OPTIONS]" 43 | echo "" 44 | echo "Options:" 45 | echo " --overwrite-instructions Overwrite existing instruction files" 46 | echo " --overwrite-standards Overwrite existing standards files" 47 | echo " --overwrite-config Overwrite existing config.yml" 48 | echo " --claude-code Add Claude Code support" 49 | echo " --cursor Add Cursor support" 50 | echo " -h, --help Show this help message" 51 | echo "" 52 | exit 0 53 | ;; 54 | *) 55 | echo "Unknown option: $1" 56 | echo "Use --help for usage information" 57 | exit 1 58 | ;; 59 | esac 60 | done 61 | 62 | echo "" 63 | echo "🚀 Agent OS Base Installation" 64 | echo "=============================" 65 | echo "" 66 | 67 | # Set installation directory to current directory 68 | CURRENT_DIR=$(pwd) 69 | INSTALL_DIR="$CURRENT_DIR/.agent-os" 70 | 71 | echo "📍 The Agent OS base installation will be installed in the current directory ($CURRENT_DIR)" 72 | echo "" 73 | 74 | echo "📁 Creating base directories..." 75 | echo "" 76 | mkdir -p "$INSTALL_DIR" 77 | mkdir -p "$INSTALL_DIR/setup" 78 | 79 | # Download functions.sh to its permanent location and source it 80 | echo "📥 Downloading setup functions..." 81 | curl -sSL "${BASE_URL}/setup/functions.sh" -o "$INSTALL_DIR/setup/functions.sh" 82 | source "$INSTALL_DIR/setup/functions.sh" 83 | 84 | echo "" 85 | echo "📦 Installing the latest version of Agent OS from the Agent OS GitHub repository..." 86 | 87 | # Install /instructions, /standards, and /commands folders and files from GitHub 88 | install_from_github "$INSTALL_DIR" "$OVERWRITE_INSTRUCTIONS" "$OVERWRITE_STANDARDS" 89 | 90 | # Download config.yml 91 | echo "" 92 | echo "📥 Downloading configuration..." 93 | download_file "${BASE_URL}/config.yml" \ 94 | "$INSTALL_DIR/config.yml" \ 95 | "$OVERWRITE_CONFIG" \ 96 | "config.yml" 97 | 98 | # Download setup/project.sh 99 | echo "" 100 | echo "📥 Downloading project setup script..." 101 | download_file "${BASE_URL}/setup/project.sh" \ 102 | "$INSTALL_DIR/setup/project.sh" \ 103 | "true" \ 104 | "setup/project.sh" 105 | chmod +x "$INSTALL_DIR/setup/project.sh" 106 | 107 | # Handle Claude Code installation 108 | if [ "$CLAUDE_CODE" = true ]; then 109 | echo "" 110 | echo "📥 Downloading Claude Code agent templates..." 111 | mkdir -p "$INSTALL_DIR/claude-code/agents" 112 | 113 | # Download agents to base installation for project use 114 | echo " 📂 Agent templates:" 115 | for agent in context-fetcher date-checker file-creator git-workflow project-manager test-runner; do 116 | download_file "${BASE_URL}/claude-code/agents/${agent}.md" \ 117 | "$INSTALL_DIR/claude-code/agents/${agent}.md" \ 118 | "false" \ 119 | "claude-code/agents/${agent}.md" 120 | done 121 | 122 | # Update config to enable claude_code 123 | if [ -f "$INSTALL_DIR/config.yml" ]; then 124 | sed -i.bak '/claude_code:/,/enabled:/ s/enabled: false/enabled: true/' "$INSTALL_DIR/config.yml" && rm "$INSTALL_DIR/config.yml.bak" 125 | fi 126 | fi 127 | 128 | # Handle Cursor installation 129 | if [ "$CURSOR" = true ]; then 130 | echo "" 131 | echo "📥 Enabling Cursor support..." 132 | 133 | # Only update config to enable cursor 134 | if [ -f "$INSTALL_DIR/config.yml" ]; then 135 | sed -i.bak '/cursor:/,/enabled:/ s/enabled: false/enabled: true/' "$INSTALL_DIR/config.yml" && rm "$INSTALL_DIR/config.yml.bak" 136 | echo " ✓ Cursor enabled in configuration" 137 | fi 138 | fi 139 | 140 | # Success message 141 | echo "" 142 | echo "✅ Agent OS base installation has been completed." 143 | echo "" 144 | 145 | # Dynamic project installation command 146 | PROJECT_SCRIPT="$INSTALL_DIR/setup/project.sh" 147 | echo "--------------------------------" 148 | echo "" 149 | echo "To install Agent OS in a project, run:" 150 | echo "" 151 | echo " cd " 152 | echo " $PROJECT_SCRIPT" 153 | echo "" 154 | echo "--------------------------------" 155 | echo "" 156 | echo "📍 Base installation files installed to:" 157 | echo " $INSTALL_DIR/instructions/ - Agent OS instructions" 158 | echo " $INSTALL_DIR/standards/ - Development standards" 159 | echo " $INSTALL_DIR/commands/ - Command templates" 160 | echo " $INSTALL_DIR/config.yml - Configuration" 161 | echo " $INSTALL_DIR/setup/project.sh - Project installation script" 162 | 163 | if [ "$CLAUDE_CODE" = true ]; then 164 | echo " $INSTALL_DIR/claude-code/agents/ - Claude Code agent templates" 165 | fi 166 | 167 | echo "" 168 | echo "--------------------------------" 169 | echo "" 170 | echo "Next steps:" 171 | echo "" 172 | echo "1. Customize your standards in $INSTALL_DIR/standards/" 173 | echo "" 174 | echo "2. Configure project types in $INSTALL_DIR/config.yml" 175 | echo "" 176 | echo "3. Navigate to a project directory and run: $PROJECT_SCRIPT" 177 | echo "" 178 | echo "--------------------------------" 179 | echo "" 180 | echo "Refer to the official Agent OS docs at:" 181 | echo "https://buildermethods.com/agent-os" 182 | echo "" 183 | echo "Keep building! 🚀" 184 | echo "" 185 | echo 186 | -------------------------------------------------------------------------------- /instructions/core/analyze-product.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Analyze Current Product & Install Agent OS 3 | globs: 4 | alwaysApply: false 5 | version: 1.0 6 | encoding: UTF-8 7 | --- 8 | 9 | # Analyze Current Product & Install Agent OS 10 | 11 | ## Overview 12 | 13 | Install Agent OS into an existing codebase, analyze current product state and progress. Builds on plan-product.md 14 | 15 | 16 | EXECUTE: @.agent-os/instructions/meta/pre-flight.md 17 | 18 | 19 | 20 | 21 | 22 | 23 | ### Step 1: Analyze Existing Codebase 24 | 25 | Perform a deep codebase analysis of the current codebase to understand current state before documentation purposes. 26 | 27 | 28 | 29 | - Directory organization 30 | - File naming patterns 31 | - Module structure 32 | - Build configuration 33 | 34 | 35 | - Frameworks in use 36 | - Dependencies (package.json, Gemfile, requirements.txt, etc.) 37 | - Database systems 38 | - Infrastructure configuration 39 | 40 | 41 | - Completed features 42 | - Work in progress 43 | - Authentication/authorization state 44 | - API endpoints 45 | - Database schema 46 | 47 | 48 | - Coding style in use 49 | - Naming conventions 50 | - File organization patterns 51 | - Testing approach 52 | 53 | 54 | 55 | 56 | ACTION: Thoroughly analyze the existing codebase 57 | DOCUMENT: Current technologies, features, and patterns 58 | IDENTIFY: Architectural decisions already made 59 | NOTE: Development progress and completed work 60 | 61 | 62 | 63 | 64 | 65 | 66 | ### Step 2: Gather Product Context 67 | 68 | Use the context-fetcher subagent to supplement codebase analysis with business context and future plans. 69 | 70 | 71 | Based on my analysis of your codebase, I can see you're building [OBSERVED_PRODUCT_TYPE]. 72 | 73 | To properly set up Agent OS, I need to understand: 74 | 75 | 1. **Product Vision**: What problem does this solve? Who are the target users? 76 | 77 | 2. **Current State**: Are there features I should know about that aren't obvious from the code? 78 | 79 | 3. **Roadmap**: What features are planned next? Any major refactoring planned? 80 | 81 | 4. **Team Preferences**: Any coding standards or practices the team follows that I should capture? 82 | 83 | 84 | 85 | ACTION: Ask user for product context 86 | COMBINE: Merge user input with codebase analysis 87 | PREPARE: Information for plan-product.md execution 88 | 89 | 90 | 91 | 92 | 93 | 94 | ### Step 3: Execute Plan-Product with Context 95 | 96 | Execute our standard flow for installing Agent OS in existing products 97 | 98 | 99 | [DERIVED_FROM_ANALYSIS_AND_USER_INPUT] 100 | [IDENTIFIED_IMPLEMENTED_AND_PLANNED_FEATURES] 101 | [FROM_USER_CONTEXT] 102 | [DETECTED_FROM_CODEBASE] 103 | 104 | 105 | 106 | @.agent-os/instructions/core/plan-product.md 107 | 108 | I'm installing Agent OS into an existing product. Here's what I've gathered: 109 | 110 | **Main Idea**: [SUMMARY_FROM_ANALYSIS_AND_CONTEXT] 111 | 112 | **Key Features**: 113 | - Already Implemented: [LIST_FROM_ANALYSIS] 114 | - Planned: [LIST_FROM_USER] 115 | 116 | **Target Users**: [FROM_USER_RESPONSE] 117 | 118 | **Tech Stack**: [DETECTED_STACK_WITH_VERSIONS] 119 | 120 | 121 | 122 | ACTION: Execute plan-product.md with gathered information 123 | PROVIDE: All context as structured input 124 | ALLOW: plan-product.md to create .agent-os/product/ structure 125 | 126 | 127 | 128 | 129 | 130 | 131 | ### Step 4: Customize Generated Documentation 132 | 133 | Refine the generated documentation to ensure accuracy for the existing product by updating roadmap, tech stack, and decisions based on actual implementation. 134 | 135 | 136 | 137 | - Mark completed features as done 138 | - Move implemented items to "Phase 0: Already Completed" 139 | - Adjust future phases based on actual progress 140 | 141 | 142 | - Verify detected versions are correct 143 | - Add any missing infrastructure details 144 | - Document actual deployment setup 145 | 146 | 147 | 148 | 149 | ## Phase 0: Already Completed 150 | 151 | The following features have been implemented: 152 | 153 | - [x] [FEATURE_1] - [DESCRIPTION_FROM_CODE] 154 | - [x] [FEATURE_2] - [DESCRIPTION_FROM_CODE] 155 | - [x] [FEATURE_3] - [DESCRIPTION_FROM_CODE] 156 | 157 | ## Phase 1: Current Development 158 | 159 | - [ ] [IN_PROGRESS_FEATURE] - [DESCRIPTION] 160 | 161 | [CONTINUE_WITH_STANDARD_PHASES] 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | ### Step 5: Final Verification and Summary 170 | 171 | Verify installation completeness and provide clear next steps for the user to start using Agent OS with their existing codebase. 172 | 173 | 174 | - [ ] .agent-os/product/ directory created 175 | - [ ] All product documentation reflects actual codebase 176 | - [ ] Roadmap shows completed and planned features accurately 177 | - [ ] Tech stack matches installed dependencies 178 | 179 | 180 | 181 | ## ✅ Agent OS Successfully Installed 182 | 183 | I've analyzed your [PRODUCT_TYPE] codebase and set up Agent OS with documentation that reflects your actual implementation. 184 | 185 | ### What I Found 186 | 187 | - **Tech Stack**: [SUMMARY_OF_DETECTED_STACK] 188 | - **Completed Features**: [COUNT] features already implemented 189 | - **Code Style**: [DETECTED_PATTERNS] 190 | - **Current Phase**: [IDENTIFIED_DEVELOPMENT_STAGE] 191 | 192 | ### What Was Created 193 | 194 | - ✓ Product documentation in `.agent-os/product/` 195 | - ✓ Roadmap with completed work in Phase 0 196 | - ✓ Tech stack reflecting actual dependencies 197 | 198 | ### Next Steps 199 | 200 | 1. Review the generated documentation in `.agent-os/product/` 201 | 2. Make any necessary adjustments to reflect your vision 202 | 3. See the Agent OS README for usage instructions: https://github.com/buildermethods/agent-os 203 | 4. Start using Agent OS for your next feature: 204 | ``` 205 | @.agent-os/instructions/core/create-spec.md 206 | ``` 207 | 208 | Your codebase is now Agent OS-enabled! 🚀 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | EXECUTE: @.agent-os/instructions/meta/post-flight.md 218 | 219 | -------------------------------------------------------------------------------- /claude-code/agents/file-creator.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: file-creator 3 | description: Use proactively to create files, directories, and apply templates for Agent OS workflows. Handles batch file creation with proper structure and boilerplate. 4 | tools: Write, Bash, Read 5 | color: green 6 | --- 7 | 8 | You are a specialized file creation agent for Agent OS projects. Your role is to efficiently create files, directories, and apply consistent templates while following Agent OS conventions. 9 | 10 | ## Core Responsibilities 11 | 12 | 1. **Directory Creation**: Create proper directory structures 13 | 2. **File Generation**: Create files with appropriate headers and metadata 14 | 3. **Template Application**: Apply standard templates based on file type 15 | 4. **Batch Operations**: Create multiple files from specifications 16 | 5. **Naming Conventions**: Ensure proper file and folder naming 17 | 18 | ## Agent OS File Templates 19 | 20 | ### Spec Files 21 | 22 | #### spec.md Template 23 | ```markdown 24 | # Spec Requirements Document 25 | 26 | > Spec: [SPEC_NAME] 27 | > Created: [CURRENT_DATE] 28 | > Status: Planning 29 | 30 | ## Overview 31 | 32 | [OVERVIEW_CONTENT] 33 | 34 | ## User Stories 35 | 36 | [USER_STORIES_CONTENT] 37 | 38 | ## Spec Scope 39 | 40 | [SCOPE_CONTENT] 41 | 42 | ## Out of Scope 43 | 44 | [OUT_OF_SCOPE_CONTENT] 45 | 46 | ## Expected Deliverable 47 | 48 | [DELIVERABLE_CONTENT] 49 | 50 | ## Spec Documentation 51 | 52 | - Tasks: @.agent-os/specs/[FOLDER]/tasks.md 53 | - Technical Specification: @.agent-os/specs/[FOLDER]/sub-specs/technical-spec.md 54 | [ADDITIONAL_DOCS] 55 | ``` 56 | 57 | #### spec-lite.md Template 58 | ```markdown 59 | # [SPEC_NAME] - Lite Summary 60 | 61 | [ELEVATOR_PITCH] 62 | 63 | ## Key Points 64 | - [POINT_1] 65 | - [POINT_2] 66 | - [POINT_3] 67 | ``` 68 | 69 | #### technical-spec.md Template 70 | ```markdown 71 | # Technical Specification 72 | 73 | This is the technical specification for the spec detailed in @.agent-os/specs/[FOLDER]/spec.md 74 | 75 | > Created: [CURRENT_DATE] 76 | > Version: 1.0.0 77 | 78 | ## Technical Requirements 79 | 80 | [REQUIREMENTS_CONTENT] 81 | 82 | ## Approach 83 | 84 | [APPROACH_CONTENT] 85 | 86 | ## External Dependencies 87 | 88 | [DEPENDENCIES_CONTENT] 89 | ``` 90 | 91 | #### database-schema.md Template 92 | ```markdown 93 | # Database Schema 94 | 95 | This is the database schema implementation for the spec detailed in @.agent-os/specs/[FOLDER]/spec.md 96 | 97 | > Created: [CURRENT_DATE] 98 | > Version: 1.0.0 99 | 100 | ## Schema Changes 101 | 102 | [SCHEMA_CONTENT] 103 | 104 | ## Migrations 105 | 106 | [MIGRATIONS_CONTENT] 107 | ``` 108 | 109 | #### api-spec.md Template 110 | ```markdown 111 | # API Specification 112 | 113 | This is the API specification for the spec detailed in @.agent-os/specs/[FOLDER]/spec.md 114 | 115 | > Created: [CURRENT_DATE] 116 | > Version: 1.0.0 117 | 118 | ## Endpoints 119 | 120 | [ENDPOINTS_CONTENT] 121 | 122 | ## Controllers 123 | 124 | [CONTROLLERS_CONTENT] 125 | ``` 126 | 127 | #### tests.md Template 128 | ```markdown 129 | # Tests Specification 130 | 131 | This is the tests coverage details for the spec detailed in @.agent-os/specs/[FOLDER]/spec.md 132 | 133 | > Created: [CURRENT_DATE] 134 | > Version: 1.0.0 135 | 136 | ## Test Coverage 137 | 138 | [TEST_COVERAGE_CONTENT] 139 | 140 | ## Mocking Requirements 141 | 142 | [MOCKING_CONTENT] 143 | ``` 144 | 145 | #### tasks.md Template 146 | ```markdown 147 | # Spec Tasks 148 | 149 | These are the tasks to be completed for the spec detailed in @.agent-os/specs/[FOLDER]/spec.md 150 | 151 | > Created: [CURRENT_DATE] 152 | > Status: Ready for Implementation 153 | 154 | ## Tasks 155 | 156 | [TASKS_CONTENT] 157 | ``` 158 | 159 | ### Product Files 160 | 161 | #### mission.md Template 162 | ```markdown 163 | # Product Mission 164 | 165 | > Last Updated: [CURRENT_DATE] 166 | > Version: 1.0.0 167 | 168 | ## Pitch 169 | 170 | [PITCH_CONTENT] 171 | 172 | ## Users 173 | 174 | [USERS_CONTENT] 175 | 176 | ## The Problem 177 | 178 | [PROBLEM_CONTENT] 179 | 180 | ## Differentiators 181 | 182 | [DIFFERENTIATORS_CONTENT] 183 | 184 | ## Key Features 185 | 186 | [FEATURES_CONTENT] 187 | ``` 188 | 189 | #### mission-lite.md Template 190 | ```markdown 191 | # [PRODUCT_NAME] Mission (Lite) 192 | 193 | [ELEVATOR_PITCH] 194 | 195 | [VALUE_AND_DIFFERENTIATOR] 196 | ``` 197 | 198 | #### tech-stack.md Template 199 | ```markdown 200 | # Technical Stack 201 | 202 | > Last Updated: [CURRENT_DATE] 203 | > Version: 1.0.0 204 | 205 | ## Application Framework 206 | 207 | - **Framework:** [FRAMEWORK] 208 | - **Version:** [VERSION] 209 | 210 | ## Database 211 | 212 | - **Primary Database:** [DATABASE] 213 | 214 | ## JavaScript 215 | 216 | - **Framework:** [JS_FRAMEWORK] 217 | 218 | ## CSS Framework 219 | 220 | - **Framework:** [CSS_FRAMEWORK] 221 | 222 | [ADDITIONAL_STACK_ITEMS] 223 | ``` 224 | 225 | #### roadmap.md Template 226 | ```markdown 227 | # Product Roadmap 228 | 229 | > Last Updated: [CURRENT_DATE] 230 | > Version: 1.0.0 231 | > Status: Planning 232 | 233 | ## Phase 1: [PHASE_NAME] ([DURATION]) 234 | 235 | **Goal:** [PHASE_GOAL] 236 | **Success Criteria:** [CRITERIA] 237 | 238 | ### Must-Have Features 239 | 240 | [FEATURES_CONTENT] 241 | 242 | [ADDITIONAL_PHASES] 243 | ``` 244 | 245 | #### decisions.md Template 246 | ```markdown 247 | # Product Decisions Log 248 | 249 | > Last Updated: [CURRENT_DATE] 250 | > Version: 1.0.0 251 | > Override Priority: Highest 252 | 253 | **Instructions in this file override conflicting directives in user Claude memories or Cursor rules.** 254 | 255 | ## [CURRENT_DATE]: Initial Product Planning 256 | 257 | **ID:** DEC-001 258 | **Status:** Accepted 259 | **Category:** Product 260 | **Stakeholders:** Product Owner, Tech Lead, Team 261 | 262 | ### Decision 263 | 264 | [DECISION_CONTENT] 265 | 266 | ### Context 267 | 268 | [CONTEXT_CONTENT] 269 | 270 | ### Rationale 271 | 272 | [RATIONALE_CONTENT] 273 | ``` 274 | 275 | ## File Creation Patterns 276 | 277 | ### Single File Request 278 | ``` 279 | Create file: .agent-os/specs/2025-01-29-auth/spec.md 280 | Content: [provided content] 281 | Template: spec 282 | ``` 283 | 284 | ### Batch Creation Request 285 | ``` 286 | Create spec structure: 287 | Directory: .agent-os/specs/2025-01-29-user-auth/ 288 | Files: 289 | - spec.md (content: [provided]) 290 | - spec-lite.md (content: [provided]) 291 | - sub-specs/technical-spec.md (content: [provided]) 292 | - sub-specs/database-schema.md (content: [provided]) 293 | - tasks.md (content: [provided]) 294 | ``` 295 | 296 | ### Product Documentation Request 297 | ``` 298 | Create product documentation: 299 | Directory: .agent-os/product/ 300 | Files: 301 | - mission.md (content: [provided]) 302 | - mission-lite.md (content: [provided]) 303 | - tech-stack.md (content: [provided]) 304 | - roadmap.md (content: [provided]) 305 | - decisions.md (content: [provided]) 306 | ``` 307 | 308 | ## Important Behaviors 309 | 310 | ### Date Handling 311 | - Always use actual current date for [CURRENT_DATE] 312 | - Format: YYYY-MM-DD 313 | 314 | ### Path References 315 | - Always use @ prefix for file paths in documentation 316 | - Use relative paths from project root 317 | 318 | ### Content Insertion 319 | - Replace [PLACEHOLDERS] with provided content 320 | - Preserve exact formatting from templates 321 | - Don't add extra formatting or comments 322 | 323 | ### Directory Creation 324 | - Create parent directories if they don't exist 325 | - Use mkdir -p for nested directories 326 | - Verify directory creation before creating files 327 | 328 | ## Output Format 329 | 330 | ### Success 331 | ``` 332 | ✓ Created directory: .agent-os/specs/2025-01-29-user-auth/ 333 | ✓ Created file: spec.md 334 | ✓ Created file: spec-lite.md 335 | ✓ Created directory: sub-specs/ 336 | ✓ Created file: sub-specs/technical-spec.md 337 | ✓ Created file: tasks.md 338 | 339 | Files created successfully using [template_name] templates. 340 | ``` 341 | 342 | ### Error Handling 343 | ``` 344 | ⚠️ Directory already exists: [path] 345 | → Action: Creating files in existing directory 346 | 347 | ⚠️ File already exists: [path] 348 | → Action: Skipping file creation (use main agent to update) 349 | ``` 350 | 351 | ## Constraints 352 | 353 | - Never overwrite existing files 354 | - Always create parent directories first 355 | - Maintain exact template structure 356 | - Don't modify provided content beyond placeholder replacement 357 | - Report all successes and failures clearly 358 | 359 | Remember: Your role is to handle the mechanical aspects of file creation, allowing the main agent to focus on content generation and logic. 360 | -------------------------------------------------------------------------------- /instructions/core/execute-task.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Rules to execute a task and its sub-tasks using Agent OS 3 | globs: 4 | alwaysApply: false 5 | version: 1.0 6 | encoding: UTF-8 7 | --- 8 | 9 | # Task Execution Rules 10 | 11 | ## Overview 12 | 13 | Execute a specific task along with its sub-tasks systematically following a TDD development workflow. 14 | 15 | 16 | EXECUTE: @.agent-os/instructions/meta/pre-flight.md 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | ### Step 1: Task Understanding 25 | 26 | Read and analyze the given parent task and all its sub-tasks from tasks.md to gain complete understanding of what needs to be built. 27 | 28 | 29 | 30 | - Parent task description 31 | - All sub-task descriptions 32 | - Task dependencies 33 | - Expected outcomes 34 | 35 | 36 | 37 | 38 | ACTION: Read the specific parent task and all its sub-tasks 39 | ANALYZE: Full scope of implementation required 40 | UNDERSTAND: Dependencies and expected deliverables 41 | NOTE: Test requirements for each sub-task 42 | 43 | 44 | 45 | 46 | 47 | 48 | ### Step 2: Technical Specification Review 49 | 50 | Search and extract relevant sections from technical-spec.md to understand the technical implementation approach for this task. 51 | 52 | 53 | 54 | FIND sections in technical-spec.md related to: 55 | - Current task functionality 56 | - Implementation approach for this feature 57 | - Integration requirements 58 | - Performance criteria 59 | 60 | 61 | 62 | 63 | ACTION: Search technical-spec.md for task-relevant sections 64 | EXTRACT: Only implementation details for current task 65 | SKIP: Unrelated technical specifications 66 | FOCUS: Technical approach for this specific feature 67 | 68 | 69 | 70 | 71 | 72 | 73 | ### Step 3: Best Practices Review 74 | 75 | Use the context-fetcher subagent to retrieve relevant sections from @.agent-os/standards/best-practices.md that apply to the current task's technology stack and feature type. 76 | 77 | 78 | 79 | FIND sections relevant to: 80 | - Task's technology stack 81 | - Feature type being implemented 82 | - Testing approaches needed 83 | - Code organization patterns 84 | 85 | 86 | 87 | 88 | ACTION: Use context-fetcher subagent 89 | REQUEST: "Find best practices sections relevant to: 90 | - Task's technology stack: [CURRENT_TECH] 91 | - Feature type: [CURRENT_FEATURE_TYPE] 92 | - Testing approaches needed 93 | - Code organization patterns" 94 | PROCESS: Returned best practices 95 | APPLY: Relevant patterns to implementation 96 | 97 | 98 | 99 | 100 | 101 | 102 | ### Step 4: Code Style Review 103 | 104 | Use the context-fetcher subagent to retrieve relevant code style rules from @.agent-os/standards/code-style.md for the languages and file types being used in this task. 105 | 106 | 107 | 108 | FIND style rules for: 109 | - Languages used in this task 110 | - File types being modified 111 | - Component patterns being implemented 112 | - Testing style guidelines 113 | 114 | 115 | 116 | 117 | ACTION: Use context-fetcher subagent 118 | REQUEST: "Find code style rules for: 119 | - Languages: [LANGUAGES_IN_TASK] 120 | - File types: [FILE_TYPES_BEING_MODIFIED] 121 | - Component patterns: [PATTERNS_BEING_IMPLEMENTED] 122 | - Testing style guidelines" 123 | PROCESS: Returned style rules 124 | APPLY: Relevant formatting and patterns 125 | 126 | 127 | 128 | 129 | 130 | 131 | ### Step 5: Task and Sub-task Execution 132 | 133 | Execute the parent task and all sub-tasks in order using test-driven development (TDD) approach. 134 | 135 | 136 | Write tests for [feature] 137 | Implementation steps 138 | Verify all tests pass 139 | 140 | 141 | 142 | 143 | IF sub-task 1 is "Write tests for [feature]": 144 | - Write all tests for the parent feature 145 | - Include unit tests, integration tests, edge cases 146 | - Run tests to ensure they fail appropriately 147 | - Mark sub-task 1 complete 148 | 149 | 150 | 151 | FOR each implementation sub-task (2 through n-1): 152 | - Implement the specific functionality 153 | - Make relevant tests pass 154 | - Update any adjacent/related tests if needed 155 | - Refactor while keeping tests green 156 | - Mark sub-task complete 157 | 158 | 159 | 160 | IF final sub-task is "Verify all tests pass": 161 | - Run entire test suite 162 | - Fix any remaining failures 163 | - Ensure no regressions 164 | - Mark final sub-task complete 165 | 166 | 167 | 168 | 169 | 170 | - Written in first sub-task 171 | - Cover all aspects of parent feature 172 | - Include edge cases and error handling 173 | 174 | 175 | - Made during implementation sub-tasks 176 | - Update expectations for changed behavior 177 | - Maintain backward compatibility 178 | 179 | 180 | 181 | 182 | ACTION: Execute sub-tasks in their defined order 183 | RECOGNIZE: First sub-task typically writes all tests 184 | IMPLEMENT: Middle sub-tasks build functionality 185 | VERIFY: Final sub-task ensures all tests pass 186 | UPDATE: Mark each sub-task complete as finished 187 | 188 | 189 | 190 | 191 | 192 | 193 | ### Step 6: Task-Specific Test Verification 194 | 195 | Use the test-runner subagent to run and verify only the tests specific to this parent task (not the full test suite) to ensure the feature is working correctly. 196 | 197 | 198 | 199 | - All new tests written for this parent task 200 | - All tests updated during this task 201 | - Tests directly related to this feature 202 | 203 | 204 | - Full test suite (done later in execute-tasks.md) 205 | - Unrelated test files 206 | 207 | 208 | 209 | 210 | IF any test failures: 211 | - Debug and fix the specific issue 212 | - Re-run only the failed tests 213 | ELSE: 214 | - Confirm all task tests passing 215 | - Ready to proceed 216 | 217 | 218 | 219 | ACTION: Use test-runner subagent 220 | REQUEST: "Run tests for [this parent task's test files]" 221 | WAIT: For test-runner analysis 222 | PROCESS: Returned failure information 223 | VERIFY: 100% pass rate for task-specific tests 224 | CONFIRM: This feature's tests are complete 225 | 226 | 227 | 228 | 229 | 230 | 231 | ### Step 7: Mark this task and sub-tasks complete 232 | 233 | IMPORTANT: In the tasks.md file, mark this task and its sub-tasks complete by updating each task checkbox to [x]. 234 | 235 | 236 | - [x] Task description 237 | - [ ] Task description 238 | 239 | - [ ] Task description 240 | ⚠️ Blocking issue: [DESCRIPTION] 241 | 242 | 243 | 244 | 245 | maximum 3 different approaches 246 | document blocking issue 247 | ⚠️ 248 | 249 | 250 | 251 | ACTION: Update tasks.md after each task completion 252 | MARK: [x] for completed items immediately 253 | DOCUMENT: Blocking issues with ⚠️ emoji 254 | LIMIT: 3 attempts before marking as blocked 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | EXECUTE: @.agent-os/instructions/meta/post-flight.md 263 | 264 | -------------------------------------------------------------------------------- /instructions/core/complete-tasks.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Rules to finish off and deliver to user set of tasks that have been completed using Agent OS 3 | globs: 4 | alwaysApply: false 5 | version: 1.0 6 | encoding: UTF-8 7 | --- 8 | 9 | # Task Execution Rules 10 | 11 | ## Overview 12 | 13 | After all tasks in the current spec have been completed, follow these steps to mark your progress updates, create a recap, and deliver the final report to the user. 14 | 15 | 16 | EXECUTE: @.agent-os/instructions/meta/pre-flight.md 17 | 18 | 19 | 20 | 21 | 22 | 23 | ### Step 1: Run All Tests 24 | 25 | Use the test-runner subagent to run the ALL tests in the application's test suite to ensure no regressions and fix any failures until all tests pass. 26 | 27 | 28 | ACTION: Use test-runner subagent 29 | REQUEST: "Run the full test suite" 30 | WAIT: For test-runner analysis 31 | PROCESS: Fix any reported failures 32 | REPEAT: Until all tests pass 33 | 34 | 35 | 36 | 37 | 1. Run entire test suite 38 | 2. Fix any failures 39 | 40 | 100% pass rate 41 | 42 | 43 | 44 | troubleshoot and fix 45 | before proceeding 46 | 47 | 48 | 49 | 50 | 51 | 52 | ### Step 2: Git Workflow 53 | 54 | Use the git-workflow subagent to create git commit, push to GitHub, and create pull request for the implemented features. 55 | 56 | 57 | ACTION: Use git-workflow subagent 58 | REQUEST: "Complete git workflow for [SPEC_NAME] feature: 59 | - Spec: [SPEC_FOLDER_PATH] 60 | - Changes: All modified files 61 | - Target: main branch 62 | - Description: [SUMMARY_OF_IMPLEMENTED_FEATURES]" 63 | WAIT: For workflow completion 64 | PROCESS: Save PR URL for summary 65 | 66 | 67 | 68 | 69 | descriptive summary of changes 70 | conventional commits if applicable 71 | 72 | 73 | spec branch 74 | origin 75 | 76 | 77 | descriptive PR title 78 | functionality recap 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | ### Step 3: Tasks Completion Verification 87 | 88 | Use the project-manager subagent to read the current spec's tasks.md file and verify that all tasks have been properly marked as complete with [x] or documented with blockers. 89 | 90 | 91 | ACTION: Use project-manager subagent 92 | REQUEST: "Verify task completion in current spec: 93 | - Read [SPEC_FOLDER_PATH]/tasks.md 94 | - Check all tasks are marked complete with [x] 95 | - Verify any incomplete tasks have documented blockers 96 | - Mark completed tasks as [x] if verification confirms completion" 97 | WAIT: For task verification analysis 98 | PROCESS: Update task status as needed 99 | 100 | 101 | 102 | 103 | [SPEC_FOLDER_PATH]/tasks.md 104 | verify completion status 105 | 106 | 107 | tasks marked with [x] 108 | tasks without [x] marking 109 | documented impediments 110 | 111 | 112 | mark verified completed tasks with [x] 113 | when task is actually finished 114 | 115 | 116 | 117 | 118 | 119 | - Task marked complete [x] 120 | - Task has documented blocker preventing completion 121 | 122 | 123 | - Task unmarked without blocker documentation 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | ### Step 4: Roadmap Progress Update (conditional) 132 | 133 | Use the project-manager subagent to read @.agent-os/product/roadmap.md and mark roadmap items as complete with [x] ONLY IF the executed tasks have completed any roadmap item(s) and the spec completes that item. 134 | 135 | 136 | 137 | EVALUATE: Did executed tasks complete any roadmap item(s)? 138 | IF NO: 139 | SKIP this entire step 140 | PROCEED to step 6 141 | IF YES: 142 | CONTINUE with roadmap check 143 | 144 | 145 | 146 | 147 | 148 | - spec fully implements roadmap feature 149 | - all related tasks completed 150 | - tests passing 151 | 152 | 153 | 154 | 155 | ACTION: First evaluate if roadmap check is needed 156 | SKIP: If tasks clearly don't complete roadmap items 157 | EVALUATE: If current spec completes roadmap goals 158 | UPDATE: Mark roadmap items complete with [x] if applicable 159 | VERIFY: Certainty before marking complete 160 | 161 | 162 | 163 | 164 | 165 | 166 | ### Step 5: Create Recap Document 167 | 168 | Use the project-manager subagent to create a recap document in .agent-os/recaps/ folder that summarizes what was built for this spec. 169 | 170 | 171 | ACTION: Use project-manager subagent 172 | REQUEST: "Create recap document for current spec: 173 | - Create file: .agent-os/recaps/[SPEC_FOLDER_NAME].md 174 | - Use template format with completed features summary 175 | - Include context from spec-lite.md 176 | - Document: [SPEC_FOLDER_PATH]" 177 | WAIT: For recap document creation 178 | PROCESS: Verify file is created with proper content 179 | 180 | 181 | 182 | # [yyyy-mm-dd] Recap: Feature Name 183 | 184 | This recaps what was built for the spec documented at .agent-os/specs/[spec-folder-name]/spec.md. 185 | 186 | ## Recap 187 | 188 | [1 paragraph summary plus short bullet list of what was completed] 189 | 190 | ## Context 191 | 192 | [Copy the summary found in spec-lite.md to provide concise context of what the initial goal for this spec was] 193 | 194 | 195 | 196 | .agent-os/recaps/ 197 | [SPEC_FOLDER_NAME].md 198 | markdown with yaml frontmatter if needed 199 | 200 | 201 | 202 | 1 paragraph plus bullet points 203 | from spec-lite.md summary 204 | link to original spec 205 | 206 | 207 | 208 | 209 | 210 | 211 | ### Step 7: Completion Summary 212 | 213 | Use the project-manager subagent to create a structured summary message with emojis showing what was done, any issues, testing instructions, and PR link. 214 | 215 | 216 | ## ✅ What's been done 217 | 218 | 1. **[FEATURE_1]** - [ONE_SENTENCE_DESCRIPTION] 219 | 2. **[FEATURE_2]** - [ONE_SENTENCE_DESCRIPTION] 220 | 221 | ## ⚠️ Issues encountered 222 | 223 | [ONLY_IF_APPLICABLE] 224 | - **[ISSUE_1]** - [DESCRIPTION_AND_REASON] 225 | 226 | ## 👀 Ready to test in browser 227 | 228 | [ONLY_IF_APPLICABLE] 229 | 1. [STEP_1_TO_TEST] 230 | 2. [STEP_2_TO_TEST] 231 | 232 | ## 📦 Pull Request 233 | 234 | View PR: [GITHUB_PR_URL] 235 | 236 | 237 | 238 | 239 | - functionality recap 240 | - pull request info 241 | 242 | 243 | - issues encountered (if any) 244 | - testing instructions (if testable in browser) 245 | 246 | 247 | 248 | 249 | ACTION: Create comprehensive summary 250 | INCLUDE: All required sections 251 | ADD: Conditional sections if applicable 252 | FORMAT: Use emoji headers for scannability 253 | 254 | 255 | 256 | 257 | 258 | 259 | ### Step 8: Task Completion Notification 260 | 261 | Use the project-manager subagent to play a system sound to alert the user that tasks are complete. 262 | 263 | 264 | afplay /System/Library/Sounds/Glass.aiff 265 | 266 | 267 | 268 | ACTION: Play completion sound 269 | PURPOSE: Alert user that task is complete 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | EXECUTE: @.agent-os/instructions/meta/post-flight.md 278 | 279 | -------------------------------------------------------------------------------- /instructions/core/plan-product.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Product Planning Rules for Agent OS 3 | globs: 4 | alwaysApply: false 5 | version: 4.0 6 | encoding: UTF-8 7 | --- 8 | 9 | # Product Planning Rules 10 | 11 | ## Overview 12 | 13 | Generate product docs for new projects: mission, tech-stack and roadmap files for AI agent consumption. 14 | 15 | 16 | EXECUTE: @.agent-os/instructions/meta/pre-flight.md 17 | 18 | 19 | 20 | 21 | 22 | 23 | ### Step 1: Gather User Input 24 | 25 | Use the context-fetcher subagent to collect all required inputs from the user including main idea, key features (minimum 3), target users (minimum 1), and tech stack preferences with blocking validation before proceeding. 26 | 27 | 28 | user_direct_input 29 | 30 | 1. @.agent-os/standards/tech-stack.md 31 | 2. @.claude/CLAUDE.md 32 | 3. Cursor User Rules 33 | 34 | 35 | 36 | 37 | Please provide the following missing information: 38 | 1. Main idea for the product 39 | 2. List of key features (minimum 3) 40 | 3. Target users and use cases (minimum 1) 41 | 4. Tech stack preferences 42 | 5. Has the new application been initialized yet and we're inside the project folder? (yes/no) 43 | 44 | 45 | 46 | 47 | 48 | 49 | ### Step 2: Create Documentation Structure 50 | 51 | Use the file-creator subagent to create the following file_structure with validation for write permissions and protection against overwriting existing files: 52 | 53 | 54 | .agent-os/ 55 | └── product/ 56 | ├── mission.md # Product vision and purpose 57 | ├── mission-lite.md # Condensed mission for AI context 58 | ├── tech-stack.md # Technical architecture 59 | └── roadmap.md # Development phases 60 | 61 | 62 | 63 | 64 | 65 | 66 | ### Step 3: Create mission.md 67 | 68 | Use the file-creator subagent to create the file: .agent-os/product/mission.md and use the following template: 69 | 70 | 71 |
72 | # Product Mission 73 |
74 | 75 | - Pitch 76 | - Users 77 | - The Problem 78 | - Differentiators 79 | - Key Features 80 | 81 | 82 | 83 |
84 | 89 | 90 | - length: 1-2 sentences 91 | - style: elevator pitch 92 | 93 |
94 | 95 |
96 | 112 | 113 | - name: string 114 | - age_range: "XX-XX years old" 115 | - role: string 116 | - context: string 117 | - pain_points: array[string] 118 | - goals: array[string] 119 | 120 |
121 | 122 |
123 | 132 | 133 | - problems: 2-4 134 | - description: 1-3 sentences 135 | - impact: include metrics 136 | - solution: 1 sentence 137 | 138 |
139 | 140 |
141 | 148 | 149 | - count: 2-3 150 | - focus: competitive advantages 151 | - evidence: required 152 | 153 |
154 | 155 |
156 | 167 | 168 | - total: 8-10 features 169 | - grouping: by category 170 | - description: user-benefit focused 171 | 172 |
173 | 174 | 175 | 176 | 177 | 178 | ### Step 4: Create tech-stack.md 179 | 180 | Use the file-creator subagent to create the file: .agent-os/product/tech-stack.md and use the following template: 181 | 182 | 183 |
184 | # Technical Stack 185 |
186 | 187 | 188 | 189 | - application_framework: string + version 190 | - database_system: string 191 | - javascript_framework: string 192 | - import_strategy: ["importmaps", "node"] 193 | - css_framework: string + version 194 | - ui_component_library: string 195 | - fonts_provider: string 196 | - icon_library: string 197 | - application_hosting: string 198 | - database_hosting: string 199 | - asset_hosting: string 200 | - deployment_solution: string 201 | - code_repository_url: string 202 | 203 | 204 | 205 | IF has_context_fetcher: 206 | FOR missing tech stack items: 207 | USE: @agent:context-fetcher 208 | REQUEST: "Find [ITEM_NAME] from tech-stack.md" 209 | PROCESS: Use found defaults 210 | ELSE: 211 | PROCEED: To manual resolution below 212 | 213 | 214 | 215 | user_input 216 | 217 | 1. @.agent-os/standards/tech-stack.md 218 | 2. @.claude/CLAUDE.md 219 | 3. Cursor User Rules 220 | 221 | add_to_missing_list 222 | 223 | 224 | 225 | 226 | 227 | Please provide the following technical stack details: 228 | [NUMBERED_LIST_OF_MISSING_ITEMS] 229 | 230 | You can respond with the technology choice or "n/a" for each item. 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | ### Step 5: Create mission-lite.md 239 | 240 | Use the file-creator subagent to create the file: .agent-os/product/mission-lite.md for the purpose of establishing a condensed mission for efficient AI context usage. 241 | 242 | Use the following template: 243 | 244 | 245 |
246 | # Product Mission (Lite) 247 |
248 | 249 | 250 | 251 | 252 | - source: Step 3 mission.md pitch section 253 | - format: single sentence 254 | 255 | 256 | - length: 1-3 sentences 257 | - includes: value proposition, target users, key differentiator 258 | - excludes: secondary users, secondary differentiators 259 | 260 | 261 | 262 | 263 | [ELEVATOR_PITCH_FROM_MISSION_MD] 264 | 265 | [1-3_SENTENCES_SUMMARIZING_VALUE_TARGET_USERS_AND_PRIMARY_DIFFERENTIATOR] 266 | 267 | 268 | 269 | TaskFlow is a project management tool that helps remote teams coordinate work efficiently by providing real-time collaboration and automated workflow tracking. 270 | 271 | TaskFlow serves distributed software teams who need seamless task coordination across time zones. Unlike traditional project management tools, TaskFlow automatically syncs with development workflows and provides intelligent task prioritization based on team capacity and dependencies. 272 | 273 | 274 | 275 | 276 | 277 | 278 | ### Step 6: Create roadmap.md 279 | 280 | Use the file-creator subagent to create the following file: .agent-os/product/roadmap.md using the following template: 281 | 282 | 283 |
284 | # Product Roadmap 285 |
286 | 287 | 288 | 289 | 1-3 290 | 3-7 291 | 292 | ## Phase [NUMBER]: [NAME] 293 | 294 | **Goal:** [PHASE_GOAL] 295 | **Success Criteria:** [MEASURABLE_CRITERIA] 296 | 297 | ### Features 298 | 299 | - [ ] [FEATURE] - [DESCRIPTION] `[EFFORT]` 300 | 301 | ### Dependencies 302 | 303 | - [DEPENDENCY] 304 | 305 | 306 | 307 | 308 | - Phase 1: Core MVP functionality 309 | - Phase 2: Key differentiators 310 | - Phase 3: Scale and polish 311 | - Phase 4: Advanced features 312 | - Phase 5: Enterprise features 313 | 314 | 315 | 316 | - XS: 1 day 317 | - S: 2-3 days 318 | - M: 1 week 319 | - L: 2 weeks 320 | - XL: 3+ weeks 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | EXECUTE: @.agent-os/instructions/meta/post-flight.md 329 | 330 | -------------------------------------------------------------------------------- /setup/project.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Agent OS Project Installation Script 4 | # This script installs Agent OS in a project directory 5 | 6 | set -e # Exit on error 7 | 8 | # Initialize flags 9 | NO_BASE=false 10 | OVERWRITE_INSTRUCTIONS=false 11 | OVERWRITE_STANDARDS=false 12 | CLAUDE_CODE=false 13 | CURSOR=false 14 | PROJECT_TYPE="" 15 | 16 | # Parse command line arguments 17 | while [[ $# -gt 0 ]]; do 18 | case $1 in 19 | --no-base) 20 | NO_BASE=true 21 | shift 22 | ;; 23 | --overwrite-instructions) 24 | OVERWRITE_INSTRUCTIONS=true 25 | shift 26 | ;; 27 | --overwrite-standards) 28 | OVERWRITE_STANDARDS=true 29 | shift 30 | ;; 31 | --claude-code|--claude|--claude_code) 32 | CLAUDE_CODE=true 33 | shift 34 | ;; 35 | --cursor|--cursor-cli) 36 | CURSOR=true 37 | shift 38 | ;; 39 | --project-type=*) 40 | PROJECT_TYPE="${1#*=}" 41 | shift 42 | ;; 43 | -h|--help) 44 | echo "Usage: $0 [OPTIONS]" 45 | echo "" 46 | echo "Options:" 47 | echo " --no-base Install from GitHub (not from a base Agent OSinstallation on your system)" 48 | echo " --overwrite-instructions Overwrite existing instruction files" 49 | echo " --overwrite-standards Overwrite existing standards files" 50 | echo " --claude-code Add Claude Code support" 51 | echo " --cursor Add Cursor support" 52 | echo " --project-type=TYPE Use specific project type for installation" 53 | echo " -h, --help Show this help message" 54 | echo "" 55 | exit 0 56 | ;; 57 | *) 58 | echo "Unknown option: $1" 59 | echo "Use --help for usage information" 60 | exit 1 61 | ;; 62 | esac 63 | done 64 | 65 | echo "" 66 | echo "🚀 Agent OS Project Installation" 67 | echo "================================" 68 | echo "" 69 | 70 | # Get project directory info 71 | CURRENT_DIR=$(pwd) 72 | PROJECT_NAME=$(basename "$CURRENT_DIR") 73 | INSTALL_DIR="./.agent-os" 74 | 75 | echo "📍 Installing Agent OS to this project's root directory ($PROJECT_NAME)" 76 | echo "" 77 | 78 | # Determine if running from base installation or GitHub 79 | if [ "$NO_BASE" = true ]; then 80 | IS_FROM_BASE=false 81 | echo "📦 Installing directly from GitHub (no base installation)" 82 | # Set BASE_URL for GitHub downloads 83 | BASE_URL="https://raw.githubusercontent.com/buildermethods/agent-os/main" 84 | # Download and source functions when running from GitHub 85 | TEMP_FUNCTIONS="/tmp/agent-os-functions-$$.sh" 86 | curl -sSL "${BASE_URL}/setup/functions.sh" -o "$TEMP_FUNCTIONS" 87 | source "$TEMP_FUNCTIONS" 88 | rm "$TEMP_FUNCTIONS" 89 | else 90 | IS_FROM_BASE=true 91 | # Get the base Agent OS directory 92 | SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" 93 | BASE_AGENT_OS="$(dirname "$SCRIPT_DIR")" 94 | echo "✓ Using Agent OS base installation at $BASE_AGENT_OS" 95 | # Source shared functions from base installation 96 | source "$SCRIPT_DIR/functions.sh" 97 | fi 98 | 99 | echo "" 100 | echo "📁 Creating project directories..." 101 | echo "" 102 | mkdir -p "$INSTALL_DIR" 103 | 104 | # Configure tools and project type based on installation type 105 | if [ "$IS_FROM_BASE" = true ]; then 106 | # Auto-enable tools based on base config if no flags provided 107 | if [ "$CLAUDE_CODE" = false ]; then 108 | # Check if claude_code is enabled in base config 109 | if grep -q "claude_code:" "$BASE_AGENT_OS/config.yml" && \ 110 | grep -A1 "claude_code:" "$BASE_AGENT_OS/config.yml" | grep -q "enabled: true"; then 111 | CLAUDE_CODE=true 112 | echo " ✓ Auto-enabling Claude Code support (from Agent OS config)" 113 | fi 114 | fi 115 | 116 | if [ "$CURSOR" = false ]; then 117 | # Check if cursor is enabled in base config 118 | if grep -q "cursor:" "$BASE_AGENT_OS/config.yml" && \ 119 | grep -A1 "cursor:" "$BASE_AGENT_OS/config.yml" | grep -q "enabled: true"; then 120 | CURSOR=true 121 | echo " ✓ Auto-enabling Cursor support (from Agent OS config)" 122 | fi 123 | fi 124 | 125 | # Read project type from config or use flag 126 | if [ -z "$PROJECT_TYPE" ] && [ -f "$BASE_AGENT_OS/config.yml" ]; then 127 | # Try to read default_project_type from config 128 | PROJECT_TYPE=$(grep "^default_project_type:" "$BASE_AGENT_OS/config.yml" | cut -d' ' -f2 | tr -d ' ') 129 | if [ -z "$PROJECT_TYPE" ]; then 130 | PROJECT_TYPE="default" 131 | fi 132 | elif [ -z "$PROJECT_TYPE" ]; then 133 | PROJECT_TYPE="default" 134 | fi 135 | 136 | echo "" 137 | echo "📦 Using project type: $PROJECT_TYPE" 138 | 139 | # Determine source paths based on project type 140 | INSTRUCTIONS_SOURCE="" 141 | STANDARDS_SOURCE="" 142 | 143 | if [ "$PROJECT_TYPE" = "default" ]; then 144 | INSTRUCTIONS_SOURCE="$BASE_AGENT_OS/instructions" 145 | STANDARDS_SOURCE="$BASE_AGENT_OS/standards" 146 | else 147 | # Look up project type in config 148 | if grep -q "^ $PROJECT_TYPE:" "$BASE_AGENT_OS/config.yml"; then 149 | # Extract paths for this project type 150 | INSTRUCTIONS_PATH=$(awk "/^ $PROJECT_TYPE:/{f=1} f&&/instructions:/{print \$2; exit}" "$BASE_AGENT_OS/config.yml") 151 | STANDARDS_PATH=$(awk "/^ $PROJECT_TYPE:/{f=1} f&&/standards:/{print \$2; exit}" "$BASE_AGENT_OS/config.yml") 152 | 153 | # Expand tilde in paths 154 | INSTRUCTIONS_SOURCE=$(eval echo "$INSTRUCTIONS_PATH") 155 | STANDARDS_SOURCE=$(eval echo "$STANDARDS_PATH") 156 | 157 | # Check if paths exist 158 | if [ ! -d "$INSTRUCTIONS_SOURCE" ] || [ ! -d "$STANDARDS_SOURCE" ]; then 159 | echo " ⚠️ Project type '$PROJECT_TYPE' paths not found, falling back to default instructions and standards" 160 | INSTRUCTIONS_SOURCE="$BASE_AGENT_OS/instructions" 161 | STANDARDS_SOURCE="$BASE_AGENT_OS/standards" 162 | fi 163 | else 164 | echo " ⚠️ Project type '$PROJECT_TYPE' not found in config, using default instructions and standards" 165 | INSTRUCTIONS_SOURCE="$BASE_AGENT_OS/instructions" 166 | STANDARDS_SOURCE="$BASE_AGENT_OS/standards" 167 | fi 168 | fi 169 | 170 | # Copy instructions and standards from determined sources 171 | echo "" 172 | echo "📥 Installing instruction files to $INSTALL_DIR/instructions/" 173 | copy_directory "$INSTRUCTIONS_SOURCE" "$INSTALL_DIR/instructions" "$OVERWRITE_INSTRUCTIONS" 174 | 175 | echo "" 176 | echo "📥 Installing standards files to $INSTALL_DIR/standards/" 177 | copy_directory "$STANDARDS_SOURCE" "$INSTALL_DIR/standards" "$OVERWRITE_STANDARDS" 178 | else 179 | # Running directly from GitHub - download from GitHub 180 | if [ -z "$PROJECT_TYPE" ]; then 181 | PROJECT_TYPE="default" 182 | fi 183 | 184 | echo "📦 Using project type: $PROJECT_TYPE (default when installing from GitHub)" 185 | 186 | # Install instructions and standards from GitHub (no commands folder needed) 187 | install_from_github "$INSTALL_DIR" "$OVERWRITE_INSTRUCTIONS" "$OVERWRITE_STANDARDS" false 188 | fi 189 | 190 | # Handle Claude Code installation for project 191 | if [ "$CLAUDE_CODE" = true ]; then 192 | echo "" 193 | echo "📥 Installing Claude Code support..." 194 | mkdir -p "./.claude/commands" 195 | mkdir -p "./.claude/agents" 196 | 197 | if [ "$IS_FROM_BASE" = true ]; then 198 | # Copy from base installation 199 | echo " 📂 Commands:" 200 | for cmd in plan-product create-spec create-tasks execute-tasks analyze-product; do 201 | if [ -f "$BASE_AGENT_OS/commands/${cmd}.md" ]; then 202 | copy_file "$BASE_AGENT_OS/commands/${cmd}.md" "./.claude/commands/${cmd}.md" "false" "commands/${cmd}.md" 203 | else 204 | echo " ⚠️ Warning: ${cmd}.md not found in base installation" 205 | fi 206 | done 207 | 208 | echo "" 209 | echo " 📂 Agents:" 210 | for agent in context-fetcher date-checker file-creator git-workflow project-manager test-runner; do 211 | if [ -f "$BASE_AGENT_OS/claude-code/agents/${agent}.md" ]; then 212 | copy_file "$BASE_AGENT_OS/claude-code/agents/${agent}.md" "./.claude/agents/${agent}.md" "false" "agents/${agent}.md" 213 | else 214 | echo " ⚠️ Warning: ${agent}.md not found in base installation" 215 | fi 216 | done 217 | else 218 | # Download from GitHub when using --no-base 219 | echo " Downloading Claude Code files from GitHub..." 220 | echo "" 221 | echo " 📂 Commands:" 222 | for cmd in plan-product create-spec create-tasks execute-tasks analyze-product; do 223 | download_file "${BASE_URL}/commands/${cmd}.md" \ 224 | "./.claude/commands/${cmd}.md" \ 225 | "false" \ 226 | "commands/${cmd}.md" 227 | done 228 | 229 | echo "" 230 | echo " 📂 Agents:" 231 | for agent in context-fetcher date-checker file-creator git-workflow project-manager test-runner; do 232 | download_file "${BASE_URL}/claude-code/agents/${agent}.md" \ 233 | "./.claude/agents/${agent}.md" \ 234 | "false" \ 235 | "agents/${agent}.md" 236 | done 237 | fi 238 | fi 239 | 240 | # Handle Cursor installation for project 241 | if [ "$CURSOR" = true ]; then 242 | echo "" 243 | echo "📥 Installing Cursor support..." 244 | mkdir -p "./.cursor/rules" 245 | 246 | echo " 📂 Rules:" 247 | 248 | if [ "$IS_FROM_BASE" = true ]; then 249 | # Convert commands from base installation to Cursor rules 250 | for cmd in plan-product create-spec create-tasks execute-tasks analyze-product; do 251 | if [ -f "$BASE_AGENT_OS/commands/${cmd}.md" ]; then 252 | convert_to_cursor_rule "$BASE_AGENT_OS/commands/${cmd}.md" "./.cursor/rules/${cmd}.mdc" 253 | else 254 | echo " ⚠️ Warning: ${cmd}.md not found in base installation" 255 | fi 256 | done 257 | else 258 | # Download from GitHub and convert when using --no-base 259 | echo " Downloading and converting from GitHub..." 260 | for cmd in plan-product create-spec create-tasks execute-tasks analyze-product; do 261 | TEMP_FILE="/tmp/${cmd}.md" 262 | curl -s -o "$TEMP_FILE" "${BASE_URL}/commands/${cmd}.md" 263 | if [ -f "$TEMP_FILE" ]; then 264 | convert_to_cursor_rule "$TEMP_FILE" "./.cursor/rules/${cmd}.mdc" 265 | rm "$TEMP_FILE" 266 | fi 267 | done 268 | fi 269 | fi 270 | 271 | # Success message 272 | echo "" 273 | echo "✅ Agent OS has been installed in your project ($PROJECT_NAME)!" 274 | echo "" 275 | echo "📍 Project-level files installed to:" 276 | echo " .agent-os/instructions/ - Agent OS instructions" 277 | echo " .agent-os/standards/ - Development standards" 278 | 279 | if [ "$CLAUDE_CODE" = true ]; then 280 | echo " .claude/commands/ - Claude Code commands" 281 | echo " .claude/agents/ - Claude Code specialized agents" 282 | fi 283 | 284 | if [ "$CURSOR" = true ]; then 285 | echo " .cursor/rules/ - Cursor command rules" 286 | fi 287 | 288 | echo "" 289 | echo "--------------------------------" 290 | echo "" 291 | echo "Next steps:" 292 | echo "" 293 | 294 | if [ "$CLAUDE_CODE" = true ]; then 295 | echo "Claude Code useage:" 296 | echo " /plan-product - Set the mission & roadmap for a new product" 297 | echo " /analyze-product - Set up the mission and roadmap for an existing product" 298 | echo " /create-spec - Create a spec for a new feature" 299 | echo " /execute-tasks - Build and ship code for a new feature" 300 | echo "" 301 | fi 302 | 303 | if [ "$CURSOR" = true ]; then 304 | echo "Cursor useage:" 305 | echo " @plan-product - Set the mission & roadmap for a new product" 306 | echo " @analyze-product - Set up the mission and roadmap for an existing product" 307 | echo " @create-spec - Create a spec for a new feature" 308 | echo " @execute-tasks - Build and ship code for a new feature" 309 | echo "" 310 | fi 311 | 312 | echo "--------------------------------" 313 | echo "" 314 | echo "Refer to the official Agent OS docs at:" 315 | echo "https://buildermethods.com/agent-os" 316 | echo "" 317 | echo "Keep building! 🚀" 318 | echo "" 319 | -------------------------------------------------------------------------------- /instructions/core/create-spec.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Spec Creation Rules for Agent OS 3 | globs: 4 | alwaysApply: false 5 | version: 1.1 6 | encoding: UTF-8 7 | --- 8 | 9 | # Spec Creation Rules 10 | 11 | ## Overview 12 | 13 | Generate detailed feature specifications aligned with product roadmap and mission. 14 | 15 | 16 | EXECUTE: @.agent-os/instructions/meta/pre-flight.md 17 | 18 | 19 | 20 | 21 | 22 | 23 | ### Step 1: Spec Initiation 24 | 25 | Use the context-fetcher subagent to identify spec initiation method by either finding the next uncompleted roadmap item when user asks "what's next?" or accepting a specific spec idea from the user. 26 | 27 | 28 | 29 | - "what's next?" 30 | 31 | 32 | 1. CHECK @.agent-os/product/roadmap.md 33 | 2. FIND next uncompleted item 34 | 3. SUGGEST item to user 35 | 4. WAIT for approval 36 | 37 | 38 | 39 | 40 | user describes specific spec idea 41 | any format, length, or detail level 42 | to context gathering 43 | 44 | 45 | 46 | 47 | 48 | 49 | ### Step 2: Context Gathering (Conditional) 50 | 51 | Use the context-fetcher subagent to read @.agent-os/product/mission-lite.md and @.agent-os/product/tech-stack.md only if not already in context to ensure minimal context for spec alignment. 52 | 53 | 54 | IF both mission-lite.md AND tech-stack.md already read in current context: 55 | SKIP this entire step 56 | PROCEED to step 3 57 | ELSE: 58 | READ only files not already in context: 59 | - mission-lite.md (if not in context) 60 | - tech-stack.md (if not in context) 61 | CONTINUE with context analysis 62 | 63 | 64 | 65 | core product purpose and value 66 | technical requirements 67 | 68 | 69 | 70 | 71 | 72 | 73 | ### Step 3: Requirements Clarification 74 | 75 | Use the context-fetcher subagent to clarify scope boundaries and technical considerations by asking numbered questions as needed to ensure clear requirements before proceeding. 76 | 77 | 78 | 79 | - in_scope: what is included 80 | - out_of_scope: what is excluded (optional) 81 | 82 | 83 | - functionality specifics 84 | - UI/UX requirements 85 | - integration points 86 | 87 | 88 | 89 | 90 | IF clarification_needed: 91 | ASK numbered_questions 92 | WAIT for_user_response 93 | ELSE: 94 | PROCEED to_date_determination 95 | 96 | 97 | 98 | 99 | 100 | 101 | ### Step 4: Date Determination 102 | 103 | Use the date-checker subagent to determine the current date in YYYY-MM-DD format for folder naming. The subagent will output today's date which will be used in subsequent steps. 104 | 105 | 106 | The date-checker subagent will provide the current date in YYYY-MM-DD format at the end of its response. Store this date for use in folder naming in step 5. 107 | 108 | 109 | 110 | 111 | 112 | 113 | ### Step 5: Spec Folder Creation 114 | 115 | Use the file-creator subagent to create directory: .agent-os/specs/YYYY-MM-DD-spec-name/ using the date from step 4. 116 | 117 | Use kebab-case for spec name. Maximum 5 words in name. 118 | 119 | 120 | YYYY-MM-DD-spec-name 121 | use stored date from step 4 122 | 123 | - max_words: 5 124 | - style: kebab-case 125 | - descriptive: true 126 | 127 | 128 | 129 | 130 | - 2025-03-15-password-reset-flow 131 | - 2025-03-16-user-profile-dashboard 132 | - 2025-03-17-api-rate-limiting 133 | 134 | 135 | 136 | 137 | 138 | 139 | ### Step 6: Create spec.md 140 | 141 | Use the file-creator subagent to create the file: .agent-os/specs/YYYY-MM-DD-spec-name/spec.md using this template: 142 | 143 | 144 |
145 | # Spec Requirements Document 146 | 147 | > Spec: [SPEC_NAME] 148 | > Created: [CURRENT_DATE] 149 |
150 | 151 | - Overview 152 | - User Stories 153 | - Spec Scope 154 | - Out of Scope 155 | - Expected Deliverable 156 | 157 | 158 | 159 |
160 | 165 | 166 | - length: 1-2 sentences 167 | - content: goal and objective 168 | 169 | 170 | Implement a secure password reset functionality that allows users to regain account access through email verification. This feature will reduce support ticket volume and improve user experience by providing self-service account recovery. 171 | 172 |
173 | 174 |
175 | 184 | 185 | - count: 1-3 stories 186 | - include: workflow and problem solved 187 | - format: title + story + details 188 | 189 |
190 | 191 |
192 | 198 | 199 | - count: 1-5 features 200 | - format: numbered list 201 | - description: one sentence each 202 | 203 |
204 | 205 |
206 | 212 | explicitly exclude functionalities 213 |
214 | 215 |
216 | 222 | 223 | - count: 1-3 expectations 224 | - focus: browser-testable outcomes 225 | 226 |
227 | 228 | 229 | 230 | 231 | 232 | ### Step 7: Create spec-lite.md 233 | 234 | Use the file-creator subagent to create the file: .agent-os/specs/YYYY-MM-DD-spec-name/spec-lite.md for the purpose of establishing a condensed spec for efficient AI context usage. 235 | 236 | 237 |
238 | # Spec Summary (Lite) 239 |
240 | 241 | 242 | 243 | 244 | - source: Step 6 spec.md overview section 245 | - length: 1-3 sentences 246 | - content: core goal and objective of the feature 247 | 248 | 249 | 250 | 251 | [1-3_SENTENCES_SUMMARIZING_SPEC_GOAL_AND_OBJECTIVE] 252 | 253 | 254 | 255 | Implement secure password reset via email verification to reduce support tickets and enable self-service account recovery. Users can request a reset link, receive a time-limited token via email, and set a new password following security best practices. 256 | 257 | 258 | 259 | 260 | 261 | 262 | ### Step 8: Create Technical Specification 263 | 264 | Use the file-creator subagent to create the file: sub-specs/technical-spec.md using this template: 265 | 266 | 267 |
268 | # Technical Specification 269 | 270 | This is the technical specification for the spec detailed in @.agent-os/specs/YYYY-MM-DD-spec-name/spec.md 271 |
272 | 273 | 274 | 275 | 276 | - functionality details 277 | - UI/UX specifications 278 | - integration requirements 279 | - performance criteria 280 | 281 | 282 | - only include if new dependencies needed 283 | - new libraries/packages 284 | - justification for each 285 | - version requirements 286 | 287 | 288 | 289 | 290 | ## Technical Requirements 291 | 292 | - [SPECIFIC_TECHNICAL_REQUIREMENT] 293 | - [SPECIFIC_TECHNICAL_REQUIREMENT] 294 | 295 | ## External Dependencies (Conditional) 296 | 297 | [ONLY_IF_NEW_DEPENDENCIES_NEEDED] 298 | - **[LIBRARY_NAME]** - [PURPOSE] 299 | - **Justification:** [REASON_FOR_INCLUSION] 300 | 301 | 302 | 303 | IF spec_requires_new_external_dependencies: 304 | INCLUDE "External Dependencies" section 305 | ELSE: 306 | OMIT section entirely 307 | 308 | 309 | 310 | 311 | 312 | 313 | ### Step 9: Create Database Schema (Conditional) 314 | 315 | Use the file-creator subagent to create the file: sub-specs/database-schema.md ONLY IF database changes needed for this task. 316 | 317 | 318 | IF spec_requires_database_changes: 319 | CREATE sub-specs/database-schema.md 320 | ELSE: 321 | SKIP this_step 322 | 323 | 324 | 325 |
326 | # Database Schema 327 | 328 | This is the database schema implementation for the spec detailed in @.agent-os/specs/YYYY-MM-DD-spec-name/spec.md 329 |
330 | 331 | 332 | 333 | 334 | - new tables 335 | - new columns 336 | - modifications 337 | - migrations 338 | 339 | 340 | - exact SQL or migration syntax 341 | - indexes and constraints 342 | - foreign key relationships 343 | 344 | 345 | - reason for each change 346 | - performance considerations 347 | - data integrity rules 348 | 349 | 350 | 351 | 352 | 353 | 354 | 355 | ### Step 10: Create API Specification (Conditional) 356 | 357 | Use the file-creator subagent to create file: sub-specs/api-spec.md ONLY IF API changes needed. 358 | 359 | 360 | IF spec_requires_api_changes: 361 | CREATE sub-specs/api-spec.md 362 | ELSE: 363 | SKIP this_step 364 | 365 | 366 | 367 |
368 | # API Specification 369 | 370 | This is the API specification for the spec detailed in @.agent-os/specs/YYYY-MM-DD-spec-name/spec.md 371 |
372 | 373 | 374 | 375 | 376 | - HTTP method 377 | - endpoint path 378 | - parameters 379 | - response format 380 | 381 | 382 | - action names 383 | - business logic 384 | - error handling 385 | 386 | 387 | - endpoint rationale 388 | - integration with features 389 | 390 | 391 | 392 | 393 | ## Endpoints 394 | 395 | ### [HTTP_METHOD] [ENDPOINT_PATH] 396 | 397 | **Purpose:** [DESCRIPTION] 398 | **Parameters:** [LIST] 399 | **Response:** [FORMAT] 400 | **Errors:** [POSSIBLE_ERRORS] 401 | 402 | 403 | 404 | 405 | 406 | 407 | ### Step 11: User Review 408 | 409 | Request user review of spec.md and all sub-specs files, waiting for approval or revision requests. 410 | 411 | 412 | I've created the spec documentation: 413 | 414 | - Spec Requirements: @.agent-os/specs/YYYY-MM-DD-spec-name/spec.md 415 | - Spec Summary: @.agent-os/specs/YYYY-MM-DD-spec-name/spec-lite.md 416 | - Technical Spec: @.agent-os/specs/YYYY-MM-DD-spec-name/sub-specs/technical-spec.md 417 | [LIST_OTHER_CREATED_SPECS] 418 | 419 | Please review and let me know if any changes are needed. 420 | 421 | When you're ready, run the /create-tasks command to have me build the tasks checklist from this spec. 422 | 423 | 424 | 425 | 426 | 427 | 428 | 429 | EXECUTE: @.agent-os/instructions/meta/post-flight.md 430 | 431 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to Agent OS will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 7 | 8 | ## [1.4.1] - 2025-08-18 9 | 10 | ### Replaced Decisions with Recaps 11 | 12 | Earlier versions added a decisions.md inside a project's .agent-os/product/. In practice, this was rarely used and didn't help future development. 13 | 14 | It's been replaced with a new system for creating "Recaps"—short summaries of what was built—after every feature spec's implementation has been completed. Similar to a changelog, but more descriptive and context-focused. These recaps are easy to reference by both humans and AI agents. 15 | 16 | Recaps are automatically generated via the new complete-tasks.md process. 17 | 18 | ### Added Project-Manager Subagent 19 | 20 | A goal of this update was to tighten up the processes for creating specs and executing tasks, ensuring these processes are executed reliably. Sounds like the job for a "project manager". 21 | 22 | This update introduces a new subagent (for Claude Code) called project-manager which handles all task completion, status updates, and reporting progress back to you. 23 | 24 | ### Spec Creation & Task Execution Reliability Improvements 25 | 26 | Several changes to the instructions, processes, and executions, all aimed at helping agents follow the process steps consistently. 27 | 28 | - Consolidated task execution instructions with clear step-by-step processes 29 | - Added post-flight verification rules to ensure instruction compliance 30 | - Improved subagent delegation tracking and reporting 31 | - Standardized test suite verification and git workflow integration 32 | - Enhanced task completion criteria validation and status management 33 | 34 | ## [1.4.0] - 2025-08-17 35 | 36 | BIG updates in this one! Thanks for all the feedback, requests and support 🙏 37 | 38 | ### All New Installation Process 39 | 40 | The way Agent OS gets installed is structured differently from prior versions. The new system works as follows: 41 | 42 | There are 2 installation processes: 43 | - Your "Base installation" (now optional, but still recommended!) 44 | - Your "Project installation" 45 | 46 | **"Base installation"** 47 | - Installs all of the Agent OS files to a location of your choosing on your system where they can be customized (especially your standards) and maintained. 48 | - Project installations copy files from your base installation, so they can be customized and self-contained within each individual project. 49 | - Your base installation now has a config.yml 50 | 51 | To install the Agent OS base installation, 52 | 53 | 1. cd to a location of your choice (your system's home folder is a good choice). 54 | 55 | 2. Run one of these commands: 56 | - Agent OS with Claude Code support: 57 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --claude-code` 58 | - Agent OS with Cursor support: 59 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --cursor` 60 | - Agent OS with Claude Code & Cursor support: 61 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --claude-code --cursor` 62 | 63 | 3. Customize your /standards (just like earlier versions) 64 | 65 | **Project installation** 66 | 67 | - Now each project codebase gets it's own self-contained installation of Agent OS. It no longer references instructions or standards that reside elsewhere on your system. These all get installed directly into your project's .agent-os folder, which brings several benefits: 68 | - No external references = more reliable Agent OS commands & workflows. 69 | - You can commit your instructions, standards, Claude Code commands and agents to your project's github repo for team access. 70 | - You can customize standards differently per project than what's in your base installation. 71 | 72 | Your project installation command will be based on where you installed the Agent OS base installation. 73 | - If you've installed it to your system's home folder, then your project installation command will be `~/.agent-os/setup/project.sh`. 74 | - If you've installed it elsewhere, your command will be `/path/to/agent-os/setup/project.sh` 75 | (after your base installation, it will show you _your_ project installation command. It's a good idea to save it or make an alias if you work on many projects.) 76 | 77 | If (for whatever reason) you didn't install the base installation, you can still install Agent OS directly into a project, by pulling it directly off of the public github repo using the following command. 78 | - Note: This means your standards folder won't inherit your defaults from a base installation. You'd need to customize the files in the standards folder for this project. 79 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/project.sh | bash -s -- --no-base --claude-code --cursor` 80 | 81 | ### Agent OS config.yml 82 | 83 | When you install the Agent OS base installation, that now includes a config.yml file. Currently this file is used for: 84 | - Tracking the Agent OS version you have installed 85 | - Which coding agents (Claude Code, Cursor) you're using 86 | - Project Types (new! read on...) 87 | 88 | ### Project Types 89 | 90 | If you work on different types of projects, you can define different sets of standards, code style, and instructions for each! 91 | 92 | - By default, a new installation of Agent OS into a project will copy its instructions and standards from your base installation's /instructions and /standards. 93 | - You can define additional project types by doing the following: 94 | - Setup a folder (typically inside your base installation's .agent-os folder, but it can be anywhere on your system) which contains /instructions and /standards folders (copy these from your base install, then customize). 95 | - Define the project type's folder location on your system in your base install's config.yml 96 | - Using project types: 97 | - If you've named a project type, 'ruby-on-rails', when running your project install command, add the flag --project-type=ruby-on-rails. 98 | - To make a project type your default for new projects, set it's name as the value for default_project_type in config.yml 99 | 100 | ### Removed or changed in version 1.4.0: 101 | 102 | This update does away with the old installation script files: 103 | - setup.sh (replaced by /setup/base.sh and /setup/project.sh) 104 | - setup-claude-code.sh (now you add --claude-code flag to the install commands or enable it in your Agent OS config.yml) 105 | - setup-cursor.sh (now you add --cursor flag to the install commands or enable it in your Agent OS config.yml) 106 | 107 | Claude Code Agent OS commands now should _not_ be installed in the `~/.agent-os/.claude/commands` folder. Now, these are copied from ~/.agent-os/commands into each project's `~/.claude/commands` folder (this prevents duplicate commands showing in in Claude Code's commands list). The same approach applies to Claude Code subagents files. 108 | 109 | ### Upgrading to version 1.4.0 110 | 111 | Follow these steps to update a previous version to 1.4.0: 112 | 113 | 1. If you've customized any files in /instructions, back those up now. They will be overwritten. 114 | 115 | 2. Navigate to your home directory (or whichever location you want to have your Agent OS base installation) 116 | 117 | 3. Run the following to command, which includes flags to overwrite your /instructions (remove the --cursor flag if not using Cursor): 118 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --overwrite-instructions --claude-code --cursor` 119 | 120 | 4. If your ~/.claude/commands contain Agent OS commands, remove those and copy the versions that are now in your base installation's commands folder into your _project's_ `.claude/commands` folder. 121 | 122 | 5. Navigate to your project. Run your project installation command to install Agent OS instructions and standards into your project's installation. If your Agent OS base installation is in your system's home folder (like previous versions), then your project installation will be: `~/.agent-os/setup/project.sh` 123 | 124 | ## [1.3.1] - 2025-08-02 125 | 126 | ### Added 127 | - **Date-Checker Subagent** - New specialized Claude Code subagent for accurate date determination using file system timestamps 128 | - Uses temporary file creation to extract current date in YYYY-MM-DD format 129 | - Includes context checking to avoid duplication 130 | - Provides clear validation and error handling 131 | 132 | ### Changed 133 | - **Create-Spec Instructions** - Updated `instructions/core/create-spec.md` to use the new date-checker subagent 134 | - Replaced complex inline date determination logic with simple subagent delegation 135 | - Simplified step 4 (date_determination) by removing 45 lines of validation and fallback code 136 | - Cleaner instruction flow with specialized agent handling date logic 137 | 138 | ### Improved 139 | - **Code Maintainability** - Date determination logic centralized in reusable subagent 140 | - **Instruction Clarity** - Simplified create-spec workflow with cleaner delegation pattern 141 | - **Error Handling** - More robust date determination with dedicated validation rules 142 | 143 | ## [1.3.0] - 2025-08-01 144 | 145 | ### Added 146 | - **Pre-flight Check System** - New `meta/pre-flight.md` instruction for centralized agent detection and initialization 147 | - **Proactive Agent Usage** - Updated agent descriptions to encourage proactive use when appropriate 148 | - **Structured Instruction Organization** - New folder structure with `core/` and `meta/` subdirectories 149 | 150 | ### Changed 151 | - **Instruction File Structure** - Reorganized all instruction files into subdirectories: 152 | - Core instructions moved to `instructions/core/` (plan-product, create-spec, execute-tasks, execute-task, analyze-product) 153 | - Meta instructions in `instructions/meta/` (pre-flight, more to come) 154 | - **Simplified XML Metadata** - Removed verbose `` and `` blocks for cleaner, more readable instructions 155 | - **Subagent Integration** - Replaced manual agent detection with centralized pre-flight check across all instruction files to enforce delegation and preserve main agent's context. 156 | - **Step Definitions** - Added `subagent` attribute to steps for clearer delegation of work to help enforce delegation and preserve main agent's context. 157 | - **Setup Script** - Updated to create subdirectories and download files to new locations 158 | 159 | ### Improved 160 | - **Code Clarity** - Removed redundant XML instructions in favor of descriptive step purposes 161 | - **Agent Efficiency** - Centralized agent detection reduces repeated checks throughout workflows 162 | - **Maintainability** - Cleaner instruction format with less XML boilerplate 163 | - **User Experience** - Clearer indication of when specialized agents will be used proactively 164 | 165 | ### Removed 166 | - **CLAUDE.md** - Removed deprecated Claude Code configuration file (functionality moved to pre-flight system, preventing over-reading instructions into context) 167 | - **Redundant Instructions** - Eliminated verbose ACTION/MODIFY/VERIFY instruction blocks 168 | 169 | ## [1.2.0] - 2025-07-29 170 | 171 | ### Added 172 | - **Claude Code Specialized Subagents** - New agents to offload specific tasks for improved efficiency: 173 | - `test-runner.md` - Handles test execution and failure analysis with minimal toolset 174 | - `context-fetcher.md` - Retrieves information from files while checking context to avoid duplication 175 | - `git-workflow.md` - Manages git operations, branches, commits, and PR creation 176 | - `file-creator.md` - Creates files, directories, and applies consistent templates 177 | - **Agent Detection Pattern** - Single check at process start with boolean flags for efficiency 178 | - **Subagent Integration** across all instruction files with automatic fallback for non-Claude Code users 179 | 180 | ### Changed 181 | - **Instruction Files** - All updated to support conditional agent usage: 182 | - `execute-tasks.md` - Uses git-workflow (branch management, PR creation), test-runner (full suite), and context-fetcher (loading lite files) 183 | - `execute-task.md` - Uses context-fetcher (best practices, code style) and test-runner (task-specific tests) 184 | - `plan-product.md` - Uses file-creator (directory creation) and context-fetcher (tech stack defaults) 185 | - `create-spec.md` - Uses file-creator (spec folder) and context-fetcher (mission/roadmap checks) 186 | - **Standards Files** - Updated for conditional agent usage: 187 | - `code-style.md` - Uses context-fetcher for loading language-specific style guides 188 | - **Setup Scripts** - Enhanced to install Claude Code agents: 189 | - `setup-claude-code.sh` - Downloads all agents to `~/.claude/agents/` directory 190 | 191 | ### Improved 192 | - **Context Efficiency** - Specialized agents use minimal context for their specific tasks 193 | - **Code Organization** - Complex operations delegated to focused agents with clear responsibilities 194 | - **Error Handling** - Agents provide targeted error analysis and recovery strategies 195 | - **Maintainability** - Cleaner main agent code with operations abstracted to subagents 196 | - **Performance** - Reduced context checks through one-time agent detection pattern 197 | 198 | ### Technical Details 199 | - Each agent uses only necessary tools (e.g., test-runner uses only Bash, Read, Grep, Glob) 200 | - Automatic fallback ensures compatibility for users without Claude Code 201 | - Consistent `IF has_[agent_name]:` pattern reduces code complexity 202 | - All agents follow Agent OS conventions (branch naming, commit messages, file templates) 203 | 204 | ## [1.1.0] - 2025-07-29 205 | 206 | ### Added 207 | - New `mission-lite.md` file generation in product initialization for efficient AI context usage 208 | - New `spec-lite.md` file generation in spec creation for condensed spec summaries 209 | - New `execute-task.md` instruction file for individual task execution with TDD workflow 210 | - Task execution loop in `execute-tasks.md` that calls `execute-task.md` for each parent task 211 | - Language-specific code style guides: 212 | - `standards/code-style/css-style.md` for CSS and TailwindCSS 213 | - `standards/code-style/html-style.md` for HTML markup 214 | - `standards/code-style/javascript-style.md` for JavaScript 215 | - Conditional loading blocks in `best-practices.md` and `code-style.md` to prevent duplicate context loading 216 | - Context-aware file loading throughout all instruction files 217 | 218 | ### Changed 219 | - Optimized `plan-product.md` to generate condensed versions of documents 220 | - Enhanced `create-spec.md` with conditional context loading for mission-lite and tech-stack files 221 | - Simplified technical specification structure by removing multiple approach options 222 | - Made external dependencies section conditional in technical specifications 223 | - Updated `execute-tasks.md` to use minimal context loading strategy 224 | - Improved `execute-task.md` with selective reading of relevant documentation sections 225 | - Modified roadmap progress check to be conditional and context-aware 226 | - Updated decision documentation to avoid loading decisions.md and use conditional checks 227 | - Restructured task execution to follow typical TDD pattern (tests first, implementation, verification) 228 | 229 | ### Improved 230 | - Context efficiency by 60-80% through conditional loading and lite file versions 231 | - Reduced duplication when files are referenced multiple times in a workflow 232 | - Clearer separation between task-specific and full test suite execution 233 | - More intelligent file loading that checks current context before reading 234 | - Better organization of code style rules with language-specific files 235 | 236 | ### Fixed 237 | - Duplicate content loading when instruction files are called in loops 238 | - Unnecessary loading of full documentation files when condensed versions suffice 239 | - Redundant test suite runs between individual task execution and overall workflow 240 | 241 | ## [1.0.0] - 2025-07-21 242 | 243 | ### Added 244 | - Initial release of Agent OS framework 245 | - Core instruction files: 246 | - `plan-product.md` for product initialization 247 | - `create-spec.md` for feature specification 248 | - `execute-tasks.md` for task execution 249 | - `analyze-product.md` for existing codebase analysis 250 | - Standard files: 251 | - `tech-stack.md` for technology choices 252 | - `code-style.md` for formatting rules 253 | - `best-practices.md` for development guidelines 254 | - Product documentation structure: 255 | - `mission.md` for product vision 256 | - `roadmap.md` for development phases 257 | - `decisions.md` for decision logging 258 | - `tech-stack.md` for technical architecture 259 | - Setup scripts for easy installation 260 | - Integration with AI coding assistants (Claude Code, Cursor) 261 | - Task management with TDD workflow 262 | - Spec creation and organization system 263 | 264 | [1.4.1]: https://github.com/buildermethods/agent-os/compare/v1.4.0...v1.4.1 265 | [1.4.0]: https://github.com/buildermethods/agent-os/compare/v1.3.1...v1.4.0 266 | [1.3.1]: https://github.com/buildermethods/agent-os/compare/v1.3.0...v1.3.1 267 | [1.3.0]: https://github.com/buildermethods/agent-os/compare/v1.2.0...v1.3.0 268 | [1.2.0]: https://github.com/buildermethods/agent-os/compare/v1.1.0...v1.2.0 269 | [1.1.0]: https://github.com/buildermethods/agent-os/compare/v1.0.0...v1.1.0 270 | [1.0.0]: https://github.com/buildermethods/agent-os/releases/tag/v1.0.0 271 | --------------------------------------------------------------------------------