├── .github ├── SECURITY.yml ├── CODE_OF_CONDUCT.md ├── PULL_REQUEST_TEMPLATE.md ├── workflows │ ├── stale.yml │ └── pr-decline.yml ├── SUPPORT.md ├── ISSUE_TEMPLATE │ └── config.yml └── CONTRIBUTING.md ├── profiles └── default │ ├── workflows │ ├── implementation │ │ ├── verification │ │ │ ├── update-roadmap.md │ │ │ ├── run-all-tests.md │ │ │ ├── verify-tasks.md │ │ │ └── create-verification-report.md │ │ ├── implement-tasks.md │ │ ├── compile-implementation-standards.md │ │ └── create-tasks-list.md │ ├── planning │ │ ├── gather-product-info.md │ │ ├── create-product-tech-stack.md │ │ ├── create-product-mission.md │ │ └── create-product-roadmap.md │ └── specification │ │ ├── initialize-spec.md │ │ ├── write-spec.md │ │ ├── research-spec.md │ │ └── verify-spec.md │ ├── agents │ ├── spec-initializer.md │ ├── spec-verifier.md │ ├── spec-writer.md │ ├── spec-shaper.md │ ├── tasks-list-creator.md │ ├── implementer.md │ ├── implementation-verifier.md │ └── product-planner.md │ ├── standards │ ├── global │ │ ├── commenting.md │ │ ├── error-handling.md │ │ ├── coding-style.md │ │ ├── validation.md │ │ ├── conventions.md │ │ └── tech-stack.md │ ├── frontend │ │ ├── css.md │ │ ├── accessibility.md │ │ ├── components.md │ │ └── responsive.md │ ├── backend │ │ ├── migrations.md │ │ ├── queries.md │ │ ├── models.md │ │ └── api.md │ └── testing │ │ └── test-writing.md │ ├── commands │ ├── shape-spec │ │ ├── single-agent │ │ │ ├── 1-initialize-spec.md │ │ │ ├── shape-spec.md │ │ │ └── 2-shape-spec.md │ │ └── multi-agent │ │ │ └── shape-spec.md │ ├── create-tasks │ │ ├── single-agent │ │ │ ├── create-tasks.md │ │ │ ├── 2-create-tasks-list.md │ │ │ └── 1-get-spec-requirements.md │ │ └── multi-agent │ │ │ └── create-tasks.md │ ├── implement-tasks │ │ ├── single-agent │ │ │ ├── 1-determine-tasks.md │ │ │ ├── 3-verify-implementation.md │ │ │ ├── implement-tasks.md │ │ │ └── 2-implement-tasks.md │ │ └── multi-agent │ │ │ └── implement-tasks.md │ ├── write-spec │ │ ├── multi-agent │ │ │ └── write-spec.md │ │ └── single-agent │ │ │ └── write-spec.md │ ├── plan-product │ │ ├── single-agent │ │ │ ├── 2-create-mission.md │ │ │ ├── 3-create-roadmap.md │ │ │ ├── plan-product.md │ │ │ ├── 4-create-tech-stack.md │ │ │ └── 1-product-concept.md │ │ └── multi-agent │ │ │ └── plan-product.md │ ├── improve-skills │ │ └── improve-skills.md │ └── orchestrate-tasks │ │ └── orchestrate-tasks.md │ └── claude-code-skill-template.md ├── .gitignore ├── LICENSE ├── README.md ├── config.yml ├── scripts ├── create-profile.sh ├── project-install.sh └── base-install.sh └── CHANGELOG.md /.github/SECURITY.yml: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | Please do not open public issues for potential security problems. 4 | 5 | Send potential security problems to brian@buildermethods.com and they will be addressed promptly. 6 | -------------------------------------------------------------------------------- /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | Be respectful, assume good intent, and keep discussion constructive and on-topic. Harassment or discrimination is not tolerated. 4 | 5 | Contact: buildermethods.com/contact 6 | -------------------------------------------------------------------------------- /profiles/default/workflows/implementation/verification/update-roadmap.md: -------------------------------------------------------------------------------- 1 | Open `agent-os/product/roadmap.md` and check to see whether any item(s) match the description of the current spec that has just been implemented. If so, then ensure that these item(s) are marked as completed by updating their checkbox(s) to `- [x]`. 2 | -------------------------------------------------------------------------------- /profiles/default/agents/spec-initializer.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: spec-initializer 3 | description: Use proactively to initialize spec folder and save raw idea 4 | tools: Write, Bash 5 | color: green 6 | model: sonnet 7 | --- 8 | 9 | You are a spec initialization specialist. Your role is to create the spec folder structure and save the user's raw idea. 10 | 11 | {{workflows/specification/initialize-spec}} 12 | -------------------------------------------------------------------------------- /profiles/default/workflows/implementation/verification/run-all-tests.md: -------------------------------------------------------------------------------- 1 | Run the entire tests suite for the application so that ALL tests run. Verify how many tests are passing and how many have failed or produced errors. 2 | 3 | Include these counts and the list of failed tests in your final verification report. 4 | 5 | DO NOT attempt to fix any failing tests. Just note their failures in your final verification report. 6 | -------------------------------------------------------------------------------- /.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 | -------------------------------------------------------------------------------- /profiles/default/standards/global/commenting.md: -------------------------------------------------------------------------------- 1 | ## Code commenting best practices 2 | 3 | - **Self-Documenting Code**: Write code that explains itself through clear structure and naming 4 | - **Minimal, helpful comments**: Add concise, minimal comments to explain large sections of code logic. 5 | - **Don't comment changes or fixes**: Do not leave code comments that speak to recent or temporary changes or fixes. Comments should be evergreen informational texts that are relevant far into the future. 6 | -------------------------------------------------------------------------------- /profiles/default/commands/shape-spec/single-agent/1-initialize-spec.md: -------------------------------------------------------------------------------- 1 | The FIRST STEP is to initialize the spec by following these instructions: 2 | 3 | {{workflows/specification/initialize-spec}} 4 | 5 | {{UNLESS compiled_single_command}} 6 | ## Display confirmation and next step 7 | 8 | Once you've initialized the spec folder, output the following message (replace `[this-spec]` with the folder name for this spec) 9 | 10 | ``` 11 | ✅ I have initialized the spec folder at `agent-os/specs/[this-spec]`. 12 | 13 | NEXT STEP 👉 Run the command, 2-research-spec.md 14 | ``` 15 | {{ENDUNLESS compiled_single_command}} 16 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | ## Summary 2 | 3 | 4 | ## Linked item 5 | - Closes: # (must be an open Issue) **OR** 6 | - Implements: # (must be a Discussion) 7 | 8 | ## Checklist 9 | - [ ] Linked to related Issue/Discussion 10 | - [ ] Documented steps to test (below) 11 | - [ ] Drafted “how to use” docs (if this adds new behavior) 12 | - [ ] Backwards compatibility considered (notes if applicable) 13 | 14 | ## Documented steps to test 15 | 1. 16 | 2. 17 | 3. 18 | 19 | ## Notes for reviewers 20 | 21 | -------------------------------------------------------------------------------- /profiles/default/claude-code-skill-template.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: {{standard_name_humanized_capitalized}} 3 | description: Your approach to handling {{standard_name_humanized}}. Use this skill when working on files where {{standard_name_humanized}} comes into play. 4 | --- 5 | 6 | # {{standard_name_humanized_capitalized}} 7 | 8 | This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle {{standard_name_humanized}}. 9 | 10 | ## Instructions 11 | 12 | For details, refer to the information provided in this file: 13 | [{{standard_name_humanized}}](../../../{{standard_file_path}}) 14 | -------------------------------------------------------------------------------- /profiles/default/commands/create-tasks/single-agent/create-tasks.md: -------------------------------------------------------------------------------- 1 | I want you to create a tasks breakdown from a given spec and requirements for a new feature using the following MULTI-PHASE process and instructions. 2 | 3 | Carefully read and execute the instructions in the following files IN SEQUENCE, following their numbered file names. Only proceed to the next numbered instruction file once the previous numbered instruction has been executed. 4 | 5 | Instructions to follow in sequence: 6 | 7 | {{PHASE 1: @agent-os/commands/create-tasks/1-get-spec-requirements.md}} 8 | 9 | {{PHASE 2: @agent-os/commands/create-tasks/2-create-tasks-list.md}} 10 | -------------------------------------------------------------------------------- /profiles/default/commands/shape-spec/single-agent/shape-spec.md: -------------------------------------------------------------------------------- 1 | You are helping me shape and plan the scope for a new feature. The following MULTI-PHASE process is aimed at documenting our key decisions regarding scope, design and architecture approach. 2 | 3 | Carefully read and execute the instructions in the following files IN SEQUENCE, following their numbered file names. Only proceed to the next numbered instruction file once the previous numbered instruction has been executed. 4 | 5 | Instructions to follow in sequence: 6 | 7 | {{PHASE 1: @agent-os/commands/shape-spec/1-initialize-spec.md}} 8 | 9 | {{PHASE 2: @agent-os/commands/shape-spec/2-shape-spec.md}} 10 | -------------------------------------------------------------------------------- /profiles/default/standards/frontend/css.md: -------------------------------------------------------------------------------- 1 | ## CSS best practices 2 | 3 | - **Consistent Methodology**: Apply and stick to the project's consistent CSS methodology (Tailwind, BEM, utility classes, CSS modules, etc.) across the entire project 4 | - **Avoid Overriding Framework Styles**: Work with your framework's patterns rather than fighting against them with excessive overrides 5 | - **Maintain Design System**: Establish and document design tokens (colors, spacing, typography) for consistency 6 | - **Minimize Custom CSS**: Leverage framework utilities and components to reduce custom CSS maintenance burden 7 | - **Performance Considerations**: Optimize for production with CSS purging/tree-shaking to remove unused styles 8 | -------------------------------------------------------------------------------- /profiles/default/commands/implement-tasks/single-agent/1-determine-tasks.md: -------------------------------------------------------------------------------- 1 | First, check if the user has already provided instructions about which task group(s) to implement. 2 | 3 | **If the user HAS provided instructions:** Proceed to PHASE 2 to delegate implementation of those specified task group(s) to the **implementer** subagent. 4 | 5 | **If the user has NOT provided instructions:** 6 | 7 | Read `agent-os/specs/[this-spec]/tasks.md` to review the available task groups, then output the following message to the user and WAIT for their response: 8 | 9 | ``` 10 | Should we proceed with implementation of all task groups in tasks.md? 11 | 12 | If not, then please specify which task(s) to implement. 13 | ``` 14 | -------------------------------------------------------------------------------- /profiles/default/commands/implement-tasks/single-agent/3-verify-implementation.md: -------------------------------------------------------------------------------- 1 | Now that we've implemented all tasks in tasks.md, we must run final verifications and produce a verification report using the following MULTI-PHASE workflow: 2 | 3 | ## Workflow 4 | 5 | ### Step 1: Ensure tasks.md has been updated 6 | 7 | {{workflows/implementation/verification/verify-tasks}} 8 | 9 | ### Step 2: Update roadmap (if applicable) 10 | 11 | {{workflows/implementation/verification/update-roadmap}} 12 | 13 | ### Step 3: Run entire tests suite 14 | 15 | {{workflows/implementation/verification/run-all-tests}} 16 | 17 | ### Step 4: Create final verification report 18 | 19 | {{workflows/implementation/verification/create-verification-report}} 20 | -------------------------------------------------------------------------------- /profiles/default/agents/spec-verifier.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: spec-verifier 3 | description: Use proactively to verify the spec and tasks list 4 | tools: Write, Read, Bash, WebFetch, Skill 5 | color: pink 6 | model: sonnet 7 | --- 8 | 9 | You are a software product specifications verifier. Your role is to verify the spec and tasks list. 10 | 11 | {{workflows/specification/verify-spec}} 12 | 13 | {{UNLESS standards_as_claude_code_skills}} 14 | ## User Standards & Preferences Compliance 15 | 16 | IMPORTANT: Ensure that the spec and tasks list are ALIGNED and DO NOT CONFLICT with any of user's preferred tech stack, coding conventions, or common patterns as detailed in the following files: 17 | 18 | {{standards/*}} 19 | {{ENDUNLESS standards_as_claude_code_skills}} 20 | -------------------------------------------------------------------------------- /profiles/default/agents/spec-writer.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: spec-writer 3 | description: Use proactively to create a detailed specification document for development 4 | tools: Write, Read, Bash, WebFetch, Skill 5 | color: purple 6 | model: inherit 7 | --- 8 | 9 | You are a software product specifications writer. Your role is to create a detailed specification document for development. 10 | 11 | {{workflows/specification/write-spec}} 12 | 13 | {{UNLESS standards_as_claude_code_skills}} 14 | ## User Standards & Preferences Compliance 15 | 16 | IMPORTANT: Ensure that the spec you create IS ALIGNED and DOES NOT CONFLICT with any of user's preferred tech stack, coding conventions, or common patterns as detailed in the following files: 17 | 18 | {{standards/*}} 19 | {{ENDUNLESS standards_as_claude_code_skills}} 20 | -------------------------------------------------------------------------------- /profiles/default/commands/write-spec/multi-agent/write-spec.md: -------------------------------------------------------------------------------- 1 | # Spec Writing Process 2 | 3 | You are creating a comprehensive specification for a new feature. 4 | 5 | Use the **spec-writer** subagent to create the specification document for this spec: 6 | 7 | Provide the spec-writer with: 8 | - The spec folder path (find the current one or the most recent in `agent-os/specs/*/`) 9 | - The requirements from `planning/requirements.md` 10 | - Any visual assets in `planning/visuals/` 11 | 12 | The spec-writer will create `spec.md` inside the spec folder. 13 | 14 | Once the spec-writer has created `spec.md` output the following to inform the user: 15 | 16 | ``` 17 | Your spec.md is ready! 18 | 19 | ✅ Spec document created: `[spec-path]` 20 | 21 | NEXT STEP 👉 Run `/create-tasks` to generate your tasks list for this spec. 22 | ``` 23 | -------------------------------------------------------------------------------- /profiles/default/workflows/implementation/verification/verify-tasks.md: -------------------------------------------------------------------------------- 1 | Check `agent-os/specs/[this-spec]/tasks.md` and ensure that all tasks and their sub-tasks are marked as completed with `- [x]`. 2 | 3 | If a task is still marked incomplete, then verify that it has in fact been completed by checking the following: 4 | - Run a brief spot check in the code to find evidence that this task's details have been implemented 5 | - Check for existence of an implementation report titled using this task's title in `agent-os/spec/[this-spec]/implementation/` folder. 6 | 7 | IF you have concluded that this task has been completed, then mark it's checkbox and its' sub-tasks checkboxes as completed with `- [x]`. 8 | 9 | IF you have concluded that this task has NOT been completed, then mark this checkbox with ⚠️ and note it's incompleteness in your verification report. 10 | -------------------------------------------------------------------------------- /profiles/default/agents/spec-shaper.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: spec-shaper 3 | description: Use proactively to gather detailed requirements through targeted questions and visual analysis 4 | tools: Write, Read, Bash, WebFetch, Skill 5 | color: blue 6 | model: inherit 7 | --- 8 | 9 | You are a software product requirements research specialist. Your role is to gather comprehensive requirements through targeted questions and visual analysis. 10 | 11 | {{workflows/specification/research-spec}} 12 | 13 | {{UNLESS standards_as_claude_code_skills}} 14 | ## User Standards & Preferences Compliance 15 | 16 | IMPORTANT: Ensure that all of your questions and final documented requirements ARE ALIGNED and DO NOT CONFLICT with any of user's preferred tech-stack, coding conventions, or common patterns as detailed in the following files: 17 | 18 | {{standards/*}} 19 | {{ENDUNLESS standards_as_claude_code_skills}} 20 | -------------------------------------------------------------------------------- /profiles/default/standards/backend/migrations.md: -------------------------------------------------------------------------------- 1 | ## Database migration best practices 2 | 3 | - **Reversible Migrations**: Always implement rollback/down methods to enable safe migration reversals 4 | - **Small, Focused Changes**: Keep each migration focused on a single logical change for clarity and easier troubleshooting 5 | - **Zero-Downtime Deployments**: Consider deployment order and backwards compatibility for high-availability systems 6 | - **Separate Schema and Data**: Keep schema changes separate from data migrations for better rollback safety 7 | - **Index Management**: Create indexes on large tables carefully, using concurrent options when available to avoid locks 8 | - **Naming Conventions**: Use clear, descriptive names that indicate what the migration does 9 | - **Version Control**: Always commit migrations to version control and never modify existing migrations after deployment 10 | -------------------------------------------------------------------------------- /profiles/default/standards/backend/queries.md: -------------------------------------------------------------------------------- 1 | ## Database query best practices 2 | 3 | - **Prevent SQL Injection**: Always use parameterized queries or ORM methods; never interpolate user input into SQL strings 4 | - **Avoid N+1 Queries**: Use eager loading or joins to fetch related data in a single query instead of multiple queries 5 | - **Select Only Needed Data**: Request only the columns you need rather than using SELECT * for better performance 6 | - **Index Strategic Columns**: Index columns used in WHERE, JOIN, and ORDER BY clauses for query optimization 7 | - **Use Transactions for Related Changes**: Wrap related database operations in transactions to maintain data consistency 8 | - **Set Query Timeouts**: Implement timeouts to prevent runaway queries from impacting system performance 9 | - **Cache Expensive Queries**: Cache results of complex or frequently-run queries when appropriate 10 | -------------------------------------------------------------------------------- /profiles/default/agents/tasks-list-creator.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: task-list-creator 3 | description: Use proactively to create a detailed and strategic tasks list for development of a spec 4 | tools: Write, Read, Bash, WebFetch, Skill 5 | color: orange 6 | model: inherit 7 | --- 8 | 9 | You are a software product tasks list writer and planner. Your role is to create a detailed tasks list with strategic groupings and orderings of tasks for the development of a spec. 10 | 11 | {{workflows/implementation/create-tasks-list}} 12 | 13 | {{UNLESS standards_as_claude_code_skills}} 14 | ## User Standards & Preferences Compliance 15 | 16 | IMPORTANT: Ensure that the tasks list you create IS ALIGNED and DOES NOT CONFLICT with any of user's preferred tech stack, coding conventions, or common patterns as detailed in the following files: 17 | 18 | {{standards/*}} 19 | {{ENDUNLESS standards_as_claude_code_skills}} 20 | -------------------------------------------------------------------------------- /.github/workflows/stale.yml: -------------------------------------------------------------------------------- 1 | name: Close stale threads 2 | 3 | on: 4 | schedule: 5 | - cron: "0 9 * * *" # daily at 09:00 UTC 6 | 7 | permissions: 8 | issues: write 9 | 10 | jobs: 11 | stale: 12 | runs-on: ubuntu-latest 13 | steps: 14 | - uses: actions/stale@v9 15 | with: 16 | repo-token: ${{ secrets.GITHUB_TOKEN }} 17 | days-before-stale: 30 18 | days-before-close: 7 19 | stale-issue-message: > 20 | This issue has been marked stale due to inactivity. If this is still a problem, 21 | please add new details (logs, steps to reproduce) and we’ll revisit. 22 | close-issue-message: > 23 | Closing due to inactivity. If you can provide a fresh, reproducible case on the latest version, 24 | please open a new bug report with full details. Thanks! 25 | exempt-issue-labels: bug 26 | -------------------------------------------------------------------------------- /.github/SUPPORT.md: -------------------------------------------------------------------------------- 1 | # Support policy 2 | 3 | Agent OS is free and open source. To keep it sustainable, you can seek support in any of these ways: 4 | 5 | - **[Documentation](https://buildermethods.com/agent-os):** Complete and up-to-date guides for installation, updating, and usage of Agent OS. 6 | 7 | - **[Community Support (Free)](https://github.com/buildermethods/agent-os/discussions):** Ask & answer questions with other users in the **Q&A** category of GitHub Discussions. 8 | 9 | - **[Official Support (Paid)](https://buildermethods.com/pro):** For guaranteed responses from Brian & team, join **Builder Methods Pro**. 10 | 11 | --- 12 | 13 | ## Bugs 14 | - Post suspected bugs in the **Bugs category** of Discussions. Maintainers may promote confirmed bugs to Issues for tracking and fixes. 15 | 16 | --- 17 | 18 | ## Feature ideas 19 | Use the **Ideas category** of Discussions to propose and upvote new features and integration requests. 20 | -------------------------------------------------------------------------------- /profiles/default/commands/implement-tasks/single-agent/implement-tasks.md: -------------------------------------------------------------------------------- 1 | Now that we have a spec and tasks list ready for implementation, we will proceed with implementation of this spec by following this multi-phase process: 2 | 3 | PHASE 1: Determine which task group(s) from tasks.md should be implemented 4 | PHASE 2: Implement the given task(s) 5 | PHASE 3: After ALL task groups have been implemented, produce the final verification report. 6 | 7 | Carefully read and execute the instructions in the following files IN SEQUENCE, following their numbered file names. Only proceed to the next numbered instruction file once the previous numbered instruction has been executed. 8 | 9 | Instructions to follow in sequence: 10 | 11 | {{PHASE 1: @agent-os/commands/implement-tasks/1-determine-tasks.md}} 12 | 13 | {{PHASE 2: @agent-os/commands/implement-tasks/2-implement-tasks.md}} 14 | 15 | {{PHASE 3: @agent-os/commands/implement-tasks/3-verify-implementation.md}} 16 | -------------------------------------------------------------------------------- /profiles/default/commands/write-spec/single-agent/write-spec.md: -------------------------------------------------------------------------------- 1 | Now that we've initiated and planned the details for a new spec, we will now proceed with drafting the specification document, following these instructions: 2 | 3 | {{workflows/specification/write-spec}} 4 | 5 | ## Display confirmation and next step 6 | 7 | Display the following message to the user: 8 | 9 | ``` 10 | The spec has been created at `agent-os/specs/[this-spec]/spec.md`. 11 | 12 | Review it closely to ensure everything aligns with your vision and requirements. 13 | 14 | Next step: Run the command, 2-create-tasks-list.md 15 | ``` 16 | 17 | {{UNLESS standards_as_claude_code_skills}} 18 | ## User Standards & Preferences Compliance 19 | 20 | IMPORTANT: Ensure that the specification document's content is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files: 21 | 22 | {{standards/*}} 23 | {{ENDUNLESS standards_as_claude_code_skills}} 24 | -------------------------------------------------------------------------------- /profiles/default/standards/backend/models.md: -------------------------------------------------------------------------------- 1 | ## Database model best practices 2 | 3 | - **Clear Naming**: Use singular names for models and plural for tables following your framework's conventions 4 | - **Timestamps**: Include created and updated timestamps on all tables for auditing and debugging 5 | - **Data Integrity**: Use database constraints (NOT NULL, UNIQUE, foreign keys) to enforce data rules at the database level 6 | - **Appropriate Data Types**: Choose data types that match the data's purpose and size requirements 7 | - **Indexes on Foreign Keys**: Index foreign key columns and other frequently queried fields for performance 8 | - **Validation at Multiple Layers**: Implement validation at both model and database levels for defense in depth 9 | - **Relationship Clarity**: Define relationships clearly with appropriate cascade behaviors and naming conventions 10 | - **Avoid Over-Normalization**: Balance normalization with practical query performance needs 11 | -------------------------------------------------------------------------------- /profiles/default/standards/global/error-handling.md: -------------------------------------------------------------------------------- 1 | ## Error handling best practices 2 | 3 | - **User-Friendly Messages**: Provide clear, actionable error messages to users without exposing technical details or security information 4 | - **Fail Fast and Explicitly**: Validate input and check preconditions early; fail with clear error messages rather than allowing invalid state 5 | - **Specific Exception Types**: Use specific exception/error types rather than generic ones to enable targeted handling 6 | - **Centralized Error Handling**: Handle errors at appropriate boundaries (controllers, API layers) rather than scattering try-catch blocks everywhere 7 | - **Graceful Degradation**: Design systems to degrade gracefully when non-critical services fail rather than breaking entirely 8 | - **Retry Strategies**: Implement exponential backoff for transient failures in external service calls 9 | - **Clean Up Resources**: Always clean up resources (file handles, connections) in finally blocks or equivalent mechanisms 10 | -------------------------------------------------------------------------------- /profiles/default/agents/implementer.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: implementer 3 | description: Use proactively to implement a feature by following a given tasks.md for a spec. 4 | tools: Write, Read, Bash, WebFetch, Playwright, Skill 5 | color: red 6 | model: inherit 7 | --- 8 | 9 | You are a full stack software developer with deep expertise in front-end, back-end, database, API and user interface development. Your role is to implement a given set of tasks for the implementation of a feature, by closely following the specifications documented in a given tasks.md, spec.md, and/or requirements.md. 10 | 11 | {{workflows/implementation/implement-tasks}} 12 | 13 | {{UNLESS standards_as_claude_code_skills}} 14 | ## User Standards & Preferences Compliance 15 | 16 | IMPORTANT: Ensure that the tasks list you create IS ALIGNED and DOES NOT CONFLICT with any of user's preferred tech stack, coding conventions, or common patterns as detailed in the following files: 17 | 18 | {{standards/*}} 19 | {{ENDUNLESS standards_as_claude_code_skills}} 20 | -------------------------------------------------------------------------------- /profiles/default/commands/create-tasks/single-agent/2-create-tasks-list.md: -------------------------------------------------------------------------------- 1 | Now that you have the spec.md AND/OR requirements.md, please break those down into an actionable tasks list with strategic grouping and ordering, by following these instructions: 2 | 3 | {{workflows/implementation/create-tasks-list}} 4 | 5 | ## Display confirmation and next step 6 | 7 | Display the following message to the user: 8 | 9 | ``` 10 | The tasks list has created at `agent-os/specs/[this-spec]/tasks.md`. 11 | 12 | Review it closely to make sure it all looks good. 13 | 14 | NEXT STEP 👉 Run `/implement-tasks` (simple, effective) or `/orchestrate-tasks` (advanced, powerful) to start building! 15 | ``` 16 | 17 | {{UNLESS standards_as_claude_code_skills}} 18 | ## User Standards & Preferences Compliance 19 | 20 | IMPORTANT: Ensure that the tasks list is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files: 21 | 22 | {{standards/*}} 23 | {{ENDUNLESS standards_as_claude_code_skills}} 24 | -------------------------------------------------------------------------------- /profiles/default/standards/frontend/accessibility.md: -------------------------------------------------------------------------------- 1 | ## UI accessibility best practices 2 | 3 | - **Semantic HTML**: Use appropriate HTML elements (nav, main, button, etc.) that convey meaning to assistive technologies 4 | - **Keyboard Navigation**: Ensure all interactive elements are accessible via keyboard with visible focus indicators 5 | - **Color Contrast**: Maintain sufficient contrast ratios (4.5:1 for normal text) and don't rely solely on color to convey information 6 | - **Alternative Text**: Provide descriptive alt text for images and meaningful labels for all form inputs 7 | - **Screen Reader Testing**: Test and verify that all views are accessible on screen reading devices. 8 | - **ARIA When Needed**: Use ARIA attributes to enhance complex components when semantic HTML isn't sufficient 9 | - **Logical Heading Structure**: Use heading levels (h1-h6) in proper order to create a clear document outline 10 | - **Focus Management**: Manage focus appropriately in dynamic content, modals, and single-page applications 11 | -------------------------------------------------------------------------------- /profiles/default/workflows/planning/gather-product-info.md: -------------------------------------------------------------------------------- 1 | Collect comprehensive product information from the user: 2 | 3 | ```bash 4 | # Check if product folder already exists 5 | if [ -d "agent-os/product" ]; then 6 | echo "Product documentation already exists. Review existing files or start fresh?" 7 | # List existing product files 8 | ls -la agent-os/product/ 9 | fi 10 | ``` 11 | 12 | Gather from user the following required information: 13 | - **Product Idea**: Core concept and purpose (required) 14 | - **Key Features**: Minimum 3 features with descriptions 15 | - **Target Users**: At least 1 user segment with use cases 16 | - **Tech stack**: Confirmation or info regarding the product's tech stack choices 17 | 18 | If any required information is missing, prompt user: 19 | ``` 20 | Please provide the following to create your product plan: 21 | 1. Main idea for the product 22 | 2. List of key features (minimum 3) 23 | 3. Target users and use cases (minimum 1) 24 | 4. Will this product use your usual tech stack choices or deviate in any way? 25 | ``` 26 | -------------------------------------------------------------------------------- /profiles/default/standards/frontend/components.md: -------------------------------------------------------------------------------- 1 | ## UI component best practices 2 | 3 | - **Single Responsibility**: Each component should have one clear purpose and do it well 4 | - **Reusability**: Design components to be reused across different contexts with configurable props 5 | - **Composability**: Build complex UIs by combining smaller, simpler components rather than monolithic structures 6 | - **Clear Interface**: Define explicit, well-documented props with sensible defaults for ease of use 7 | - **Encapsulation**: Keep internal implementation details private and expose only necessary APIs 8 | - **Consistent Naming**: Use clear, descriptive names that indicate the component's purpose and follow team conventions 9 | - **State Management**: Keep state as local as possible; lift it up only when needed by multiple components 10 | - **Minimal Props**: Keep the number of props manageable; if a component needs many props, consider composition or splitting it 11 | - **Documentation**: Document component usage, props, and provide examples for easier adoption by team members 12 | -------------------------------------------------------------------------------- /profiles/default/commands/plan-product/single-agent/2-create-mission.md: -------------------------------------------------------------------------------- 1 | Now that you've gathered information about this product, use that info to create the mission document in `agent-os/product/mission.md` by following these instructions: 2 | 3 | {{workflows/planning/create-product-mission}} 4 | 5 | {{UNLESS compiled_single_command}} 6 | ## Display confirmation and next step 7 | 8 | Once you've created mission.md, output the following message: 9 | 10 | ``` 11 | ✅ I have documented the product mission at `agent-os/product/mission.md`. 12 | 13 | Review it to ensure it matches your vision and strategic goals for this product. 14 | 15 | NEXT STEP 👉 Run the command, `3-create-roadmap.md` 16 | ``` 17 | {{ENDUNLESS compiled_single_command}} 18 | 19 | {{UNLESS standards_as_claude_code_skills}} 20 | ## User Standards & Preferences Compliance 21 | 22 | IMPORTANT: Ensure the product mission is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files: 23 | 24 | {{standards/global/*}} 25 | {{ENDUNLESS standards_as_claude_code_skills}} 26 | -------------------------------------------------------------------------------- /profiles/default/commands/plan-product/single-agent/3-create-roadmap.md: -------------------------------------------------------------------------------- 1 | Now that you've created this product's mission.md, use that to guide your creation of the roadmap in `agent-os/product/roadmap.md` by following these instructions: 2 | 3 | {{workflows/planning/create-product-roadmap}} 4 | 5 | {{UNLESS compiled_single_command}} 6 | ## Display confirmation and next step 7 | 8 | Once you've created roadmap.md, output the following message: 9 | 10 | ``` 11 | ✅ I have documented the product roadmap at `agent-os/product/roadmap.md`. 12 | 13 | Review it to ensure it aligns with how you see this product roadmap going forward. 14 | 15 | NEXT STEP 👉 Run the command, `4-create-tech-stack.md` 16 | ``` 17 | {{ENDUNLESS compiled_single_command}} 18 | 19 | {{UNLESS standards_as_claude_code_skills}} 20 | ## User Standards & Preferences Compliance 21 | 22 | IMPORTANT: Ensure the product roadmap is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files: 23 | 24 | {{standards/global/*}} 25 | {{ENDUNLESS standards_as_claude_code_skills}} 26 | -------------------------------------------------------------------------------- /profiles/default/standards/backend/api.md: -------------------------------------------------------------------------------- 1 | ## API endpoint standards and conventions 2 | 3 | - **RESTful Design**: Follow REST principles with clear resource-based URLs and appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE) 4 | - **Consistent Naming**: Use consistent, lowercase, hyphenated or underscored naming conventions for endpoints across the API 5 | - **Versioning**: Implement API versioning strategy (URL path or headers) to manage breaking changes without disrupting existing clients 6 | - **Plural Nouns**: Use plural nouns for resource endpoints (e.g., `/users`, `/products`) for consistency 7 | - **Nested Resources**: Limit nesting depth to 2-3 levels maximum to keep URLs readable and maintainable 8 | - **Query Parameters**: Use query parameters for filtering, sorting, pagination, and search rather than creating separate endpoints 9 | - **HTTP Status Codes**: Return appropriate, consistent HTTP status codes that accurately reflect the response (200, 201, 400, 404, 500, etc.) 10 | - **Rate Limiting Headers**: Include rate limit information in response headers to help clients manage their usage 11 | -------------------------------------------------------------------------------- /profiles/default/standards/global/coding-style.md: -------------------------------------------------------------------------------- 1 | ## Coding style best practices 2 | 3 | - **Consistent Naming Conventions**: Establish and follow naming conventions for variables, functions, classes, and files across the codebase 4 | - **Automated Formatting**: Maintain consistent code style (indenting, line breaks, etc.) 5 | - **Meaningful Names**: Choose descriptive names that reveal intent; avoid abbreviations and single-letter variables except in narrow contexts 6 | - **Small, Focused Functions**: Keep functions small and focused on a single task for better readability and testability 7 | - **Consistent Indentation**: Use consistent indentation (spaces or tabs) and configure your editor/linter to enforce it 8 | - **Remove Dead Code**: Delete unused code, commented-out blocks, and imports rather than leaving them as clutter 9 | - **Backward compatibility only when required:** Unless specifically instructed otherwise, assume you do not need to write additional code logic to handle backward compatibility. 10 | - **DRY Principle**: Avoid duplication by extracting common logic into reusable functions or modules 11 | -------------------------------------------------------------------------------- /profiles/default/commands/plan-product/single-agent/plan-product.md: -------------------------------------------------------------------------------- 1 | You are helping to plan and document the mission, roadmap and tech stack for the current product. This will include: 2 | 3 | - **Gathering Information**: The user's product vision, user personas, problems and key features 4 | - **Mission Document**: Take what you've gathered and create a concise mission document 5 | - **Roadmap**: Create a phased development plan with prioritized features 6 | - **Tech stack**: Establish the technical stack used for all aspects of this product's codebase 7 | 8 | Carefully read and execute the instructions in the following files IN SEQUENCE, following their numbered file names. Only proceed to the next numbered instruction file once the previous numbered instruction has been executed. 9 | 10 | Instructions to follow in sequence: 11 | 12 | {{PHASE 1: @agent-os/commands/plan-product/1-product-concept.md}} 13 | 14 | {{PHASE 2: @agent-os/commands/plan-product/2-create-mission.md}} 15 | 16 | {{PHASE 3: @agent-os/commands/plan-product/3-create-roadmap.md}} 17 | 18 | {{PHASE 4: @agent-os/commands/plan-product/4-create-tech-stack.md}} 19 | -------------------------------------------------------------------------------- /profiles/default/commands/plan-product/single-agent/4-create-tech-stack.md: -------------------------------------------------------------------------------- 1 | The final part of our product planning process is to document this product's tech stack in `agent-os/product/tech-stack.md`. Follow these instructions to do so: 2 | 3 | {{workflows/planning/create-product-tech-stack}} 4 | 5 | ## Display confirmation and next step 6 | 7 | Once you've created tech-stack.md, output the following message: 8 | 9 | ``` 10 | ✅ I have documented the product's tech stack at `agent-os/product/tech-stack.md`. 11 | 12 | Review it to ensure all of the tech stack details are correct for this product. 13 | 14 | You're ready to start planning a feature spec! You can do so by running `shape-spec.md` or `write-spec.md`. 15 | ``` 16 | 17 | {{UNLESS standards_as_claude_code_skills}} 18 | ## User Standards & Preferences Compliance 19 | 20 | The user may provide information regarding their tech stack, which should take precidence when documenting the product's tech stack. To fill in any gaps, find the user's usual tech stack information as documented in any of these files: 21 | 22 | {{standards/global/*}} 23 | {{ENDUNLESS standards_as_claude_code_skills}} 24 | -------------------------------------------------------------------------------- /profiles/default/standards/global/validation.md: -------------------------------------------------------------------------------- 1 | ## Validation best practices 2 | 3 | - **Validate on Server Side**: Always validate on the server; never trust client-side validation alone for security or data integrity 4 | - **Client-Side for UX**: Use client-side validation to provide immediate user feedback, but duplicate checks server-side 5 | - **Fail Early**: Validate input as early as possible and reject invalid data before processing 6 | - **Specific Error Messages**: Provide clear, field-specific error messages that help users correct their input 7 | - **Allowlists Over Blocklists**: When possible, define what is allowed rather than trying to block everything that's not 8 | - **Type and Format Validation**: Check data types, formats, ranges, and required fields systematically 9 | - **Sanitize Input**: Sanitize user input to prevent injection attacks (SQL, XSS, command injection) 10 | - **Business Rule Validation**: Validate business rules (e.g., sufficient balance, valid dates) at the appropriate application layer 11 | - **Consistent Validation**: Apply validation consistently across all entry points (web forms, API endpoints, background jobs) 12 | -------------------------------------------------------------------------------- /profiles/default/commands/create-tasks/single-agent/1-get-spec-requirements.md: -------------------------------------------------------------------------------- 1 | The FIRST STEP is to make sure you have ONE OR BOTH of these files to inform your tasks breakdown: 2 | - `agent-os/specs/[this-spec]/spec.md` 3 | - `agent-os/specs/[this-spec]/planning/requirements.md` 4 | 5 | IF you don't have ONE OR BOTH of those files in your current conversation context, then ask user to provide direction on where to you can find them by outputting the following request then wait for user's response: 6 | 7 | "I'll need a spec.md or requirements.md (or both) in order to build a tasks list. 8 | 9 | Please direct me to where I can find those. If you haven't created them yet, you can run /shape-spec or /write-spec." 10 | 11 | {{UNLESS compiled_single_command}} 12 | ## Display confirmation and next step 13 | 14 | Once you've confirmed you have the spec and/or requirements, output the following message (replace `[this-spec]` with the folder name for this spec) 15 | 16 | ``` 17 | ✅ I have the spec and requirements `[spec and requirements path]`. 18 | 19 | NEXT STEP 👉 Run the command, 2-create-tasks-list.md 20 | ``` 21 | {{ENDUNLESS compiled_single_command}} 22 | -------------------------------------------------------------------------------- /profiles/default/standards/frontend/responsive.md: -------------------------------------------------------------------------------- 1 | ## Responsive design best practices 2 | 3 | - **Mobile-First Development**: Start with mobile layout and progressively enhance for larger screens 4 | - **Standard Breakpoints**: Consistently use standard breakpoints across the application (e.g., mobile, tablet, desktop) 5 | - **Fluid Layouts**: Use percentage-based widths and flexible containers that adapt to screen size 6 | - **Relative Units**: Prefer rem/em units over fixed pixels for better scalability and accessibility 7 | - **Test Across Devices**: Test and verify UI changes across multiple screen sizes from mobile to tablet to desktop screen sizes and ensure a balanced, user-friendly viewing and reading experience on all 8 | - **Touch-Friendly Design**: Ensure tap targets are appropriately sized (minimum 44x44px) for mobile users 9 | - **Performance on Mobile**: Optimize images and assets for mobile network conditions and smaller screens 10 | - **Readable Typography**: Maintain readable font sizes across all breakpoints without requiring zoom 11 | - **Content Priority**: Show the most important content first on smaller screens through thoughtful layout decisions 12 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /profiles/default/standards/testing/test-writing.md: -------------------------------------------------------------------------------- 1 | ## Test coverage best practices 2 | 3 | - **Write Minimal Tests During Development**: Do NOT write tests for every change or intermediate step. Focus on completing the feature implementation first, then add strategic tests only at logical completion points 4 | - **Test Only Core User Flows**: Write tests exclusively for critical paths and primary user workflows. Skip writing tests for non-critical utilities and secondary workflows until if/when you're instructed to do so. 5 | - **Defer Edge Case Testing**: Do NOT test edge cases, error states, or validation logic unless they are business-critical. These can be addressed in dedicated testing phases, not during feature development. 6 | - **Test Behavior, Not Implementation**: Focus tests on what the code does, not how it does it, to reduce brittleness 7 | - **Clear Test Names**: Use descriptive names that explain what's being tested and the expected outcome 8 | - **Mock External Dependencies**: Isolate units by mocking databases, APIs, file systems, and other external services 9 | - **Fast Execution**: Keep unit tests fast (milliseconds) so developers run them frequently during development 10 | -------------------------------------------------------------------------------- /profiles/default/commands/plan-product/single-agent/1-product-concept.md: -------------------------------------------------------------------------------- 1 | This begins a multi-step process for planning and documenting the mission and roadmap for the current product. 2 | 3 | The FIRST STEP is to confirm the product details by following these instructions: 4 | 5 | {{workflows/planning/gather-product-info}} 6 | 7 | Then WAIT for me to give you specific instructions on how to use the information you've gathered to create the mission and roadmap. 8 | 9 | {{UNLESS compiled_single_command}} 10 | ## Display confirmation and next step 11 | 12 | Once you've gathered all of the necessary information, output the following message: 13 | 14 | ``` 15 | I have all the info I need to help you plan this product. 16 | 17 | NEXT STEP 👉 Run the command, `2-create-mission.md` 18 | ``` 19 | {{ENDUNLESS compiled_single_command}} 20 | 21 | {{UNLESS standards_as_claude_code_skills}} 22 | ## User Standards & Preferences Compliance 23 | 24 | When planning the product's tech stack, mission statement and roadmap, use the user's standards and preferences for context and baseline assumptions, as documented in these files: 25 | 26 | {{standards/global/*}} 27 | {{ENDUNLESS standards_as_claude_code_skills}} 28 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | 3 | contact_links: 4 | - name: 🐛 Report a bug or propose a fix 5 | url: https://github.com/buildermethods/agent-os/discussions/categories/bugs 6 | about: Already checked the docs and found a reproducible bug? Please report it in the 'Bugs' discussion area. 7 | 8 | - name: 💡 Feature request or idea 9 | url: https://github.com/buildermethods/agent-os/discussions/categories/ideas 10 | about: Request new features, integrations, or other improvements in the 'Ideas' discussion area. 11 | 12 | - name: ❓ Ask a question 13 | url: https://github.com/buildermethods/agent-os/discussions/categories/q-a 14 | about: For community support and general questions, use the 'Q&A' discussion area. 15 | 16 | - name: 🎯 Member support request 17 | url: https://buildermethods.com/pro 18 | about: Join Builder Methods Pro for official Agent OS support with guaranteed responses from Brian & team, plus access to community chat, workshops, courses and more. 19 | 20 | - name: 📗 Check the official docs 21 | url: https://buildermethods.com/agent-os 22 | about: Please review the docs before posting a bug, question, or idea. 23 | -------------------------------------------------------------------------------- /profiles/default/standards/global/conventions.md: -------------------------------------------------------------------------------- 1 | ## General development conventions 2 | 3 | - **Consistent Project Structure**: Organize files and directories in a predictable, logical structure that team members can navigate easily 4 | - **Clear Documentation**: Maintain up-to-date README files with setup instructions, architecture overview, and contribution guidelines 5 | - **Version Control Best Practices**: Use clear commit messages, feature branches, and meaningful pull/merge requests with descriptions 6 | - **Environment Configuration**: Use environment variables for configuration; never commit secrets or API keys to version control 7 | - **Dependency Management**: Keep dependencies up-to-date and minimal; document why major dependencies are used 8 | - **Code Review Process**: Establish a consistent code review process with clear expectations for reviewers and authors 9 | - **Testing Requirements**: Define what level of testing is required before merging (unit tests, integration tests, etc.) 10 | - **Feature Flags**: Use feature flags for incomplete features rather than long-lived feature branches 11 | - **Changelog Maintenance**: Keep a changelog or release notes to track significant changes and improvements 12 | -------------------------------------------------------------------------------- /profiles/default/commands/shape-spec/single-agent/2-shape-spec.md: -------------------------------------------------------------------------------- 1 | Now that you've initialized the folder for this new spec, proceed with the research phase. 2 | 3 | Follow these instructions for researching this spec's requirements: 4 | 5 | {{workflows/specification/research-spec}} 6 | 7 | ## Display confirmation and next step 8 | 9 | Once you've completed your research and documented it, output the following message: 10 | 11 | ``` 12 | ✅ I have documented this spec's research and requirements in `agent-os/specs/[this-spec]/planning`. 13 | 14 | Next step: Run the command, `1-create-spec.md`. 15 | ``` 16 | 17 | After all steps complete, inform the user: 18 | 19 | ``` 20 | Spec initialized successfully! 21 | 22 | ✅ Spec folder created: `[spec-path]` 23 | ✅ Requirements gathered 24 | ✅ Visual assets: [Found X files / No files provided] 25 | 26 | 👉 Run `/write-spec` to create the spec.md document. 27 | ``` 28 | 29 | {{UNLESS standards_as_claude_code_skills}} 30 | ## User Standards & Preferences Compliance 31 | 32 | IMPORTANT: Ensure that your research questions and insights are ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files: 33 | 34 | {{standards/global/*}} 35 | {{ENDUNLESS standards_as_claude_code_skills}} 36 | -------------------------------------------------------------------------------- /profiles/default/commands/implement-tasks/single-agent/2-implement-tasks.md: -------------------------------------------------------------------------------- 1 | Now that you have the task group(s) to be implemented, proceed with implementation by following these instructions: 2 | 3 | {{workflows/implementation/implement-tasks}} 4 | 5 | ## Display confirmation and next step 6 | 7 | Display a summary of what was implemented. 8 | 9 | IF all tasks are now marked as done (with `- [x]`) in tasks.md, display this message to user: 10 | 11 | ``` 12 | All tasks have been implemented: `agent-os/specs/[this-spec]/tasks.md`. 13 | 14 | NEXT STEP 👉 Run `3-verify-implementation.md` to verify the implementation. 15 | ``` 16 | 17 | IF there are still tasks in tasks.md that have yet to be implemented (marked unfinished with `- [ ]`) then display this message to user: 18 | 19 | ``` 20 | Would you like to proceed with implementation of the remaining tasks in tasks.md? 21 | 22 | If not, please specify which task group(s) to implement next. 23 | ``` 24 | 25 | {{UNLESS standards_as_claude_code_skills}} 26 | ## User Standards & Preferences Compliance 27 | 28 | IMPORTANT: Ensure that the tasks list is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files: 29 | 30 | {{standards/*}} 31 | {{ENDUNLESS standards_as_claude_code_skills}} 32 | -------------------------------------------------------------------------------- /profiles/default/standards/global/tech-stack.md: -------------------------------------------------------------------------------- 1 | ## Tech stack 2 | 3 | Define your technical stack below. This serves as a reference for all team members and helps maintain consistency across the project. 4 | 5 | ### Framework & Runtime 6 | - **Application Framework:** [e.g., Rails, Django, Next.js, Express] 7 | - **Language/Runtime:** [e.g., Ruby, Python, Node.js, Java] 8 | - **Package Manager:** [e.g., bundler, pip, npm, yarn] 9 | 10 | ### Frontend 11 | - **JavaScript Framework:** [e.g., React, Vue, Svelte, Alpine, vanilla JS] 12 | - **CSS Framework:** [e.g., Tailwind CSS, Bootstrap, custom] 13 | - **UI Components:** [e.g., shadcn/ui, Material UI, custom library] 14 | 15 | ### Database & Storage 16 | - **Database:** [e.g., PostgreSQL, MySQL, MongoDB] 17 | - **ORM/Query Builder:** [e.g., ActiveRecord, Prisma, Sequelize] 18 | - **Caching:** [e.g., Redis, Memcached] 19 | 20 | ### Testing & Quality 21 | - **Test Framework:** [e.g., Jest, RSpec, pytest] 22 | - **Linting/Formatting:** [e.g., ESLint, Prettier, RuboCop] 23 | 24 | ### Deployment & Infrastructure 25 | - **Hosting:** [e.g., Heroku, AWS, Vercel, Railway] 26 | - **CI/CD:** [e.g., GitHub Actions, CircleCI] 27 | 28 | ### Third-Party Services 29 | - **Authentication:** [e.g., Auth0, Devise, NextAuth] 30 | - **Email:** [e.g., SendGrid, Postmark] 31 | - **Monitoring:** [e.g., Sentry, Datadog] 32 | -------------------------------------------------------------------------------- /profiles/default/workflows/planning/create-product-tech-stack.md: -------------------------------------------------------------------------------- 1 | Create `agent-os/product/tech-stack.md` with a list of all tech stack choices that cover all aspects of this product's codebase. 2 | 3 | ### Creating the Tech Stack document 4 | 5 | #### Step 1: Note User's Input Regarding Tech Stack 6 | 7 | IF the user has provided specific information in the current conversation in regards to tech stack choices, these notes ALWAYS take precidence. These must be reflected in your final `tech-stack.md` document that you will create. 8 | 9 | #### Step 2: Gather User's Default Tech Stack Information 10 | 11 | Reconcile and fill in the remaining gaps in the tech stack list by finding, reading and analyzing information regarding the tech stack. Find this information in the following sources, in this order: 12 | 13 | 1. If user has provided their default tech stack under "User Standards & Preferences Compliance", READ and analyze this document. 14 | 2. If the current project has any of these files, read them to find information regarding tech stack choices for this codebase: 15 | - `claude.md` 16 | - `agents.md` 17 | 18 | #### Step 3: Create the Tech Stack Document 19 | 20 | Create `agent-os/product/tech-stack.md` and populate it with the final list of all technical stack choices, reconciled between the information the user has provided to you and the information found in provided sources. 21 | -------------------------------------------------------------------------------- /profiles/default/agents/implementation-verifier.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: implementation-verifier 3 | description: Use proactively to verify the end-to-end implementation of a spec 4 | tools: Write, Read, Bash, WebFetch, Playwright 5 | color: green 6 | model: inherit 7 | --- 8 | 9 | You are a product spec verifier responsible for verifying the end-to-end implementation of a spec, updating the product roadmap (if necessary), and producing a final verification report. 10 | 11 | ## Core Responsibilities 12 | 13 | 1. **Ensure tasks.md has been updated**: Check this spec's `tasks.md` to ensure all tasks and sub-tasks have been marked complete with `- [x]` 14 | 2. **Update roadmap (if applicable)**: Check `agent-os/product/roadmap.md` and check items that have been completed as a result of this spec's implementation by marking their checkbox(s) with `- [x]`. 15 | 3. **Run entire tests suite**: Verify that all tests pass and there have been no regressions as a result of this implementation. 16 | 4. **Create final verification report**: Write your final verification report for this spec's implementation. 17 | 18 | ## Workflow 19 | 20 | ### Step 1: Ensure tasks.md has been updated 21 | 22 | {{workflows/implementation/verification/verify-tasks}} 23 | 24 | ### Step 2: Update roadmap (if applicable) 25 | 26 | {{workflows/implementation/verification/update-roadmap}} 27 | 28 | ### Step 3: Run entire tests suite 29 | 30 | {{workflows/implementation/verification/run-all-tests}} 31 | 32 | ### Step 4: Create final verification report 33 | 34 | {{workflows/implementation/verification/create-verification-report}} 35 | -------------------------------------------------------------------------------- /profiles/default/workflows/planning/create-product-mission.md: -------------------------------------------------------------------------------- 1 | Create `agent-os/product/mission.md` with comprehensive product definition following this structure for its' content: 2 | 3 | #### Mission Structure: 4 | ```markdown 5 | # Product Mission 6 | 7 | ## Pitch 8 | [PRODUCT_NAME] is a [PRODUCT_TYPE] that helps [TARGET_USERS] [SOLVE_PROBLEM] 9 | by providing [KEY_VALUE_PROPOSITION]. 10 | 11 | ## Users 12 | 13 | ### Primary Customers 14 | - [CUSTOMER_SEGMENT_1]: [DESCRIPTION] 15 | - [CUSTOMER_SEGMENT_2]: [DESCRIPTION] 16 | 17 | ### User Personas 18 | **[USER_TYPE]** ([AGE_RANGE]) 19 | - **Role:** [JOB_TITLE/CONTEXT] 20 | - **Context:** [BUSINESS/PERSONAL_CONTEXT] 21 | - **Pain Points:** [SPECIFIC_PROBLEMS] 22 | - **Goals:** [DESIRED_OUTCOMES] 23 | 24 | ## The Problem 25 | 26 | ### [PROBLEM_TITLE] 27 | [PROBLEM_DESCRIPTION]. [QUANTIFIABLE_IMPACT]. 28 | 29 | **Our Solution:** [SOLUTION_APPROACH] 30 | 31 | ## Differentiators 32 | 33 | ### [DIFFERENTIATOR_TITLE] 34 | Unlike [COMPETITOR/ALTERNATIVE], we provide [SPECIFIC_ADVANTAGE]. 35 | This results in [MEASURABLE_BENEFIT]. 36 | 37 | ## Key Features 38 | 39 | ### Core Features 40 | - **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION] 41 | 42 | ### Collaboration Features 43 | - **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION] 44 | 45 | ### Advanced Features 46 | - **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION] 47 | ``` 48 | 49 | #### Important Constraints 50 | 51 | - **Focus on user benefits** in feature descriptions, not technical details 52 | - **Keep it concise** and easy for users to scan and get the more important concepts quickly 53 | -------------------------------------------------------------------------------- /profiles/default/workflows/implementation/implement-tasks.md: -------------------------------------------------------------------------------- 1 | Implement all tasks assigned to you and ONLY those task(s) that have been assigned to you. 2 | 3 | ## Implementation process: 4 | 5 | 1. Analyze the provided spec.md, requirements.md, and visuals (if any) 6 | 2. Analyze patterns in the codebase according to its built-in workflow 7 | 3. Implement the assigned task group according to requirements and standards 8 | 4. Update `agent-os/specs/[this-spec]/tasks.md` to update the tasks you've implemented to mark that as done by updating their checkbox to checked state: `- [x]` 9 | 10 | ## Guide your implementation using: 11 | - **The existing patterns** that you've found and analyzed in the codebase. 12 | - **Specific notes provided in requirements.md, spec.md AND/OR tasks.md** 13 | - **Visuals provided (if any)** which would be located in `agent-os/specs/[this-spec]/planning/visuals/` 14 | - **User Standards & Preferences** which are defined below. 15 | 16 | ## Self-verify and test your work by: 17 | - Running ONLY the tests you've written (if any) and ensuring those tests pass. 18 | - IF your task involves user-facing UI, and IF you have access to browser testing tools, open a browser and use the feature you've implemented as if you are a user to ensure a user can use the feature in the intended way. 19 | - Take screenshots of the views and UI elements you've tested and store those in `agent-os/specs/[this-spec]/verification/screenshots/`. Do not store screenshots anywhere else in the codebase other than this location. 20 | - Analyze the screenshot(s) you've taken to check them against your current requirements. 21 | -------------------------------------------------------------------------------- /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, usage, & best practices 👉 [It's all here](https://buildermethods.com/agent-os) 22 | 23 | --- 24 | 25 | ### Follow updates & releases 26 | 27 | Read the [changelog](CHANGELOG.md) 28 | 29 | [Subscribe to be notified of major new releases of Agent OS](https://buildermethods.com/agent-os) 30 | 31 | --- 32 | 33 | ### Created by Brian Casel @ Builder Methods 34 | 35 | Created by Brian Casel, the creator of [Builder Methods](https://buildermethods.com), where Brian helps professional software developers and teams build with AI. 36 | 37 | Get Brian's free resources on building with AI: 38 | - [Builder Briefing newsletter](https://buildermethods.com) 39 | - [YouTube](https://youtube.com/@briancasel) 40 | 41 | Join [Builder Methods Pro](https://buildermethods.com/pro) for official support and connect with our community of AI-first builders: 42 | -------------------------------------------------------------------------------- /profiles/default/commands/plan-product/multi-agent/plan-product.md: -------------------------------------------------------------------------------- 1 | ## Product Planning Process 2 | 3 | You are helping to plan and document the mission, roadmap and tech stack for the current product. This will include: 4 | 5 | - **Gathering Information**: The user's product vision, user personas, problems and key features 6 | - **Mission Document**: Take what you've gathered and create a concise mission document 7 | - **Roadmap**: Create a phased development plan with prioritized features 8 | - **Tech stack**: Establish the technical stack used for all aspects of this product's codebase 9 | 10 | This process will create these files in `agent-os/product/` directory. 11 | 12 | ### PHASE 1: Gather Product Requirements 13 | 14 | Use the **product-planner** subagent to create comprehensive product documentation. 15 | 16 | IF the user has provided any details in regards to the product idea, its purpose, features list, target users and any other details then provide those to the **product-planner** subagent. 17 | 18 | The product-planner will: 19 | - Confirm (or gather) product idea, features, target users, confirm the tech stack and gather other details 20 | - Create `agent-os/product/mission.md` with product vision and strategy 21 | - Create `agent-os/product/roadmap.md` with phased development plan 22 | - Create `agent-os/product/tech-stack.md` documenting all of this product's tech stack choices 23 | 24 | ### PHASE 2: Inform the user 25 | 26 | After all steps are complete, output the following to inform the user: 27 | 28 | ``` 29 | Your product planning is all set! 30 | 31 | ✅ Product mission: `agent-os/product/mission.md` 32 | ✅ Product roadmap: `agent-os/product/roadmap.md` 33 | ✅ Product tech stack: `agent-os/product/tech-stack.md` 34 | 35 | NEXT STEP 👉 Run `/shape-spec` or `/write-spec` to start work on a feature! 36 | ``` 37 | -------------------------------------------------------------------------------- /profiles/default/commands/create-tasks/multi-agent/create-tasks.md: -------------------------------------------------------------------------------- 1 | # Task List Creation Process 2 | 3 | You are creating a tasks breakdown from a given spec and requirements for a new feature. 4 | 5 | ## PHASE 1: Get and read the spec.md and/or requirements document(s) 6 | 7 | You will need ONE OR BOTH of these files to inform your tasks breakdown: 8 | - `agent-os/specs/[this-spec]/spec.md` 9 | - `agent-os/specs/[this-spec]/planning/requirements.md` 10 | 11 | IF you don't have ONE OR BOTH of those files in your current conversation context, then ask user to provide direction on where to you can find them by outputting the following request then wait for user's response: 12 | 13 | ``` 14 | I'll need a spec.md or requirements.md (or both) in order to build a tasks list. 15 | 16 | Please direct me to where I can find those. If you haven't created them yet, you can run /shape-spec or /write-spec. 17 | ``` 18 | 19 | ## PHASE 2: Create tasks.md 20 | 21 | Once you have `spec.md` AND/OR `requirements.md`, use the **tasks-list-creator** subagent to break down the spec and requirements into an actionable tasks list with strategic grouping and ordering. 22 | 23 | Provide the tasks-list-creator: 24 | - `agent-os/specs/[this-spec]/spec.md` (if present) 25 | - `agent-os/specs/[this-spec]/planning/requirements.md` (if present) 26 | - `agent-os/specs/[this-spec]/planning/visuals/` and its' contents (if present) 27 | 28 | The tasks-list-creator will create `tasks.md` inside the spec folder. 29 | 30 | ## PHASE 3: Inform user 31 | 32 | Once the tasks-list-creator has created `tasks.md` output the following to inform the user: 33 | 34 | ``` 35 | Your tasks list ready! 36 | 37 | ✅ Tasks list created: `agent-os/specs/[this-spec]/tasks.md` 38 | 39 | NEXT STEP 👉 Run `/implement-tasks` (simple, effective) or `/orchestrate-tasks` (advanced, powerful) to start building! 40 | ``` 41 | -------------------------------------------------------------------------------- /profiles/default/workflows/implementation/compile-implementation-standards.md: -------------------------------------------------------------------------------- 1 | #### Compile Implementation Standards 2 | 3 | Use the following logic to compile a list of file references to standards that should guide implementation: 4 | 5 | ##### Steps to Compile Standards List 6 | 7 | 1. Find the current task group in `orchestration.yml` 8 | 2. Check the list of `standards` specified for this task group in `orchestration.yml` 9 | 3. Compile the list of file references to those standards, one file reference per line, using this logic for determining which files to include: 10 | a. If the value for `standards` is simply `all`, then include every single file, folder, sub-folder and files within sub-folders in your list of files. 11 | b. If the item under standards ends with "*" then it means that all files within this folder or sub-folder should be included. For example, `frontend/*` means include all files and sub-folders and their files located inside of `agent-os/standards/frontend/`. 12 | c. If a file ends in `.md` then it means this is one specific file you must include in your list of files. For example `backend/api.md` means you must include the file located at `agent-os/standards/backend/api.md`. 13 | d. De-duplicate files in your list of file references. 14 | 15 | ##### Output Format 16 | 17 | The compiled list of standards should look something like this, where each file reference is on its own line and begins with `@`. The exact list of files will vary: 18 | 19 | ``` 20 | @agent-os/standards/global/coding-style.md 21 | @agent-os/standards/global/conventions.md 22 | @agent-os/standards/global/tech-stack.md 23 | @agent-os/standards/backend/api/authentication.md 24 | @agent-os/standards/backend/api/endpoints.md 25 | @agent-os/standards/backend/api/responses.md 26 | @agent-os/standards/frontend/css.md 27 | @agent-os/standards/frontend/responsive.md 28 | ``` 29 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to Agent OS 2 | 3 | Thanks for considering a contribution! Agent OS is free and open source, but to keep things manageable we follow a **Discussions-first workflow**. 4 | 5 | --- 6 | 7 | ## Where things go 8 | 9 | - **Discussions (Bugs):** Report suspected bugs. Maintainers may promote confirmed bugs into Issues. 10 | 👉 **Check the docs before posting:** [buildermethods.com/agent-os](https://buildermethods.com/agent-os) 11 | 12 | - **Discussions (Ideas):** Share feature ideas and proposals. 13 | 👉 **Check the docs first** to ensure it’s not already supported. 14 | 15 | - **Discussions (Q&A):** Ask & answer community questions. 16 | 17 | - **Builder Methods Pro:** Paid membership with guaranteed support responses → https://buildermethods.com/pro 18 | 19 | --- 20 | 21 | ## Pull Requests (read first!) 22 | 23 | To avoid wasted effort and to protect maintainer time: 24 | 25 | - **Bug-fix PRs:** 26 | Please include `[bug fix]` in your PR title and clearly describe the steps to reproduce and test the fix. 27 | 28 | - **Feature PRs:** 29 | > 💡 **Ideas welcome!** We strongly recommend starting with a Discussion in our **Ideas** section to gather feedback and community support before submitting a PR. This helps us understand your use case and explore the best approach together. 30 | > Please note: New features are rarely accepted into core as we must consider long-term roadmap, maintainability, and support implications. A declined PR doesn't mean "never"—it means "not now." Starting with a Discussion gives your idea the best chance of success. 31 | 32 | - **Docs-only PRs:** 33 | Typos, clarifications, and doc improvements are always welcomed. 34 | 35 | --- 36 | 37 | ## How to propose a new feature or integration 38 | 39 | Open a Discussion in **Ideas** with: 40 | - Problem & motivation 41 | - Proposed change & alternatives 42 | - User experience impact 43 | - Updating & compatibility considerations 44 | 45 | If a maintainer labels it **`approved`**, then a PR may be opened. 46 | 47 | --- 48 | 49 | ## Code of Conduct 50 | 51 | By participating, you agree to our [Code of Conduct](./CODE_OF_CONDUCT.md). Be respectful and constructive. 52 | -------------------------------------------------------------------------------- /profiles/default/commands/shape-spec/multi-agent/shape-spec.md: -------------------------------------------------------------------------------- 1 | # Spec Shaping Process 2 | 3 | You are helping me shape and plan the scope for a new feature. The following process is aimed at documenting our key decisions regarding scope, design and architecture approach. We will use our findings from this process later when we write the formal spec document (but we are NOT writing the formal spec yet). 4 | 5 | This process will follow 3 main phases, each with their own workflow steps: 6 | 7 | Process overview (details to follow) 8 | 9 | PHASE 1. Initilize spec 10 | PHASE 2. Research requirements for this spec 11 | PHASE 3. Inform the user that the spec has been initialized 12 | 13 | Follow each of these phases and their individual workflows IN SEQUENCE: 14 | 15 | ## Multi-Phase Process: 16 | 17 | ### PHASE 1: Initialize Spec 18 | 19 | Use the **spec-initializer** subagent to initialize a new spec. 20 | 21 | IF the user has provided a description, provide that to the spec-initializer. 22 | 23 | The spec-initializer will provide the path to the dated spec folder (YYYY-MM-DD-spec-name) they've created. 24 | 25 | ### PHASE 2: Research Requirements 26 | 27 | After spec-initializer completes, immediately use the **spec-shaper** subagent: 28 | 29 | Provide the spec-shaper with: 30 | - The spec folder path from spec-initializer 31 | 32 | The spec-shaper will give you several separate responses that you MUST show to the user. These include: 33 | 1. Numbered clarifying questions along with a request for visual assets (show these to user, wait for user's response) 34 | 2. Follow-up questions if needed (based on user's answers and provided visuals) 35 | 36 | **IMPORTANT**: 37 | - Display these questions to the user and wait for their response 38 | - The spec-shaper may ask you to relay follow-up questions that you must present to user 39 | 40 | ### PHASE 3: Inform the user 41 | 42 | After all steps complete, inform the user: 43 | 44 | ``` 45 | Spec shaping is complete! 46 | 47 | ✅ Spec folder created: `[spec-path]` 48 | ✅ Requirements gathered 49 | ✅ Visual assets: [Found X files / No files provided] 50 | 51 | NEXT STEP 👉 Run `/write-spec` to generate the detailed specification document. 52 | ``` 53 | -------------------------------------------------------------------------------- /profiles/default/agents/product-planner.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: product-planner 3 | description: Use proactively to create product documentation including mission, and roadmap 4 | tools: Write, Read, Bash, WebFetch 5 | color: cyan 6 | model: inherit 7 | --- 8 | 9 | You are a product planning specialist. Your role is to create comprehensive product documentation including mission, and development roadmap. 10 | 11 | # Product Planning 12 | 13 | ## Core Responsibilities 14 | 15 | 1. **Gather Requirements**: Collect from user their product idea, list of key features, target users and any other details they wish to provide 16 | 2. **Create Product Documentation**: Generate mission, and roadmap files 17 | 3. **Define Product Vision**: Establish clear product purpose and differentiators 18 | 4. **Plan Development Phases**: Create structured roadmap with prioritized features 19 | 5. **Document Product Tech Stack**: Document the tech stack used on all aspects of this product's codebase 20 | 21 | ## Workflow 22 | 23 | ### Step 1: Gather Product Requirements 24 | 25 | {{workflows/planning/gather-product-info}} 26 | 27 | ### Step 2: Create Mission Document 28 | 29 | {{workflows/planning/create-product-mission}} 30 | 31 | ### Step 3: Create Development Roadmap 32 | 33 | {{workflows/planning/create-product-roadmap}} 34 | 35 | ### Step 4: Document Tech Stack 36 | 37 | {{workflows/planning/create-product-tech-stack}} 38 | 39 | ### Step 5: Final Validation 40 | 41 | Verify all files created successfully: 42 | 43 | ```bash 44 | # Validate all product files exist 45 | for file in mission.md roadmap.md; do 46 | if [ ! -f "agent-os/product/$file" ]; then 47 | echo "Error: Missing $file" 48 | else 49 | echo "✓ Created agent-os/product/$file" 50 | fi 51 | done 52 | 53 | echo "Product planning complete! Review your product documentation in agent-os/product/" 54 | ``` 55 | 56 | {{UNLESS standards_as_claude_code_skills}} 57 | ## User Standards & Preferences Compliance 58 | 59 | IMPORTANT: Ensure the product mission and roadmap are ALIGNED and DO NOT CONFLICT with the user's preferences and standards as detailed in the following files: 60 | 61 | {{standards/global/*}} 62 | {{ENDUNLESS standards_as_claude_code_skills}} 63 | -------------------------------------------------------------------------------- /profiles/default/workflows/implementation/verification/create-verification-report.md: -------------------------------------------------------------------------------- 1 | Create your final verification report in `agent-os/specs/[this-spec]/verifications/final-verification.md`. 2 | 3 | The content of this report should follow this structure: 4 | 5 | ```markdown 6 | # Verification Report: [Spec Title] 7 | 8 | **Spec:** `[spec-name]` 9 | **Date:** [Current Date] 10 | **Verifier:** implementation-verifier 11 | **Status:** ✅ Passed | ⚠️ Passed with Issues | ❌ Failed 12 | 13 | --- 14 | 15 | ## Executive Summary 16 | 17 | [Brief 2-3 sentence overview of the verification results and overall implementation quality] 18 | 19 | --- 20 | 21 | ## 1. Tasks Verification 22 | 23 | **Status:** ✅ All Complete | ⚠️ Issues Found 24 | 25 | ### Completed Tasks 26 | - [x] Task Group 1: [Title] 27 | - [x] Subtask 1.1 28 | - [x] Subtask 1.2 29 | - [x] Task Group 2: [Title] 30 | - [x] Subtask 2.1 31 | 32 | ### Incomplete or Issues 33 | [List any tasks that were found incomplete or have issues, or note "None" if all complete] 34 | 35 | --- 36 | 37 | ## 2. Documentation Verification 38 | 39 | **Status:** ✅ Complete | ⚠️ Issues Found 40 | 41 | ### Implementation Documentation 42 | - [x] Task Group 1 Implementation: `implementations/1-[task-name]-implementation.md` 43 | - [x] Task Group 2 Implementation: `implementations/2-[task-name]-implementation.md` 44 | 45 | ### Verification Documentation 46 | [List verification documents from area verifiers if applicable] 47 | 48 | ### Missing Documentation 49 | [List any missing documentation, or note "None"] 50 | 51 | --- 52 | 53 | ## 3. Roadmap Updates 54 | 55 | **Status:** ✅ Updated | ⚠️ No Updates Needed | ❌ Issues Found 56 | 57 | ### Updated Roadmap Items 58 | - [x] [Roadmap item that was marked complete] 59 | 60 | ### Notes 61 | [Any relevant notes about roadmap updates, or note if no updates were needed] 62 | 63 | --- 64 | 65 | ## 4. Test Suite Results 66 | 67 | **Status:** ✅ All Passing | ⚠️ Some Failures | ❌ Critical Failures 68 | 69 | ### Test Summary 70 | - **Total Tests:** [count] 71 | - **Passing:** [count] 72 | - **Failing:** [count] 73 | - **Errors:** [count] 74 | 75 | ### Failed Tests 76 | [List any failing tests with their descriptions, or note "None - all tests passing"] 77 | 78 | ### Notes 79 | [Any additional context about test results, known issues, or regressions] 80 | ``` 81 | -------------------------------------------------------------------------------- /config.yml: -------------------------------------------------------------------------------- 1 | version: 2.1.1 2 | base_install: true 3 | 4 | 5 | # CONFIGURATION 6 | # Configure defaults for the tools you use and how Agent OS should compile commands for your projects. 7 | 8 | 9 | # ================================================ 10 | # Do you use Claude Code? 11 | # Set to true to install commands in your project's .claude/commands/agent-os/ folder 12 | # 13 | # Override this default when running project-install.sh by using the flag --claude-code-commands=true/false 14 | # ================================================ 15 | claude_code_commands: true 16 | 17 | 18 | # ================================================ 19 | # Do you use other coding tools (Cursor, Windsurf, etc.)? 20 | # Set to true to install commands in your project's agent-os/commands/ folder 21 | # 22 | # Override this default when running project-install.sh by using the flag --agent-os-commands true/false 23 | # ================================================ 24 | agent_os_commands: false 25 | 26 | 27 | # ================================================ 28 | # Do you want Claude Code to use subagents? 29 | # Set to true to install agents in .claude/agents/agent-os/ and have commands delegate to them 30 | # Requires claude_code_commands: true 31 | # 32 | # Override this default when running project-install.sh by using the flag --use-claude-code-subagents true/false 33 | # ================================================ 34 | use_claude_code_subagents: true 35 | 36 | 37 | # ================================================ 38 | # Should standards be provided to Claude Code as Skills? 39 | # Set to true to use Claude Code's Skills feature for reading standards 40 | # Set to false to inject standards as file references in command prompts 41 | # Requires claude_code_commands: true (automatically treated as false if claude_code_commands is false) 42 | # 43 | # Override this default when running project-install.sh by using the flag --standards-as-claude-code-skills true/false 44 | # ================================================ 45 | standards_as_claude_code_skills: false 46 | 47 | 48 | # ================================================ 49 | # PROFILE 50 | # 51 | # Use this profile by default. 52 | # 53 | # Override this default when running project-install.sh by using the flag --profile [profile-name] 54 | # ================================================ 55 | 56 | profile: default 57 | -------------------------------------------------------------------------------- /profiles/default/workflows/planning/create-product-roadmap.md: -------------------------------------------------------------------------------- 1 | Generate `agent-os/product/roadmap.md` with an ordered feature checklist: 2 | 3 | Do not include any tasks for initializing a new codebase or bootstrapping a new application. Assume the user is already inside the project's codebase and has a bare-bones application initialized. 4 | 5 | #### Creating the Roadmap: 6 | 7 | 1. **Review the Mission** - Read `agent-os/product/mission.md` to understand the product's goals, target users, and success criteria. 8 | 9 | 2. **Identify Features** - Based on the mission, determine the list of concrete features needed to achieve the product vision. 10 | 11 | 3. **Strategic Ordering** - Order features based on: 12 | - Technical dependencies (foundational features first) 13 | - Most direct path to achieving the mission 14 | - Building incrementally from MVP to full product 15 | 16 | 4. **Create the Roadmap** - Use the structure below as your template. Replace all bracketed placeholders (e.g., `[FEATURE_NAME]`, `[DESCRIPTION]`, `[EFFORT]`) with real content that you create based on the mission. 17 | 18 | #### Roadmap Structure: 19 | ```markdown 20 | # Product Roadmap 21 | 22 | 1. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]` 23 | 2. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]` 24 | 3. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]` 25 | 4. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]` 26 | 5. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]` 27 | 6. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]` 28 | 7. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]` 29 | 8. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]` 30 | 31 | > Notes 32 | > - Order items by technical dependencies and product architecture 33 | > - Each item should represent an end-to-end (frontend + backend) functional and testable feature 34 | ``` 35 | 36 | Effort scale: 37 | - `XS`: 1 day 38 | - `S`: 2-3 days 39 | - `M`: 1 week 40 | - `L`: 2 weeks 41 | - `XL`: 3+ weeks 42 | 43 | #### Important Constraints 44 | 45 | - **Make roadmap actionable** - include effort estimates and dependencies 46 | - **Priorities guided by mission** - When deciding on order, aim for the most direct path to achieving the mission as documented in mission.md 47 | - **Ensure phases are achievable** - start with MVP, build incrementally 48 | -------------------------------------------------------------------------------- /profiles/default/workflows/specification/initialize-spec.md: -------------------------------------------------------------------------------- 1 | # Spec Initialization 2 | 3 | ## Core Responsibilities 4 | 5 | 1. **Get the description of the feature:** Receive it from the user or check the product roadmap 6 | 2. **Initialize Spec Structure**: Create the spec folder with date prefix 7 | 3. **Save Raw Idea**: Document the user's exact description without modification 8 | 4. **Create Create Implementation & Verification Folders**: Setup folder structure for tracking implementation of this spec. 9 | 5. **Prepare for Requirements**: Set up structure for next phase 10 | 11 | ## Workflow 12 | 13 | ### Step 1: Get the description of the feature 14 | 15 | IF you were given a description of the feature, then use that to initiate a new spec. 16 | 17 | OTHERWISE follow these steps to get the description: 18 | 19 | 1. Check `@agent-os/product/roadmap.md` to find the next feature in the roadmap. 20 | 2. OUTPUT the following to user and WAIT for user's response: 21 | 22 | ``` 23 | Which feature would you like to initiate a new spec for? 24 | 25 | - The roadmap shows [feature description] is next. Go with that? 26 | - Or provide a description of a feature you'd like to initiate a spec for. 27 | ``` 28 | 29 | **If you have not yet received a description from the user, WAIT until user responds.** 30 | 31 | ### Step 2: Initialize Spec Structure 32 | 33 | Determine a kebab-case spec name from the user's description, then create the spec folder: 34 | 35 | ```bash 36 | # Get today's date in YYYY-MM-DD format 37 | TODAY=$(date +%Y-%m-%d) 38 | 39 | # Determine kebab-case spec name from user's description 40 | SPEC_NAME="[kebab-case-name]" 41 | 42 | # Create dated folder name 43 | DATED_SPEC_NAME="${TODAY}-${SPEC_NAME}" 44 | 45 | # Store this path for output 46 | SPEC_PATH="agent-os/specs/$DATED_SPEC_NAME" 47 | 48 | # Create folder structure following architecture 49 | mkdir -p $SPEC_PATH/planning 50 | mkdir -p $SPEC_PATH/planning/visuals 51 | 52 | echo "Created spec folder: $SPEC_PATH" 53 | ``` 54 | 55 | ### Step 3: Create Implementation Folder 56 | 57 | Create 2 folders: 58 | - `$SPEC_PATH/implementation/` 59 | 60 | Leave this folder empty, for now. Later, this folder will be populated with reports documented by implementation agents. 61 | 62 | ### Step 4: Output Confirmation 63 | 64 | Return or output the following: 65 | 66 | ``` 67 | Spec folder initialized: `[spec-path]` 68 | 69 | Structure created: 70 | - planning/ - For requirements and specifications 71 | - planning/visuals/ - For mockups and screenshots 72 | - implementation/ - For implementation documentation 73 | 74 | Ready for requirements research phase. 75 | ``` 76 | 77 | ## Important Constraints 78 | 79 | - Always use dated folder names (YYYY-MM-DD-spec-name) 80 | - Pass the exact spec path back to the orchestrator 81 | - Follow folder structure exactly 82 | - Implementation folder should be empty, for now 83 | -------------------------------------------------------------------------------- /profiles/default/commands/implement-tasks/multi-agent/implement-tasks.md: -------------------------------------------------------------------------------- 1 | # Spec Implementation Process 2 | 3 | Now that we have a spec and tasks list ready for implementation, we will proceed with implementation of this spec by following this multi-phase process: 4 | 5 | PHASE 1: Determine which task group(s) from tasks.md should be implemented 6 | PHASE 2: Delegate implementation to the implementer subagent 7 | PHASE 3: After ALL task groups have been implemented, delegate to implementation-verifier to produce the final verification report. 8 | 9 | Follow each of these phases and their individual workflows IN SEQUENCE: 10 | 11 | ## Multi-Phase Process 12 | 13 | ### PHASE 1: Determine which task group(s) to implement 14 | 15 | First, check if the user has already provided instructions about which task group(s) to implement. 16 | 17 | **If the user HAS provided instructions:** Proceed to PHASE 2 to delegate implementation of those specified task group(s) to the **implementer** subagent. 18 | 19 | **If the user has NOT provided instructions:** 20 | 21 | Read `agent-os/specs/[this-spec]/tasks.md` to review the available task groups, then output the following message to the user and WAIT for their response: 22 | 23 | ``` 24 | Should we proceed with implementation of all task groups in tasks.md? 25 | 26 | If not, then please specify which task(s) to implement. 27 | ``` 28 | 29 | ### PHASE 2: Delegate implementation to the implementer subagent 30 | 31 | Delegate to the **implementer** subagent to implement the specified task group(s): 32 | 33 | Provide to the subagent: 34 | - The specific task group(s) from `agent-os/specs/[this-spec]/tasks.md` including the parent task, all sub-tasks, and any sub-bullet points 35 | - The path to this spec's documentation: `agent-os/specs/[this-spec]/spec.md` 36 | - The path to this spec's requirements: `agent-os/specs/[this-spec]/planning/requirements.md` 37 | - The path to this spec's visuals (if any): `agent-os/specs/[this-spec]/planning/visuals` 38 | 39 | Instruct the subagent to: 40 | 1. Analyze the provided spec.md, requirements.md, and visuals (if any) 41 | 2. Analyze patterns in the codebase according to its built-in workflow 42 | 3. Implement the assigned task group according to requirements and standards 43 | 4. Update `agent-os/specs/[this-spec]/tasks.md` to mark completed tasks with `- [x]` 44 | 45 | ### PHASE 3: Produce the final verification report 46 | 47 | IF ALL task groups in tasks.md are marked complete with `- [x]`, then proceed with this step. Otherwise, return to PHASE 1. 48 | 49 | Assuming all tasks are marked complete, then delegate to the **implementation-verifier** subagent to do its implementation verification and produce its final verification report. 50 | 51 | Provide to the subagent the following: 52 | - The path to this spec: `agent-os/specs/[this-spec]` 53 | Instruct the subagent to do the following: 54 | 1. Run all of its final verifications according to its built-in workflow 55 | 2. Produce the final verification report in `agent-os/specs/[this-spec]/verifications/final-verification.md`. 56 | -------------------------------------------------------------------------------- /profiles/default/workflows/specification/write-spec.md: -------------------------------------------------------------------------------- 1 | # Spec Writing 2 | 3 | ## Core Responsibilities 4 | 5 | 1. **Analyze Requirements**: Load and analyze requirements and visual assets thoroughly 6 | 2. **Search for Reusable Code**: Find reusable components and patterns in existing codebase 7 | 3. **Create Specification**: Write comprehensive specification document 8 | 9 | ## Workflow 10 | 11 | ### Step 1: Analyze Requirements and Context 12 | 13 | Read and understand all inputs and THINK HARD: 14 | ```bash 15 | # Read the requirements document 16 | cat agent-os/specs/[current-spec]/planning/requirements.md 17 | 18 | # Check for visual assets 19 | ls -la agent-os/specs/[current-spec]/planning/visuals/ 2>/dev/null | grep -v "^total" | grep -v "^d" 20 | ``` 21 | 22 | Parse and analyze: 23 | - User's feature description and goals 24 | - Requirements gathered by spec-shaper 25 | - Visual mockups or screenshots (if present) 26 | - Any constraints or out-of-scope items mentioned 27 | 28 | ### Step 2: Search for Reusable Code 29 | 30 | Before creating specifications, search the codebase for existing patterns and components that can be reused. 31 | 32 | Based on the feature requirements, identify relevant keywords and search for: 33 | - Similar features or functionality 34 | - Existing UI components that match your needs 35 | - Models, services, or controllers with related logic 36 | - API patterns that could be extended 37 | - Database structures that could be reused 38 | 39 | Use appropriate search tools and commands for the project's technology stack to find: 40 | - Components that can be reused or extended 41 | - Patterns to follow from similar features 42 | - Naming conventions used in the codebase 43 | - Architecture patterns already established 44 | 45 | Document your findings for use in the specification. 46 | 47 | ### Step 3: Create Core Specification 48 | 49 | Write the main specification to `agent-os/specs/[current-spec]/spec.md`. 50 | 51 | DO NOT write actual code in the spec.md document. Just describe the requirements clearly and concisely. 52 | 53 | Keep it short and include only essential information for each section. 54 | 55 | Follow this structure exactly when creating the content of `spec.md`: 56 | 57 | ```markdown 58 | # Specification: [Feature Name] 59 | 60 | ## Goal 61 | [1-2 sentences describing the core objective] 62 | 63 | ## User Stories 64 | - As a [user type], I want to [action] so that [benefit] 65 | - [repeat for up to 2 max additional user stories] 66 | 67 | ## Specific Requirements 68 | 69 | **Specific requirement name** 70 | - [Up to 8 CONCISE sub-bullet points to clarify specific sub-requirements, design or architectual decisions that go into this requirement, or the technical approach to take when implementing this requirement] 71 | 72 | [repeat for up to a max of 10 specific requirements] 73 | 74 | ## Visual Design 75 | [If mockups provided] 76 | 77 | **`planning/visuals/[filename]`** 78 | - [up to 8 CONCISE bullets describing specific UI elements found in this visual to address when building] 79 | 80 | [repeat for each file in the `planning/visuals` folder] 81 | 82 | ## Existing Code to Leverage 83 | 84 | **Code, component, or existing logic found** 85 | - [up to 5 bullets that describe what this existing code does and how it should be re-used or replicated when building this spec] 86 | 87 | [repeat for up to 5 existing code areas] 88 | 89 | ## Out of Scope 90 | - [up to 10 concise descriptions of specific features that are out of scope and MUST NOT be built in this spec] 91 | ``` 92 | 93 | ## Important Constraints 94 | 95 | 1. **Always search for reusable code** before specifying new components 96 | 2. **Reference visual assets** when available 97 | 3. **Do NOT write actual code** in the spec 98 | 4. **Keep each section short**, with clear, direct, skimmable specifications 99 | 5. **Do NOT deviate from the template above** and do not add additional sections 100 | -------------------------------------------------------------------------------- /profiles/default/commands/improve-skills/improve-skills.md: -------------------------------------------------------------------------------- 1 | I want you to help me improve the files that make up my Claude Code Skills by rewriting their descriptions so that they can be more readily discovered and used by Claude Code when it works on coding tasks. 2 | 3 | You can refer to the Claude Code documentation on the Skills feature here: https://docs.claude.com/en/docs/claude-code/skills 4 | 5 | All of the Skills in our project are located in `.claude/skills/`. Each Skill has its own folder and inside each Skill folder is a file called `SKILL.md`. 6 | 7 | LOOP through each `SKILL.md` file and FOR EACH use the following process to revise its content and improve it: 8 | 9 | ## Claude Code Skill Improvement Process 10 | 11 | ### Step 1: Confirm which skills to improve 12 | 13 | First, ask the user to confirm whether they want ALL of their Claude Code skills to be improved, only select Skills. Assume the answer will be "all" but ask the user to confirm by displaying the following message, then WAIT for the user's response before proceeding to Step 2: 14 | 15 | ``` 16 | Before I proceed with improving your Claude Code Skills, can you confirm that you want me to revise and improve ALL Skills in your .claude/skills/ folder? 17 | 18 | If not, then please specify which Skills I should include or exclude. 19 | ``` 20 | 21 | ### Step 2: Analyze what this Skill does 22 | 23 | Analyze and read the skill file to understand what it is, what it should be used for, and when it should be used. The specific best practices are described and linked within it. Look to these places to read and understand each skill: 24 | 25 | - The Skill's name and file name. 26 | - The Skill.md contains a link that points to `agent_os/standards/...` — Follow that link and read its contents. 27 | 28 | ### Step 3: Rewrite the Skill description 29 | 30 | The most important element of a skill.md file that impacts its discoverability and trigger-ability by Claude Code is the content we write in the `description` in the skill.md frontmatter. 31 | 32 | Rewrite this description using the following guidelines: 33 | 34 | - The first sentence should clearly describe what this skill is. For example: "Write Tailwind CSS code and structure front-end UIs using Tailwind CSS utility classes." 35 | - The second sentence and subsequent sentences should clearly and directly describe multiple examples where and when this skill should be used. 36 | - The use case examples can include "When writing or editing [file types]" where [file types] can be a list of file extensions or types of files or components commonly found in software projects. 37 | - The use case examples can also include situations or areas or tools where using this skill should come into play. 38 | - The description text can be long. There is no maximum character or word limit. 39 | - Focus on adding examples where the skill SHOULD be used. Do not include instructions on when NOT to use a skill (our goal is for the Skill to be readily found and used frequently). 40 | 41 | ### Step 4: Insert a section for 'When to use this skill' 42 | 43 | At the top of the content of skill.md, below the frontmatter, insert an H2 heading, "When to use this skill" followed by a list of use case examples. 44 | 45 | The use case examples can repeat the same one(s) listed in the description and/or expand on them. 46 | 47 | Example: 48 | ```markdown 49 | ## When to use this skill: 50 | 51 | - [Descriptive example A] 52 | - [Descriptive example B] 53 | - [Descriptive example C] 54 | ... 55 | ``` 56 | 57 | ### Step 5: Advise the user on improving their skills further 58 | 59 | After revising ALL Skill.md files located in the project's `.claude/skills/` folder, display the following message to the user to advise them on how to improve their Claude Code Skills further: 60 | 61 | ``` 62 | All Claude Code Skills have been analyzed and revised! 63 | 64 | RECOMMENDATION 👉 Review and revise them further using these tips: 65 | 66 | - Make Skills as descriptive as possible 67 | - Use their 'description' frontmatter to tell Claude Code when it should proactively use this skill. 68 | - Include all relevant instructions, details and directives within the content of the Skill. 69 | - You can link to other files (like your Agent OS standards files) using markdown links. 70 | - You can consolidate multiple similar skills into single skills where it makes sense for Claude to find and use them together. 71 | 72 | For more best practices, refer to the official Claude Code documentation on Skills: 73 | https://docs.claude.com/en/docs/claude-code/skills 74 | ``` 75 | -------------------------------------------------------------------------------- /.github/workflows/pr-decline.yml: -------------------------------------------------------------------------------- 1 | name: PR manual decline (label or button) 2 | 3 | on: 4 | pull_request_target: 5 | types: [labeled] 6 | 7 | workflow_dispatch: 8 | inputs: 9 | pr_number: 10 | description: "PR number to act on" 11 | required: true 12 | reason: 13 | description: "Reason to use" 14 | required: true 15 | type: choice 16 | options: [Out of scope, Low info, Duplicate, Spam] 17 | 18 | permissions: 19 | pull-requests: write 20 | contents: read 21 | 22 | env: 23 | REPO: ${{ github.repository }} 24 | IDEAS_URL: https://github.com/buildermethods/agent-os/discussions/categories/ideas 25 | CONTRIBUTING_URL: https://github.com/buildermethods/agent-os/blob/main/.github/CONTRIBUTING.md 26 | 27 | jobs: 28 | decline: 29 | runs-on: ubuntu-latest 30 | 31 | steps: 32 | - name: Determine PR number and reason (from label or dispatch) 33 | id: vars 34 | uses: actions/github-script@v7 35 | with: 36 | script: | 37 | let prNumber = ""; 38 | let reason = ""; 39 | let skip = false; 40 | 41 | if (context.eventName === "pull_request_target" && context.payload.action === "labeled") { 42 | prNumber = String(context.payload.pull_request.number); 43 | const label = (context.payload.label?.name || "").trim(); 44 | 45 | const map = { 46 | "Close PR: Out of scope": "Out of scope", 47 | "Close PR: Low info": "Low info", 48 | "Close PR: Duplicate": "Duplicate", 49 | "Close PR: Spam": "Spam", 50 | }; 51 | 52 | if (map[label]) { 53 | reason = map[label]; 54 | } else { 55 | skip = true; // not one of your decline labels 56 | } 57 | } 58 | 59 | if (context.eventName === "workflow_dispatch") { 60 | prNumber = (core.getInput("pr_number") || "").trim(); 61 | reason = (core.getInput("reason") || "").trim(); 62 | } 63 | 64 | core.setOutput("skip", skip ? "true" : "false"); 65 | core.setOutput("pr", prNumber); 66 | core.setOutput("reason", reason); 67 | 68 | - name: Stop if not a decline event 69 | if: steps.vars.outputs.skip == 'true' || steps.vars.outputs.pr == '' || steps.vars.outputs.reason == '' 70 | run: echo "No decline action to run." 71 | 72 | - name: Build canned message 73 | if: steps.vars.outputs.skip != 'true' && steps.vars.outputs.pr != '' && steps.vars.outputs.reason != '' 74 | id: msg 75 | uses: actions/github-script@v7 76 | env: 77 | REASON: ${{ steps.vars.outputs.reason }} # <-- pass raw string 78 | IDEAS_URL: ${{ env.IDEAS_URL }} 79 | CONTRIBUTING_URL: ${{ env.CONTRIBUTING_URL }} 80 | with: 81 | script: | 82 | const reason = process.env.REASON; // <-- read raw string 83 | const IDEAS = process.env.IDEAS_URL; 84 | const CONTRIB = process.env.CONTRIBUTING_URL; 85 | 86 | let body = ""; 87 | switch (reason) { 88 | case "Out of scope": 89 | body = 90 | "Thanks for the PR! After review, this change isn’t on the current roadmap for Agent OS. " + 91 | "We keep core focused to manage long-term maintenance and compatibility.\n\n" + 92 | `If you'd like to continue the conversation, please start a proposal in **Ideas**: ${IDEAS}\n` + 93 | "If you publish a fork/plugin/example, feel free to share it in **Show & Tell** so others can try it.\n\n" + 94 | "_Closing to keep the backlog focused._"; 95 | break; 96 | 97 | case "Low info": 98 | body = 99 | "Thanks for the PR! We’re missing required details for review.\n\n" + 100 | "Please update the PR with:\n" + 101 | "• **Summary**\n" + 102 | "• **Checklist**\n" + 103 | "• **Documented steps to test**\n\n" + 104 | `Guidelines: ${CONTRIB}\n\n` + 105 | "Once updated, you can open a new PR or ask a maintainer to reopen."; 106 | break; 107 | 108 | case "Duplicate": 109 | body = 110 | "Thanks for the PR! This appears to duplicate existing work or discussion. " + 111 | "We’ll consolidate on the canonical thread/PR to reduce churn.\n\n" + 112 | "_Closing this one to keep things tidy._"; 113 | break; 114 | 115 | case "Spam": 116 | body = "Closing this PR. It doesn’t meet our contribution policy."; 117 | break; 118 | 119 | default: 120 | body = "Thanks for the PR! Closing per maintainer review."; 121 | } 122 | 123 | core.setOutput("body", body); 124 | 125 | - name: Comment and close PR 126 | if: steps.vars.outputs.skip != 'true' && steps.vars.outputs.pr != '' && steps.msg.outputs.body != '' 127 | env: 128 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 129 | REPO: ${{ env.REPO }} 130 | run: | 131 | PR="${{ steps.vars.outputs.pr }}" 132 | BODY="${{ steps.msg.outputs.body }}" 133 | 134 | gh pr comment "$PR" --repo "$REPO" --body "$BODY" 135 | gh pr close "$PR" --repo "$REPO" 136 | -------------------------------------------------------------------------------- /profiles/default/workflows/implementation/create-tasks-list.md: -------------------------------------------------------------------------------- 1 | # Task List Creation 2 | 3 | ## Core Responsibilities 4 | 5 | 1. **Analyze spec and requirements**: Read and analyze the spec.md and/or requirements.md to inform the tasks list you will create. 6 | 2. **Plan task execution order**: Break the requirements into a list of tasks in an order that takes their dependencies into account. 7 | 3. **Group tasks by specialization**: Group tasks that require the same skill or stack specialization together (backend, api, ui design, etc.) 8 | 4. **Create Tasks list**: Create the markdown tasks list broken into groups with sub-tasks. 9 | 10 | ## Workflow 11 | 12 | ### Step 1: Analyze Spec & Requirements 13 | 14 | Read each of these files (whichever are available) and analyze them to understand the requirements for this feature implementation: 15 | - `agent-os/specs/[this-spec]/spec.md` 16 | - `agent-os/specs/[this-spec]/planning/requirements.md` 17 | 18 | Use your learnings to inform the tasks list and groupings you will create in the next step. 19 | 20 | 21 | ### Step 2: Create Tasks Breakdown 22 | 23 | Generate `agent-os/specs/[current-spec]/tasks.md`. 24 | 25 | **Important**: The exact tasks, task groups, and organization will vary based on the feature's specific requirements. The following is an example format - adapt the content of the tasks list to match what THIS feature actually needs. 26 | 27 | ```markdown 28 | # Task Breakdown: [Feature Name] 29 | 30 | ## Overview 31 | Total Tasks: [count] 32 | 33 | ## Task List 34 | 35 | ### Database Layer 36 | 37 | #### Task Group 1: Data Models and Migrations 38 | **Dependencies:** None 39 | 40 | - [ ] 1.0 Complete database layer 41 | - [ ] 1.1 Write 2-8 focused tests for [Model] functionality 42 | - Limit to 2-8 highly focused tests maximum 43 | - Test only critical model behaviors (e.g., primary validation, key association, core method) 44 | - Skip exhaustive coverage of all methods and edge cases 45 | - [ ] 1.2 Create [Model] with validations 46 | - Fields: [list] 47 | - Validations: [list] 48 | - Reuse pattern from: [existing model if applicable] 49 | - [ ] 1.3 Create migration for [table] 50 | - Add indexes for: [fields] 51 | - Foreign keys: [relationships] 52 | - [ ] 1.4 Set up associations 53 | - [Model] has_many [related] 54 | - [Model] belongs_to [parent] 55 | - [ ] 1.5 Ensure database layer tests pass 56 | - Run ONLY the 2-8 tests written in 1.1 57 | - Verify migrations run successfully 58 | - Do NOT run the entire test suite at this stage 59 | 60 | **Acceptance Criteria:** 61 | - The 2-8 tests written in 1.1 pass 62 | - Models pass validation tests 63 | - Migrations run successfully 64 | - Associations work correctly 65 | 66 | ### API Layer 67 | 68 | #### Task Group 2: API Endpoints 69 | **Dependencies:** Task Group 1 70 | 71 | - [ ] 2.0 Complete API layer 72 | - [ ] 2.1 Write 2-8 focused tests for API endpoints 73 | - Limit to 2-8 highly focused tests maximum 74 | - Test only critical controller actions (e.g., primary CRUD operation, auth check, key error case) 75 | - Skip exhaustive testing of all actions and scenarios 76 | - [ ] 2.2 Create [resource] controller 77 | - Actions: index, show, create, update, destroy 78 | - Follow pattern from: [existing controller] 79 | - [ ] 2.3 Implement authentication/authorization 80 | - Use existing auth pattern 81 | - Add permission checks 82 | - [ ] 2.4 Add API response formatting 83 | - JSON responses 84 | - Error handling 85 | - Status codes 86 | - [ ] 2.5 Ensure API layer tests pass 87 | - Run ONLY the 2-8 tests written in 2.1 88 | - Verify critical CRUD operations work 89 | - Do NOT run the entire test suite at this stage 90 | 91 | **Acceptance Criteria:** 92 | - The 2-8 tests written in 2.1 pass 93 | - All CRUD operations work 94 | - Proper authorization enforced 95 | - Consistent response format 96 | 97 | ### Frontend Components 98 | 99 | #### Task Group 3: UI Design 100 | **Dependencies:** Task Group 2 101 | 102 | - [ ] 3.0 Complete UI components 103 | - [ ] 3.1 Write 2-8 focused tests for UI components 104 | - Limit to 2-8 highly focused tests maximum 105 | - Test only critical component behaviors (e.g., primary user interaction, key form submission, main rendering case) 106 | - Skip exhaustive testing of all component states and interactions 107 | - [ ] 3.2 Create [Component] component 108 | - Reuse: [existing component] as base 109 | - Props: [list] 110 | - State: [list] 111 | - [ ] 3.3 Implement [Feature] form 112 | - Fields: [list] 113 | - Validation: client-side 114 | - Submit handling 115 | - [ ] 3.4 Build [View] page 116 | - Layout: [description] 117 | - Components: [list] 118 | - Match mockup: `planning/visuals/[file]` 119 | - [ ] 3.5 Apply base styles 120 | - Follow existing design system 121 | - Use variables from: [style file] 122 | - [ ] 3.6 Implement responsive design 123 | - Mobile: 320px - 768px 124 | - Tablet: 768px - 1024px 125 | - Desktop: 1024px+ 126 | - [ ] 3.7 Add interactions and animations 127 | - Hover states 128 | - Transitions 129 | - Loading states 130 | - [ ] 3.8 Ensure UI component tests pass 131 | - Run ONLY the 2-8 tests written in 3.1 132 | - Verify critical component behaviors work 133 | - Do NOT run the entire test suite at this stage 134 | 135 | **Acceptance Criteria:** 136 | - The 2-8 tests written in 3.1 pass 137 | - Components render correctly 138 | - Forms validate and submit 139 | - Matches visual design 140 | 141 | ### Testing 142 | 143 | #### Task Group 4: Test Review & Gap Analysis 144 | **Dependencies:** Task Groups 1-3 145 | 146 | - [ ] 4.0 Review existing tests and fill critical gaps only 147 | - [ ] 4.1 Review tests from Task Groups 1-3 148 | - Review the 2-8 tests written by database-engineer (Task 1.1) 149 | - Review the 2-8 tests written by api-engineer (Task 2.1) 150 | - Review the 2-8 tests written by ui-designer (Task 3.1) 151 | - Total existing tests: approximately 6-24 tests 152 | - [ ] 4.2 Analyze test coverage gaps for THIS feature only 153 | - Identify critical user workflows that lack test coverage 154 | - Focus ONLY on gaps related to this spec's feature requirements 155 | - Do NOT assess entire application test coverage 156 | - Prioritize end-to-end workflows over unit test gaps 157 | - [ ] 4.3 Write up to 10 additional strategic tests maximum 158 | - Add maximum of 10 new tests to fill identified critical gaps 159 | - Focus on integration points and end-to-end workflows 160 | - Do NOT write comprehensive coverage for all scenarios 161 | - Skip edge cases, performance tests, and accessibility tests unless business-critical 162 | - [ ] 4.4 Run feature-specific tests only 163 | - Run ONLY tests related to this spec's feature (tests from 1.1, 2.1, 3.1, and 4.3) 164 | - Expected total: approximately 16-34 tests maximum 165 | - Do NOT run the entire application test suite 166 | - Verify critical workflows pass 167 | 168 | **Acceptance Criteria:** 169 | - All feature-specific tests pass (approximately 16-34 tests total) 170 | - Critical user workflows for this feature are covered 171 | - No more than 10 additional tests added when filling in testing gaps 172 | - Testing focused exclusively on this spec's feature requirements 173 | 174 | ## Execution Order 175 | 176 | Recommended implementation sequence: 177 | 1. Database Layer (Task Group 1) 178 | 2. API Layer (Task Group 2) 179 | 3. Frontend Design (Task Group 3) 180 | 4. Test Review & Gap Analysis (Task Group 4) 181 | ``` 182 | 183 | **Note**: Adapt this structure based on the actual feature requirements. Some features may need: 184 | - Different task groups (e.g., email notifications, payment processing, data migration) 185 | - Different execution order based on dependencies 186 | - More or fewer sub-tasks per group 187 | 188 | ## Important Constraints 189 | 190 | - **Create tasks that are specific and verifiable** 191 | - **Group related tasks:** For example, group back-end engineering tasks together and front-end UI tasks together. 192 | - **Limit test writing during development**: 193 | - Each task group (1-3) should write 2-8 focused tests maximum 194 | - Tests should cover only critical behaviors, not exhaustive coverage 195 | - Test verification should run ONLY the newly written tests, not the entire suite 196 | - If there is a dedicated test coverage group for filling in gaps in test coverage, this group should add only a maximum of 10 additional tests IF NECESSARY to fill critical gaps 197 | - **Use a focused test-driven approach** where each task group starts with writing 2-8 tests (x.1 sub-task) and ends with running ONLY those tests (final sub-task) 198 | - **Include acceptance criteria** for each task group 199 | - **Reference visual assets** if visuals are available 200 | -------------------------------------------------------------------------------- /profiles/default/commands/orchestrate-tasks/orchestrate-tasks.md: -------------------------------------------------------------------------------- 1 | # Process for Orchestrating a Spec's Implementation 2 | 3 | Now that we have a spec and tasks list ready for implementation, we will proceed with orchestrating implementation of each task group by a dedicated agent using the following MULTI-PHASE process. 4 | 5 | Follow each of these phases and their individual workflows IN SEQUENCE: 6 | 7 | ## Multi-Phase Process 8 | 9 | ### FIRST: Get tasks.md for this spec 10 | 11 | IF you already know which spec we're working on and IF that spec folder has a `tasks.md` file, then use that and skip to the NEXT phase. 12 | 13 | IF you don't already know which spec we're working on and IF that spec folder doesn't yet have a `tasks.md` THEN output the following request to the user: 14 | 15 | ``` 16 | Please point me to a spec's `tasks.md` that you want to orchestrate implementation for. 17 | 18 | If you don't have one yet, then run any of these commands first: 19 | /shape-spec 20 | /write-spec 21 | /create-tasks 22 | ``` 23 | 24 | ### NEXT: Create orchestration.yml to serve as a roadmap for orchestration of task groups 25 | 26 | In this spec's folder, create this file: `agent-os/specs/[this-spec]/orchestration.yml`. 27 | 28 | Populate this file with with the names of each task group found in this spec's `tasks.md` and use this EXACT structure for the content of `orchestration.yml`: 29 | 30 | ```yaml 31 | task_groups: 32 | - name: [task-group-name] 33 | - name: [task-group-name] 34 | - name: [task-group-name] 35 | # Repeat for each task group found in tasks.md 36 | ``` 37 | 38 | {{IF use_claude_code_subagents}} 39 | ### NEXT: Ask user to assign subagents to each task group 40 | 41 | Next we must determine which subagents should be assigned to which task groups. Ask the user to provide this info using the following request to user and WAIT for user's response: 42 | 43 | ``` 44 | Please specify the name of each subagent to be assigned to each task group: 45 | 46 | 1. [task-group-name] 47 | 2. [task-group-name] 48 | 3. [task-group-name] 49 | [repeat for each task-group you've added to orchestration.yml] 50 | 51 | Simply respond with the subagent names and corresponding task group number and I'll update orchestration.yml accordingly. 52 | ``` 53 | 54 | Using the user's responses, update `orchestration.yml` to specify those subagent names. `orchestration.yml` should end up looking like this: 55 | 56 | ```yaml 57 | task_groups: 58 | - name: [task-group-name] 59 | claude_code_subagent: [subagent-name] 60 | - name: [task-group-name] 61 | claude_code_subagent: [subagent-name] 62 | - name: [task-group-name] 63 | claude_code_subagent: [subagent-name] 64 | # Repeat for each task group found in tasks.md 65 | ``` 66 | 67 | For example, after this step, the `orchestration.yml` file might look like this (exact names will vary): 68 | 69 | ```yaml 70 | task_groups: 71 | - name: authentication-system 72 | claude_code_subagent: backend-specialist 73 | - name: user-dashboard 74 | claude_code_subagent: frontend-specialist 75 | - name: api-endpoints 76 | claude_code_subagent: backend-specialist 77 | ``` 78 | {{ENDIF use_claude_code_subagents}} 79 | 80 | {{UNLESS standards_as_claude_code_skills}} 81 | ### NEXT: Ask user to assign standards to each task group 82 | 83 | Next we must determine which standards should guide the implementation of each task group. Ask the user to provide this info using the following request to user and WAIT for user's response: 84 | 85 | ``` 86 | Please specify the standard(s) that should be used to guide the implementation of each task group: 87 | 88 | 1. [task-group-name] 89 | 2. [task-group-name] 90 | 3. [task-group-name] 91 | [repeat for each task-group you've added to orchestration.yml] 92 | 93 | For each task group number, you can specify any combination of the following: 94 | 95 | "all" to include all of your standards 96 | "global/*" to include all of the files inside of standards/global 97 | "frontend/css.md" to include the css.md standard file 98 | "none" to include no standards for this task group. 99 | ``` 100 | 101 | Using the user's responses, update `orchestration.yml` to specify those standards for each task group. `orchestration.yml` should end up having AT LEAST the following information added to it: 102 | 103 | ```yaml 104 | task_groups: 105 | - name: [task-group-name] 106 | standards: 107 | - [users' 1st response for this task group] 108 | - [users' 2nd response for this task group] 109 | - [users' 3rd response for this task group] 110 | # Repeat for all standards that the user specified for this task group 111 | - name: [task-group-name] 112 | standards: 113 | - [users' 1st response for this task group] 114 | - [users' 2nd response for this task group] 115 | # Repeat for all standards that the user specified for this task group 116 | # Repeat for each task group found in tasks.md 117 | ``` 118 | 119 | For example, after this step, the `orchestration.yml` file might look like this (exact names will vary): 120 | 121 | ```yaml 122 | task_groups: 123 | - name: authentication-system 124 | standards: 125 | - all 126 | - name: user-dashboard 127 | standards: 128 | - global/* 129 | - frontend/components.md 130 | - frontend/css.md 131 | - name: task-group-with-no-standards 132 | - name: api-endpoints 133 | standards: 134 | - backend/* 135 | - global/error-handling.md 136 | ``` 137 | 138 | Note: If the `use_claude_code_subagents` flag is enabled, the final `orchestration.yml` would include BOTH `claude_code_subagent` assignments AND `standards` for each task group. 139 | {{ENDUNLESS standards_as_claude_code_skills}} 140 | 141 | {{IF use_claude_code_subagents}} 142 | ### NEXT: Delegate task groups implementations to assigned subagents 143 | 144 | Loop through each task group in `agent-os/specs/[this-spec]/tasks.md` and delegate its implementation to the assigned subagent specified in `orchestration.yml`. 145 | 146 | For each delegation, provide the subagent with: 147 | - The task group (including the parent task and all sub-tasks) 148 | - The spec file: `agent-os/specs/[this-spec]/spec.md` 149 | - Instruct subagent to: 150 | - Perform their implementation 151 | - Check off the task and sub-task(s) in `agent-os/specs/[this-spec]/tasks.md` 152 | {{UNLESS standards_as_claude_code_skills}} 153 | 154 | In addition to the above items, also instruct the subagent to closely adhere to the user's standards & preferences as specified in the following files. To build the list of file references to give to the subagent, follow these instructions: 155 | 156 | {{workflows/implementation/compile-implementation-standards}} 157 | 158 | Provide all of the above to the subagent when delegating tasks for it to implement. 159 | {{ENDUNLESS standards_as_claude_code_skills}} 160 | {{ENDIF use_claude_code_subagents}} 161 | 162 | {{UNLESS use_claude_code_subagents}} 163 | ### NEXT: Generate prompts 164 | 165 | Now we must generate an ordered series of prompt texts, which will be used to direct the implementation of each task group listed in `orchestration.yml`. 166 | 167 | Follow these steps to generate this spec's ordered series of prompts texts, each in its own .md file located in `agent-os/specs/[this-spec]/implementation/prompts/`. 168 | 169 | LOOP through EACH task group in `agent-os/specs/[this-spec]/tasks.md` and for each, use the following workflow to generate a markdown file with prompt text for each task group: 170 | 171 | #### Step 1. Create the prompt markdown file 172 | 173 | Create the prompt markdown file using this naming convention: 174 | `agent-os/specs/[this-spec]/implementation/prompts/[task-group-number]-[task-group-title].md`. 175 | 176 | For example, if the 3rd task group in tasks.md is named "Comment System" then create `3-comment-system.md`. 177 | 178 | #### Step 2. Populate the prompt file 179 | 180 | Populate the prompt markdown file using the following Prompt file content template. 181 | 182 | ##### Bracket content replacements 183 | 184 | In the content template below, replace "[spec-title]" and "[this-spec]" with the current spec's title, and "[task-group-number]" with the current task group's number. 185 | 186 | {{UNLESS standards_as_claude_code_skills}} 187 | To replace "[orchestrated-standards]", use the following workflow: 188 | 189 | {{workflows/implementation/compile-implementation-standards}} 190 | {{ENDUNLESS standards_as_claude_code_skills}} 191 | 192 | #### Prompt file content template: 193 | 194 | ```markdown 195 | We're continuing our implementation of [spec-title] by implementing task group number [task-group-number]: 196 | 197 | ## Implement this task and its sub-tasks: 198 | 199 | [paste entire task group including parent task, all of its' sub-tasks, and sub-bullet points] 200 | 201 | ## Understand the context 202 | 203 | Read @agent-os/specs/[this-spec]/spec.md to understand the context for this spec and where the current task fits into it. 204 | 205 | Also read these further context and reference: 206 | - @agent-os/specs/[this-spec/]/planning/requirements.md 207 | - @agent-os/specs/[this-spec/]/planning/visuals 208 | 209 | ## Perform the implementation 210 | 211 | {{workflows/implementation/implement-tasks}} 212 | 213 | {{UNLESS standards_as_claude_code_skills}} 214 | ## User Standards & Preferences Compliance 215 | 216 | IMPORTANT: Ensure that your implementation work is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files: 217 | 218 | [orchestrated-standards] 219 | {{ENDUNLESS standards_as_claude_code_skills}} 220 | ``` 221 | 222 | ### Step 3: Output the list of created prompt files 223 | 224 | Output to user the following: 225 | 226 | ``` 227 | Ready to begin implementation of [spec-title]! 228 | 229 | Use the following list of prompts to direct the implementation of each task group: 230 | 231 | [list prompt files in order] 232 | 233 | Input those prompts into this chat one-by-one or queue them to run in order. 234 | 235 | Progress will be tracked in `agent-os/specs/[this-spec]/tasks.md` 236 | ``` 237 | {{ENDUNLESS use_claude_code_subagents}} 238 | -------------------------------------------------------------------------------- /profiles/default/workflows/specification/research-spec.md: -------------------------------------------------------------------------------- 1 | # Spec Research 2 | 3 | ## Core Responsibilities 4 | 5 | 1. **Read Initial Idea**: Load the raw idea from initialization.md 6 | 2. **Analyze Product Context**: Understand product mission, roadmap, and how this feature fits 7 | 3. **Ask Clarifying Questions**: Generate targeted questions WITH visual asset request AND reusability check 8 | 4. **Process Answers**: Analyze responses and any provided visuals 9 | 5. **Ask Follow-ups**: Based on answers and visual analysis if needed 10 | 6. **Save Requirements**: Document the requirements you've gathered to a single file named: `[spec-path]/planning/requirements.md` 11 | 12 | ## Workflow 13 | 14 | ### Step 1: Read Initial Idea 15 | 16 | Read the raw idea from `[spec-path]/planning/initialization.md` to understand what the user wants to build. 17 | 18 | ### Step 2: Analyze Product Context 19 | 20 | Before generating questions, understand the broader product context: 21 | 22 | 1. **Read Product Mission**: Load `agent-os/product/mission.md` to understand: 23 | - The product's overall mission and purpose 24 | - Target users and their primary use cases 25 | - Core problems the product aims to solve 26 | - How users are expected to benefit 27 | 28 | 2. **Read Product Roadmap**: Load `agent-os/product/roadmap.md` to understand: 29 | - Features and capabilities already completed 30 | - The current state of the product 31 | - Where this new feature fits in the broader roadmap 32 | - Related features that might inform or constrain this work 33 | 34 | 3. **Read Product Tech Stack**: Load `agent-os/product/tech-stack.md` to understand: 35 | - Technologies and frameworks in use 36 | - Technical constraints and capabilities 37 | - Libraries and tools available 38 | 39 | This context will help you: 40 | - Ask more relevant and contextual questions 41 | - Identify existing features that might be reused or referenced 42 | - Ensure the feature aligns with product goals 43 | - Understand user needs and expectations 44 | 45 | ### Step 3: Generate First Round of Questions WITH Visual Request AND Reusability Check 46 | 47 | Based on the initial idea, generate 4-8 targeted, NUMBERED questions that explore requirements while suggesting reasonable defaults. 48 | 49 | **CRITICAL: Always include the visual asset request AND reusability question at the END of your questions.** 50 | 51 | **Question generation guidelines:** 52 | - Start each question with a number 53 | - Propose sensible assumptions based on best practices 54 | - Frame questions as "I'm assuming X, is that correct?" 55 | - Make it easy for users to confirm or provide alternatives 56 | - Include specific suggestions they can say yes/no to 57 | - Always end with an open question about exclusions 58 | 59 | **Required output format:** 60 | ``` 61 | Based on your idea for [spec name], I have some clarifying questions: 62 | 63 | 1. I assume [specific assumption]. Is that correct, or [alternative]? 64 | 2. I'm thinking [specific approach]. Should we [alternative]? 65 | 3. [Continue with numbered questions...] 66 | [Last numbered question about exclusions] 67 | 68 | **Existing Code Reuse:** 69 | Are there existing features in your codebase with similar patterns we should reference? For example: 70 | - Similar interface elements or UI components to re-use 71 | - Comparable page layouts or navigation patterns 72 | - Related backend logic or service objects 73 | - Existing models or controllers with similar functionality 74 | 75 | Please provide file/folder paths or names of these features if they exist. 76 | 77 | **Visual Assets Request:** 78 | Do you have any design mockups, wireframes, or screenshots that could help guide the development? 79 | 80 | If yes, please place them in: `[spec-path]/planning/visuals/` 81 | 82 | Use descriptive file names like: 83 | - homepage-mockup.png 84 | - dashboard-wireframe.jpg 85 | - lofi-form-layout.png 86 | - mobile-view.png 87 | - existing-ui-screenshot.png 88 | 89 | Please answer the questions above and let me know if you've added any visual files or can point to similar existing features. 90 | ``` 91 | 92 | **OUTPUT these questions to the orchestrator and STOP - wait for user response.** 93 | 94 | ### Step 4: Process Answers and MANDATORY Visual Check 95 | 96 | After receiving user's answers from the orchestrator: 97 | 98 | 1. Store the user's answers for later documentation 99 | 100 | 2. **MANDATORY: Check for visual assets regardless of user's response:** 101 | 102 | **CRITICAL**: You MUST run the following bash command even if the user says "no visuals" or doesn't mention visuals (Users often add files without mentioning them): 103 | 104 | ```bash 105 | # List all files in visuals folder - THIS IS MANDATORY 106 | ls -la [spec-path]/planning/visuals/ 2>/dev/null | grep -E '\.(png|jpg|jpeg|gif|svg|pdf)$' || echo "No visual files found" 107 | ``` 108 | 109 | 3. IF visual files are found (bash command returns filenames): 110 | - Use Read tool to analyze EACH visual file found 111 | - Note key design elements, patterns, and user flows 112 | - Document observations for each file 113 | - Check filenames for low-fidelity indicators (lofi, lo-fi, wireframe, sketch, rough, etc.) 114 | 115 | 4. IF user provided paths or names of similar features: 116 | - Make note of these paths/names for spec-writer to reference 117 | - DO NOT explore them yourself (to save time), but DO document their names for future reference by the spec-writer. 118 | 119 | ### Step 5: Generate Follow-up Questions (if needed) 120 | 121 | Determine if follow-up questions are needed based on: 122 | 123 | **Visual-triggered follow-ups:** 124 | - If visuals were found but user didn't mention them: "I found [filename(s)] in the visuals folder. Let me analyze these for the specification." 125 | - If filenames contain "lofi", "lo-fi", "wireframe", "sketch", or "rough": "I notice you've provided [filename(s)] which appear to be wireframes/low-fidelity mockups. Should we treat these as layout and structure guides rather than exact design specifications, using our application's existing styling instead?" 126 | - If visuals show features not discussed in answers 127 | - If there are discrepancies between answers and visuals 128 | 129 | **Reusability follow-ups:** 130 | - If user didn't provide similar features but the spec seems common: "This seems like it might share patterns with existing features. Could you point me to any similar forms/pages/logic in your app?" 131 | - If provided paths seem incomplete you can ask something like: "You mentioned [feature]. Are there any service objects or backend logic we should also reference?" 132 | 133 | **User's Answers-triggered follow-ups:** 134 | - Vague requirements need clarification 135 | - Missing technical details 136 | - Unclear scope boundaries 137 | 138 | **If follow-ups needed, OUTPUT to orchestrator:** 139 | ``` 140 | Based on your answers [and the visual files I found], I have a few follow-up questions: 141 | 142 | 1. [Specific follow-up question] 143 | 2. [Another follow-up if needed] 144 | 145 | Please provide these additional details. 146 | ``` 147 | 148 | **Then STOP and wait for responses.** 149 | 150 | ### Step 6: Save Complete Requirements 151 | 152 | After all questions are answered, record ALL gathered information to ONE FILE at this location with this name: `[spec-path]/planning/requirements.md` 153 | 154 | Use the following structure and do not deviate from this structure when writing your gathered information to `requirements.md`. Include ONLY the items specified in the following structure: 155 | 156 | ```markdown 157 | # Spec Requirements: [Spec Name] 158 | 159 | ## Initial Description 160 | [User's original spec description from initialization.md] 161 | 162 | ## Requirements Discussion 163 | 164 | ### First Round Questions 165 | 166 | **Q1:** [First question asked] 167 | **Answer:** [User's answer] 168 | 169 | **Q2:** [Second question asked] 170 | **Answer:** [User's answer] 171 | 172 | [Continue for all questions] 173 | 174 | ### Existing Code to Reference 175 | [Based on user's response about similar features] 176 | 177 | **Similar Features Identified:** 178 | - Feature: [Name] - Path: `[path provided by user]` 179 | - Components to potentially reuse: [user's description] 180 | - Backend logic to reference: [user's description] 181 | 182 | [If user provided no similar features] 183 | No similar existing features identified for reference. 184 | 185 | ### Follow-up Questions 186 | [If any were asked] 187 | 188 | **Follow-up 1:** [Question] 189 | **Answer:** [User's answer] 190 | 191 | ## Visual Assets 192 | 193 | ### Files Provided: 194 | [Based on actual bash check, not user statement] 195 | - `filename.png`: [Description of what it shows from your analysis] 196 | - `filename2.jpg`: [Key elements observed from your analysis] 197 | 198 | ### Visual Insights: 199 | - [Design patterns identified] 200 | - [User flow implications] 201 | - [UI components shown] 202 | - [Fidelity level: high-fidelity mockup / low-fidelity wireframe] 203 | 204 | [If bash check found no files] 205 | No visual assets provided. 206 | 207 | ## Requirements Summary 208 | 209 | ### Functional Requirements 210 | - [Core functionality based on answers] 211 | - [User actions enabled] 212 | - [Data to be managed] 213 | 214 | ### Reusability Opportunities 215 | - [Components that might exist already based on user's input] 216 | - [Backend patterns to investigate] 217 | - [Similar features to model after] 218 | 219 | ### Scope Boundaries 220 | **In Scope:** 221 | - [What will be built] 222 | 223 | **Out of Scope:** 224 | - [What won't be built] 225 | - [Future enhancements mentioned] 226 | 227 | ### Technical Considerations 228 | - [Integration points mentioned] 229 | - [Existing system constraints] 230 | - [Technology preferences stated] 231 | - [Similar code patterns to follow] 232 | ``` 233 | 234 | ### Step 7: Output Completion 235 | 236 | Return to orchestrator: 237 | 238 | ``` 239 | Requirements research complete! 240 | 241 | ✅ Processed [X] clarifying questions 242 | ✅ Visual check performed: [Found and analyzed Y files / No files found] 243 | ✅ Reusability opportunities: [Identified Z similar features / None identified] 244 | ✅ Requirements documented comprehensively 245 | 246 | Requirements saved to: `[spec-path]/planning/requirements.md` 247 | 248 | Ready for specification creation. 249 | ``` 250 | 251 | ## Important Constraints 252 | 253 | - **MANDATORY**: Always run bash command to check visuals folder after receiving user answers 254 | - DO NOT write technical specifications for development. Just record your findings from information gathering to this single file: `[spec-path]/planning/requirements.md`. 255 | - Visual check is based on actual file(s) found via bash, NOT user statements 256 | - Check filenames for low-fidelity indicators and clarify design intent if found 257 | - Ask about existing similar features to promote code reuse 258 | - Keep follow-ups minimal (1-3 questions max) 259 | - Save user's exact answers, not interpretations 260 | - Document all visual findings including fidelity level 261 | - Document paths to similar features for spec-writer to reference 262 | - OUTPUT questions and STOP to wait for orchestrator to relay responses 263 | -------------------------------------------------------------------------------- /scripts/create-profile.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # ============================================================================= 4 | # Agent OS Create Profile Script 5 | # Creates a new profile for Agent OS 6 | # ============================================================================= 7 | 8 | set -e # Exit on error 9 | 10 | # Get the directory where this script is located 11 | SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" 12 | BASE_DIR="$HOME/agent-os" 13 | PROFILES_DIR="$BASE_DIR/profiles" 14 | 15 | # Source common functions 16 | source "$SCRIPT_DIR/common-functions.sh" 17 | 18 | # ----------------------------------------------------------------------------- 19 | # Default Values 20 | # ----------------------------------------------------------------------------- 21 | 22 | PROFILE_NAME="" 23 | INHERIT_FROM="" 24 | COPY_FROM="" 25 | 26 | # ----------------------------------------------------------------------------- 27 | # Validation Functions 28 | # ----------------------------------------------------------------------------- 29 | 30 | validate_installation() { 31 | # Check base installation 32 | validate_base_installation 33 | 34 | if [[ ! -d "$PROFILES_DIR" ]]; then 35 | print_error "Profiles directory not found at $PROFILES_DIR" 36 | exit 1 37 | fi 38 | } 39 | 40 | # ----------------------------------------------------------------------------- 41 | # Profile Functions 42 | # ----------------------------------------------------------------------------- 43 | 44 | get_available_profiles() { 45 | local profiles=() 46 | 47 | # Find all directories in profiles/ 48 | for dir in "$PROFILES_DIR"/*; do 49 | if [[ -d "$dir" ]]; then 50 | profiles+=("$(basename "$dir")") 51 | fi 52 | done 53 | 54 | echo "${profiles[@]}" 55 | } 56 | 57 | # ----------------------------------------------------------------------------- 58 | # Profile Name Input 59 | # ----------------------------------------------------------------------------- 60 | 61 | get_profile_name() { 62 | local valid=false 63 | 64 | while [[ "$valid" == "false" ]]; do 65 | echo "" 66 | echo "" 67 | echo "" 68 | print_status "Enter a name for the new profile:" 69 | echo "Example names: 'rails', 'python', 'react', 'wordpress'" 70 | echo "" 71 | 72 | read -p "$(echo -e "${BLUE}Profile name: ${NC}")" profile_input 73 | 74 | # Normalize the name 75 | PROFILE_NAME=$(normalize_name "$profile_input") 76 | 77 | if [[ -z "$PROFILE_NAME" ]]; then 78 | print_error "Profile name cannot be empty" 79 | continue 80 | fi 81 | 82 | # Check if profile already exists 83 | if [[ -d "$PROFILES_DIR/$PROFILE_NAME" ]]; then 84 | print_error "Profile '$PROFILE_NAME' already exists" 85 | echo "Please choose a different name" 86 | continue 87 | fi 88 | 89 | valid=true 90 | print_success "Profile name set to: $PROFILE_NAME" 91 | done 92 | } 93 | 94 | # ----------------------------------------------------------------------------- 95 | # Inheritance Selection 96 | # ----------------------------------------------------------------------------- 97 | 98 | select_inheritance() { 99 | local profiles=($(get_available_profiles)) 100 | 101 | if [[ ${#profiles[@]} -eq 0 ]]; then 102 | print_warning "No existing profiles found to inherit from" 103 | INHERIT_FROM="" 104 | return 105 | fi 106 | 107 | echo "" 108 | echo "" 109 | echo "" 110 | 111 | if [[ ${#profiles[@]} -eq 1 ]]; then 112 | # Only one profile exists 113 | print_status "Should this profile inherit from the '${profiles[0]}' profile?" 114 | echo "" 115 | read -p "$(echo -e "${BLUE}Inherit from '${profiles[0]}'? (y/n): ${NC}")" inherit_choice 116 | 117 | if [[ "$inherit_choice" == "y" ]] || [[ "$inherit_choice" == "Y" ]]; then 118 | INHERIT_FROM="${profiles[0]}" 119 | print_success "Profile will inherit from: $INHERIT_FROM" 120 | else 121 | INHERIT_FROM="" 122 | print_status "Profile will not inherit from any profile" 123 | fi 124 | else 125 | # Multiple profiles exist 126 | print_status "Select a profile to inherit from:" 127 | echo "" 128 | echo " 1) Don't inherit from any profile" 129 | 130 | local index=2 131 | for profile in "${profiles[@]}"; do 132 | echo " $index) $profile" 133 | ((index++)) || true 134 | done 135 | 136 | echo "" 137 | read -p "$(echo -e "${BLUE}Enter selection (1-$((${#profiles[@]}+1))): ${NC}")" selection 138 | 139 | if [[ "$selection" == "1" ]]; then 140 | INHERIT_FROM="" 141 | print_status "Profile will not inherit from any profile" 142 | elif [[ "$selection" =~ ^[0-9]+$ ]] && [[ "$selection" -ge 2 ]] && [[ "$selection" -le $((${#profiles[@]}+1)) ]]; then 143 | INHERIT_FROM="${profiles[$((selection-2))]}" 144 | print_success "Profile will inherit from: $INHERIT_FROM" 145 | else 146 | print_error "Invalid selection" 147 | exit 1 148 | fi 149 | fi 150 | } 151 | 152 | # ----------------------------------------------------------------------------- 153 | # Copy Selection 154 | # ----------------------------------------------------------------------------- 155 | 156 | select_copy_source() { 157 | # Only ask about copying if not inheriting 158 | if [[ -n "$INHERIT_FROM" ]]; then 159 | COPY_FROM="" 160 | return 161 | fi 162 | 163 | local profiles=($(get_available_profiles)) 164 | 165 | if [[ ${#profiles[@]} -eq 0 ]]; then 166 | print_warning "No existing profiles found to copy from" 167 | COPY_FROM="" 168 | return 169 | fi 170 | 171 | echo "" 172 | echo "" 173 | echo "" 174 | 175 | if [[ ${#profiles[@]} -eq 1 ]]; then 176 | # Only one profile exists 177 | print_status "Do you want to copy the contents from the '${profiles[0]}' profile?" 178 | echo "" 179 | read -p "$(echo -e "${BLUE}Copy from '${profiles[0]}'? (y/n): ${NC}")" copy_choice 180 | 181 | if [[ "$copy_choice" == "y" ]] || [[ "$copy_choice" == "Y" ]]; then 182 | COPY_FROM="${profiles[0]}" 183 | print_success "Will copy contents from: $COPY_FROM" 184 | else 185 | COPY_FROM="" 186 | print_status "Will create empty profile structure" 187 | fi 188 | else 189 | # Multiple profiles exist 190 | print_status "Select a profile to copy from:" 191 | echo "" 192 | echo " 1) Don't copy from any profile" 193 | 194 | local index=2 195 | for profile in "${profiles[@]}"; do 196 | echo " $index) $profile" 197 | ((index++)) || true 198 | done 199 | 200 | echo "" 201 | read -p "$(echo -e "${BLUE}Enter selection (1-$((${#profiles[@]}+1))): ${NC}")" selection 202 | 203 | if [[ "$selection" == "1" ]]; then 204 | COPY_FROM="" 205 | print_status "Will create empty profile structure" 206 | elif [[ "$selection" =~ ^[0-9]+$ ]] && [[ "$selection" -ge 2 ]] && [[ "$selection" -le $((${#profiles[@]}+1)) ]]; then 207 | COPY_FROM="${profiles[$((selection-2))]}" 208 | print_success "Will copy contents from: $COPY_FROM" 209 | else 210 | print_error "Invalid selection" 211 | exit 1 212 | fi 213 | fi 214 | } 215 | 216 | # ----------------------------------------------------------------------------- 217 | # Profile Creation 218 | # ----------------------------------------------------------------------------- 219 | 220 | create_profile_structure() { 221 | local profile_path="$PROFILES_DIR/$PROFILE_NAME" 222 | 223 | print_status "Creating profile structure..." 224 | 225 | if [[ -n "$COPY_FROM" ]]; then 226 | # Copy from existing profile 227 | print_status "Copying from profile: $COPY_FROM" 228 | cp -r "$PROFILES_DIR/$COPY_FROM" "$profile_path" 229 | 230 | # Update profile-config.yml 231 | cat > "$profile_path/profile-config.yml" << EOF 232 | inherits_from: false 233 | 234 | # Profile configuration for $PROFILE_NAME 235 | # Copied from: $COPY_FROM 236 | EOF 237 | 238 | print_success "Profile copied and configured" 239 | 240 | else 241 | # Create new structure 242 | mkdir -p "$profile_path" 243 | 244 | # Create standard directories 245 | mkdir -p "$profile_path/standards/" 246 | mkdir -p "$profile_path/workflows/implementation" 247 | mkdir -p "$profile_path/workflows/planning" 248 | mkdir -p "$profile_path/workflows/specification" 249 | 250 | # Create profile-config.yml 251 | if [[ -n "$INHERIT_FROM" ]]; then 252 | cat > "$profile_path/profile-config.yml" << EOF 253 | inherits_from: $INHERIT_FROM 254 | 255 | # Uncomment and modify to exclude specific inherited files: 256 | # exclude_inherited_files: 257 | # - standards/backend/api/* 258 | # - standards/backend/database/migrations.md 259 | # - workflows/implementation/specific-workflow.md 260 | EOF 261 | else 262 | cat > "$profile_path/profile-config.yml" << EOF 263 | inherits_from: false 264 | 265 | # Profile configuration for $PROFILE_NAME 266 | EOF 267 | fi 268 | 269 | print_success "Profile structure created" 270 | fi 271 | } 272 | 273 | # ----------------------------------------------------------------------------- 274 | # Main Execution 275 | # ----------------------------------------------------------------------------- 276 | 277 | main() { 278 | clear 279 | echo "" 280 | echo -e "${BLUE}=== Agent OS - Create Profile Utility ===${NC}" 281 | echo "" 282 | 283 | # Validate installation 284 | validate_installation 285 | 286 | # Get profile name 287 | get_profile_name 288 | 289 | # Select inheritance 290 | select_inheritance 291 | 292 | # Select copy source (if not inheriting) 293 | select_copy_source 294 | 295 | # Create the profile 296 | create_profile_structure 297 | 298 | # Success message 299 | echo "" 300 | echo -e "${GREEN}════════════════════════════════════════════${NC}" 301 | echo "" 302 | print_success "Profile '$PROFILE_NAME' has been successfully created!" 303 | echo "" 304 | print_status "Location: $PROFILES_DIR/$PROFILE_NAME" 305 | 306 | if [[ -n "$INHERIT_FROM" ]]; then 307 | echo "" 308 | print_status "This profile inherits from: $INHERIT_FROM" 309 | elif [[ -n "$COPY_FROM" ]]; then 310 | echo "" 311 | print_status "This profile was copied from: $COPY_FROM" 312 | fi 313 | 314 | echo "" 315 | print_status "Next steps:" 316 | echo " 1. Customize standards, workflows, and configurations in your profile" 317 | echo " 2. Install Agent OS in a project using this profile with: ~/agent-os/scripts/project-install.sh --profile $PROFILE_NAME" 318 | echo "" 319 | echo -e "${GREEN}Visit the docs on customizing your profile: https://buildermethods.com/agent-os/profiles${NC}" 320 | echo "" 321 | echo -e "${GREEN}════════════════════════════════════════════${NC}" 322 | echo "" 323 | } 324 | 325 | # Run main function 326 | main "$@" 327 | -------------------------------------------------------------------------------- /profiles/default/workflows/specification/verify-spec.md: -------------------------------------------------------------------------------- 1 | # Spec Verification 2 | 3 | ## Core Responsibilities 4 | 5 | 1. **Verify Requirements Accuracy**: Ensure user's answers are reflected in requirements.md 6 | 2. **Check Structural Integrity**: Verify all expected files and folders exist 7 | 3. **Analyze Visual Alignment**: If visuals exist, verify they're properly referenced 8 | 4. **Validate Reusability**: Check that existing code is reused appropriately 9 | 5. **Verify Limited Testing Approach**: Ensure tasks follow focused, limited test writing (2-8 tests per task group) 10 | 6. **Document Findings**: Create verification report 11 | 12 | ## Workflow 13 | 14 | ### Step 1: Gather User Q&A Data 15 | 16 | Read these materials that were provided to you so that you can use them as the basis for upcoming verifications and THINK HARD: 17 | - The questions that were asked to the user during requirements gathering 18 | - The user's raw responses to those questions 19 | - The spec folder path 20 | 21 | ### Step 2: Basic Structural Verification 22 | 23 | Perform these checks: 24 | 25 | #### Check 1: Requirements Accuracy 26 | Read `agent-os/specs/[this-spec]/planning/requirements.md` and verify: 27 | - All user answers from the Q&A are accurately captured 28 | - No answers are missing or misrepresented 29 | - Any follow-up questions and answers are included 30 | - Reusability opportunities are documented (paths or names of similar features)—but DO NOT search and read these paths. Just verify existence of their documentation in requirements.md. 31 | - Any additional notes that the user provided are included in requirements.md. 32 | 33 | #### Check 2: Visual Assets 34 | 35 | Check for existence of any visual assets in the planning/visuals folder by running: 36 | 37 | ```bash 38 | # Check for visual assets 39 | ls -la [spec-path]/planning/visuals/ 2>/dev/null | grep -v "^total" | grep -v "^d" 40 | ``` 41 | 42 | IF visuals exist verify they're mentioned in requirements.md 43 | 44 | ### Step 3: Deep Content Validation 45 | 46 | Perform these detailed content checks: 47 | 48 | #### Check 3: Visual Asset Analysis (if visuals exist) 49 | If visual files were found in Check 4: 50 | 1. **Read each visual file** in `agent-os/specs/[this-spec]/planning/visuals/` 51 | 2. **Document what you observe**: UI components, layouts, colors, typography, spacing, interaction patterns 52 | 3. **Verify these design elements appear in**: 53 | - `agent-os/specs/[this-spec]/spec.md` - Check if visual elements, layout or important visual details are present: 54 | - Verification examples (depending on the visuals): 55 | * UI Components section matches visual components 56 | * Page Layouts section reflects visual layouts 57 | * Styling Guidelines align with visual design 58 | - `agent-os/specs/[this-spec]/tasks.md` - Confirm at least some tasks specifically reference: 59 | * Visual file names 60 | * Components shown in visuals 61 | * Layouts depicted in mockups 62 | 63 | #### Check 4: Requirements Deep Dive 64 | Read `agent-os/specs/[this-spec]/planning/requirements.md` and create a mental list of: 65 | - **Explicit features requested**: What the user specifically said they want 66 | - **Constraints stated**: Limitations, performance needs, or technical requirements 67 | - **Out-of-scope items**: What the user explicitly said NOT to include 68 | - **Reusability opportunities**: Names of similar features/paths the user provided 69 | - **Implicit needs**: Things implied but not directly stated 70 | 71 | #### Check 5: Core Specification Validation 72 | Read `agent-os/specs/[this-spec]/spec.md` and verify each section: 73 | 1. **Goal**: Must directly address the problem stated in initial requirements 74 | 2. **User Stories**: The stories are relevant and aligned to the initial requirements 75 | 3. **Core Requirements**: Only include features from the requirement stated explicit features 76 | 4. **Out of Scope**: Must match what the requirements state should not be included in scope 77 | 5. **Reusability Notes**: The spec mentions similar features to reuse (if user provided them) 78 | 79 | Look for these issues: 80 | - Added features not in requirements 81 | - Missing features that were requested 82 | - Changed scope from what was discussed 83 | - Missing reusability opportunities (if user provided any) 84 | 85 | #### Check 6: Task List Detailed Validation 86 | Read `agent-os/specs/[this-spec]/tasks.md` and check each task group's tasks: 87 | 1. **Test Writing Limits**: Verify test writing follows limited approach: 88 | - Each implementation task group (1-3) should specify writing 2-8 focused tests maximum 89 | - Test verification subtasks should run ONLY the newly written tests, not entire suite 90 | - Testing-engineer's task group should add maximum 10 additional tests if necessary 91 | - Flag if tasks call for comprehensive/exhaustive testing or running full test suite 92 | 2. **Reusability References**: Tasks should note "(reuse existing: [name])" where applicable 93 | 3. **Specificity**: Each task must reference a specific feature/component 94 | 4. **Traceability**: Each task must trace back to requirements 95 | 5. **Scope**: No tasks for features not in requirements 96 | 6. **Visual alignment**: Visual files (if they exist) must be referenced in at least some tasks 97 | 7. **Task count**: Should be 3-10 tasks per task group (flag if >10 or <3) 98 | 99 | #### Check 7: Reusability and Over-Engineering Check 100 | Review all specifications for: 101 | 1. **Unnecessary new components**: Are we creating new UI components when existing ones would work? 102 | 2. **Duplicated logic**: Are we recreating backend logic that already exists? 103 | 3. **Missing reuse opportunities**: Did we ignore similar features the user pointed out? 104 | 4. **Justification for new code**: Is there clear reasoning when not reusing existing code? 105 | 106 | ### Step 4: Document Findings and Issues 107 | 108 | Create `agent-os/specs/[this-spec]/verification/spec-verification.md` with the following structure: 109 | 110 | ```markdown 111 | # Specification Verification Report 112 | 113 | ## Verification Summary 114 | - Overall Status: ✅ Passed / ⚠️ Issues Found / ❌ Failed 115 | - Date: [Current date] 116 | - Spec: [Spec name] 117 | - Reusability Check: ✅ Passed / ⚠️ Concerns / ❌ Failed 118 | - Test Writing Limits: ✅ Compliant / ⚠️ Partial / ❌ Excessive Testing 119 | 120 | ## Structural Verification (Checks 1-2) 121 | 122 | ### Check 1: Requirements Accuracy 123 | [Document any discrepancies between Q&A and requirements.md] 124 | ✅ All user answers accurately captured 125 | ✅ Reusability opportunities documented 126 | [OR specific issues like:] 127 | ⚠️ User mentioned similar feature at "app/views/posts" but not in requirements 128 | 129 | ### Check 2: Visual Assets 130 | [Document visual files found and verification] 131 | ✅ Found 3 visual files, all referenced in requirements.md 132 | [OR issues] 133 | 134 | ## Content Validation (Checks 3-7) 135 | 136 | ### Check 3: Visual Design Tracking 137 | [Only if visuals exist] 138 | **Visual Files Analyzed:** 139 | - `homepage-mockup.png`: Shows header with logo, 3-column grid, footer 140 | - `form-design.jpg`: Shows 5 form fields with specific labels 141 | 142 | **Design Element Verification:** 143 | - Header with logo: ✅ Specified in spec.md 144 | - 3-column grid: ⚠️ Not in tasks.md 145 | - Form fields: ✅ All 5 fields in spec.md 146 | [List each visual element and its status] 147 | 148 | ### Check 4: Requirements Coverage 149 | **Explicit Features Requested:** 150 | - Feature A: ✅ Covered in specs 151 | - Feature B: ❌ Missing from specs 152 | [List all] 153 | 154 | **Reusability Opportunities:** 155 | - Similar forms at app/views/posts: ✅ Referenced in spec 156 | - UserService pattern: ⚠️ Not leveraged in spec 157 | 158 | **Out-of-Scope Items:** 159 | - Correctly excluded: [list] 160 | - Incorrectly included: [list] 161 | 162 | ### Check 5: Core Specification Issues 163 | - Goal alignment: ✅ Matches user need 164 | - User stories: ⚠️ Story #3 not from requirements 165 | - Core requirements: ✅ All from user discussion 166 | - Out of scope: ❌ Missing "no payment processing" 167 | - Reusability notes: ⚠️ Missing reference to similar features 168 | 169 | ### Check 6: Task List Issues 170 | 171 | **Test Writing Limits:** 172 | - ✅ Task Group 1 specifies 2-8 focused tests 173 | - ❌ Task Group 2 calls for "comprehensive test coverage" (violates limits) 174 | - ⚠️ Task Group 3 doesn't specify test limits 175 | - ❌ Testing-engineer group plans 25 additional tests (exceeds 10 max) 176 | - ❌ Tasks call for running entire test suite (should run only new tests) 177 | [OR if compliant:] 178 | - ✅ All task groups specify 2-8 focused tests maximum 179 | - ✅ Test verification limited to newly written tests only 180 | - ✅ Testing-engineer adds maximum 10 tests 181 | 182 | **Reusability References:** 183 | - ❌ Task 3.2 doesn't mention reusing existing form partial 184 | - ❌ Task 4.3 recreates validation that exists in UserValidator 185 | 186 | **Task Specificity:** 187 | - ⚠️ Task 3.4 "Implement best practices" too vague 188 | - ⚠️ Task 4.2 "Add validation" needs specifics 189 | 190 | **Visual References:** 191 | - ❌ Interface tasks don't mention mockup files 192 | - ❌ No tasks for header component from mockup 193 | 194 | **Task Count:** 195 | - Structure: 6 tasks ✅ 196 | - Interface: 12 tasks ⚠️ (possibly over-engineered) 197 | 198 | ### Check 7: Reusability and Over-Engineering 199 | **Unnecessary New Components:** 200 | - ❌ Creating new FormField component when shared/_form_field.erb exists 201 | - ❌ New DataTable when components/data_table.erb available 202 | 203 | **Duplicated Logic:** 204 | - ⚠️ EmailValidator being recreated (exists in app/validators/) 205 | - ⚠️ Similar pagination logic already in PaginationService 206 | 207 | **Missing Reuse Opportunities:** 208 | - User pointed to app/views/posts but not referenced 209 | - Existing test factories not mentioned in Quality spec 210 | 211 | ## Critical Issues 212 | [Issues that must be fixed before implementation] 213 | 1. Not reusing existing FormField component - will create duplication 214 | 3. Visual mockup ignored: Sidebar in mockup but not specified 215 | 216 | ## Minor Issues 217 | [Issues that should be addressed but don't block progress] 218 | 1. Vague task descriptions 219 | 2. Extra database field that wasn't requested 220 | 3. Could leverage existing validators 221 | 222 | ## Over-Engineering Concerns 223 | [Features/complexity added beyond requirements] 224 | 1. Creating new components instead of reusing: FormField, DataTable 225 | 2. Audit logging system not requested 226 | 3. Complex state management for simple form 227 | 4. Excessive test coverage planned (e.g., 50+ tests when 16-34 is appropriate) 228 | 5. Comprehensive test suite requirements violating focused testing approach 229 | 230 | ## Recommendations 231 | 1. Update spec to reuse existing form components 232 | 2. Reorder tasks to take dependencies into account 233 | 3. Add reusability analysis sections to spec 234 | 4. Update tasks to reference existing code where applicable 235 | 5. Remove unnecessary new component creation 236 | 237 | ## Conclusion 238 | [Overall assessment: Ready for implementation? Needs revision? Major concerns?] 239 | ``` 240 | 241 | ### Step 5: Output Summary 242 | 243 | OUTPUT the following: 244 | 245 | ``` 246 | Specification verification complete! 247 | 248 | ✅ Verified requirements accuracy 249 | ✅ Checked structural integrity 250 | ✅ Validated specification alignment 251 | ✅ Verified test writing limits (2-8 tests per task group, ~16-34 total) 252 | [If visuals] ✅ Analyzed [X] visual assets 253 | ⚠️ Reusability check: [Y issues found] 254 | 255 | [If passed] 256 | All specifications accurately reflect requirements, follow limited testing approach, and properly leverage existing code 257 | 258 | [If issues found] 259 | ⚠️ Found [X] issues requiring attention: 260 | - [Number] reusability issues 261 | - [Number] test writing limit violations 262 | - [Number] critical issues 263 | - [Number] minor issues 264 | - [Number] over-engineering concerns 265 | 266 | See agent-os/specs/[this-spec]/verification/spec-verification.md for full details. 267 | ``` 268 | 269 | ## Important Constraints 270 | 271 | - Compare user's raw answers against requirements.md exactly 272 | - Check for reusability opportunities and verify that they're documented but DO NOT search and explore the codebase yourself. 273 | - Verify test writing limits strictly: Flag any tasks that call for comprehensive testing, exhaustive coverage, or running full test suites 274 | - Expected test counts: Implementation task groups should write 2-8 tests each, testing-engineer adds maximum 10, total ~16-34 tests per feature 275 | - Don't add new requirements or specifications 276 | - Focus on alignment and accuracy, not style 277 | - Be specific about any issues found 278 | - Distinguish between critical and minor issues 279 | - Always check visuals even if not mentioned in requirements 280 | - Document everything for transparency 281 | - Visual design elements must be traceable through all specs 282 | - Reusability should be prioritized in specs and tasks over creating new code 283 | -------------------------------------------------------------------------------- /scripts/project-install.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # ============================================================================= 4 | # Agent OS Project Installation Script 5 | # Installs Agent OS into a project's codebase 6 | # ============================================================================= 7 | 8 | set -e # Exit on error 9 | 10 | # Get the directory where this script is located 11 | SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" 12 | BASE_DIR="$HOME/agent-os" 13 | PROJECT_DIR="$(pwd)" 14 | 15 | # Source common functions 16 | source "$SCRIPT_DIR/common-functions.sh" 17 | 18 | # ----------------------------------------------------------------------------- 19 | # Default Values 20 | # ----------------------------------------------------------------------------- 21 | 22 | DRY_RUN="false" 23 | VERBOSE="false" 24 | PROFILE="" 25 | CLAUDE_CODE_COMMANDS="" 26 | USE_CLAUDE_CODE_SUBAGENTS="" 27 | AGENT_OS_COMMANDS="" 28 | STANDARDS_AS_CLAUDE_CODE_SKILLS="" 29 | RE_INSTALL="false" 30 | OVERWRITE_ALL="false" 31 | OVERWRITE_STANDARDS="false" 32 | OVERWRITE_COMMANDS="false" 33 | OVERWRITE_AGENTS="false" 34 | INSTALLED_FILES=() 35 | 36 | # ----------------------------------------------------------------------------- 37 | # Help Function 38 | # ----------------------------------------------------------------------------- 39 | 40 | show_help() { 41 | cat << EOF 42 | Usage: $0 [OPTIONS] 43 | 44 | Install Agent OS into the current project directory. 45 | 46 | Options: 47 | --profile PROFILE Use specified profile (default: from config.yml) 48 | --claude-code-commands [BOOL] Install Claude Code commands (default: from config.yml) 49 | --use-claude-code-subagents [BOOL] Use Claude Code subagents (default: from config.yml) 50 | --agent-os-commands [BOOL] Install agent-os commands (default: from config.yml) 51 | --standards-as-claude-code-skills [BOOL] Use Claude Code Skills for standards (default: from config.yml) 52 | --re-install Delete and reinstall Agent OS 53 | --overwrite-all Overwrite all existing files during update 54 | --overwrite-standards Overwrite existing standards during update 55 | --overwrite-commands Overwrite existing commands during update 56 | --overwrite-agents Overwrite existing agents during update 57 | --dry-run Show what would be done without doing it 58 | --verbose Show detailed output 59 | -h, --help Show this help message 60 | 61 | Note: Flags accept both hyphens and underscores (e.g., --use-claude-code-subagents or --use_claude_code_subagents) 62 | 63 | Examples: 64 | $0 65 | $0 --profile rails 66 | $0 --claude-code-commands true --use-claude-code-subagents true 67 | $0 --agent-os-commands true --dry-run 68 | 69 | EOF 70 | exit 0 71 | } 72 | 73 | # ----------------------------------------------------------------------------- 74 | # Parse Command Line Arguments 75 | # ----------------------------------------------------------------------------- 76 | 77 | parse_arguments() { 78 | while [[ $# -gt 0 ]]; do 79 | # Normalize flag by replacing underscores with hyphens 80 | local flag="${1//_/-}" 81 | 82 | case $flag in 83 | --profile) 84 | PROFILE="$2" 85 | shift 2 86 | ;; 87 | --claude-code-commands) 88 | read CLAUDE_CODE_COMMANDS shift_count <<< "$(parse_bool_flag "$CLAUDE_CODE_COMMANDS" "$2")" 89 | shift $shift_count 90 | ;; 91 | --use-claude-code-subagents) 92 | read USE_CLAUDE_CODE_SUBAGENTS shift_count <<< "$(parse_bool_flag "$USE_CLAUDE_CODE_SUBAGENTS" "$2")" 93 | shift $shift_count 94 | ;; 95 | --agent-os-commands) 96 | read AGENT_OS_COMMANDS shift_count <<< "$(parse_bool_flag "$AGENT_OS_COMMANDS" "$2")" 97 | shift $shift_count 98 | ;; 99 | --standards-as-claude-code-skills) 100 | read STANDARDS_AS_CLAUDE_CODE_SKILLS shift_count <<< "$(parse_bool_flag "$STANDARDS_AS_CLAUDE_CODE_SKILLS" "$2")" 101 | shift $shift_count 102 | ;; 103 | --re-install) 104 | RE_INSTALL="true" 105 | shift 106 | ;; 107 | --overwrite-all) 108 | OVERWRITE_ALL="true" 109 | shift 110 | ;; 111 | --overwrite-standards) 112 | OVERWRITE_STANDARDS="true" 113 | shift 114 | ;; 115 | --overwrite-commands) 116 | OVERWRITE_COMMANDS="true" 117 | shift 118 | ;; 119 | --overwrite-agents) 120 | OVERWRITE_AGENTS="true" 121 | shift 122 | ;; 123 | --dry-run) 124 | DRY_RUN="true" 125 | shift 126 | ;; 127 | --verbose) 128 | VERBOSE="true" 129 | shift 130 | ;; 131 | -h|--help) 132 | show_help 133 | ;; 134 | *) 135 | print_error "Unknown option: $1" 136 | show_help 137 | ;; 138 | esac 139 | done 140 | } 141 | 142 | # ----------------------------------------------------------------------------- 143 | # Configuration Functions 144 | # ----------------------------------------------------------------------------- 145 | 146 | load_configuration() { 147 | # Load base configuration using common function 148 | load_base_config 149 | 150 | # Set effective values (command line overrides base config) 151 | EFFECTIVE_PROFILE="${PROFILE:-$BASE_PROFILE}" 152 | EFFECTIVE_CLAUDE_CODE_COMMANDS="${CLAUDE_CODE_COMMANDS:-$BASE_CLAUDE_CODE_COMMANDS}" 153 | EFFECTIVE_USE_CLAUDE_CODE_SUBAGENTS="${USE_CLAUDE_CODE_SUBAGENTS:-$BASE_USE_CLAUDE_CODE_SUBAGENTS}" 154 | EFFECTIVE_AGENT_OS_COMMANDS="${AGENT_OS_COMMANDS:-$BASE_AGENT_OS_COMMANDS}" 155 | EFFECTIVE_STANDARDS_AS_CLAUDE_CODE_SKILLS="${STANDARDS_AS_CLAUDE_CODE_SKILLS:-$BASE_STANDARDS_AS_CLAUDE_CODE_SKILLS}" 156 | EFFECTIVE_VERSION="$BASE_VERSION" 157 | 158 | # Validate configuration using common function (may override EFFECTIVE_STANDARDS_AS_CLAUDE_CODE_SKILLS if dependency not met) 159 | validate_config "$EFFECTIVE_CLAUDE_CODE_COMMANDS" "$EFFECTIVE_USE_CLAUDE_CODE_SUBAGENTS" "$EFFECTIVE_AGENT_OS_COMMANDS" "$EFFECTIVE_STANDARDS_AS_CLAUDE_CODE_SKILLS" "$EFFECTIVE_PROFILE" 160 | 161 | print_verbose "Configuration loaded:" 162 | print_verbose " Profile: $EFFECTIVE_PROFILE" 163 | print_verbose " Claude Code commands: $EFFECTIVE_CLAUDE_CODE_COMMANDS" 164 | print_verbose " Use Claude Code subagents: $EFFECTIVE_USE_CLAUDE_CODE_SUBAGENTS" 165 | print_verbose " Agent OS commands: $EFFECTIVE_AGENT_OS_COMMANDS" 166 | print_verbose " Standards as Claude Code Skills: $EFFECTIVE_STANDARDS_AS_CLAUDE_CODE_SKILLS" 167 | } 168 | 169 | # ----------------------------------------------------------------------------- 170 | # Installation Functions 171 | # ----------------------------------------------------------------------------- 172 | 173 | # Install standards files 174 | install_standards() { 175 | if [[ "$DRY_RUN" != "true" ]]; then 176 | print_status "Installing standards" 177 | fi 178 | 179 | local standards_count=0 180 | 181 | while read file; do 182 | if [[ "$file" == standards/* ]]; then 183 | local source=$(get_profile_file "$EFFECTIVE_PROFILE" "$file" "$BASE_DIR") 184 | local dest="$PROJECT_DIR/agent-os/$file" 185 | 186 | if [[ -f "$source" ]]; then 187 | local installed_file=$(copy_file "$source" "$dest") 188 | if [[ -n "$installed_file" ]]; then 189 | INSTALLED_FILES+=("$installed_file") 190 | ((standards_count++)) || true 191 | fi 192 | fi 193 | fi 194 | done < <(get_profile_files "$EFFECTIVE_PROFILE" "$BASE_DIR" "standards") 195 | 196 | if [[ "$DRY_RUN" != "true" ]]; then 197 | if [[ $standards_count -gt 0 ]]; then 198 | echo "✓ Installed $standards_count standards in agent-os/standards" 199 | fi 200 | fi 201 | } 202 | 203 | # Install and compile single-agent mode commands 204 | # Install Claude Code commands with delegation (multi-agent files) 205 | install_claude_code_commands_with_delegation() { 206 | if [[ "$DRY_RUN" != "true" ]]; then 207 | print_status "Installing Claude Code commands (with delegation to subagents)..." 208 | fi 209 | 210 | local commands_count=0 211 | local target_dir="$PROJECT_DIR/.claude/commands/agent-os" 212 | 213 | mkdir -p "$target_dir" 214 | 215 | while read file; do 216 | # Process multi-agent command files OR orchestrate-tasks special case 217 | if [[ "$file" == commands/*/multi-agent/* ]] || [[ "$file" == commands/orchestrate-tasks/orchestrate-tasks.md ]]; then 218 | local source=$(get_profile_file "$EFFECTIVE_PROFILE" "$file" "$BASE_DIR") 219 | if [[ -f "$source" ]]; then 220 | # Extract command name from path (e.g., commands/create-spec/multi-agent/create-spec.md -> create-spec) 221 | local cmd_name=$(echo "$file" | cut -d'/' -f2) 222 | local dest="$target_dir/${cmd_name}.md" 223 | 224 | # Compile with workflow and standards injection (includes conditional compilation) 225 | local compiled=$(compile_command "$source" "$dest" "$BASE_DIR" "$EFFECTIVE_PROFILE") 226 | if [[ "$DRY_RUN" == "true" ]]; then 227 | INSTALLED_FILES+=("$dest") 228 | fi 229 | ((commands_count++)) || true 230 | fi 231 | fi 232 | done < <(get_profile_files "$EFFECTIVE_PROFILE" "$BASE_DIR" "commands") 233 | 234 | if [[ "$DRY_RUN" != "true" ]]; then 235 | if [[ $commands_count -gt 0 ]]; then 236 | echo "✓ Installed $commands_count Claude Code commands (with delegation)" 237 | fi 238 | fi 239 | } 240 | 241 | # Install Claude Code commands without delegation (single-agent files with injection) 242 | install_claude_code_commands_without_delegation() { 243 | if [[ "$DRY_RUN" != "true" ]]; then 244 | print_status "Installing Claude Code commands (without delegation)..." 245 | fi 246 | 247 | local commands_count=0 248 | 249 | while read file; do 250 | # Process single-agent command files OR orchestrate-tasks special case 251 | if [[ "$file" == commands/*/single-agent/* ]] || [[ "$file" == commands/orchestrate-tasks/orchestrate-tasks.md ]]; then 252 | local source=$(get_profile_file "$EFFECTIVE_PROFILE" "$file" "$BASE_DIR") 253 | if [[ -f "$source" ]]; then 254 | # Handle orchestrate-tasks specially (flat destination) 255 | if [[ "$file" == commands/orchestrate-tasks/orchestrate-tasks.md ]]; then 256 | local dest="$PROJECT_DIR/.claude/commands/agent-os/orchestrate-tasks.md" 257 | # Compile without PHASE embedding for orchestrate-tasks 258 | local compiled=$(compile_command "$source" "$dest" "$BASE_DIR" "$EFFECTIVE_PROFILE" "") 259 | if [[ "$DRY_RUN" == "true" ]]; then 260 | INSTALLED_FILES+=("$dest") 261 | fi 262 | ((commands_count++)) || true 263 | else 264 | # Only install non-numbered files (e.g., plan-product.md, not 1-product-concept.md) 265 | local filename=$(basename "$file") 266 | if [[ ! "$filename" =~ ^[0-9]+-.*\.md$ ]]; then 267 | # Extract command name (e.g., commands/plan-product/single-agent/plan-product.md -> plan-product.md) 268 | local cmd_name=$(echo "$file" | sed 's|commands/\([^/]*\)/single-agent/.*|\1|') 269 | local dest="$PROJECT_DIR/.claude/commands/agent-os/$cmd_name.md" 270 | 271 | # Compile with PHASE embedding (mode="embed") 272 | local compiled=$(compile_command "$source" "$dest" "$BASE_DIR" "$EFFECTIVE_PROFILE" "embed") 273 | if [[ "$DRY_RUN" == "true" ]]; then 274 | INSTALLED_FILES+=("$dest") 275 | fi 276 | ((commands_count++)) || true 277 | fi 278 | fi 279 | fi 280 | fi 281 | done < <(get_profile_files "$EFFECTIVE_PROFILE" "$BASE_DIR" "commands") 282 | 283 | if [[ "$DRY_RUN" != "true" ]]; then 284 | if [[ $commands_count -gt 0 ]]; then 285 | echo "✓ Installed $commands_count Claude Code commands (without delegation)" 286 | fi 287 | fi 288 | } 289 | 290 | # Install Claude Code static agents 291 | install_claude_code_agents() { 292 | if [[ "$DRY_RUN" != "true" ]]; then 293 | print_status "Installing Claude Code agents..." 294 | fi 295 | 296 | local agents_count=0 297 | local target_dir="$PROJECT_DIR/.claude/agents/agent-os" 298 | 299 | mkdir -p "$target_dir" 300 | 301 | while read file; do 302 | # Include all agent files (flatten structure - no subfolders in output) 303 | if [[ "$file" == agents/*.md ]] && [[ "$file" != agents/templates/* ]]; then 304 | local source=$(get_profile_file "$EFFECTIVE_PROFILE" "$file" "$BASE_DIR") 305 | if [[ -f "$source" ]]; then 306 | # Get just the filename (flatten directory structure) 307 | local filename=$(basename "$file") 308 | local dest="$target_dir/$filename" 309 | 310 | # Compile with workflow and standards injection 311 | local compiled=$(compile_agent "$source" "$dest" "$BASE_DIR" "$EFFECTIVE_PROFILE" "") 312 | if [[ "$DRY_RUN" == "true" ]]; then 313 | INSTALLED_FILES+=("$dest") 314 | fi 315 | ((agents_count++)) || true 316 | fi 317 | fi 318 | done < <(get_profile_files "$EFFECTIVE_PROFILE" "$BASE_DIR" "agents") 319 | 320 | if [[ "$DRY_RUN" != "true" ]]; then 321 | if [[ $agents_count -gt 0 ]]; then 322 | echo "✓ Installed $agents_count Claude Code agents" 323 | fi 324 | fi 325 | } 326 | 327 | # Install agent-os commands (single-agent files with injection) 328 | install_agent_os_commands() { 329 | if [[ "$DRY_RUN" != "true" ]]; then 330 | print_status "Installing agent-os commands..." 331 | fi 332 | 333 | local commands_count=0 334 | 335 | while read file; do 336 | # Process single-agent command files OR orchestrate-tasks special case 337 | if [[ "$file" == commands/*/single-agent/* ]] || [[ "$file" == commands/orchestrate-tasks/orchestrate-tasks.md ]]; then 338 | local source=$(get_profile_file "$EFFECTIVE_PROFILE" "$file" "$BASE_DIR") 339 | if [[ -f "$source" ]]; then 340 | # Handle orchestrate-tasks specially (preserve folder structure) 341 | if [[ "$file" == commands/orchestrate-tasks/orchestrate-tasks.md ]]; then 342 | local dest="$PROJECT_DIR/agent-os/commands/orchestrate-tasks/orchestrate-tasks.md" 343 | else 344 | # Extract command name and preserve numbering 345 | local cmd_path=$(echo "$file" | sed 's|commands/\([^/]*\)/single-agent/\(.*\)|\1/\2|') 346 | local dest="$PROJECT_DIR/agent-os/commands/$cmd_path" 347 | fi 348 | 349 | # Compile with workflow and standards injection and PHASE embedding 350 | local compiled=$(compile_command "$source" "$dest" "$BASE_DIR" "$EFFECTIVE_PROFILE" "embed") 351 | if [[ "$DRY_RUN" == "true" ]]; then 352 | INSTALLED_FILES+=("$dest") 353 | fi 354 | ((commands_count++)) || true 355 | fi 356 | fi 357 | done < <(get_profile_files "$EFFECTIVE_PROFILE" "$BASE_DIR" "commands") 358 | 359 | if [[ "$DRY_RUN" != "true" ]]; then 360 | if [[ $commands_count -gt 0 ]]; then 361 | echo "✓ Installed $commands_count agent-os commands" 362 | fi 363 | fi 364 | } 365 | 366 | # Create agent-os folder structure 367 | create_agent_os_folder() { 368 | if [[ "$DRY_RUN" != "true" ]]; then 369 | print_status "Installing agent-os folder" 370 | fi 371 | 372 | # Create the main agent-os folder 373 | ensure_dir "$PROJECT_DIR/agent-os" 374 | 375 | # Create the configuration file 376 | local config_file=$(write_project_config "$EFFECTIVE_VERSION" "$EFFECTIVE_PROFILE" \ 377 | "$EFFECTIVE_CLAUDE_CODE_COMMANDS" "$EFFECTIVE_USE_CLAUDE_CODE_SUBAGENTS" \ 378 | "$EFFECTIVE_AGENT_OS_COMMANDS" "$EFFECTIVE_STANDARDS_AS_CLAUDE_CODE_SKILLS") 379 | if [[ "$DRY_RUN" == "true" && -n "$config_file" ]]; then 380 | INSTALLED_FILES+=("$config_file") 381 | fi 382 | 383 | if [[ "$DRY_RUN" != "true" ]]; then 384 | echo "✓ Created agent-os folder" 385 | echo "✓ Created agent-os project configuration" 386 | fi 387 | } 388 | 389 | # Perform fresh installation 390 | perform_installation() { 391 | # Show dry run warning at the top if applicable 392 | if [[ "$DRY_RUN" == "true" ]]; then 393 | print_warning "DRY RUN - No files will be actually created" 394 | echo "" 395 | fi 396 | 397 | # Display configuration at the top 398 | echo "" 399 | print_status "Configuration:" 400 | echo -e " Profile: ${YELLOW}$EFFECTIVE_PROFILE${NC}" 401 | echo -e " Claude Code commands: ${YELLOW}$EFFECTIVE_CLAUDE_CODE_COMMANDS${NC}" 402 | echo -e " Use Claude Code subagents: ${YELLOW}$EFFECTIVE_USE_CLAUDE_CODE_SUBAGENTS${NC}" 403 | echo -e " Standards as Claude Code Skills: ${YELLOW}$EFFECTIVE_STANDARDS_AS_CLAUDE_CODE_SKILLS${NC}" 404 | echo -e " Agent OS commands: ${YELLOW}$EFFECTIVE_AGENT_OS_COMMANDS${NC}" 405 | echo "" 406 | 407 | # In dry run mode, just collect files silently 408 | if [[ "$DRY_RUN" == "true" ]]; then 409 | # Collect files without output 410 | create_agent_os_folder 411 | install_standards 412 | 413 | # Install Claude Code files if enabled 414 | if [[ "$EFFECTIVE_CLAUDE_CODE_COMMANDS" == "true" ]]; then 415 | if [[ "$EFFECTIVE_USE_CLAUDE_CODE_SUBAGENTS" == "true" ]]; then 416 | install_claude_code_commands_with_delegation 417 | install_claude_code_agents 418 | else 419 | install_claude_code_commands_without_delegation 420 | fi 421 | install_claude_code_skills 422 | install_improve_skills_command 423 | fi 424 | 425 | # Install agent-os commands if enabled 426 | if [[ "$EFFECTIVE_AGENT_OS_COMMANDS" == "true" ]]; then 427 | install_agent_os_commands 428 | fi 429 | 430 | echo "" 431 | print_status "The following files would be created:" 432 | for file in "${INSTALLED_FILES[@]}"; do 433 | # Make paths relative to project root 434 | local relative_path="${file#$PROJECT_DIR/}" 435 | echo " - $relative_path" 436 | done 437 | else 438 | # Normal installation with output 439 | create_agent_os_folder 440 | echo "" 441 | 442 | install_standards 443 | echo "" 444 | 445 | # Install Claude Code files if enabled 446 | if [[ "$EFFECTIVE_CLAUDE_CODE_COMMANDS" == "true" ]]; then 447 | if [[ "$EFFECTIVE_USE_CLAUDE_CODE_SUBAGENTS" == "true" ]]; then 448 | install_claude_code_commands_with_delegation 449 | echo "" 450 | install_claude_code_agents 451 | echo "" 452 | else 453 | install_claude_code_commands_without_delegation 454 | echo "" 455 | fi 456 | install_claude_code_skills 457 | install_improve_skills_command 458 | echo "" 459 | fi 460 | 461 | # Install agent-os commands if enabled 462 | if [[ "$EFFECTIVE_AGENT_OS_COMMANDS" == "true" ]]; then 463 | install_agent_os_commands 464 | echo "" 465 | fi 466 | fi 467 | 468 | if [[ "$DRY_RUN" == "true" ]]; then 469 | echo "" 470 | read -p "Proceed with actual installation? (y/n): " -n 1 -r 471 | echo 472 | if [[ $REPLY =~ ^[Yy]$ ]]; then 473 | DRY_RUN="false" 474 | INSTALLED_FILES=() 475 | perform_installation 476 | fi 477 | else 478 | print_success "Agent OS has been successfully installed in your project!" 479 | echo "" 480 | echo -e "${GREEN}Visit the docs for guides on how to use Agent OS: https://buildermethods.com/agent-os${NC}" 481 | echo "" 482 | fi 483 | } 484 | 485 | # Handle re-installation 486 | handle_reinstallation() { 487 | print_section "Re-installation" 488 | 489 | print_warning "This will DELETE your current agent-os/ folder and reinstall from scratch." 490 | echo "" 491 | 492 | # Check for Claude Code files 493 | if [[ -d "$PROJECT_DIR/.claude/agents/agent-os" ]] || [[ -d "$PROJECT_DIR/.claude/commands/agent-os" ]]; then 494 | print_warning "This will also DELETE:" 495 | [[ -d "$PROJECT_DIR/.claude/agents/agent-os" ]] && echo " - .claude/agents/agent-os/" 496 | [[ -d "$PROJECT_DIR/.claude/commands/agent-os" ]] && echo " - .claude/commands/agent-os/" 497 | echo "" 498 | fi 499 | 500 | read -p "Are you sure you want to proceed? (y/n): " -n 1 -r 501 | echo 502 | if [[ ! $REPLY =~ ^[Yy]$ ]]; then 503 | print_status "Re-installation cancelled" 504 | exit 0 505 | fi 506 | 507 | if [[ "$DRY_RUN" != "true" ]]; then 508 | print_status "Removing existing installation..." 509 | rm -rf "$PROJECT_DIR/agent-os" 510 | rm -rf "$PROJECT_DIR/.claude/agents/agent-os" 511 | rm -rf "$PROJECT_DIR/.claude/commands/agent-os" 512 | echo "✓ Existing installation removed" 513 | echo "" 514 | fi 515 | 516 | perform_installation 517 | } 518 | 519 | # ----------------------------------------------------------------------------- 520 | # Main Execution 521 | # ----------------------------------------------------------------------------- 522 | 523 | main() { 524 | print_section "Agent OS Project Installation" 525 | 526 | # Parse command line arguments 527 | parse_arguments "$@" 528 | 529 | # Check if we're trying to install in the base installation directory 530 | check_not_base_installation 531 | 532 | # Validate base installation using common function 533 | validate_base_installation 534 | 535 | # Load configuration 536 | load_configuration 537 | 538 | # Check if Agent OS is already installed 539 | if is_agent_os_installed "$PROJECT_DIR"; then 540 | if [[ "$RE_INSTALL" == "true" ]]; then 541 | handle_reinstallation 542 | else 543 | # Delegate to update script 544 | print_status "Agent OS is already installed. Running update..." 545 | exec "$BASE_DIR/scripts/project-update.sh" "$@" 546 | fi 547 | else 548 | # Fresh installation 549 | perform_installation 550 | fi 551 | } 552 | 553 | # Run main function 554 | main "$@" 555 | -------------------------------------------------------------------------------- /scripts/base-install.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Agent OS Base Installation Script 4 | # Installs Agent OS from GitHub repository to ~/agent-os 5 | 6 | set -e 7 | 8 | # Repository configuration 9 | REPO_URL="https://github.com/buildermethods/agent-os" 10 | 11 | # Installation paths 12 | BASE_DIR="$HOME/agent-os" 13 | TEMP_DIR=$(mktemp -d) 14 | COMMON_FUNCTIONS_TEMP="$TEMP_DIR/common-functions.sh" 15 | 16 | # ----------------------------------------------------------------------------- 17 | # Bootstrap Functions (before common-functions.sh is available) 18 | # ----------------------------------------------------------------------------- 19 | 20 | # Minimal color codes for bootstrap 21 | BLUE='\033[0;36m' 22 | RED='\033[0;31m' 23 | YELLOW='\033[1;33m' 24 | NC='\033[0m' 25 | 26 | # Bootstrap print functions 27 | bootstrap_print() { 28 | echo -e "${BLUE}$1${NC}" 29 | } 30 | 31 | bootstrap_error() { 32 | echo -e "${RED}✗ $1${NC}" 33 | } 34 | 35 | # Download common-functions.sh first 36 | download_common_functions() { 37 | local functions_url="${REPO_URL}/raw/main/scripts/common-functions.sh" 38 | 39 | if curl -sL --fail "$functions_url" -o "$COMMON_FUNCTIONS_TEMP"; then 40 | # Source the common functions 41 | source "$COMMON_FUNCTIONS_TEMP" 42 | return 0 43 | else 44 | bootstrap_error "Failed to download common-functions.sh" 45 | exit 1 46 | fi 47 | } 48 | 49 | # ----------------------------------------------------------------------------- 50 | # Initialize common functions 51 | # ----------------------------------------------------------------------------- 52 | 53 | bootstrap_print "Initializing..." 54 | download_common_functions 55 | 56 | # Clean up temp directory on exit and restore cursor 57 | cleanup() { 58 | if [[ -d "$TEMP_DIR" ]]; then 59 | rm -rf "$TEMP_DIR" 60 | fi 61 | # Always restore cursor on exit 62 | tput cnorm 2>/dev/null || true 63 | } 64 | trap cleanup EXIT 65 | 66 | # ----------------------------------------------------------------------------- 67 | # Version Functions 68 | # ----------------------------------------------------------------------------- 69 | 70 | # Get latest version from GitHub 71 | get_latest_version() { 72 | local config_url="${REPO_URL}/raw/main/config.yml" 73 | curl -sL "$config_url" | grep "^version:" | sed 's/version: *//' | tr -d '\r\n' 74 | } 75 | 76 | # ----------------------------------------------------------------------------- 77 | # Download Functions 78 | # ----------------------------------------------------------------------------- 79 | 80 | # Download file from GitHub 81 | download_file() { 82 | local relative_path=$1 83 | local dest_path=$2 84 | local file_url="${REPO_URL}/raw/main/${relative_path}" 85 | 86 | mkdir -p "$(dirname "$dest_path")" 87 | 88 | if curl -sL --fail "$file_url" -o "$dest_path"; then 89 | return 0 90 | else 91 | return 1 92 | fi 93 | } 94 | 95 | # Define exclusion patterns 96 | EXCLUSIONS=( 97 | "scripts/base-install.sh" 98 | "old-versions/*" 99 | ".git*" 100 | ".github/*" 101 | ) 102 | 103 | # Check if a file should be excluded 104 | should_exclude() { 105 | local file_path=$1 106 | 107 | for pattern in "${EXCLUSIONS[@]}"; do 108 | # Check exact match 109 | if [[ "$file_path" == "$pattern" ]]; then 110 | return 0 111 | fi 112 | # Check wildcard patterns 113 | if [[ "$pattern" == *"*"* ]]; then 114 | local prefix="${pattern%\*}" 115 | if [[ "$file_path" == "$prefix"* ]]; then 116 | return 0 117 | fi 118 | fi 119 | done 120 | 121 | return 1 122 | } 123 | 124 | # Get all files from GitHub repo using the tree API 125 | get_all_repo_files() { 126 | # Get the default branch (usually main or master) 127 | local branch="main" 128 | 129 | # Extract owner and repo name from URL 130 | # From: https://github.com/owner/repo to owner/repo 131 | local repo_path=$(echo "$REPO_URL" | sed 's|^https://github.com/||') 132 | 133 | print_verbose "Repository path: $repo_path" 134 | 135 | # Build API URL 136 | local tree_url="https://api.github.com/repos/${repo_path}/git/trees/${branch}?recursive=true" 137 | 138 | print_verbose "Fetching from: $tree_url" 139 | 140 | local response=$(curl -sL "$tree_url") 141 | 142 | # Check if we got a valid response 143 | if [[ -z "$response" ]]; then 144 | print_verbose "Empty response from GitHub API" 145 | return 1 146 | fi 147 | 148 | # Debug: Show first 500 chars of response 149 | print_verbose "Response preview: ${response:0:500}" 150 | 151 | if echo "$response" | grep -q '"message"'; then 152 | local error_msg=$(echo "$response" | grep -o '"message":"[^"]*"' | sed 's/"message":"//' | sed 's/"$//') 153 | print_verbose "GitHub API error: $error_msg" 154 | return 1 155 | fi 156 | 157 | # Check if we have tree data (use grep -c to avoid broken pipe) 158 | if [[ $(echo "$response" | grep -c '"tree"' 2>/dev/null || true) -eq 0 ]]; then 159 | print_verbose "No tree data in response" 160 | return 1 161 | fi 162 | 163 | # Use jq if available, otherwise use python 164 | if command -v jq &> /dev/null; then 165 | print_verbose "Using jq to parse JSON" 166 | echo "$response" | jq -r '.tree[] | select(.type=="blob") | .path' | while read -r file_path; do 167 | if ! should_exclude "$file_path"; then 168 | echo "$file_path" 169 | fi 170 | done 171 | elif command -v python3 &> /dev/null; then 172 | print_verbose "Using python to parse JSON" 173 | echo "$response" | python3 -c " 174 | import sys, json 175 | data = json.load(sys.stdin) 176 | for item in data.get('tree', []): 177 | if item.get('type') == 'blob': 178 | print(item.get('path', '')) 179 | " | while read -r file_path; do 180 | if [[ -n "$file_path" ]] && ! should_exclude "$file_path"; then 181 | echo "$file_path" 182 | fi 183 | done 184 | else 185 | print_verbose "Using sed/awk to parse JSON (less reliable)" 186 | # Parse JSON using sed and awk - less reliable but works for simple cases 187 | echo "$response" | awk -F'"' '/"type":"blob"/{blob=1} blob && /"path":/{print $4; blob=0}' | while read -r file_path; do 188 | if ! should_exclude "$file_path"; then 189 | echo "$file_path" 190 | fi 191 | done 192 | fi 193 | } 194 | 195 | # Download all files from the repository 196 | download_all_files() { 197 | local dest_base=$1 198 | local file_count=0 199 | 200 | print_verbose "Fetching repository file list..." 201 | 202 | # Get list of all files (excluding our exclusion list) 203 | local all_files=$(get_all_repo_files) 204 | 205 | if [[ -z "$all_files" ]]; then 206 | echo "0" # Return 0 to indicate no files downloaded 207 | return 1 208 | fi 209 | 210 | # Download each file (using process substitution to avoid subshell variable issue) 211 | while IFS= read -r file_path; do 212 | if [[ -n "$file_path" ]]; then 213 | local dest_file="${dest_base}/${file_path}" 214 | 215 | # Create directory if needed 216 | local dir_path=$(dirname "$dest_file") 217 | [[ -d "$dir_path" ]] || mkdir -p "$dir_path" 218 | 219 | if download_file "$file_path" "$dest_file"; then 220 | ((file_count++)) || true 221 | print_verbose " Downloaded: ${file_path}" 222 | else 223 | print_verbose " Failed to download: ${file_path}" 224 | fi 225 | fi 226 | done <<< "$all_files" 227 | 228 | echo "$file_count" 229 | } 230 | 231 | # ----------------------------------------------------------------------------- 232 | # Helper Functions 233 | # ----------------------------------------------------------------------------- 234 | 235 | # Print status message without newline 236 | print_status_no_newline() { 237 | echo -ne "${BLUE}$1${NC}" 238 | } 239 | 240 | # Animated spinner for long-running operations 241 | spinner() { 242 | local delay=0.5 243 | while true; do 244 | for dot_count in "" "." ".." "..."; do 245 | echo -ne "\r${BLUE}Installing Agent OS files${dot_count}${NC} " 246 | sleep $delay 247 | done 248 | done 249 | } 250 | 251 | # ----------------------------------------------------------------------------- 252 | # Installation Functions 253 | # ----------------------------------------------------------------------------- 254 | 255 | # Install all files from repository 256 | install_all_files() { 257 | if [[ "$DRY_RUN" != "true" ]]; then 258 | # Start spinner in background 259 | spinner_pid="" 260 | if [[ "$VERBOSE" != "true" ]]; then 261 | # Hide cursor before starting spinner 262 | tput civis 2>/dev/null || true 263 | spinner & 264 | spinner_pid=$! 265 | else 266 | print_status "Installing Agent OS files..." 267 | fi 268 | fi 269 | 270 | # Download all files (excluding those in exclusion list) 271 | local file_count 272 | file_count=$(download_all_files "$BASE_DIR") 273 | local download_status=$? 274 | 275 | # Stop spinner if running 276 | if [[ -n "$spinner_pid" ]]; then 277 | kill $spinner_pid 2>/dev/null 278 | wait $spinner_pid 2>/dev/null 279 | # Clear the line and restore cursor 280 | echo -ne "\r\033[K" 281 | tput cnorm 2>/dev/null || true # Show cursor again 282 | fi 283 | 284 | if [[ "$DRY_RUN" != "true" ]]; then 285 | if [[ $download_status -eq 0 && $file_count -gt 0 ]]; then 286 | echo "✓ Installed $file_count files to ~/agent-os" 287 | else 288 | print_error "No files were downloaded" 289 | return 1 290 | fi 291 | fi 292 | 293 | # Make scripts executable 294 | if [[ -d "$BASE_DIR/scripts" ]]; then 295 | chmod +x "$BASE_DIR/scripts/"*.sh 2>/dev/null || true 296 | fi 297 | 298 | return 0 299 | } 300 | 301 | # ----------------------------------------------------------------------------- 302 | # Overwrite Functions 303 | # ----------------------------------------------------------------------------- 304 | 305 | # Prompt for overwrite choice 306 | prompt_overwrite_choice() { 307 | local current_version=$1 308 | local latest_version=$2 309 | 310 | echo "" 311 | echo -e "${YELLOW}=== ⚠️ Existing Installation Detected ===${NC}" 312 | echo "" 313 | 314 | echo "You already have a base installation of Agent OS" 315 | 316 | if [[ -n "$current_version" ]]; then 317 | echo -e " Your installed version: ${YELLOW}$current_version${NC}" 318 | else 319 | echo " Your installed version: (unknown)" 320 | fi 321 | 322 | if [[ -n "$latest_version" ]]; then 323 | echo -e " Latest available version: ${YELLOW}$latest_version${NC}" 324 | else 325 | echo " Latest available version: (unable to determine)" 326 | fi 327 | 328 | echo "" 329 | print_status "What would you like to do?" 330 | echo "" 331 | 332 | echo -e "${YELLOW}1) Full update${NC}" 333 | echo "" 334 | echo " Updates & overwrites:" 335 | echo " - ~/agent-os/profiles/default/*" 336 | echo " - ~/agent-os/scripts/*" 337 | echo " - ~/agent-os/CHANGELOG.md" 338 | echo "" 339 | echo " Updates your version number in ~/agent-os/config.yml but doesn't change anything else in this file." 340 | echo "" 341 | echo " Everything else in your ~/agent-os folder will remain intact." 342 | echo "" 343 | 344 | echo -e "${YELLOW}2) Update default profile only${NC}" 345 | echo "" 346 | echo " Updates & overwrites:" 347 | echo " - ~/agent-os/profiles/default/*" 348 | echo "" 349 | echo " Everything else in your ~/agent-os folder will remain intact." 350 | echo "" 351 | 352 | echo -e "${YELLOW}3) Update scripts only${NC}" 353 | echo "" 354 | echo " Updates & overwrites:" 355 | echo " - ~/agent-os/scripts/*" 356 | echo "" 357 | echo " Everything else in your ~/agent-os folder will remain intact." 358 | echo "" 359 | 360 | echo -e "${YELLOW}4) Update config.yml only${NC}" 361 | echo "" 362 | echo " Updates & overwrites:" 363 | echo " - ~/agent-os/config.yml" 364 | echo "" 365 | echo " Everything else in your ~/agent-os folder will remain intact." 366 | echo "" 367 | 368 | echo -e "${YELLOW}5) Delete & reinstall fresh${NC}" 369 | echo "" 370 | echo " - Makes a backup of your current ~/agent-os folder at ~/agent-os.backup" 371 | echo " - Deletes your current ~/agent-os folder and all of its contents." 372 | echo " - Installs a fresh ~/agent-os base installation" 373 | echo "" 374 | 375 | echo -e "${YELLOW}6) Cancel and abort${NC}" 376 | echo "" 377 | 378 | read -p "Enter your choice (1-6): " choice < /dev/tty 379 | 380 | case $choice in 381 | 1) 382 | echo "" 383 | print_status "Performing full update..." 384 | full_update "$latest_version" 385 | ;; 386 | 2) 387 | echo "" 388 | print_status "Updating default profile..." 389 | create_backup 390 | overwrite_profile 391 | ;; 392 | 3) 393 | echo "" 394 | print_status "Updating scripts..." 395 | create_backup 396 | overwrite_scripts 397 | ;; 398 | 4) 399 | echo "" 400 | print_status "Updating config.yml..." 401 | create_backup 402 | overwrite_config 403 | ;; 404 | 5) 405 | echo "" 406 | print_status "Deleting & reinstalling fresh..." 407 | overwrite_all 408 | ;; 409 | 6) 410 | echo "" 411 | print_warning "Installation cancelled" 412 | exit 0 413 | ;; 414 | *) 415 | print_error "Invalid choice. Installation cancelled." 416 | exit 1 417 | ;; 418 | esac 419 | } 420 | 421 | # Create backup of existing installation 422 | create_backup() { 423 | # Backup existing installation 424 | if [[ -d "$BASE_DIR.backup" ]]; then 425 | rm -rf "$BASE_DIR.backup" 426 | fi 427 | cp -R "$BASE_DIR" "$BASE_DIR.backup" 428 | echo "✓ Backed up existing installation to ~/agent-os.backup" 429 | echo "" 430 | } 431 | 432 | # Full update - updates profile, scripts, CHANGELOG.md, and version number in config.yml 433 | full_update() { 434 | local latest_version=$1 435 | 436 | # Create backup first 437 | create_backup 438 | 439 | # Update default profile 440 | print_status "Updating default profile..." 441 | rm -rf "$BASE_DIR/profiles/default" 442 | local file_count=0 443 | local all_files=$(get_all_repo_files | grep "^profiles/default/") 444 | if [[ -n "$all_files" ]]; then 445 | while IFS= read -r file_path; do 446 | if [[ -n "$file_path" ]]; then 447 | local dest_file="${BASE_DIR}/${file_path}" 448 | local dir_path=$(dirname "$dest_file") 449 | [[ -d "$dir_path" ]] || mkdir -p "$dir_path" 450 | if download_file "$file_path" "$dest_file"; then 451 | ((file_count++)) || true 452 | print_verbose " Downloaded: ${file_path}" 453 | fi 454 | fi 455 | done <<< "$all_files" 456 | fi 457 | echo "✓ Updated default profile ($file_count files)" 458 | echo "" 459 | 460 | # Update scripts 461 | print_status "Updating scripts..." 462 | rm -rf "$BASE_DIR/scripts" 463 | file_count=0 464 | all_files=$(get_all_repo_files | grep "^scripts/") 465 | if [[ -n "$all_files" ]]; then 466 | while IFS= read -r file_path; do 467 | if [[ -n "$file_path" ]]; then 468 | local dest_file="${BASE_DIR}/${file_path}" 469 | local dir_path=$(dirname "$dest_file") 470 | [[ -d "$dir_path" ]] || mkdir -p "$dir_path" 471 | if download_file "$file_path" "$dest_file"; then 472 | ((file_count++)) || true 473 | print_verbose " Downloaded: ${file_path}" 474 | fi 475 | fi 476 | done <<< "$all_files" 477 | chmod +x "$BASE_DIR/scripts/"*.sh 2>/dev/null || true 478 | fi 479 | echo "✓ Updated scripts ($file_count files)" 480 | echo "" 481 | 482 | # Update CHANGELOG.md 483 | print_status "Updating CHANGELOG.md..." 484 | if download_file "CHANGELOG.md" "$BASE_DIR/CHANGELOG.md"; then 485 | echo "✓ Updated CHANGELOG.md" 486 | fi 487 | echo "" 488 | 489 | # Update version number in config.yml (without overwriting the entire file) 490 | print_status "Updating version number in config.yml..." 491 | if [[ -f "$BASE_DIR/config.yml" ]] && [[ -n "$latest_version" ]]; then 492 | # Use sed to update only the version line 493 | sed -i.bak "s/^version:.*/version: $latest_version/" "$BASE_DIR/config.yml" 494 | rm -f "$BASE_DIR/config.yml.bak" 495 | echo "✓ Updated version to $latest_version in config.yml" 496 | fi 497 | echo "" 498 | 499 | print_success "Full update completed!" 500 | } 501 | 502 | # Overwrite everything 503 | overwrite_all() { 504 | # Backup existing installation 505 | if [[ -d "$BASE_DIR.backup" ]]; then 506 | rm -rf "$BASE_DIR.backup" 507 | fi 508 | mv "$BASE_DIR" "$BASE_DIR.backup" 509 | echo "✓ Backed up existing installation to ~/agent-os.backup" 510 | echo "" 511 | 512 | # Perform fresh installation 513 | perform_fresh_installation 514 | } 515 | 516 | # Overwrite only profile 517 | overwrite_profile() { 518 | # Remove existing default profile 519 | rm -rf "$BASE_DIR/profiles/default" 520 | 521 | # Download only profile files 522 | local file_count=0 523 | 524 | # Get all files and filter for profiles/default 525 | local all_files=$(get_all_repo_files | grep "^profiles/default/") 526 | 527 | if [[ -n "$all_files" ]]; then 528 | while IFS= read -r file_path; do 529 | if [[ -n "$file_path" ]]; then 530 | local dest_file="${BASE_DIR}/${file_path}" 531 | local dir_path=$(dirname "$dest_file") 532 | [[ -d "$dir_path" ]] || mkdir -p "$dir_path" 533 | 534 | if download_file "$file_path" "$dest_file"; then 535 | ((file_count++)) || true 536 | print_verbose " Downloaded: ${file_path}" 537 | fi 538 | fi 539 | done <<< "$all_files" 540 | fi 541 | 542 | echo "✓ Updated default profile ($file_count files)" 543 | echo "" 544 | print_success "Default profile has been updated!" 545 | } 546 | 547 | # Overwrite only scripts 548 | overwrite_scripts() { 549 | # Remove existing scripts 550 | rm -rf "$BASE_DIR/scripts" 551 | 552 | # Download only script files 553 | local file_count=0 554 | 555 | # Get all files and filter for scripts/ 556 | local all_files=$(get_all_repo_files | grep "^scripts/") 557 | 558 | if [[ -n "$all_files" ]]; then 559 | while IFS= read -r file_path; do 560 | if [[ -n "$file_path" ]]; then 561 | local dest_file="${BASE_DIR}/${file_path}" 562 | local dir_path=$(dirname "$dest_file") 563 | [[ -d "$dir_path" ]] || mkdir -p "$dir_path" 564 | 565 | if download_file "$file_path" "$dest_file"; then 566 | ((file_count++)) || true 567 | print_verbose " Downloaded: ${file_path}" 568 | fi 569 | fi 570 | done <<< "$all_files" 571 | 572 | # Make scripts executable 573 | chmod +x "$BASE_DIR/scripts/"*.sh 2>/dev/null || true 574 | fi 575 | 576 | echo "✓ Updated scripts ($file_count files)" 577 | echo "" 578 | print_success "Scripts have been updated!" 579 | } 580 | 581 | # Overwrite only config 582 | overwrite_config() { 583 | # Download new config.yml 584 | if download_file "config.yml" "$BASE_DIR/config.yml"; then 585 | print_verbose " Downloaded: config.yml" 586 | fi 587 | 588 | echo "✓ Updated config.yml" 589 | echo "" 590 | print_success "Config has been updated!" 591 | } 592 | 593 | # ----------------------------------------------------------------------------- 594 | # Main Installation Functions 595 | # ----------------------------------------------------------------------------- 596 | 597 | # Perform fresh installation 598 | perform_fresh_installation() { 599 | echo "" 600 | print_status "Configuration:" 601 | echo -e " Repository: ${YELLOW}${REPO_URL}${NC}" 602 | echo -e " Target: ${YELLOW}~/agent-os${NC}" 603 | echo "" 604 | 605 | # Create base directory 606 | ensure_dir "$BASE_DIR" 607 | echo "✓ Created base directory: ~/agent-os" 608 | echo "" 609 | 610 | # Install all files from repository 611 | if ! install_all_files; then 612 | print_error "Installation failed" 613 | exit 1 614 | fi 615 | 616 | echo "" 617 | print_success "Agent OS has been successfully installed!" 618 | echo "" 619 | echo -e "${GREEN}Next steps:${NC}" 620 | echo "" 621 | echo -e "${GREEN}1) Customize your profile's standards in ~/agent-os/profiles/default/standards${NC}" 622 | echo "" 623 | echo -e "${GREEN}2) Navigate to a project directory${NC}" 624 | echo -e " ${YELLOW}cd path/to/project-directory${NC}" 625 | echo "" 626 | echo -e "${GREEN}3) Install Agent OS in your project by running:${NC}" 627 | echo -e " ${YELLOW}~/agent-os/scripts/project-install.sh${NC}" 628 | echo "" 629 | echo -e "${GREEN}Visit the docs for guides on how to use Agent OS: https://buildermethods.com/agent-os${NC}" 630 | echo "" 631 | } 632 | 633 | # Check for existing installation 634 | check_existing_installation() { 635 | if [[ -d "$BASE_DIR" ]]; then 636 | # Get current version if available 637 | local current_version="" 638 | if [[ -f "$BASE_DIR/config.yml" ]]; then 639 | current_version=$(get_yaml_value "$BASE_DIR/config.yml" "version" "") 640 | fi 641 | 642 | # Get latest version from GitHub 643 | local latest_version=$(get_latest_version) 644 | 645 | # Prompt for overwrite choice 646 | prompt_overwrite_choice "$current_version" "$latest_version" 647 | else 648 | # Fresh installation 649 | perform_fresh_installation 650 | fi 651 | } 652 | 653 | # ----------------------------------------------------------------------------- 654 | # Global Variables 655 | # ----------------------------------------------------------------------------- 656 | 657 | VERBOSE=false 658 | DRY_RUN=false 659 | 660 | # ----------------------------------------------------------------------------- 661 | # Main Execution 662 | # ----------------------------------------------------------------------------- 663 | 664 | main() { 665 | print_section "Agent OS Base Installation" 666 | 667 | # Parse command line arguments 668 | while [[ $# -gt 0 ]]; do 669 | case $1 in 670 | -v|--verbose) 671 | VERBOSE=true 672 | shift 673 | ;; 674 | -h|--help) 675 | echo "Usage: $0 [OPTIONS]" 676 | echo "" 677 | echo "Options:" 678 | echo " -v, --verbose Show verbose output" 679 | echo " -h, --help Show this help message" 680 | exit 0 681 | ;; 682 | *) 683 | print_error "Unknown option: $1" 684 | echo "Use -h or --help for usage information" 685 | exit 1 686 | ;; 687 | esac 688 | done 689 | 690 | # Check for curl 691 | if ! command -v curl &> /dev/null; then 692 | print_error "curl is required but not installed. Please install curl and try again." 693 | exit 1 694 | fi 695 | 696 | # Check for existing installation or perform fresh install 697 | check_existing_installation 698 | } 699 | 700 | # Run main function 701 | main "$@" 702 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | Get notified of major releases by subscribing here: 4 | https://buildermethods.com/agent-os 5 | 6 | ## [2.1.1] - 2025-10-29 7 | 8 | - Replaced references to 'spec-researcher' (depreciated agent name) with 'spec-shaper'. 9 | - Clarified --dry-run output to user to reassure we're in dry-run mode 10 | - Tightened up template and istructions for writing spec.md, aiming to keep it shorter, easier to scan, and covering only the essentials. 11 | - Tweaked create-task-list workflow for consistency. 12 | - When planning product roadmap, removed instruction to limit it to 12 items. 13 | - Clarified instructions in implement-tasks in regards to useage of Playwright and screenshots. 14 | 15 | ## [2.1.0] - 2025-10-21 16 | 17 | Version 2.1 implemented a round of significant changes to how things work in Agent OS. Here is a summary of what's new in version 2.1.0: 18 | 19 | ### TL;DR 20 | 21 | Here's the brief overview. It's all detailed below and the [docs](https://buildermethods.com/agent-os) have been updated to reflect all of this. 22 | 23 | - Option to leverage Claude Code's new "Skills" feature for reading standards 24 | - Option to enable or disable delegating to Claude Code subagents 25 | - Replaced "single/multi-agent modes" with more flexible configuration options 26 | - Retired the short-lived "roles" system. Too complex, and better handled with standard tooling (more below). 27 | - Removed documentation & verification bloat 28 | - Went from 4 to 6 more specific development phases (use 'em all or pick and choose!): 29 | 1. plan-product -- (no change) Plan your product's mission & roadmap 30 | 2. shape-spec -- For shaping and planning a feature before writing it up 31 | 3. write-spec -- For writing your spec.md 32 | 4. create-tasks -- For creating your tasks.md 33 | 5. implement-tasks -- Simple single-agent implementation of tasks.md 34 | 6. orchestrate-tasks -- For more advanced, fine-grain control and multi-agent orchestration of tasks.md. 35 | - Simplified & improved project upgrade script 36 | 37 | Let's unpack these updates in detail: 38 | 39 | ### Claude Code Skills support 40 | 41 | 2.1 adds official support for [Claude Code Skills](https://docs.claude.com/en/docs/claude-code/skills). 42 | 43 | When the config option standards_as_claude_code_skills is true, this will convert all of your standards into Claude Code Skills and _not_ inject references to those Standards like Agent OS normally would. 44 | 45 | 2.1 also provides a Claude Code command, `improve-skills` which you **definitely should** run after installing Agent OS in your project with the skills option turned on. This command is designed to improve and rewrite each of your Claude Code Skills descriptions to make them more useable and discoverable by Claude Code. 46 | 47 | ### Enable/Disable delegation to Claude Code subagents 48 | 49 | 2.1 introduces an config option to enable or disable delegating tasks to Claude Code subagents. You can disable subagents by setting use_claude_code_subagents to false. 50 | 51 | When set to false, and when using Claude Code, you can still run Agent OS commands in Claude Code, and instead of delegating most tasks to subagents, Claude Code's main agent will execute everything. 52 | 53 | While you lose some context efficiency of using subagents, you can token efficiency and some speed gains without the use of subagents. 54 | 55 | ### Replaced "single-agent & multi-agent modes" with new config options 56 | 57 | 2.0.x had introduced the concepts of multi-agent and single-agent modes, where multi-agent mode was designed for using Claude Code with subagents. This naming and configuration design proved suboptimal and inflexible, so 2.1.0 does away with the terms "single-agent mode" and "multi-agent mode". 58 | 59 | Now we configure Agent OS using these boolean options in your base ~/agent-os/config.yml: 60 | 61 | claude_code_commands: true/false 62 | use_claude_code_subagents: true/false 63 | agent_os_commands: true/false 64 | 65 | The benefits of this new configuration approach are: 66 | 67 | - Now you can use Agent OS with Claude Code *with* or *without* delegating to subagents. (subagents bring many benefits like context efficiency, but also come with some tradeoffs—higher token usage, less transparency, slower to finish tasks). 68 | 69 | - Before, when you had *both* single-agent and multi-agent modes enabled, your project's agent-os/commands/ folder ended up with "multi-agent/" and "single-agent/" subfolders for each command, which is confusing and clumsy to use. Now in 2.1.0, your project's agent-os/commands/ folder will not have these additional "modes" subfolders. 70 | 71 | - Easier to integrate additional feature configurations as they become available, so that you can mix and match the exact set of features that fit your preferred coding tools and workflow style. For example, we're also introducing an option to make use of the new Claude Code Skills feature (or you can opt out). More on this below. 72 | 73 | ### Retired (short-lived) "Roles" system 74 | 75 | 2.0.x had introduced a concept of "Roles", where your roles/implementers.yml and roles/verifiers.yml contained convoluted lists of agents that could be assigned to implement tasks. It also had a script for adding additional "roles". 76 | 77 | All of that is removed in 2.1.0. That system added no real benefit over simply using available tooling (like Claude Code's own subagent generator) for spinning up your subagents. 78 | 79 | 2.1.0 introduces an 'orchestrate-tasks' phase, which achieves the same thing that the old "Roles" system intended: Advanced orchestration of multiple specialized subagents to carry out a complex implementation. More on this below. 80 | 81 | ### Removed documentation & verification bloat 82 | 83 | 2.0.x had introduced a bunch of "bloat" that quickly proved unnecessary and inefficient. These bits have been removed in 2.1.0: 84 | 85 | - Verification of your spec (although the spec-verifier Claude Code subagent is still available for you to call on, if/when you want) 86 | - Documentation of every task's implementation 87 | - Specialized verifiers (backend-verifier, frontend-verifier) 88 | 89 | The final overall verification step for a spec's implementation remains intact. 90 | 91 | ### From 4 to 6 more specific development phases 92 | 93 | While some users use all of Agent OS' workflow for everything, many have been picking the parts they find useful and discarding those that don't fit their workflow—AS THEY SHOULD! 94 | 95 | 2.1.0 establishes this as a core principle of Agent OS: You can use as much or as little of it as you want! 96 | 97 | With that in mind, we've moved from 4 to 6 different phases of development that can _potentially_ be powered by Agent OS: 98 | 99 | 1. `plan-product` -- No changes here. This is for establishing your product's mission, roadmap and tech-stack. 100 | 101 | 2. `shape-spec` -- Use this when you need to take your rough idea for a feature and shape it into a well-scoped and strategized plan, before officially writing it up. This is where the agent asks you clarifying questions and ends up producing your requirements.md. 102 | - Already got your requirements shaped? Skip this and drop those right into your spec's requirements.md 👍 103 | 104 | 3. `write-spec` -- Takes your requirements.md and formalizes it into a clear and concise spec.md. 105 | 106 | 4. `create-tasks` -- Takes your spec.md and breaks it down into a tasks list, grouped, prioritized and ready for implementation. 107 | 108 | 5. `implement-tasks` -- Just want to build right now(!), then use this to implement your tasks.md with your main agent. 109 | 110 | 6. `orchestrate-tasks` -- Got a big complex feature and want to orchestrate multiple agents, with more fine-grain control over their contexts? Use this. It provides a structure to delegate your task groups to any Claude Code subagents you've created. Or if you're not using Claude Code, it generates targeted prompt files (as was established in 2.0.x). 111 | 112 | ### Simplified & improved project upgrade script 113 | 114 | Now whenever you need to upgrade your Agent OS project installation (to a new version or to push configuration changes or standards changes to a project), now when you run project-install.sh or project-update.sh, the system will: 115 | 116 | - Check and compare your incoming version & configs to your current project's 117 | - Show you what will stay intact or be removed & re-installed 118 | - Ask you to confirm to proceed. 119 | 120 | 121 | ## [2.0.5] - 2025-10-16 122 | 123 | - Updated base installation update options to include a "Full update" option, which is the easiest way to pull and update the latest Agent OS stuff (default profile, scripts) without losing your base installation's custom profiles. 124 | - The "Full update" option also dynamically updates your base install config.yml version number without changing your configurations. 125 | 126 | ## [2.0.4] - 2025-10-14 127 | 128 | - Fixed multi-agent-mode not installing the roles/ files in the project agent-os folder. 129 | - Clarified spec-research instructions. 130 | - In single-agent mode, added verification prompt generation to the implementation phase. 131 | 132 | ## [2.0.3] - 2025-10-10 133 | 134 | - Updated instructions and default standards to reduce excessive tests writing and test running during feature development to improve speed and token useage. 135 | - For Claude Code users: 136 | - Replaced hard-coding of 'opus' model setting on agents with 'inherit' so that it inherits whichever model your Claude Code is currently using. 137 | - Updated create-role script to add the "Inherit" option when creating new agents. 138 | 139 | ## [2.0.2] - 2025-10-09 140 | 141 | - Clarified /create-spec command so that task list creation doesn't begin until spec.md has been written. 142 | - Clarified spec-writer workflow to ensure actual code isn't written in spec.md. 143 | - Fixed instructions to ensure spec-verification.md is stored in the spec's verication folder. 144 | - Ensured Claude Code subagents are installed to a project's .claude/agents/agent-os and not sub-folders within that. 145 | - Fixed compilation of Claude Code implementer and verifier agents not replacing their dynamic tags. 146 | - Added instruction in single-agent mode to inform user of next command to run during spec creation process. 147 | 148 | ## [2.0.1] - 2025-10-08 149 | 150 | ### Fixed 151 | 152 | #### Installation Script Compatibility Issues 153 | 154 | Fixed bugs in the project installation scripts (`project-install.sh`, `project-update.sh`, and `common-functions.sh`) that caused installations to fail in certain bash environments. These issues were triggered by stricter bash implementations and configurations, particularly when `set -e` (exit on error) was enabled. 155 | 156 | ## [2.0.0] - 2025-10-07 157 | 158 | Agent OS 2.0 is a major new release that brings several core architectural changes and improvements. 159 | 160 | The big headline here is the dual mode architecture for supporting both multi-agent tools (Claude Code) and single-agent tools (every other tool). 161 | 162 | [this page](https://buildermethods.com/agent-os/version-2) documents: 163 | 164 | - The new features in Agent OS 2.0 165 | - Architectural changes in 2.0 166 | - What changed from 1.x 167 | - Updating guide 168 | 169 | [The Agent OS docs](https://buildermethods.com/agent-os) also received a complete overhaul and expansion. It's now broken out into multiple pages that document every detail of how to install, use and customize Agent OS. 170 | 171 | ## [1.4.2] - 2025-08-24 172 | 173 | ### Enforced full three-phase task execution 174 | 175 | - Updated `instructions/core/execute-tasks.md` to strictly require all three phases (pre-execution, execution loop, post-execution) and to invoke `instructions/core/post-execution-tasks.md` after task completion. 176 | 177 | ### Post-execution process overhaul 178 | 179 | - Renamed `instructions/core/complete-tasks.md` to `instructions/core/post-execution-tasks.md`. 180 | - Improved the post-execution workflow by adding clarity and removing bloat in instructions. 181 | 182 | ## [1.4.1] - 2025-08-18 183 | 184 | ### Replaced Decisions with Recaps 185 | 186 | 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. 187 | 188 | 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. 189 | 190 | Recaps are automatically generated via the new complete-tasks.md process. 191 | 192 | ### Added Project-Manager Subagent 193 | 194 | 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". 195 | 196 | 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. 197 | 198 | ### Spec Creation & Task Execution Reliability Improvements 199 | 200 | Several changes to the instructions, processes, and executions, all aimed at helping agents follow the process steps consistently. 201 | 202 | - Consolidated task execution instructions with clear step-by-step processes 203 | - Added post-flight verification rules to ensure instruction compliance 204 | - Improved subagent delegation tracking and reporting 205 | - Standardized test suite verification and git workflow integration 206 | - Enhanced task completion criteria validation and status management 207 | 208 | ## [1.4.0] - 2025-08-17 209 | 210 | BIG updates in this one! Thanks for all the feedback, requests and support 🙏 211 | 212 | ### All New Installation Process 213 | 214 | The way Agent OS gets installed is structured differently from prior versions. The new system works as follows: 215 | 216 | There are 2 installation processes: 217 | - Your "Base installation" (now optional, but still recommended!) 218 | - Your "Project installation" 219 | 220 | **"Base installation"** 221 | - 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. 222 | - Project installations copy files from your base installation, so they can be customized and self-contained within each individual project. 223 | - Your base installation now has a config.yml 224 | 225 | To install the Agent OS base installation, 226 | 227 | 1. cd to a location of your choice (your system's home folder is a good choice). 228 | 229 | 2. Run one of these commands: 230 | - Agent OS with Claude Code support: 231 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --claude-code` 232 | - Agent OS with Cursor support: 233 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --cursor` 234 | - Agent OS with Claude Code & Cursor support: 235 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --claude-code --cursor` 236 | 237 | 3. Customize your /standards (just like earlier versions) 238 | 239 | **Project installation** 240 | 241 | - 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: 242 | - No external references = more reliable Agent OS commands & workflows. 243 | - You can commit your instructions, standards, Claude Code commands and agents to your project's github repo for team access. 244 | - You can customize standards differently per project than what's in your base installation. 245 | 246 | Your project installation command will be based on where you installed the Agent OS base installation. 247 | - If you've installed it to your system's home folder, then your project installation command will be `~/.agent-os/setup/project.sh`. 248 | - If you've installed it elsewhere, your command will be `/path/to/agent-os/setup/project.sh` 249 | (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.) 250 | 251 | 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. 252 | - 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. 253 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/project.sh | bash -s -- --no-base --claude-code --cursor` 254 | 255 | ### Agent OS config.yml 256 | 257 | When you install the Agent OS base installation, that now includes a config.yml file. Currently this file is used for: 258 | - Tracking the Agent OS version you have installed 259 | - Which coding agents (Claude Code, Cursor) you're using 260 | - Project Types (new! read on...) 261 | 262 | ### Project Types 263 | 264 | If you work on different types of projects, you can define different sets of standards, code style, and instructions for each! 265 | 266 | - 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. 267 | - You can define additional project types by doing the following: 268 | - 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). 269 | - Define the project type's folder location on your system in your base install's config.yml 270 | - Using project types: 271 | - If you've named a project type, 'ruby-on-rails', when running your project install command, add the flag --project-type=ruby-on-rails. 272 | - To make a project type your default for new projects, set it's name as the value for default_project_type in config.yml 273 | 274 | ### Removed or changed in version 1.4.0: 275 | 276 | This update does away with the old installation script files: 277 | - setup.sh (replaced by /setup/base.sh and /setup/project.sh) 278 | - setup-claude-code.sh (now you add --claude-code flag to the install commands or enable it in your Agent OS config.yml) 279 | - setup-cursor.sh (now you add --cursor flag to the install commands or enable it in your Agent OS config.yml) 280 | 281 | 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. 282 | 283 | ### Upgrading to version 1.4.0 284 | 285 | Follow these steps to update a previous version to 1.4.0: 286 | 287 | 1. If you've customized any files in /instructions, back those up now. They will be overwritten. 288 | 289 | 2. Navigate to your home directory (or whichever location you want to have your Agent OS base installation) 290 | 291 | 3. Run the following to command, which includes flags to overwrite your /instructions (remove the --cursor flag if not using Cursor): 292 | `curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --overwrite-instructions --claude-code --cursor` 293 | 294 | 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. 295 | 296 | 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` 297 | 298 | ## [1.3.1] - 2025-08-02 299 | 300 | ### Added 301 | - **Date-Checker Subagent** - New specialized Claude Code subagent for accurate date determination using file system timestamps 302 | - Uses temporary file creation to extract current date in YYYY-MM-DD format 303 | - Includes context checking to avoid duplication 304 | - Provides clear validation and error handling 305 | 306 | ### Changed 307 | - **Create-Spec Instructions** - Updated `instructions/core/create-spec.md` to use the new date-checker subagent 308 | - Replaced complex inline date determination logic with simple subagent delegation 309 | - Simplified step 4 (date_determination) by removing 45 lines of validation and fallback code 310 | - Cleaner instruction flow with specialized agent handling date logic 311 | 312 | ### Improved 313 | - **Code Maintainability** - Date determination logic centralized in reusable subagent 314 | - **Instruction Clarity** - Simplified create-spec workflow with cleaner delegation pattern 315 | - **Error Handling** - More robust date determination with dedicated validation rules 316 | 317 | ## [1.3.0] - 2025-08-01 318 | 319 | ### Added 320 | - **Pre-flight Check System** - New `meta/pre-flight.md` instruction for centralized agent detection and initialization 321 | - **Proactive Agent Usage** - Updated agent descriptions to encourage proactive use when appropriate 322 | - **Structured Instruction Organization** - New folder structure with `core/` and `meta/` subdirectories 323 | 324 | ### Changed 325 | - **Instruction File Structure** - Reorganized all instruction files into subdirectories: 326 | - Core instructions moved to `instructions/core/` (plan-product, create-spec, execute-tasks, execute-task, analyze-product) 327 | - Meta instructions in `instructions/meta/` (pre-flight, more to come) 328 | - **Simplified XML Metadata** - Removed verbose `` and `` blocks for cleaner, more readable instructions 329 | - **Subagent Integration** - Replaced manual agent detection with centralized pre-flight check across all instruction files to enforce delegation and preserve main agent's context. 330 | - **Step Definitions** - Added `subagent` attribute to steps for clearer delegation of work to help enforce delegation and preserve main agent's context. 331 | - **Setup Script** - Updated to create subdirectories and download files to new locations 332 | 333 | ### Improved 334 | - **Code Clarity** - Removed redundant XML instructions in favor of descriptive step purposes 335 | - **Agent Efficiency** - Centralized agent detection reduces repeated checks throughout workflows 336 | - **Maintainability** - Cleaner instruction format with less XML boilerplate 337 | - **User Experience** - Clearer indication of when specialized agents will be used proactively 338 | 339 | ### Removed 340 | - **CLAUDE.md** - Removed deprecated Claude Code configuration file (functionality moved to pre-flight system, preventing over-reading instructions into context) 341 | - **Redundant Instructions** - Eliminated verbose ACTION/MODIFY/VERIFY instruction blocks 342 | 343 | ## [1.2.0] - 2025-07-29 344 | 345 | ### Added 346 | - **Claude Code Specialized Subagents** - New agents to offload specific tasks for improved efficiency: 347 | - `test-runner.md` - Handles test execution and failure analysis with minimal toolset 348 | - `context-fetcher.md` - Retrieves information from files while checking context to avoid duplication 349 | - `git-workflow.md` - Manages git operations, branches, commits, and PR creation 350 | - `file-creator.md` - Creates files, directories, and applies consistent templates 351 | - **Agent Detection Pattern** - Single check at process start with boolean flags for efficiency 352 | - **Subagent Integration** across all instruction files with automatic fallback for non-Claude Code users 353 | 354 | ### Changed 355 | - **Instruction Files** - All updated to support conditional agent usage: 356 | - `execute-tasks.md` - Uses git-workflow (branch management, PR creation), test-runner (full suite), and context-fetcher (loading lite files) 357 | - `execute-task.md` - Uses context-fetcher (best practices, code style) and test-runner (task-specific tests) 358 | - `plan-product.md` - Uses file-creator (directory creation) and context-fetcher (tech stack defaults) 359 | - `create-spec.md` - Uses file-creator (spec folder) and context-fetcher (mission/roadmap checks) 360 | - **Standards Files** - Updated for conditional agent usage: 361 | - `code-style.md` - Uses context-fetcher for loading language-specific style guides 362 | - **Setup Scripts** - Enhanced to install Claude Code agents: 363 | - `setup-claude-code.sh` - Downloads all agents to `~/.claude/agents/` directory 364 | 365 | ### Improved 366 | - **Context Efficiency** - Specialized agents use minimal context for their specific tasks 367 | - **Code Organization** - Complex operations delegated to focused agents with clear responsibilities 368 | - **Error Handling** - Agents provide targeted error analysis and recovery strategies 369 | - **Maintainability** - Cleaner main agent code with operations abstracted to subagents 370 | - **Performance** - Reduced context checks through one-time agent detection pattern 371 | 372 | ### Technical Details 373 | - Each agent uses only necessary tools (e.g., test-runner uses only Bash, Read, Grep, Glob) 374 | - Automatic fallback ensures compatibility for users without Claude Code 375 | - Consistent `IF has_[agent_name]:` pattern reduces code complexity 376 | - All agents follow Agent OS conventions (branch naming, commit messages, file templates) 377 | 378 | ## [1.1.0] - 2025-07-29 379 | 380 | ### Added 381 | - New `mission-lite.md` file generation in product initialization for efficient AI context usage 382 | - New `spec-lite.md` file generation in spec creation for condensed spec summaries 383 | - New `execute-task.md` instruction file for individual task execution with TDD workflow 384 | - Task execution loop in `execute-tasks.md` that calls `execute-task.md` for each parent task 385 | - Language-specific code style guides: 386 | - `standards/code-style/css-style.md` for CSS and TailwindCSS 387 | - `standards/code-style/html-style.md` for HTML markup 388 | - `standards/code-style/javascript-style.md` for JavaScript 389 | - Conditional loading blocks in `best-practices.md` and `code-style.md` to prevent duplicate context loading 390 | - Context-aware file loading throughout all instruction files 391 | 392 | ### Changed 393 | - Optimized `plan-product.md` to generate condensed versions of documents 394 | - Enhanced `create-spec.md` with conditional context loading for mission-lite and tech-stack files 395 | - Simplified technical specification structure by removing multiple approach options 396 | - Made external dependencies section conditional in technical specifications 397 | - Updated `execute-tasks.md` to use minimal context loading strategy 398 | - Improved `execute-task.md` with selective reading of relevant documentation sections 399 | - Modified roadmap progress check to be conditional and context-aware 400 | - Updated decision documentation to avoid loading decisions.md and use conditional checks 401 | - Restructured task execution to follow typical TDD pattern (tests first, implementation, verification) 402 | 403 | ### Improved 404 | - Context efficiency by 60-80% through conditional loading and lite file versions 405 | - Reduced duplication when files are referenced multiple times in a workflow 406 | - Clearer separation between task-specific and full test suite execution 407 | - More intelligent file loading that checks current context before reading 408 | - Better organization of code style rules with language-specific files 409 | 410 | ### Fixed 411 | - Duplicate content loading when instruction files are called in loops 412 | - Unnecessary loading of full documentation files when condensed versions suffice 413 | - Redundant test suite runs between individual task execution and overall workflow 414 | 415 | ## [1.0.0] - 2025-07-21 416 | 417 | ### Added 418 | - Initial release of Agent OS framework 419 | - Core instruction files: 420 | - `plan-product.md` for product initialization 421 | - `create-spec.md` for feature specification 422 | - `execute-tasks.md` for task execution 423 | - `analyze-product.md` for existing codebase analysis 424 | - Standard files: 425 | - `tech-stack.md` for technology choices 426 | - `code-style.md` for formatting rules 427 | - `best-practices.md` for development guidelines 428 | - Product documentation structure: 429 | - `mission.md` for product vision 430 | - `roadmap.md` for development phases 431 | - `decisions.md` for decision logging 432 | - `tech-stack.md` for technical architecture 433 | - Setup scripts for easy installation 434 | - Integration with AI coding assistants (Claude Code, Cursor) 435 | - Task management with TDD workflow 436 | - Spec creation and organization system 437 | 438 | [1.4.1]: https://github.com/buildermethods/agent-os/compare/v1.4.0...v1.4.1 439 | [1.4.2]: https://github.com/buildermethods/agent-os/compare/v1.4.1...v1.4.2 440 | [1.4.0]: https://github.com/buildermethods/agent-os/compare/v1.3.1...v1.4.0 441 | [1.3.1]: https://github.com/buildermethods/agent-os/compare/v1.3.0...v1.3.1 442 | [1.3.0]: https://github.com/buildermethods/agent-os/compare/v1.2.0...v1.3.0 443 | [1.2.0]: https://github.com/buildermethods/agent-os/compare/v1.1.0...v1.2.0 444 | [1.1.0]: https://github.com/buildermethods/agent-os/compare/v1.0.0...v1.1.0 445 | [1.0.0]: https://github.com/buildermethods/agent-os/releases/tag/v1.0.0 446 | --------------------------------------------------------------------------------