{"owner":"buildermethods","repo":"agent-os","hasSkills":true,"totalSkillsCount":5,"totalTokensCount":7190,"categories":["command-prompt"],"hasMcp":false,"mcpConfig":null,"found":["commands/agent-os/inject-standards.md","commands/agent-os/index-standards.md","commands/agent-os/discover-standards.md","commands/agent-os/shape-spec.md","commands/agent-os/plan-product.md"],"skills":{"commands/agent-os/inject-standards.md":"# Inject Standards\n\nInject relevant standards into the current context, formatted appropriately for the situation.\n\n## Usage Modes\n\nThis command supports two modes:\n\n### Auto-Suggest Mode (no arguments)\n```\n/inject-standards\n```\nAnalyzes context and suggests relevant standards.\n\n### Explicit Mode (with arguments)\n```\n/inject-standards api                           # All standards in api/\n/inject-standards api/response-format           # Single file\n/inject-standards api/response-format api/auth  # Multiple files\n/inject-standards root                          # All standards in the root folder\n/inject-standards root/naming                   # Single file from root folder\n```\nDirectly injects specified standards without suggestions.\n\n**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder).\n\n## Process\n\n### Step 1: Detect Context Scenario\n\nBefore injecting standards, determine which scenario we're in. Read the current conversation and check if we're in plan mode.\n\n**Three scenarios:**\n\n1. **Conversation** — Regular chat, implementing code, answering questions\n2. **Creating a Skill** — Building a `.claude/skills/` file\n3. **Shaping/Planning** — In plan mode, building a spec, running `/shape-spec`\n\n**Detection logic:**\n\n- If currently in plan mode OR conversation clearly mentions \"spec\", \"plan\", \"shape\" → **Shaping/Planning**\n- If conversation clearly mentions creating a skill, editing `.claude/skills/`, or building a reusable procedure → **Creating a Skill**\n- Otherwise → **Ask to confirm** (do not assume)\n\n**If neither skill nor plan is clearly detected**, use AskUserQuestion to confirm:\n\n```\nI'll inject the relevant standards. How should I format them?\n\n1. **Conversation** — Read standards into our chat (for implementation work)\n2. **Skill** — Output file references to include in a skill you're building\n3. **Plan** — Output file references to include in a plan/spec\n\nWhich scenario? (1, 2, or 3)\n```\n\nAlways ask when uncertain — don't assume conversation by default.\n\n### Step 2: Read the Index (Auto-Suggest Mode)\n\nRead `agent-os/standards/index.yml` to get the list of available standards and their descriptions.\n\nIf index.yml doesn't exist or is empty:\n```\nNo standards index found. Run /discover-standards first to create standards,\nor /index-standards if you have standards files without an index.\n```\n\n### Step 3: Analyze Work Context\n\nLook at the current conversation to understand what the user is working on:\n- What type of work? (API, database, UI, etc.)\n- What technologies mentioned?\n- What's the goal?\n\n### Step 4: Match and Suggest\n\nMatch index descriptions against the context. Use AskUserQuestion to present suggestions:\n\n```\nBased on your task, these standards may be relevant:\n\n1. **api/response-format** — API response envelope structure, status codes\n2. **api/error-handling** — Error codes, exception handling, error responses\n3. **global/naming** — File naming, variable naming conventions\n\nInject these standards? (yes / just 1 and 3 / add: database/migrations / none)\n```\n\nKeep suggestions focused — typically 2-5 standards. Don't overwhelm with too many options.\n\n### Step 5: Inject Based on Scenario\n\nFormat the output differently based on the detected scenario:\n\n---\n\n#### Scenario: Conversation\n\nRead the standards and announce them:\n\n```\nI've read the following standards as they are relevant to what we're working on:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n**Key points:**\n- All API responses use { success, data, error } envelope\n- Error codes follow AUTH_xxx, DB_xxx pattern\n```\n\n---\n\n#### Scenario: Creating a Skill\n\nFirst, use AskUserQuestion to determine how to include the standards:\n\n```\nHow should these standards be included in your skill?\n\n1. **References** — Add @ file paths that point to the standards (keeps skill lightweight, standards stay in sync)\n2. **Copy content** — Paste the full standards content into the skill (self-contained, but won't update if standards change)\n\nWhich approach? (1 or 2)\n```\n\n**If References (option 1):**\n\n```\nBe sure to include references to the following standards files in the appropriate location in the file(s) that make up this skill:\n\n@agent-os/standards/api/response-format.md\n@agent-os/standards/api/error-handling.md\n@agent-os/standards/global/naming.md\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n**If Copy content (option 2):**\n\n```\nInclude the following standards content in your skill:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n---\n\n#### Scenario: Shaping/Planning\n\nFirst, use AskUserQuestion to determine how to include the standards:\n\n```\nHow should these standards be included in your plan?\n\n1. **References** — Add @ file paths that point to the standards (keeps plan lightweight, standards stay in sync)\n2. **Copy content** — Paste the full standards content into the plan (self-contained, but won't update if standards change)\n\nWhich approach? (1 or 2)\n```\n\n**If References (option 1):**\n\n```\nBe sure to include references to the following standards files in the appropriate location in the plan we're building:\n\n@agent-os/standards/api/response-format.md\n@agent-os/standards/api/error-handling.md\n@agent-os/standards/global/naming.md\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n**If Copy content (option 2):**\n\n```\nInclude the following standards content in your plan:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n---\n\n### Step 6: Surface Related Skills (Conversation scenario only)\n\nWhen in conversation scenario, check if `.claude/skills/` exists and contains related skills:\n\n```\nRelated Skills you might want to use:\n- create-api-endpoint — Scaffolds new API endpoints following these standards\n```\n\nDon't invoke skills automatically — just surface them for awareness.\n\n---\n\n## Explicit Mode\n\nWhen arguments are provided, skip the suggestion step but still detect scenario.\n\n### Step 1: Detect Scenario\n\nSame as auto-suggest mode.\n\n### Step 2: Parse Arguments\n\nArguments can be:\n- **Folder name** — `api` → inject all `.md` files in `agent-os/standards/api/`\n- **Folder/file** — `api/response-format` → inject `agent-os/standards/api/response-format.md`\n- **Root folder** — `root` → inject all `.md` files directly in `agent-os/standards/` (not in subfolders)\n- **Root file** — `root/naming` → inject `agent-os/standards/naming.md`\n\nMultiple arguments inject multiple standards.\n\n### Step 3: Validate\n\nCheck that specified files/folders exist. If not:\n\n```\nStandard not found: api/nonexistent\n\nAvailable standards in api/:\n- response-format\n- error-handling\n- authentication\n\nDid you mean one of these?\n```\n\n### Step 4: Inject Based on Scenario\n\nSame formatting as auto-suggest mode, based on detected scenario.\n\n---\n\n## Tips\n\n- **Run early** — Inject standards at the start of a task, before implementation\n- **Be specific** — If you know which standards apply, use explicit mode\n- **Check the index** — If suggestions seem wrong, run `/index-standards` to rebuild\n- **Keep standards concise** — Injected standards consume tokens; shorter is better\n\n## Integration\n\nThis command is called internally by `/shape-spec` to inject relevant standards during planning. You can also invoke it directly anytime you need standards in context.\n","commands/agent-os/index-standards.md":"# Index Standards\n\nRebuild and maintain the standards index file (`index.yml`).\n\n## Purpose\n\nThe index enables `/inject-standards` to suggest relevant standards without reading all files. It maps each standard to a brief description for quick matching.\n\n## Process\n\n### Step 1: Scan for Standards Files\n\n1. List all `.md` files in `agent-os/standards/` and its subfolders\n2. Build a list of all standards organized by folder:\n   ```\n   root/coding-style.md        # Files in standards/ root use \"root\" as the folder name\n   root/naming.md\n   api/response-format.md\n   api/error-handling.md\n   database/migrations.md\n   ```\n\n**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder). Do not create an actual folder named \"root\".\n\n### Step 2: Load Existing Index\n\nRead `agent-os/standards/index.yml` if it exists. Note which entries already have descriptions.\n\n### Step 3: Identify Changes\n\nCompare the file scan with the existing index:\n\n- **New files** — Standards files without index entries\n- **Deleted files** — Index entries for files that no longer exist\n- **Existing files** — Already indexed, keep as-is\n\n### Step 4: Handle New Files\n\nFor each new standard file that needs an index entry:\n\n1. Read the file to understand its content\n2. Use AskUserQuestion to propose a description:\n\n```\nNew standard needs indexing:\n  File: api/response-format.md\n\nSuggested description: \"API response envelope structure and error format\"\n\nAccept? (yes / or type a better description)\n```\n\nKeep descriptions to **one short sentence** — they're for matching, not documentation.\n\n### Step 5: Handle Deleted Files\n\nIf there are index entries for files that no longer exist:\n\n1. List them for the user\n2. Remove them from the index automatically (no confirmation needed)\n\nReport: \"Removed 2 stale index entries: api/old-pattern.md, testing/deprecated.md\"\n\n### Step 6: Write Updated Index\n\nGenerate `agent-os/standards/index.yml` with this structure:\n\n```yaml\nfolder-name:\n  file-name:\n    description: Brief description here\n```\n\n**Rules:**\n- Alphabetize folders\n- Alphabetize files within each folder\n- File names without `.md` extension\n- One-line descriptions only\n\n**Example:**\n```yaml\nroot:\n  coding-style:\n    description: General coding style, formatting, linting rules\n  naming:\n    description: File naming, variable naming, class naming conventions\n\napi:\n  error-handling:\n    description: Error codes, exception handling, error response format\n  response-format:\n    description: API response envelope structure, status codes, pagination\n\ndatabase:\n  migrations:\n    description: Migration file structure, naming conventions, rollback patterns\n```\n\n**Note:** `root` appears first and contains standards files that live directly in `agent-os/standards/` (not in subfolders).\n\n### Step 7: Report Results\n\nSummarize what changed:\n\n```\nIndex updated:\n  ✓ 2 new entries added\n  ✓ 1 stale entry removed\n  ✓ 8 entries unchanged\n\nTotal: 9 standards indexed\n```\n\n## When to Run\n\n- After manually creating or deleting standards files\n- If `/inject-standards` suggestions seem out of sync\n- To clean up a messy or outdated index\n\n**Note:** `/discover-standards` runs this automatically as its final step, so you usually don't need to call it separately after discovering standards.\n\n## Output\n\nUpdates `agent-os/standards/index.yml`\n","commands/agent-os/discover-standards.md":"# Discover Standards\n\nExtract tribal knowledge from your codebase into concise, documented standards.\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Write concise standards** — Use minimal words. Standards must be scannable by AI agents without bloating context windows.\n- **Offer suggestions** — Present options the user can confirm, choose between, or correct. Don't make them think harder than necessary.\n\n## Process\n\n### Step 1: Determine Focus Area\n\nCheck if the user specified an area when running this command. If they did, skip to Step 2.\n\nIf no area was specified:\n\n1. Analyze the codebase structure (folders, file types, patterns)\n2. Identify 3-5 major areas. Examples:\n   - **Frontend areas:** UI components, styling/CSS, state management, forms, routing\n   - **Backend areas:** API routes, database/models, authentication, background jobs\n   - **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure\n3. Use AskUserQuestion to present the areas:\n\n```\nI've identified these areas in your codebase:\n\n1. **API Routes** (src/api/) — Request handling, response formats\n2. **Database** (src/models/, src/db/) — Models, queries, migrations\n3. **React Components** (src/components/) — UI patterns, props, state\n4. **Authentication** (src/auth/) — Login, sessions, permissions\n\nWhich area should we focus on for discovering standards? (Pick one, or suggest a different area)\n```\n\nWait for user response before proceeding.\n\n### Step 2: Analyze & Present Findings\n\nOnce an area is determined:\n\n1. Read key files in that area (5-10 representative files)\n2. Look for patterns that are:\n   - **Unusual or unconventional** — Not standard framework/library patterns\n   - **Opinionated** — Specific choices that could have gone differently\n   - **Tribal** — Things a new developer wouldn't know without being told\n   - **Consistent** — Patterns repeated across multiple files\n\n3. Use AskUserQuestion to present findings and let user select:\n\n```\nI analyzed [area] and found these potential standards worth documenting:\n\n1. **API Response Envelope** — All responses use { success, data, error } structure\n2. **Error Codes** — Custom error codes like AUTH_001, DB_002 with specific meanings\n3. **Pagination Pattern** — Cursor-based pagination with consistent param names\n\nWhich would you like to document?\n\nOptions:\n- \"Yes, all of them\"\n- \"Just 1 and 3\"\n- \"Add: [your suggestion]\"\n- \"Skip this area\"\n```\n\nWait for user selection before proceeding.\n\n### Step 3: Ask Why, Then Draft Each Standard\n\n**IMPORTANT:** For each selected standard, you MUST complete this full loop before moving to the next standard:\n\n1. **Ask 1-2 clarifying questions** about the \"why\" behind the pattern. Use your AskUserQuestion tool for this.\n2. **Wait for user response**\n3. **Draft the standard** incorporating their answer\n4. **Confirm with user** before creating the file\n5. **Create the file** if approved\n\nExample questions to ask (adapt based on the specific standard):\n\n- \"What problem does this pattern solve? Why not use the default/common approach?\"\n- \"Are there exceptions where this pattern shouldn't be used?\"\n- \"What's the most common mistake a developer or agent makes with this?\"\n\n**Do NOT batch all questions upfront.** Process one standard at a time through the full loop.\n\n### Step 4: Create the Standard File\n\nFor each standard (after completing Step 3's Q&A):\n\n1. Determine the appropriate folder (create if needed):\n   - `api/`, `database/`, `javascript/`, `css/`, `backend/`, `testing/`, `global/`\n\n2. Check if a related standard file already exists — append to it if so\n\n3. Draft the content and use AskUserQuestion to confirm:\n\n```\nHere's the draft for api/response-format.md:\n\n---\n# API Response Format\n\nAll API responses use this envelope:\n\n\\`\\`\\`json\n{ \"success\": true, \"data\": { ... } }\n{ \"success\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }\n\\`\\`\\`\n\n- Never return raw data without the envelope\n- Error responses must include both code and message\n- Success responses omit the error field entirely\n---\n\nCreate this file? (yes / edit: [your changes] / skip)\n```\n\n4. Create or update the file in `agent-os/standards/[folder]/`\n5. **Then repeat Steps 3-4 for the next selected standard**\n\n### Step 5: Update the Index\n\nAfter all standards are created:\n\n1. Scan `agent-os/standards/` for all `.md` files\n2. For each new file without an index entry, use AskUserQuestion:\n\n```\nNew standard needs an index entry:\n  File: api/response-format.md\n\nSuggested description: \"API response envelope structure and error format\"\n\nAccept this description? (yes / or type a better one)\n```\n\n3. Update `agent-os/standards/index.yml`:\n\n```yaml\napi:\n  response-format:\n    description: API response envelope structure and error format\n```\n\nAlphabetize by folder, then by filename.\n\n### Step 6: Offer to Continue\n\nUse AskUserQuestion:\n\n```\nStandards created for [area]:\n- api/response-format.md\n- api/error-codes.md\n\nWould you like to discover standards in another area, or are we done?\n```\n\n## Output Location\n\nAll standards: `agent-os/standards/[folder]/[standard].md`\nIndex file: `agent-os/standards/index.yml`\n\n## Writing Concise Standards\n\nStandards will be injected into AI context windows. Every word costs tokens. Follow these rules:\n\n- **Lead with the rule** — State what to do first, explain why second (if needed)\n- **Use code examples** — Show, don't tell\n- **Skip the obvious** — Don't document what the code already makes clear\n- **One standard per concept** — Don't combine unrelated patterns\n- **Bullet points over paragraphs** — Scannable beats readable\n\n**Good:**\n```markdown\n# Error Responses\n\nUse error codes: `AUTH_001`, `DB_001`, `VAL_001`\n\n\\`\\`\\`json\n{ \"success\": false, \"error\": { \"code\": \"AUTH_001\", \"message\": \"...\" } }\n\\`\\`\\`\n\n- Always include both code and message\n- Log full error server-side, return safe message to client\n```\n\n**Bad:**\n```markdown\n# Error Handling Guidelines\n\nWhen an error occurs in our application, we have established a consistent pattern for how errors should be formatted and returned to the client. This helps maintain consistency across our API and makes it easier for frontend developers to handle errors appropriately...\n[continues for 3 more paragraphs]\n```\n\n## Example: Full Loop for One Standard\n\nHere's how to process a single standard through the complete workflow:\n\n**1. Present findings (Step 2):**\n```\nI found these patterns in your API code:\n1. **Response Envelope** — All responses use { success, data, error }\n2. **Error Codes** — Custom codes like AUTH_001\n\nWhich would you like to document?\n```\n\nUser: \"Both\"\n\n**2. Ask why for first standard (Step 3):**\n```\nFor the Response Envelope pattern:\n- What problem does this solve? Why not return raw data?\n- Are there any endpoints that don't use this pattern?\n```\n\nUser: \"We use it so the frontend always knows where to find the data. All endpoints use it, no exceptions.\"\n\n**3. Draft first standard (Step 3 continued):**\n```\nHere's the draft for api/response-envelope.md:\n\n---\n# Response Envelope\n\nAll API responses use this structure:\n\\`\\`\\`json\n{ \"success\": true, \"data\": { ... } }\n{ \"success\": false, \"error\": { ... } }\n\\`\\`\\`\n\n- Frontend always checks `success` first, then reads `data` or `error`\n- No exceptions — every endpoint uses this format\n---\n\nCreate this file?\n```\n\nUser: \"Yes\"\n\n**4. Create file, then move to next standard:**\n\n[Create the file]\n\n**5. Ask why for second standard (back to Step 3):**\n```\nFor the Error Codes pattern:\n- What's the naming convention for codes?\n- Where should new error codes be documented?\n```\n\nUser: \"Format is AREA_NUMBER like AUTH_001. We keep a list in the wiki.\"\n\n**6. Draft second standard, confirm, create file...**\n\n[Continue until all selected standards are done]\n\n**Key point:** Complete the full ask → draft → confirm → create cycle for each standard before starting the next one.\n","commands/agent-os/shape-spec.md":"# Shape Spec\n\nGather context and structure planning for significant work. **Run this command while in plan mode.**\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Offer suggestions** — Present options the user can confirm, adjust, or correct\n- **Keep it lightweight** — This is shaping, not exhaustive documentation\n\n## Prerequisites\n\nThis command **must be run in plan mode**.\n\n**Before proceeding, check if you are currently in plan mode.**\n\nIf NOT in plan mode, **stop immediately** and tell the user:\n\n```\nShape-spec must be run in plan mode. Please enter plan mode first, then run /shape-spec again.\n```\n\nDo not proceed with any steps below until confirmed to be in plan mode.\n\n## Process\n\n### Step 1: Clarify What We're Building\n\nUse AskUserQuestion to understand the scope:\n\n```\nWhat are we building? Please describe the feature or change.\n\n(Be as specific as you like — I'll ask follow-up questions if needed)\n```\n\nBased on their response, ask 1-2 clarifying questions if the scope is unclear. Examples:\n- \"Is this a new feature or a change to existing functionality?\"\n- \"What's the expected outcome when this is done?\"\n- \"Are there any constraints or requirements I should know about?\"\n\n### Step 2: Gather Visuals\n\nUse AskUserQuestion:\n\n```\nDo you have any visuals to reference?\n\n- Mockups or wireframes\n- Screenshots of similar features\n- Examples from other apps\n\n(Paste images, share file paths, or say \"none\")\n```\n\nIf visuals are provided, note them for inclusion in the spec folder.\n\n### Step 3: Identify Reference Implementations\n\nUse AskUserQuestion:\n\n```\nIs there similar code in this codebase I should reference?\n\nExamples:\n- \"The comments feature is similar to what we're building\"\n- \"Look at how src/features/notifications/ handles real-time updates\"\n- \"No existing references\"\n\n(Point me to files, folders, or features to study)\n```\n\nIf references are provided, read and analyze them to inform the plan.\n\n### Step 4: Check Product Context\n\nCheck if `agent-os/product/` exists and contains files.\n\nIf it exists, read key files (like `mission.md`, `roadmap.md`, `tech-stack.md`) and use AskUserQuestion:\n\n```\nI found product context in agent-os/product/. Should this feature align with any specific product goals or constraints?\n\nKey points from your product docs:\n- [summarize relevant points]\n\n(Confirm alignment or note any adjustments)\n```\n\nIf no product folder exists, skip this step.\n\n### Step 5: Surface Relevant Standards\n\nRead `agent-os/standards/index.yml` to identify relevant standards based on the feature being built.\n\nUse AskUserQuestion to confirm:\n\n```\nBased on what we're building, these standards may apply:\n\n1. **api/response-format** — API response envelope structure\n2. **api/error-handling** — Error codes and exception handling\n3. **database/migrations** — Migration patterns\n\nShould I include these in the spec? (yes / adjust: remove 3, add frontend/forms)\n```\n\nRead the confirmed standards files to include their content in the plan context.\n\n### Step 6: Generate Spec Folder Name\n\nCreate a folder name using this format:\n```\nYYYY-MM-DD-HHMM-{feature-slug}/\n```\n\nWhere:\n- Date/time is current timestamp\n- Feature slug is derived from the feature description (lowercase, hyphens, max 40 chars)\n\nExample: `2026-01-15-1430-user-comment-system/`\n\n**Note:** If `agent-os/specs/` doesn't exist, create it when saving the spec folder.\n\n### Step 7: Structure the Plan\n\nNow build the plan with **Task 1 always being \"Save spec documentation\"**.\n\nPresent this structure to the user:\n\n```\nHere's the plan structure. Task 1 saves all our shaping work before implementation begins.\n\n---\n\n## Task 1: Save Spec Documentation\n\nCreate `agent-os/specs/{folder-name}/` with:\n\n- **plan.md** — This full plan\n- **shape.md** — Shaping notes (scope, decisions, context from our conversation)\n- **standards.md** — Relevant standards that apply to this work\n- **references.md** — Pointers to reference implementations studied\n- **visuals/** — Any mockups or screenshots provided\n\n## Task 2: [First implementation task]\n\n[Description based on the feature]\n\n## Task 3: [Next task]\n\n...\n\n---\n\nDoes this plan structure look right? I'll fill in the implementation tasks next.\n```\n\n### Step 8: Complete the Plan\n\nAfter Task 1 is confirmed, continue building out the remaining implementation tasks based on:\n- The feature scope from Step 1\n- Patterns from reference implementations (Step 3)\n- Constraints from standards (Step 5)\n\nEach task should be specific and actionable.\n\n### Step 9: Ready for Execution\n\nWhen the full plan is ready:\n\n```\nPlan complete. When you approve and execute:\n\n1. Task 1 will save all spec documentation first\n2. Then implementation tasks will proceed\n\nReady to start? (approve / adjust)\n```\n\n## Output Structure\n\nThe spec folder will contain:\n\n```\nagent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/\n├── plan.md           # The full plan\n├── shape.md          # Shaping decisions and context\n├── standards.md      # Which standards apply and key points\n├── references.md     # Pointers to similar code\n└── visuals/          # Mockups, screenshots (if any)\n```\n\n## shape.md Content\n\nThe shape.md file should capture:\n\n```markdown\n# {Feature Name} — Shaping Notes\n\n## Scope\n\n[What we're building, from Step 1]\n\n## Decisions\n\n- [Key decisions made during shaping]\n- [Constraints or requirements noted]\n\n## Context\n\n- **Visuals:** [List of visuals provided, or \"None\"]\n- **References:** [Code references studied]\n- **Product alignment:** [Notes from product context, or \"N/A\"]\n\n## Standards Applied\n\n- api/response-format — [why it applies]\n- api/error-handling — [why it applies]\n```\n\n## standards.md Content\n\nInclude the full content of each relevant standard:\n\n```markdown\n# Standards for {Feature Name}\n\nThe following standards apply to this work.\n\n---\n\n## api/response-format\n\n[Full content of the standard file]\n\n---\n\n## api/error-handling\n\n[Full content of the standard file]\n```\n\n## references.md Content\n\n```markdown\n# References for {Feature Name}\n\n## Similar Implementations\n\n### {Reference 1 name}\n\n- **Location:** `src/features/comments/`\n- **Relevance:** [Why this is relevant]\n- **Key patterns:** [What to borrow from this]\n\n### {Reference 2 name}\n\n...\n```\n\n## Tips\n\n- **Keep shaping fast** — Don't over-document. Capture enough to start, refine as you build.\n- **Visuals are optional** — Not every feature needs mockups.\n- **Standards guide, not dictate** — They inform the plan but aren't always mandatory.\n- **Specs are discoverable** — Months later, someone can find this spec and understand what was built and why.\n","commands/agent-os/plan-product.md":"# Plan Product\n\nEstablish foundational product documentation through an interactive conversation. Creates mission, roadmap, and tech stack files in `agent-os/product/`.\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Keep it lightweight** — gather enough to create useful docs without over-documenting\n- **One question at a time** — don't overwhelm with multiple questions\n\n## Process\n\n### Step 1: Check for Existing Product Docs\n\nCheck if `agent-os/product/` exists and contains any of these files:\n- `mission.md`\n- `roadmap.md`\n- `tech-stack.md`\n\n**If any files exist**, use AskUserQuestion:\n\n```\nI found existing product documentation:\n- mission.md: [exists/missing]\n- roadmap.md: [exists/missing]\n- tech-stack.md: [exists/missing]\n\nWould you like to:\n1. Start fresh (replace all)\n2. Update specific files\n3. Cancel\n\n(Choose 1, 2, or 3)\n```\n\nIf option 2, ask which files to update and only gather info for those.\nIf option 3, stop here.\n\n**If no files exist**, proceed to Step 2.\n\n### Step 2: Gather Product Vision (for mission.md)\n\nUse AskUserQuestion:\n\n```\nLet's define your product's mission.\n\n**What problem does this product solve?**\n\n(Describe the core problem or pain point you're addressing)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**Who is this product for?**\n\n(Describe your target users or audience)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**What makes your solution unique?**\n\n(What's the key differentiator or approach?)\n```\n\n### Step 3: Gather Roadmap (for roadmap.md)\n\nUse AskUserQuestion:\n\n```\nNow let's outline your development roadmap.\n\n**What are the must-have features for launch (MVP)?**\n\n(List the core features needed for the first usable version)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**What features are planned for after launch?**\n\n(List features you'd like to add in future phases, or say \"none yet\")\n```\n\n### Step 4: Establish Tech Stack (for tech-stack.md)\n\nFirst, check if `agent-os/standards/global/tech-stack.md` exists.\n\n**If the tech-stack standard exists**, read it and use AskUserQuestion:\n\n```\nI found a tech stack standard in your standards:\n\n[Summarize the key technologies from global/tech-stack.md]\n\nDoes this project use the same tech stack, or does it differ?\n\n1. Same as standard (use as-is)\n2. Different (I'll specify)\n\n(Choose 1 or 2)\n```\n\nIf they choose option 1, use the standard's content for tech-stack.md.\nIf they choose option 2, proceed to ask them to specify (see below).\n\n**If no tech-stack standard exists** (or they chose option 2 above), use AskUserQuestion:\n\n```\n**What technologies does this project use?**\n\nPlease describe your tech stack:\n- Frontend: (e.g., React, Vue, vanilla JS, or N/A)\n- Backend: (e.g., Rails, Node, Django, or N/A)\n- Database: (e.g., PostgreSQL, MongoDB, or N/A)\n- Other: (hosting, APIs, tools, etc.)\n```\n\n### Step 5: Generate Files\n\nCreate the `agent-os/product/` directory if it doesn't exist.\n\nGenerate each file based on the information gathered:\n\n#### mission.md\n\n```markdown\n# Product Mission\n\n## Problem\n\n[Insert what problem this product solves - from Step 2]\n\n## Target Users\n\n[Insert who this product is for - from Step 2]\n\n## Solution\n\n[Insert what makes the solution unique - from Step 2]\n```\n\n#### roadmap.md\n\n```markdown\n# Product Roadmap\n\n## Phase 1: MVP\n\n[Insert must-have features for launch - from Step 3]\n\n## Phase 2: Post-Launch\n\n[Insert planned future features - from Step 3, or \"To be determined\" if they said none yet]\n```\n\n#### tech-stack.md\n\n```markdown\n# Tech Stack\n\n[Organize the tech stack information into logical sections]\n\n## Frontend\n\n[Frontend technologies, or \"N/A\" if not applicable]\n\n## Backend\n\n[Backend technologies, or \"N/A\" if not applicable]\n\n## Database\n\n[Database choice, or \"N/A\" if not applicable]\n\n## Other\n\n[Other tools, hosting, services - or omit this section if nothing mentioned]\n```\n\n### Step 6: Confirm Completion\n\nAfter creating all files, output to user:\n\n```\n✓ Product documentation created:\n\n  agent-os/product/mission.md\n  agent-os/product/roadmap.md\n  agent-os/product/tech-stack.md\n\nReview these files to ensure they accurately capture your product vision.\nYou can edit them directly or run /plan-product again to update.\n```\n\n## Tips\n\n- If the user provides very brief answers, that's fine — the docs can be expanded later\n- If they want to skip a section, create the file with a placeholder like \"To be defined\"\n- The `/shape-spec` command will read these files when planning features, so having them populated helps with context\n"},"files":{"commands/agent-os/inject-standards.md":"# Inject Standards\n\nInject relevant standards into the current context, formatted appropriately for the situation.\n\n## Usage Modes\n\nThis command supports two modes:\n\n### Auto-Suggest Mode (no arguments)\n```\n/inject-standards\n```\nAnalyzes context and suggests relevant standards.\n\n### Explicit Mode (with arguments)\n```\n/inject-standards api                           # All standards in api/\n/inject-standards api/response-format           # Single file\n/inject-standards api/response-format api/auth  # Multiple files\n/inject-standards root                          # All standards in the root folder\n/inject-standards root/naming                   # Single file from root folder\n```\nDirectly injects specified standards without suggestions.\n\n**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder).\n\n## Process\n\n### Step 1: Detect Context Scenario\n\nBefore injecting standards, determine which scenario we're in. Read the current conversation and check if we're in plan mode.\n\n**Three scenarios:**\n\n1. **Conversation** — Regular chat, implementing code, answering questions\n2. **Creating a Skill** — Building a `.claude/skills/` file\n3. **Shaping/Planning** — In plan mode, building a spec, running `/shape-spec`\n\n**Detection logic:**\n\n- If currently in plan mode OR conversation clearly mentions \"spec\", \"plan\", \"shape\" → **Shaping/Planning**\n- If conversation clearly mentions creating a skill, editing `.claude/skills/`, or building a reusable procedure → **Creating a Skill**\n- Otherwise → **Ask to confirm** (do not assume)\n\n**If neither skill nor plan is clearly detected**, use AskUserQuestion to confirm:\n\n```\nI'll inject the relevant standards. How should I format them?\n\n1. **Conversation** — Read standards into our chat (for implementation work)\n2. **Skill** — Output file references to include in a skill you're building\n3. **Plan** — Output file references to include in a plan/spec\n\nWhich scenario? (1, 2, or 3)\n```\n\nAlways ask when uncertain — don't assume conversation by default.\n\n### Step 2: Read the Index (Auto-Suggest Mode)\n\nRead `agent-os/standards/index.yml` to get the list of available standards and their descriptions.\n\nIf index.yml doesn't exist or is empty:\n```\nNo standards index found. Run /discover-standards first to create standards,\nor /index-standards if you have standards files without an index.\n```\n\n### Step 3: Analyze Work Context\n\nLook at the current conversation to understand what the user is working on:\n- What type of work? (API, database, UI, etc.)\n- What technologies mentioned?\n- What's the goal?\n\n### Step 4: Match and Suggest\n\nMatch index descriptions against the context. Use AskUserQuestion to present suggestions:\n\n```\nBased on your task, these standards may be relevant:\n\n1. **api/response-format** — API response envelope structure, status codes\n2. **api/error-handling** — Error codes, exception handling, error responses\n3. **global/naming** — File naming, variable naming conventions\n\nInject these standards? (yes / just 1 and 3 / add: database/migrations / none)\n```\n\nKeep suggestions focused — typically 2-5 standards. Don't overwhelm with too many options.\n\n### Step 5: Inject Based on Scenario\n\nFormat the output differently based on the detected scenario:\n\n---\n\n#### Scenario: Conversation\n\nRead the standards and announce them:\n\n```\nI've read the following standards as they are relevant to what we're working on:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n**Key points:**\n- All API responses use { success, data, error } envelope\n- Error codes follow AUTH_xxx, DB_xxx pattern\n```\n\n---\n\n#### Scenario: Creating a Skill\n\nFirst, use AskUserQuestion to determine how to include the standards:\n\n```\nHow should these standards be included in your skill?\n\n1. **References** — Add @ file paths that point to the standards (keeps skill lightweight, standards stay in sync)\n2. **Copy content** — Paste the full standards content into the skill (self-contained, but won't update if standards change)\n\nWhich approach? (1 or 2)\n```\n\n**If References (option 1):**\n\n```\nBe sure to include references to the following standards files in the appropriate location in the file(s) that make up this skill:\n\n@agent-os/standards/api/response-format.md\n@agent-os/standards/api/error-handling.md\n@agent-os/standards/global/naming.md\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n**If Copy content (option 2):**\n\n```\nInclude the following standards content in your skill:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n---\n\n#### Scenario: Shaping/Planning\n\nFirst, use AskUserQuestion to determine how to include the standards:\n\n```\nHow should these standards be included in your plan?\n\n1. **References** — Add @ file paths that point to the standards (keeps plan lightweight, standards stay in sync)\n2. **Copy content** — Paste the full standards content into the plan (self-contained, but won't update if standards change)\n\nWhich approach? (1 or 2)\n```\n\n**If References (option 1):**\n\n```\nBe sure to include references to the following standards files in the appropriate location in the plan we're building:\n\n@agent-os/standards/api/response-format.md\n@agent-os/standards/api/error-handling.md\n@agent-os/standards/global/naming.md\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n**If Copy content (option 2):**\n\n```\nInclude the following standards content in your plan:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n---\n\n### Step 6: Surface Related Skills (Conversation scenario only)\n\nWhen in conversation scenario, check if `.claude/skills/` exists and contains related skills:\n\n```\nRelated Skills you might want to use:\n- create-api-endpoint — Scaffolds new API endpoints following these standards\n```\n\nDon't invoke skills automatically — just surface them for awareness.\n\n---\n\n## Explicit Mode\n\nWhen arguments are provided, skip the suggestion step but still detect scenario.\n\n### Step 1: Detect Scenario\n\nSame as auto-suggest mode.\n\n### Step 2: Parse Arguments\n\nArguments can be:\n- **Folder name** — `api` → inject all `.md` files in `agent-os/standards/api/`\n- **Folder/file** — `api/response-format` → inject `agent-os/standards/api/response-format.md`\n- **Root folder** — `root` → inject all `.md` files directly in `agent-os/standards/` (not in subfolders)\n- **Root file** — `root/naming` → inject `agent-os/standards/naming.md`\n\nMultiple arguments inject multiple standards.\n\n### Step 3: Validate\n\nCheck that specified files/folders exist. If not:\n\n```\nStandard not found: api/nonexistent\n\nAvailable standards in api/:\n- response-format\n- error-handling\n- authentication\n\nDid you mean one of these?\n```\n\n### Step 4: Inject Based on Scenario\n\nSame formatting as auto-suggest mode, based on detected scenario.\n\n---\n\n## Tips\n\n- **Run early** — Inject standards at the start of a task, before implementation\n- **Be specific** — If you know which standards apply, use explicit mode\n- **Check the index** — If suggestions seem wrong, run `/index-standards` to rebuild\n- **Keep standards concise** — Injected standards consume tokens; shorter is better\n\n## Integration\n\nThis command is called internally by `/shape-spec` to inject relevant standards during planning. You can also invoke it directly anytime you need standards in context.\n","commands/agent-os/index-standards.md":"# Index Standards\n\nRebuild and maintain the standards index file (`index.yml`).\n\n## Purpose\n\nThe index enables `/inject-standards` to suggest relevant standards without reading all files. It maps each standard to a brief description for quick matching.\n\n## Process\n\n### Step 1: Scan for Standards Files\n\n1. List all `.md` files in `agent-os/standards/` and its subfolders\n2. Build a list of all standards organized by folder:\n   ```\n   root/coding-style.md        # Files in standards/ root use \"root\" as the folder name\n   root/naming.md\n   api/response-format.md\n   api/error-handling.md\n   database/migrations.md\n   ```\n\n**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder). Do not create an actual folder named \"root\".\n\n### Step 2: Load Existing Index\n\nRead `agent-os/standards/index.yml` if it exists. Note which entries already have descriptions.\n\n### Step 3: Identify Changes\n\nCompare the file scan with the existing index:\n\n- **New files** — Standards files without index entries\n- **Deleted files** — Index entries for files that no longer exist\n- **Existing files** — Already indexed, keep as-is\n\n### Step 4: Handle New Files\n\nFor each new standard file that needs an index entry:\n\n1. Read the file to understand its content\n2. Use AskUserQuestion to propose a description:\n\n```\nNew standard needs indexing:\n  File: api/response-format.md\n\nSuggested description: \"API response envelope structure and error format\"\n\nAccept? (yes / or type a better description)\n```\n\nKeep descriptions to **one short sentence** — they're for matching, not documentation.\n\n### Step 5: Handle Deleted Files\n\nIf there are index entries for files that no longer exist:\n\n1. List them for the user\n2. Remove them from the index automatically (no confirmation needed)\n\nReport: \"Removed 2 stale index entries: api/old-pattern.md, testing/deprecated.md\"\n\n### Step 6: Write Updated Index\n\nGenerate `agent-os/standards/index.yml` with this structure:\n\n```yaml\nfolder-name:\n  file-name:\n    description: Brief description here\n```\n\n**Rules:**\n- Alphabetize folders\n- Alphabetize files within each folder\n- File names without `.md` extension\n- One-line descriptions only\n\n**Example:**\n```yaml\nroot:\n  coding-style:\n    description: General coding style, formatting, linting rules\n  naming:\n    description: File naming, variable naming, class naming conventions\n\napi:\n  error-handling:\n    description: Error codes, exception handling, error response format\n  response-format:\n    description: API response envelope structure, status codes, pagination\n\ndatabase:\n  migrations:\n    description: Migration file structure, naming conventions, rollback patterns\n```\n\n**Note:** `root` appears first and contains standards files that live directly in `agent-os/standards/` (not in subfolders).\n\n### Step 7: Report Results\n\nSummarize what changed:\n\n```\nIndex updated:\n  ✓ 2 new entries added\n  ✓ 1 stale entry removed\n  ✓ 8 entries unchanged\n\nTotal: 9 standards indexed\n```\n\n## When to Run\n\n- After manually creating or deleting standards files\n- If `/inject-standards` suggestions seem out of sync\n- To clean up a messy or outdated index\n\n**Note:** `/discover-standards` runs this automatically as its final step, so you usually don't need to call it separately after discovering standards.\n\n## Output\n\nUpdates `agent-os/standards/index.yml`\n","commands/agent-os/discover-standards.md":"# Discover Standards\n\nExtract tribal knowledge from your codebase into concise, documented standards.\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Write concise standards** — Use minimal words. Standards must be scannable by AI agents without bloating context windows.\n- **Offer suggestions** — Present options the user can confirm, choose between, or correct. Don't make them think harder than necessary.\n\n## Process\n\n### Step 1: Determine Focus Area\n\nCheck if the user specified an area when running this command. If they did, skip to Step 2.\n\nIf no area was specified:\n\n1. Analyze the codebase structure (folders, file types, patterns)\n2. Identify 3-5 major areas. Examples:\n   - **Frontend areas:** UI components, styling/CSS, state management, forms, routing\n   - **Backend areas:** API routes, database/models, authentication, background jobs\n   - **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure\n3. Use AskUserQuestion to present the areas:\n\n```\nI've identified these areas in your codebase:\n\n1. **API Routes** (src/api/) — Request handling, response formats\n2. **Database** (src/models/, src/db/) — Models, queries, migrations\n3. **React Components** (src/components/) — UI patterns, props, state\n4. **Authentication** (src/auth/) — Login, sessions, permissions\n\nWhich area should we focus on for discovering standards? (Pick one, or suggest a different area)\n```\n\nWait for user response before proceeding.\n\n### Step 2: Analyze & Present Findings\n\nOnce an area is determined:\n\n1. Read key files in that area (5-10 representative files)\n2. Look for patterns that are:\n   - **Unusual or unconventional** — Not standard framework/library patterns\n   - **Opinionated** — Specific choices that could have gone differently\n   - **Tribal** — Things a new developer wouldn't know without being told\n   - **Consistent** — Patterns repeated across multiple files\n\n3. Use AskUserQuestion to present findings and let user select:\n\n```\nI analyzed [area] and found these potential standards worth documenting:\n\n1. **API Response Envelope** — All responses use { success, data, error } structure\n2. **Error Codes** — Custom error codes like AUTH_001, DB_002 with specific meanings\n3. **Pagination Pattern** — Cursor-based pagination with consistent param names\n\nWhich would you like to document?\n\nOptions:\n- \"Yes, all of them\"\n- \"Just 1 and 3\"\n- \"Add: [your suggestion]\"\n- \"Skip this area\"\n```\n\nWait for user selection before proceeding.\n\n### Step 3: Ask Why, Then Draft Each Standard\n\n**IMPORTANT:** For each selected standard, you MUST complete this full loop before moving to the next standard:\n\n1. **Ask 1-2 clarifying questions** about the \"why\" behind the pattern. Use your AskUserQuestion tool for this.\n2. **Wait for user response**\n3. **Draft the standard** incorporating their answer\n4. **Confirm with user** before creating the file\n5. **Create the file** if approved\n\nExample questions to ask (adapt based on the specific standard):\n\n- \"What problem does this pattern solve? Why not use the default/common approach?\"\n- \"Are there exceptions where this pattern shouldn't be used?\"\n- \"What's the most common mistake a developer or agent makes with this?\"\n\n**Do NOT batch all questions upfront.** Process one standard at a time through the full loop.\n\n### Step 4: Create the Standard File\n\nFor each standard (after completing Step 3's Q&A):\n\n1. Determine the appropriate folder (create if needed):\n   - `api/`, `database/`, `javascript/`, `css/`, `backend/`, `testing/`, `global/`\n\n2. Check if a related standard file already exists — append to it if so\n\n3. Draft the content and use AskUserQuestion to confirm:\n\n```\nHere's the draft for api/response-format.md:\n\n---\n# API Response Format\n\nAll API responses use this envelope:\n\n\\`\\`\\`json\n{ \"success\": true, \"data\": { ... } }\n{ \"success\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }\n\\`\\`\\`\n\n- Never return raw data without the envelope\n- Error responses must include both code and message\n- Success responses omit the error field entirely\n---\n\nCreate this file? (yes / edit: [your changes] / skip)\n```\n\n4. Create or update the file in `agent-os/standards/[folder]/`\n5. **Then repeat Steps 3-4 for the next selected standard**\n\n### Step 5: Update the Index\n\nAfter all standards are created:\n\n1. Scan `agent-os/standards/` for all `.md` files\n2. For each new file without an index entry, use AskUserQuestion:\n\n```\nNew standard needs an index entry:\n  File: api/response-format.md\n\nSuggested description: \"API response envelope structure and error format\"\n\nAccept this description? (yes / or type a better one)\n```\n\n3. Update `agent-os/standards/index.yml`:\n\n```yaml\napi:\n  response-format:\n    description: API response envelope structure and error format\n```\n\nAlphabetize by folder, then by filename.\n\n### Step 6: Offer to Continue\n\nUse AskUserQuestion:\n\n```\nStandards created for [area]:\n- api/response-format.md\n- api/error-codes.md\n\nWould you like to discover standards in another area, or are we done?\n```\n\n## Output Location\n\nAll standards: `agent-os/standards/[folder]/[standard].md`\nIndex file: `agent-os/standards/index.yml`\n\n## Writing Concise Standards\n\nStandards will be injected into AI context windows. Every word costs tokens. Follow these rules:\n\n- **Lead with the rule** — State what to do first, explain why second (if needed)\n- **Use code examples** — Show, don't tell\n- **Skip the obvious** — Don't document what the code already makes clear\n- **One standard per concept** — Don't combine unrelated patterns\n- **Bullet points over paragraphs** — Scannable beats readable\n\n**Good:**\n```markdown\n# Error Responses\n\nUse error codes: `AUTH_001`, `DB_001`, `VAL_001`\n\n\\`\\`\\`json\n{ \"success\": false, \"error\": { \"code\": \"AUTH_001\", \"message\": \"...\" } }\n\\`\\`\\`\n\n- Always include both code and message\n- Log full error server-side, return safe message to client\n```\n\n**Bad:**\n```markdown\n# Error Handling Guidelines\n\nWhen an error occurs in our application, we have established a consistent pattern for how errors should be formatted and returned to the client. This helps maintain consistency across our API and makes it easier for frontend developers to handle errors appropriately...\n[continues for 3 more paragraphs]\n```\n\n## Example: Full Loop for One Standard\n\nHere's how to process a single standard through the complete workflow:\n\n**1. Present findings (Step 2):**\n```\nI found these patterns in your API code:\n1. **Response Envelope** — All responses use { success, data, error }\n2. **Error Codes** — Custom codes like AUTH_001\n\nWhich would you like to document?\n```\n\nUser: \"Both\"\n\n**2. Ask why for first standard (Step 3):**\n```\nFor the Response Envelope pattern:\n- What problem does this solve? Why not return raw data?\n- Are there any endpoints that don't use this pattern?\n```\n\nUser: \"We use it so the frontend always knows where to find the data. All endpoints use it, no exceptions.\"\n\n**3. Draft first standard (Step 3 continued):**\n```\nHere's the draft for api/response-envelope.md:\n\n---\n# Response Envelope\n\nAll API responses use this structure:\n\\`\\`\\`json\n{ \"success\": true, \"data\": { ... } }\n{ \"success\": false, \"error\": { ... } }\n\\`\\`\\`\n\n- Frontend always checks `success` first, then reads `data` or `error`\n- No exceptions — every endpoint uses this format\n---\n\nCreate this file?\n```\n\nUser: \"Yes\"\n\n**4. Create file, then move to next standard:**\n\n[Create the file]\n\n**5. Ask why for second standard (back to Step 3):**\n```\nFor the Error Codes pattern:\n- What's the naming convention for codes?\n- Where should new error codes be documented?\n```\n\nUser: \"Format is AREA_NUMBER like AUTH_001. We keep a list in the wiki.\"\n\n**6. Draft second standard, confirm, create file...**\n\n[Continue until all selected standards are done]\n\n**Key point:** Complete the full ask → draft → confirm → create cycle for each standard before starting the next one.\n","commands/agent-os/shape-spec.md":"# Shape Spec\n\nGather context and structure planning for significant work. **Run this command while in plan mode.**\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Offer suggestions** — Present options the user can confirm, adjust, or correct\n- **Keep it lightweight** — This is shaping, not exhaustive documentation\n\n## Prerequisites\n\nThis command **must be run in plan mode**.\n\n**Before proceeding, check if you are currently in plan mode.**\n\nIf NOT in plan mode, **stop immediately** and tell the user:\n\n```\nShape-spec must be run in plan mode. Please enter plan mode first, then run /shape-spec again.\n```\n\nDo not proceed with any steps below until confirmed to be in plan mode.\n\n## Process\n\n### Step 1: Clarify What We're Building\n\nUse AskUserQuestion to understand the scope:\n\n```\nWhat are we building? Please describe the feature or change.\n\n(Be as specific as you like — I'll ask follow-up questions if needed)\n```\n\nBased on their response, ask 1-2 clarifying questions if the scope is unclear. Examples:\n- \"Is this a new feature or a change to existing functionality?\"\n- \"What's the expected outcome when this is done?\"\n- \"Are there any constraints or requirements I should know about?\"\n\n### Step 2: Gather Visuals\n\nUse AskUserQuestion:\n\n```\nDo you have any visuals to reference?\n\n- Mockups or wireframes\n- Screenshots of similar features\n- Examples from other apps\n\n(Paste images, share file paths, or say \"none\")\n```\n\nIf visuals are provided, note them for inclusion in the spec folder.\n\n### Step 3: Identify Reference Implementations\n\nUse AskUserQuestion:\n\n```\nIs there similar code in this codebase I should reference?\n\nExamples:\n- \"The comments feature is similar to what we're building\"\n- \"Look at how src/features/notifications/ handles real-time updates\"\n- \"No existing references\"\n\n(Point me to files, folders, or features to study)\n```\n\nIf references are provided, read and analyze them to inform the plan.\n\n### Step 4: Check Product Context\n\nCheck if `agent-os/product/` exists and contains files.\n\nIf it exists, read key files (like `mission.md`, `roadmap.md`, `tech-stack.md`) and use AskUserQuestion:\n\n```\nI found product context in agent-os/product/. Should this feature align with any specific product goals or constraints?\n\nKey points from your product docs:\n- [summarize relevant points]\n\n(Confirm alignment or note any adjustments)\n```\n\nIf no product folder exists, skip this step.\n\n### Step 5: Surface Relevant Standards\n\nRead `agent-os/standards/index.yml` to identify relevant standards based on the feature being built.\n\nUse AskUserQuestion to confirm:\n\n```\nBased on what we're building, these standards may apply:\n\n1. **api/response-format** — API response envelope structure\n2. **api/error-handling** — Error codes and exception handling\n3. **database/migrations** — Migration patterns\n\nShould I include these in the spec? (yes / adjust: remove 3, add frontend/forms)\n```\n\nRead the confirmed standards files to include their content in the plan context.\n\n### Step 6: Generate Spec Folder Name\n\nCreate a folder name using this format:\n```\nYYYY-MM-DD-HHMM-{feature-slug}/\n```\n\nWhere:\n- Date/time is current timestamp\n- Feature slug is derived from the feature description (lowercase, hyphens, max 40 chars)\n\nExample: `2026-01-15-1430-user-comment-system/`\n\n**Note:** If `agent-os/specs/` doesn't exist, create it when saving the spec folder.\n\n### Step 7: Structure the Plan\n\nNow build the plan with **Task 1 always being \"Save spec documentation\"**.\n\nPresent this structure to the user:\n\n```\nHere's the plan structure. Task 1 saves all our shaping work before implementation begins.\n\n---\n\n## Task 1: Save Spec Documentation\n\nCreate `agent-os/specs/{folder-name}/` with:\n\n- **plan.md** — This full plan\n- **shape.md** — Shaping notes (scope, decisions, context from our conversation)\n- **standards.md** — Relevant standards that apply to this work\n- **references.md** — Pointers to reference implementations studied\n- **visuals/** — Any mockups or screenshots provided\n\n## Task 2: [First implementation task]\n\n[Description based on the feature]\n\n## Task 3: [Next task]\n\n...\n\n---\n\nDoes this plan structure look right? I'll fill in the implementation tasks next.\n```\n\n### Step 8: Complete the Plan\n\nAfter Task 1 is confirmed, continue building out the remaining implementation tasks based on:\n- The feature scope from Step 1\n- Patterns from reference implementations (Step 3)\n- Constraints from standards (Step 5)\n\nEach task should be specific and actionable.\n\n### Step 9: Ready for Execution\n\nWhen the full plan is ready:\n\n```\nPlan complete. When you approve and execute:\n\n1. Task 1 will save all spec documentation first\n2. Then implementation tasks will proceed\n\nReady to start? (approve / adjust)\n```\n\n## Output Structure\n\nThe spec folder will contain:\n\n```\nagent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/\n├── plan.md           # The full plan\n├── shape.md          # Shaping decisions and context\n├── standards.md      # Which standards apply and key points\n├── references.md     # Pointers to similar code\n└── visuals/          # Mockups, screenshots (if any)\n```\n\n## shape.md Content\n\nThe shape.md file should capture:\n\n```markdown\n# {Feature Name} — Shaping Notes\n\n## Scope\n\n[What we're building, from Step 1]\n\n## Decisions\n\n- [Key decisions made during shaping]\n- [Constraints or requirements noted]\n\n## Context\n\n- **Visuals:** [List of visuals provided, or \"None\"]\n- **References:** [Code references studied]\n- **Product alignment:** [Notes from product context, or \"N/A\"]\n\n## Standards Applied\n\n- api/response-format — [why it applies]\n- api/error-handling — [why it applies]\n```\n\n## standards.md Content\n\nInclude the full content of each relevant standard:\n\n```markdown\n# Standards for {Feature Name}\n\nThe following standards apply to this work.\n\n---\n\n## api/response-format\n\n[Full content of the standard file]\n\n---\n\n## api/error-handling\n\n[Full content of the standard file]\n```\n\n## references.md Content\n\n```markdown\n# References for {Feature Name}\n\n## Similar Implementations\n\n### {Reference 1 name}\n\n- **Location:** `src/features/comments/`\n- **Relevance:** [Why this is relevant]\n- **Key patterns:** [What to borrow from this]\n\n### {Reference 2 name}\n\n...\n```\n\n## Tips\n\n- **Keep shaping fast** — Don't over-document. Capture enough to start, refine as you build.\n- **Visuals are optional** — Not every feature needs mockups.\n- **Standards guide, not dictate** — They inform the plan but aren't always mandatory.\n- **Specs are discoverable** — Months later, someone can find this spec and understand what was built and why.\n","commands/agent-os/plan-product.md":"# Plan Product\n\nEstablish foundational product documentation through an interactive conversation. Creates mission, roadmap, and tech stack files in `agent-os/product/`.\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Keep it lightweight** — gather enough to create useful docs without over-documenting\n- **One question at a time** — don't overwhelm with multiple questions\n\n## Process\n\n### Step 1: Check for Existing Product Docs\n\nCheck if `agent-os/product/` exists and contains any of these files:\n- `mission.md`\n- `roadmap.md`\n- `tech-stack.md`\n\n**If any files exist**, use AskUserQuestion:\n\n```\nI found existing product documentation:\n- mission.md: [exists/missing]\n- roadmap.md: [exists/missing]\n- tech-stack.md: [exists/missing]\n\nWould you like to:\n1. Start fresh (replace all)\n2. Update specific files\n3. Cancel\n\n(Choose 1, 2, or 3)\n```\n\nIf option 2, ask which files to update and only gather info for those.\nIf option 3, stop here.\n\n**If no files exist**, proceed to Step 2.\n\n### Step 2: Gather Product Vision (for mission.md)\n\nUse AskUserQuestion:\n\n```\nLet's define your product's mission.\n\n**What problem does this product solve?**\n\n(Describe the core problem or pain point you're addressing)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**Who is this product for?**\n\n(Describe your target users or audience)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**What makes your solution unique?**\n\n(What's the key differentiator or approach?)\n```\n\n### Step 3: Gather Roadmap (for roadmap.md)\n\nUse AskUserQuestion:\n\n```\nNow let's outline your development roadmap.\n\n**What are the must-have features for launch (MVP)?**\n\n(List the core features needed for the first usable version)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**What features are planned for after launch?**\n\n(List features you'd like to add in future phases, or say \"none yet\")\n```\n\n### Step 4: Establish Tech Stack (for tech-stack.md)\n\nFirst, check if `agent-os/standards/global/tech-stack.md` exists.\n\n**If the tech-stack standard exists**, read it and use AskUserQuestion:\n\n```\nI found a tech stack standard in your standards:\n\n[Summarize the key technologies from global/tech-stack.md]\n\nDoes this project use the same tech stack, or does it differ?\n\n1. Same as standard (use as-is)\n2. Different (I'll specify)\n\n(Choose 1 or 2)\n```\n\nIf they choose option 1, use the standard's content for tech-stack.md.\nIf they choose option 2, proceed to ask them to specify (see below).\n\n**If no tech-stack standard exists** (or they chose option 2 above), use AskUserQuestion:\n\n```\n**What technologies does this project use?**\n\nPlease describe your tech stack:\n- Frontend: (e.g., React, Vue, vanilla JS, or N/A)\n- Backend: (e.g., Rails, Node, Django, or N/A)\n- Database: (e.g., PostgreSQL, MongoDB, or N/A)\n- Other: (hosting, APIs, tools, etc.)\n```\n\n### Step 5: Generate Files\n\nCreate the `agent-os/product/` directory if it doesn't exist.\n\nGenerate each file based on the information gathered:\n\n#### mission.md\n\n```markdown\n# Product Mission\n\n## Problem\n\n[Insert what problem this product solves - from Step 2]\n\n## Target Users\n\n[Insert who this product is for - from Step 2]\n\n## Solution\n\n[Insert what makes the solution unique - from Step 2]\n```\n\n#### roadmap.md\n\n```markdown\n# Product Roadmap\n\n## Phase 1: MVP\n\n[Insert must-have features for launch - from Step 3]\n\n## Phase 2: Post-Launch\n\n[Insert planned future features - from Step 3, or \"To be determined\" if they said none yet]\n```\n\n#### tech-stack.md\n\n```markdown\n# Tech Stack\n\n[Organize the tech stack information into logical sections]\n\n## Frontend\n\n[Frontend technologies, or \"N/A\" if not applicable]\n\n## Backend\n\n[Backend technologies, or \"N/A\" if not applicable]\n\n## Database\n\n[Database choice, or \"N/A\" if not applicable]\n\n## Other\n\n[Other tools, hosting, services - or omit this section if nothing mentioned]\n```\n\n### Step 6: Confirm Completion\n\nAfter creating all files, output to user:\n\n```\n✓ Product documentation created:\n\n  agent-os/product/mission.md\n  agent-os/product/roadmap.md\n  agent-os/product/tech-stack.md\n\nReview these files to ensure they accurately capture your product vision.\nYou can edit them directly or run /plan-product again to update.\n```\n\n## Tips\n\n- If the user provides very brief answers, that's fine — the docs can be expanded later\n- If they want to skip a section, create the file with a placeholder like \"To be defined\"\n- The `/shape-spec` command will read these files when planning features, so having them populated helps with context\n"},"items":[{"name":"discover-standards.md","path":"commands/agent-os/discover-standards.md","rawUrl":"https://raw.githubusercontent.com/buildermethods/agent-os/HEAD/commands/agent-os/discover-standards.md","title":"Command: /discover-standards","category":"command-prompt","format":"markdown","content":"# Discover Standards\n\nExtract tribal knowledge from your codebase into concise, documented standards.\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Write concise standards** — Use minimal words. Standards must be scannable by AI agents without bloating context windows.\n- **Offer suggestions** — Present options the user can confirm, choose between, or correct. Don't make them think harder than necessary.\n\n## Process\n\n### Step 1: Determine Focus Area\n\nCheck if the user specified an area when running this command. If they did, skip to Step 2.\n\nIf no area was specified:\n\n1. Analyze the codebase structure (folders, file types, patterns)\n2. Identify 3-5 major areas. Examples:\n   - **Frontend areas:** UI components, styling/CSS, state management, forms, routing\n   - **Backend areas:** API routes, database/models, authentication, background jobs\n   - **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure\n3. Use AskUserQuestion to present the areas:\n\n```\nI've identified these areas in your codebase:\n\n1. **API Routes** (src/api/) — Request handling, response formats\n2. **Database** (src/models/, src/db/) — Models, queries, migrations\n3. **React Components** (src/components/) — UI patterns, props, state\n4. **Authentication** (src/auth/) — Login, sessions, permissions\n\nWhich area should we focus on for discovering standards? (Pick one, or suggest a different area)\n```\n\nWait for user response before proceeding.\n\n### Step 2: Analyze & Present Findings\n\nOnce an area is determined:\n\n1. Read key files in that area (5-10 representative files)\n2. Look for patterns that are:\n   - **Unusual or unconventional** — Not standard framework/library patterns\n   - **Opinionated** — Specific choices that could have gone differently\n   - **Tribal** — Things a new developer wouldn't know without being told\n   - **Consistent** — Patterns repeated across multiple files\n\n3. Use AskUserQuestion to present findings and let user select:\n\n```\nI analyzed [area] and found these potential standards worth documenting:\n\n1. **API Response Envelope** — All responses use { success, data, error } structure\n2. **Error Codes** — Custom error codes like AUTH_001, DB_002 with specific meanings\n3. **Pagination Pattern** — Cursor-based pagination with consistent param names\n\nWhich would you like to document?\n\nOptions:\n- \"Yes, all of them\"\n- \"Just 1 and 3\"\n- \"Add: [your suggestion]\"\n- \"Skip this area\"\n```\n\nWait for user selection before proceeding.\n\n### Step 3: Ask Why, Then Draft Each Standard\n\n**IMPORTANT:** For each selected standard, you MUST complete this full loop before moving to the next standard:\n\n1. **Ask 1-2 clarifying questions** about the \"why\" behind the pattern. Use your AskUserQuestion tool for this.\n2. **Wait for user response**\n3. **Draft the standard** incorporating their answer\n4. **Confirm with user** before creating the file\n5. **Create the file** if approved\n\nExample questions to ask (adapt based on the specific standard):\n\n- \"What problem does this pattern solve? Why not use the default/common approach?\"\n- \"Are there exceptions where this pattern shouldn't be used?\"\n- \"What's the most common mistake a developer or agent makes with this?\"\n\n**Do NOT batch all questions upfront.** Process one standard at a time through the full loop.\n\n### Step 4: Create the Standard File\n\nFor each standard (after completing Step 3's Q&A):\n\n1. Determine the appropriate folder (create if needed):\n   - `api/`, `database/`, `javascript/`, `css/`, `backend/`, `testing/`, `global/`\n\n2. Check if a related standard file already exists — append to it if so\n\n3. Draft the content and use AskUserQuestion to confirm:\n\n```\nHere's the draft for api/response-format.md:\n\n---\n# API Response Format\n\nAll API responses use this envelope:\n\n\\`\\`\\`json\n{ \"success\": true, \"data\": { ... } }\n{ \"success\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }\n\\`\\`\\`\n\n- Never return raw data without the envelope\n- Error responses must include both code and message\n- Success responses omit the error field entirely\n---\n\nCreate this file? (yes / edit: [your changes] / skip)\n```\n\n4. Create or update the file in `agent-os/standards/[folder]/`\n5. **Then repeat Steps 3-4 for the next selected standard**\n\n### Step 5: Update the Index\n\nAfter all standards are created:\n\n1. Scan `agent-os/standards/` for all `.md` files\n2. For each new file without an index entry, use AskUserQuestion:\n\n```\nNew standard needs an index entry:\n  File: api/response-format.md\n\nSuggested description: \"API response envelope structure and error format\"\n\nAccept this description? (yes / or type a better one)\n```\n\n3. Update `agent-os/standards/index.yml`:\n\n```yaml\napi:\n  response-format:\n    description: API response envelope structure and error format\n```\n\nAlphabetize by folder, then by filename.\n\n### Step 6: Offer to Continue\n\nUse AskUserQuestion:\n\n```\nStandards created for [area]:\n- api/response-format.md\n- api/error-codes.md\n\nWould you like to discover standards in another area, or are we done?\n```\n\n## Output Location\n\nAll standards: `agent-os/standards/[folder]/[standard].md`\nIndex file: `agent-os/standards/index.yml`\n\n## Writing Concise Standards\n\nStandards will be injected into AI context windows. Every word costs tokens. Follow these rules:\n\n- **Lead with the rule** — State what to do first, explain why second (if needed)\n- **Use code examples** — Show, don't tell\n- **Skip the obvious** — Don't document what the code already makes clear\n- **One standard per concept** — Don't combine unrelated patterns\n- **Bullet points over paragraphs** — Scannable beats readable\n\n**Good:**\n```markdown\n# Error Responses\n\nUse error codes: `AUTH_001`, `DB_001`, `VAL_001`\n\n\\`\\`\\`json\n{ \"success\": false, \"error\": { \"code\": \"AUTH_001\", \"message\": \"...\" } }\n\\`\\`\\`\n\n- Always include both code and message\n- Log full error server-side, return safe message to client\n```\n\n**Bad:**\n```markdown\n# Error Handling Guidelines\n\nWhen an error occurs in our application, we have established a consistent pattern for how errors should be formatted and returned to the client. This helps maintain consistency across our API and makes it easier for frontend developers to handle errors appropriately...\n[continues for 3 more paragraphs]\n```\n\n## Example: Full Loop for One Standard\n\nHere's how to process a single standard through the complete workflow:\n\n**1. Present findings (Step 2):**\n```\nI found these patterns in your API code:\n1. **Response Envelope** — All responses use { success, data, error }\n2. **Error Codes** — Custom codes like AUTH_001\n\nWhich would you like to document?\n```\n\nUser: \"Both\"\n\n**2. Ask why for first standard (Step 3):**\n```\nFor the Response Envelope pattern:\n- What problem does this solve? Why not return raw data?\n- Are there any endpoints that don't use this pattern?\n```\n\nUser: \"We use it so the frontend always knows where to find the data. All endpoints use it, no exceptions.\"\n\n**3. Draft first standard (Step 3 continued):**\n```\nHere's the draft for api/response-envelope.md:\n\n---\n# Response Envelope\n\nAll API responses use this structure:\n\\`\\`\\`json\n{ \"success\": true, \"data\": { ... } }\n{ \"success\": false, \"error\": { ... } }\n\\`\\`\\`\n\n- Frontend always checks `success` first, then reads `data` or `error`\n- No exceptions — every endpoint uses this format\n---\n\nCreate this file?\n```\n\nUser: \"Yes\"\n\n**4. Create file, then move to next standard:**\n\n[Create the file]\n\n**5. Ask why for second standard (back to Step 3):**\n```\nFor the Error Codes pattern:\n- What's the naming convention for codes?\n- Where should new error codes be documented?\n```\n\nUser: \"Format is AREA_NUMBER like AUTH_001. We keep a list in the wiki.\"\n\n**6. Draft second standard, confirm, create file...**\n\n[Continue until all selected standards are done]\n\n**Key point:** Complete the full ask → draft → confirm → create cycle for each standard before starting the next one.\n","isInternal":false,"tokens":1899,"sizeBytes":7978},{"name":"index-standards.md","path":"commands/agent-os/index-standards.md","rawUrl":"https://raw.githubusercontent.com/buildermethods/agent-os/HEAD/commands/agent-os/index-standards.md","title":"Command: /index-standards","category":"command-prompt","format":"markdown","content":"# Index Standards\n\nRebuild and maintain the standards index file (`index.yml`).\n\n## Purpose\n\nThe index enables `/inject-standards` to suggest relevant standards without reading all files. It maps each standard to a brief description for quick matching.\n\n## Process\n\n### Step 1: Scan for Standards Files\n\n1. List all `.md` files in `agent-os/standards/` and its subfolders\n2. Build a list of all standards organized by folder:\n   ```\n   root/coding-style.md        # Files in standards/ root use \"root\" as the folder name\n   root/naming.md\n   api/response-format.md\n   api/error-handling.md\n   database/migrations.md\n   ```\n\n**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder). Do not create an actual folder named \"root\".\n\n### Step 2: Load Existing Index\n\nRead `agent-os/standards/index.yml` if it exists. Note which entries already have descriptions.\n\n### Step 3: Identify Changes\n\nCompare the file scan with the existing index:\n\n- **New files** — Standards files without index entries\n- **Deleted files** — Index entries for files that no longer exist\n- **Existing files** — Already indexed, keep as-is\n\n### Step 4: Handle New Files\n\nFor each new standard file that needs an index entry:\n\n1. Read the file to understand its content\n2. Use AskUserQuestion to propose a description:\n\n```\nNew standard needs indexing:\n  File: api/response-format.md\n\nSuggested description: \"API response envelope structure and error format\"\n\nAccept? (yes / or type a better description)\n```\n\nKeep descriptions to **one short sentence** — they're for matching, not documentation.\n\n### Step 5: Handle Deleted Files\n\nIf there are index entries for files that no longer exist:\n\n1. List them for the user\n2. Remove them from the index automatically (no confirmation needed)\n\nReport: \"Removed 2 stale index entries: api/old-pattern.md, testing/deprecated.md\"\n\n### Step 6: Write Updated Index\n\nGenerate `agent-os/standards/index.yml` with this structure:\n\n```yaml\nfolder-name:\n  file-name:\n    description: Brief description here\n```\n\n**Rules:**\n- Alphabetize folders\n- Alphabetize files within each folder\n- File names without `.md` extension\n- One-line descriptions only\n\n**Example:**\n```yaml\nroot:\n  coding-style:\n    description: General coding style, formatting, linting rules\n  naming:\n    description: File naming, variable naming, class naming conventions\n\napi:\n  error-handling:\n    description: Error codes, exception handling, error response format\n  response-format:\n    description: API response envelope structure, status codes, pagination\n\ndatabase:\n  migrations:\n    description: Migration file structure, naming conventions, rollback patterns\n```\n\n**Note:** `root` appears first and contains standards files that live directly in `agent-os/standards/` (not in subfolders).\n\n### Step 7: Report Results\n\nSummarize what changed:\n\n```\nIndex updated:\n  ✓ 2 new entries added\n  ✓ 1 stale entry removed\n  ✓ 8 entries unchanged\n\nTotal: 9 standards indexed\n```\n\n## When to Run\n\n- After manually creating or deleting standards files\n- If `/inject-standards` suggestions seem out of sync\n- To clean up a messy or outdated index\n\n**Note:** `/discover-standards` runs this automatically as its final step, so you usually don't need to call it separately after discovering standards.\n\n## Output\n\nUpdates `agent-os/standards/index.yml`\n","isInternal":false,"tokens":779,"sizeBytes":3398},{"name":"inject-standards.md","path":"commands/agent-os/inject-standards.md","rawUrl":"https://raw.githubusercontent.com/buildermethods/agent-os/HEAD/commands/agent-os/inject-standards.md","title":"Command: /inject-standards","category":"command-prompt","format":"markdown","content":"# Inject Standards\n\nInject relevant standards into the current context, formatted appropriately for the situation.\n\n## Usage Modes\n\nThis command supports two modes:\n\n### Auto-Suggest Mode (no arguments)\n```\n/inject-standards\n```\nAnalyzes context and suggests relevant standards.\n\n### Explicit Mode (with arguments)\n```\n/inject-standards api                           # All standards in api/\n/inject-standards api/response-format           # Single file\n/inject-standards api/response-format api/auth  # Multiple files\n/inject-standards root                          # All standards in the root folder\n/inject-standards root/naming                   # Single file from root folder\n```\nDirectly injects specified standards without suggestions.\n\n**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder).\n\n## Process\n\n### Step 1: Detect Context Scenario\n\nBefore injecting standards, determine which scenario we're in. Read the current conversation and check if we're in plan mode.\n\n**Three scenarios:**\n\n1. **Conversation** — Regular chat, implementing code, answering questions\n2. **Creating a Skill** — Building a `.claude/skills/` file\n3. **Shaping/Planning** — In plan mode, building a spec, running `/shape-spec`\n\n**Detection logic:**\n\n- If currently in plan mode OR conversation clearly mentions \"spec\", \"plan\", \"shape\" → **Shaping/Planning**\n- If conversation clearly mentions creating a skill, editing `.claude/skills/`, or building a reusable procedure → **Creating a Skill**\n- Otherwise → **Ask to confirm** (do not assume)\n\n**If neither skill nor plan is clearly detected**, use AskUserQuestion to confirm:\n\n```\nI'll inject the relevant standards. How should I format them?\n\n1. **Conversation** — Read standards into our chat (for implementation work)\n2. **Skill** — Output file references to include in a skill you're building\n3. **Plan** — Output file references to include in a plan/spec\n\nWhich scenario? (1, 2, or 3)\n```\n\nAlways ask when uncertain — don't assume conversation by default.\n\n### Step 2: Read the Index (Auto-Suggest Mode)\n\nRead `agent-os/standards/index.yml` to get the list of available standards and their descriptions.\n\nIf index.yml doesn't exist or is empty:\n```\nNo standards index found. Run /discover-standards first to create standards,\nor /index-standards if you have standards files without an index.\n```\n\n### Step 3: Analyze Work Context\n\nLook at the current conversation to understand what the user is working on:\n- What type of work? (API, database, UI, etc.)\n- What technologies mentioned?\n- What's the goal?\n\n### Step 4: Match and Suggest\n\nMatch index descriptions against the context. Use AskUserQuestion to present suggestions:\n\n```\nBased on your task, these standards may be relevant:\n\n1. **api/response-format** — API response envelope structure, status codes\n2. **api/error-handling** — Error codes, exception handling, error responses\n3. **global/naming** — File naming, variable naming conventions\n\nInject these standards? (yes / just 1 and 3 / add: database/migrations / none)\n```\n\nKeep suggestions focused — typically 2-5 standards. Don't overwhelm with too many options.\n\n### Step 5: Inject Based on Scenario\n\nFormat the output differently based on the detected scenario:\n\n---\n\n#### Scenario: Conversation\n\nRead the standards and announce them:\n\n```\nI've read the following standards as they are relevant to what we're working on:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n**Key points:**\n- All API responses use { success, data, error } envelope\n- Error codes follow AUTH_xxx, DB_xxx pattern\n```\n\n---\n\n#### Scenario: Creating a Skill\n\nFirst, use AskUserQuestion to determine how to include the standards:\n\n```\nHow should these standards be included in your skill?\n\n1. **References** — Add @ file paths that point to the standards (keeps skill lightweight, standards stay in sync)\n2. **Copy content** — Paste the full standards content into the skill (self-contained, but won't update if standards change)\n\nWhich approach? (1 or 2)\n```\n\n**If References (option 1):**\n\n```\nBe sure to include references to the following standards files in the appropriate location in the file(s) that make up this skill:\n\n@agent-os/standards/api/response-format.md\n@agent-os/standards/api/error-handling.md\n@agent-os/standards/global/naming.md\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n**If Copy content (option 2):**\n\n```\nInclude the following standards content in your skill:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n---\n\n#### Scenario: Shaping/Planning\n\nFirst, use AskUserQuestion to determine how to include the standards:\n\n```\nHow should these standards be included in your plan?\n\n1. **References** — Add @ file paths that point to the standards (keeps plan lightweight, standards stay in sync)\n2. **Copy content** — Paste the full standards content into the plan (self-contained, but won't update if standards change)\n\nWhich approach? (1 or 2)\n```\n\n**If References (option 1):**\n\n```\nBe sure to include references to the following standards files in the appropriate location in the plan we're building:\n\n@agent-os/standards/api/response-format.md\n@agent-os/standards/api/error-handling.md\n@agent-os/standards/global/naming.md\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n**If Copy content (option 2):**\n\n```\nInclude the following standards content in your plan:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n---\n\n### Step 6: Surface Related Skills (Conversation scenario only)\n\nWhen in conversation scenario, check if `.claude/skills/` exists and contains related skills:\n\n```\nRelated Skills you might want to use:\n- create-api-endpoint — Scaffolds new API endpoints following these standards\n```\n\nDon't invoke skills automatically — just surface them for awareness.\n\n---\n\n## Explicit Mode\n\nWhen arguments are provided, skip the suggestion step but still detect scenario.\n\n### Step 1: Detect Scenario\n\nSame as auto-suggest mode.\n\n### Step 2: Parse Arguments\n\nArguments can be:\n- **Folder name** — `api` → inject all `.md` files in `agent-os/standards/api/`\n- **Folder/file** — `api/response-format` → inject `agent-os/standards/api/response-format.md`\n- **Root folder** — `root` → inject all `.md` files directly in `agent-os/standards/` (not in subfolders)\n- **Root file** — `root/naming` → inject `agent-os/standards/naming.md`\n\nMultiple arguments inject multiple standards.\n\n### Step 3: Validate\n\nCheck that specified files/folders exist. If not:\n\n```\nStandard not found: api/nonexistent\n\nAvailable standards in api/:\n- response-format\n- error-handling\n- authentication\n\nDid you mean one of these?\n```\n\n### Step 4: Inject Based on Scenario\n\nSame formatting as auto-suggest mode, based on detected scenario.\n\n---\n\n## Tips\n\n- **Run early** — Inject standards at the start of a task, before implementation\n- **Be specific** — If you know which standards apply, use explicit mode\n- **Check the index** — If suggestions seem wrong, run `/index-standards` to rebuild\n- **Keep standards concise** — Injected standards consume tokens; shorter is better\n\n## Integration\n\nThis command is called internally by `/shape-spec` to inject relevant standards during planning. You can also invoke it directly anytime you need standards in context.\n","isInternal":false,"tokens":1862,"sizeBytes":8354},{"name":"plan-product.md","path":"commands/agent-os/plan-product.md","rawUrl":"https://raw.githubusercontent.com/buildermethods/agent-os/HEAD/commands/agent-os/plan-product.md","title":"Command: /plan-product","category":"command-prompt","format":"markdown","content":"# Plan Product\n\nEstablish foundational product documentation through an interactive conversation. Creates mission, roadmap, and tech stack files in `agent-os/product/`.\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Keep it lightweight** — gather enough to create useful docs without over-documenting\n- **One question at a time** — don't overwhelm with multiple questions\n\n## Process\n\n### Step 1: Check for Existing Product Docs\n\nCheck if `agent-os/product/` exists and contains any of these files:\n- `mission.md`\n- `roadmap.md`\n- `tech-stack.md`\n\n**If any files exist**, use AskUserQuestion:\n\n```\nI found existing product documentation:\n- mission.md: [exists/missing]\n- roadmap.md: [exists/missing]\n- tech-stack.md: [exists/missing]\n\nWould you like to:\n1. Start fresh (replace all)\n2. Update specific files\n3. Cancel\n\n(Choose 1, 2, or 3)\n```\n\nIf option 2, ask which files to update and only gather info for those.\nIf option 3, stop here.\n\n**If no files exist**, proceed to Step 2.\n\n### Step 2: Gather Product Vision (for mission.md)\n\nUse AskUserQuestion:\n\n```\nLet's define your product's mission.\n\n**What problem does this product solve?**\n\n(Describe the core problem or pain point you're addressing)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**Who is this product for?**\n\n(Describe your target users or audience)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**What makes your solution unique?**\n\n(What's the key differentiator or approach?)\n```\n\n### Step 3: Gather Roadmap (for roadmap.md)\n\nUse AskUserQuestion:\n\n```\nNow let's outline your development roadmap.\n\n**What are the must-have features for launch (MVP)?**\n\n(List the core features needed for the first usable version)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**What features are planned for after launch?**\n\n(List features you'd like to add in future phases, or say \"none yet\")\n```\n\n### Step 4: Establish Tech Stack (for tech-stack.md)\n\nFirst, check if `agent-os/standards/global/tech-stack.md` exists.\n\n**If the tech-stack standard exists**, read it and use AskUserQuestion:\n\n```\nI found a tech stack standard in your standards:\n\n[Summarize the key technologies from global/tech-stack.md]\n\nDoes this project use the same tech stack, or does it differ?\n\n1. Same as standard (use as-is)\n2. Different (I'll specify)\n\n(Choose 1 or 2)\n```\n\nIf they choose option 1, use the standard's content for tech-stack.md.\nIf they choose option 2, proceed to ask them to specify (see below).\n\n**If no tech-stack standard exists** (or they chose option 2 above), use AskUserQuestion:\n\n```\n**What technologies does this project use?**\n\nPlease describe your tech stack:\n- Frontend: (e.g., React, Vue, vanilla JS, or N/A)\n- Backend: (e.g., Rails, Node, Django, or N/A)\n- Database: (e.g., PostgreSQL, MongoDB, or N/A)\n- Other: (hosting, APIs, tools, etc.)\n```\n\n### Step 5: Generate Files\n\nCreate the `agent-os/product/` directory if it doesn't exist.\n\nGenerate each file based on the information gathered:\n\n#### mission.md\n\n```markdown\n# Product Mission\n\n## Problem\n\n[Insert what problem this product solves - from Step 2]\n\n## Target Users\n\n[Insert who this product is for - from Step 2]\n\n## Solution\n\n[Insert what makes the solution unique - from Step 2]\n```\n\n#### roadmap.md\n\n```markdown\n# Product Roadmap\n\n## Phase 1: MVP\n\n[Insert must-have features for launch - from Step 3]\n\n## Phase 2: Post-Launch\n\n[Insert planned future features - from Step 3, or \"To be determined\" if they said none yet]\n```\n\n#### tech-stack.md\n\n```markdown\n# Tech Stack\n\n[Organize the tech stack information into logical sections]\n\n## Frontend\n\n[Frontend technologies, or \"N/A\" if not applicable]\n\n## Backend\n\n[Backend technologies, or \"N/A\" if not applicable]\n\n## Database\n\n[Database choice, or \"N/A\" if not applicable]\n\n## Other\n\n[Other tools, hosting, services - or omit this section if nothing mentioned]\n```\n\n### Step 6: Confirm Completion\n\nAfter creating all files, output to user:\n\n```\n✓ Product documentation created:\n\n  agent-os/product/mission.md\n  agent-os/product/roadmap.md\n  agent-os/product/tech-stack.md\n\nReview these files to ensure they accurately capture your product vision.\nYou can edit them directly or run /plan-product again to update.\n```\n\n## Tips\n\n- If the user provides very brief answers, that's fine — the docs can be expanded later\n- If they want to skip a section, create the file with a placeholder like \"To be defined\"\n- The `/shape-spec` command will read these files when planning features, so having them populated helps with context\n","isInternal":false,"tokens":1111,"sizeBytes":4572},{"name":"shape-spec.md","path":"commands/agent-os/shape-spec.md","rawUrl":"https://raw.githubusercontent.com/buildermethods/agent-os/HEAD/commands/agent-os/shape-spec.md","title":"Command: /shape-spec","category":"command-prompt","format":"markdown","content":"# Shape Spec\n\nGather context and structure planning for significant work. **Run this command while in plan mode.**\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Offer suggestions** — Present options the user can confirm, adjust, or correct\n- **Keep it lightweight** — This is shaping, not exhaustive documentation\n\n## Prerequisites\n\nThis command **must be run in plan mode**.\n\n**Before proceeding, check if you are currently in plan mode.**\n\nIf NOT in plan mode, **stop immediately** and tell the user:\n\n```\nShape-spec must be run in plan mode. Please enter plan mode first, then run /shape-spec again.\n```\n\nDo not proceed with any steps below until confirmed to be in plan mode.\n\n## Process\n\n### Step 1: Clarify What We're Building\n\nUse AskUserQuestion to understand the scope:\n\n```\nWhat are we building? Please describe the feature or change.\n\n(Be as specific as you like — I'll ask follow-up questions if needed)\n```\n\nBased on their response, ask 1-2 clarifying questions if the scope is unclear. Examples:\n- \"Is this a new feature or a change to existing functionality?\"\n- \"What's the expected outcome when this is done?\"\n- \"Are there any constraints or requirements I should know about?\"\n\n### Step 2: Gather Visuals\n\nUse AskUserQuestion:\n\n```\nDo you have any visuals to reference?\n\n- Mockups or wireframes\n- Screenshots of similar features\n- Examples from other apps\n\n(Paste images, share file paths, or say \"none\")\n```\n\nIf visuals are provided, note them for inclusion in the spec folder.\n\n### Step 3: Identify Reference Implementations\n\nUse AskUserQuestion:\n\n```\nIs there similar code in this codebase I should reference?\n\nExamples:\n- \"The comments feature is similar to what we're building\"\n- \"Look at how src/features/notifications/ handles real-time updates\"\n- \"No existing references\"\n\n(Point me to files, folders, or features to study)\n```\n\nIf references are provided, read and analyze them to inform the plan.\n\n### Step 4: Check Product Context\n\nCheck if `agent-os/product/` exists and contains files.\n\nIf it exists, read key files (like `mission.md`, `roadmap.md`, `tech-stack.md`) and use AskUserQuestion:\n\n```\nI found product context in agent-os/product/. Should this feature align with any specific product goals or constraints?\n\nKey points from your product docs:\n- [summarize relevant points]\n\n(Confirm alignment or note any adjustments)\n```\n\nIf no product folder exists, skip this step.\n\n### Step 5: Surface Relevant Standards\n\nRead `agent-os/standards/index.yml` to identify relevant standards based on the feature being built.\n\nUse AskUserQuestion to confirm:\n\n```\nBased on what we're building, these standards may apply:\n\n1. **api/response-format** — API response envelope structure\n2. **api/error-handling** — Error codes and exception handling\n3. **database/migrations** — Migration patterns\n\nShould I include these in the spec? (yes / adjust: remove 3, add frontend/forms)\n```\n\nRead the confirmed standards files to include their content in the plan context.\n\n### Step 6: Generate Spec Folder Name\n\nCreate a folder name using this format:\n```\nYYYY-MM-DD-HHMM-{feature-slug}/\n```\n\nWhere:\n- Date/time is current timestamp\n- Feature slug is derived from the feature description (lowercase, hyphens, max 40 chars)\n\nExample: `2026-01-15-1430-user-comment-system/`\n\n**Note:** If `agent-os/specs/` doesn't exist, create it when saving the spec folder.\n\n### Step 7: Structure the Plan\n\nNow build the plan with **Task 1 always being \"Save spec documentation\"**.\n\nPresent this structure to the user:\n\n```\nHere's the plan structure. Task 1 saves all our shaping work before implementation begins.\n\n---\n\n## Task 1: Save Spec Documentation\n\nCreate `agent-os/specs/{folder-name}/` with:\n\n- **plan.md** — This full plan\n- **shape.md** — Shaping notes (scope, decisions, context from our conversation)\n- **standards.md** — Relevant standards that apply to this work\n- **references.md** — Pointers to reference implementations studied\n- **visuals/** — Any mockups or screenshots provided\n\n## Task 2: [First implementation task]\n\n[Description based on the feature]\n\n## Task 3: [Next task]\n\n...\n\n---\n\nDoes this plan structure look right? I'll fill in the implementation tasks next.\n```\n\n### Step 8: Complete the Plan\n\nAfter Task 1 is confirmed, continue building out the remaining implementation tasks based on:\n- The feature scope from Step 1\n- Patterns from reference implementations (Step 3)\n- Constraints from standards (Step 5)\n\nEach task should be specific and actionable.\n\n### Step 9: Ready for Execution\n\nWhen the full plan is ready:\n\n```\nPlan complete. When you approve and execute:\n\n1. Task 1 will save all spec documentation first\n2. Then implementation tasks will proceed\n\nReady to start? (approve / adjust)\n```\n\n## Output Structure\n\nThe spec folder will contain:\n\n```\nagent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/\n├── plan.md           # The full plan\n├── shape.md          # Shaping decisions and context\n├── standards.md      # Which standards apply and key points\n├── references.md     # Pointers to similar code\n└── visuals/          # Mockups, screenshots (if any)\n```\n\n## shape.md Content\n\nThe shape.md file should capture:\n\n```markdown\n# {Feature Name} — Shaping Notes\n\n## Scope\n\n[What we're building, from Step 1]\n\n## Decisions\n\n- [Key decisions made during shaping]\n- [Constraints or requirements noted]\n\n## Context\n\n- **Visuals:** [List of visuals provided, or \"None\"]\n- **References:** [Code references studied]\n- **Product alignment:** [Notes from product context, or \"N/A\"]\n\n## Standards Applied\n\n- api/response-format — [why it applies]\n- api/error-handling — [why it applies]\n```\n\n## standards.md Content\n\nInclude the full content of each relevant standard:\n\n```markdown\n# Standards for {Feature Name}\n\nThe following standards apply to this work.\n\n---\n\n## api/response-format\n\n[Full content of the standard file]\n\n---\n\n## api/error-handling\n\n[Full content of the standard file]\n```\n\n## references.md Content\n\n```markdown\n# References for {Feature Name}\n\n## Similar Implementations\n\n### {Reference 1 name}\n\n- **Location:** `src/features/comments/`\n- **Relevance:** [Why this is relevant]\n- **Key patterns:** [What to borrow from this]\n\n### {Reference 2 name}\n\n...\n```\n\n## Tips\n\n- **Keep shaping fast** — Don't over-document. Capture enough to start, refine as you build.\n- **Visuals are optional** — Not every feature needs mockups.\n- **Standards guide, not dictate** — They inform the plan but aren't always mandatory.\n- **Specs are discoverable** — Months later, someone can find this spec and understand what was built and why.\n","isInternal":false,"tokens":1539,"sizeBytes":6684}],"systemPromptSnippet":"<yakaai_skills repo=\"buildermethods/agent-os\">\n<!-- File: commands/agent-os/discover-standards.md (Tokens: ~1899 | Category: command-prompt) -->\n# Discover Standards\n\nExtract tribal knowledge from your codebase into concise, documented standards.\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Write concise standards** — Use minimal words. Standards must be scannable by AI agents without bloating context windows.\n- **Offer suggestions** — Present options the user can confirm, choose between, or correct. Don't make them think harder than necessary.\n\n## Process\n\n### Step 1: Determine Focus Area\n\nCheck if the user specified an area when running this command. If they did, skip to Step 2.\n\nIf no area was specified:\n\n1. Analyze the codebase structure (folders, file types, patterns)\n2. Identify 3-5 major areas. Examples:\n   - **Frontend areas:** UI components, styling/CSS, state management, forms, routing\n   - **Backend areas:** API routes, database/models, authentication, background jobs\n   - **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure\n3. Use AskUserQuestion to present the areas:\n\n```\nI've identified these areas in your codebase:\n\n1. **API Routes** (src/api/) — Request handling, response formats\n2. **Database** (src/models/, src/db/) — Models, queries, migrations\n3. **React Components** (src/components/) — UI patterns, props, state\n4. **Authentication** (src/auth/) — Login, sessions, permissions\n\nWhich area should we focus on for discovering standards? (Pick one, or suggest a different area)\n```\n\nWait for user response before proceeding.\n\n### Step 2: Analyze & Present Findings\n\nOnce an area is determined:\n\n1. Read key files in that area (5-10 representative files)\n2. Look for patterns that are:\n   - **Unusual or unconventional** — Not standard framework/library patterns\n   - **Opinionated** — Specific choices that could have gone differently\n   - **Tribal** — Things a new developer wouldn't know without being told\n   - **Consistent** — Patterns repeated across multiple files\n\n3. Use AskUserQuestion to present findings and let user select:\n\n```\nI analyzed [area] and found these potential standards worth documenting:\n\n1. **API Response Envelope** — All responses use { success, data, error } structure\n2. **Error Codes** — Custom error codes like AUTH_001, DB_002 with specific meanings\n3. **Pagination Pattern** — Cursor-based pagination with consistent param names\n\nWhich would you like to document?\n\nOptions:\n- \"Yes, all of them\"\n- \"Just 1 and 3\"\n- \"Add: [your suggestion]\"\n- \"Skip this area\"\n```\n\nWait for user selection before proceeding.\n\n### Step 3: Ask Why, Then Draft Each Standard\n\n**IMPORTANT:** For each selected standard, you MUST complete this full loop before moving to the next standard:\n\n1. **Ask 1-2 clarifying questions** about the \"why\" behind the pattern. Use your AskUserQuestion tool for this.\n2. **Wait for user response**\n3. **Draft the standard** incorporating their answer\n4. **Confirm with user** before creating the file\n5. **Create the file** if approved\n\nExample questions to ask (adapt based on the specific standard):\n\n- \"What problem does this pattern solve? Why not use the default/common approach?\"\n- \"Are there exceptions where this pattern shouldn't be used?\"\n- \"What's the most common mistake a developer or agent makes with this?\"\n\n**Do NOT batch all questions upfront.** Process one standard at a time through the full loop.\n\n### Step 4: Create the Standard File\n\nFor each standard (after completing Step 3's Q&A):\n\n1. Determine the appropriate folder (create if needed):\n   - `api/`, `database/`, `javascript/`, `css/`, `backend/`, `testing/`, `global/`\n\n2. Check if a related standard file already exists — append to it if so\n\n3. Draft the content and use AskUserQuestion to confirm:\n\n```\nHere's the draft for api/response-format.md:\n\n---\n# API Response Format\n\nAll API responses use this envelope:\n\n\\`\\`\\`json\n{ \"success\": true, \"data\": { ... } }\n{ \"success\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }\n\\`\\`\\`\n\n- Never return raw data without the envelope\n- Error responses must include both code and message\n- Success responses omit the error field entirely\n---\n\nCreate this file? (yes / edit: [your changes] / skip)\n```\n\n4. Create or update the file in `agent-os/standards/[folder]/`\n5. **Then repeat Steps 3-4 for the next selected standard**\n\n### Step 5: Update the Index\n\nAfter all standards are created:\n\n1. Scan `agent-os/standards/` for all `.md` files\n2. For each new file without an index entry, use AskUserQuestion:\n\n```\nNew standard needs an index entry:\n  File: api/response-format.md\n\nSuggested description: \"API response envelope structure and error format\"\n\nAccept this description? (yes / or type a better one)\n```\n\n3. Update `agent-os/standards/index.yml`:\n\n```yaml\napi:\n  response-format:\n    description: API response envelope structure and error format\n```\n\nAlphabetize by folder, then by filename.\n\n### Step 6: Offer to Continue\n\nUse AskUserQuestion:\n\n```\nStandards created for [area]:\n- api/response-format.md\n- api/error-codes.md\n\nWould you like to discover standards in another area, or are we done?\n```\n\n## Output Location\n\nAll standards: `agent-os/standards/[folder]/[standard].md`\nIndex file: `agent-os/standards/index.yml`\n\n## Writing Concise Standards\n\nStandards will be injected into AI context windows. Every word costs tokens. Follow these rules:\n\n- **Lead with the rule** — State what to do first, explain why second (if needed)\n- **Use code examples** — Show, don't tell\n- **Skip the obvious** — Don't document what the code already makes clear\n- **One standard per concept** — Don't combine unrelated patterns\n- **Bullet points over paragraphs** — Scannable beats readable\n\n**Good:**\n```markdown\n# Error Responses\n\nUse error codes: `AUTH_001`, `DB_001`, `VAL_001`\n\n\\`\\`\\`json\n{ \"success\": false, \"error\": { \"code\": \"AUTH_001\", \"message\": \"...\" } }\n\\`\\`\\`\n\n- Always include both code and message\n- Log full error server-side, return safe message to client\n```\n\n**Bad:**\n```markdown\n# Error Handling Guidelines\n\nWhen an error occurs in our application, we have established a consistent pattern for how errors should be formatted and returned to the client. This helps maintain consistency across our API and makes it easier for frontend developers to handle errors appropriately...\n[continues for 3 more paragraphs]\n```\n\n## Example: Full Loop for One Standard\n\nHere's how to process a single standard through the complete workflow:\n\n**1. Present findings (Step 2):**\n```\nI found these patterns in your API code:\n1. **Response Envelope** — All responses use { success, data, error }\n2. **Error Codes** — Custom codes like AUTH_001\n\nWhich would you like to document?\n```\n\nUser: \"Both\"\n\n**2. Ask why for first standard (Step 3):**\n```\nFor the Response Envelope pattern:\n- What problem does this solve? Why not return raw data?\n- Are there any endpoints that don't use this pattern?\n```\n\nUser: \"We use it so the frontend always knows where to find the data. All endpoints use it, no exceptions.\"\n\n**3. Draft first standard (Step 3 continued):**\n```\nHere's the draft for api/response-envelope.md:\n\n---\n# Response Envelope\n\nAll API responses use this structure:\n\\`\\`\\`json\n{ \"success\": true, \"data\": { ... } }\n{ \"success\": false, \"error\": { ... } }\n\\`\\`\\`\n\n- Frontend always checks `success` first, then reads `data` or `error`\n- No exceptions — every endpoint uses this format\n---\n\nCreate this file?\n```\n\nUser: \"Yes\"\n\n**4. Create file, then move to next standard:**\n\n[Create the file]\n\n**5. Ask why for second standard (back to Step 3):**\n```\nFor the Error Codes pattern:\n- What's the naming convention for codes?\n- Where should new error codes be documented?\n```\n\nUser: \"Format is AREA_NUMBER like AUTH_001. We keep a list in the wiki.\"\n\n**6. Draft second standard, confirm, create file...**\n\n[Continue until all selected standards are done]\n\n**Key point:** Complete the full ask → draft → confirm → create cycle for each standard before starting the next one.\n\n<!-- File: commands/agent-os/index-standards.md (Tokens: ~779 | Category: command-prompt) -->\n# Index Standards\n\nRebuild and maintain the standards index file (`index.yml`).\n\n## Purpose\n\nThe index enables `/inject-standards` to suggest relevant standards without reading all files. It maps each standard to a brief description for quick matching.\n\n## Process\n\n### Step 1: Scan for Standards Files\n\n1. List all `.md` files in `agent-os/standards/` and its subfolders\n2. Build a list of all standards organized by folder:\n   ```\n   root/coding-style.md        # Files in standards/ root use \"root\" as the folder name\n   root/naming.md\n   api/response-format.md\n   api/error-handling.md\n   database/migrations.md\n   ```\n\n**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder). Do not create an actual folder named \"root\".\n\n### Step 2: Load Existing Index\n\nRead `agent-os/standards/index.yml` if it exists. Note which entries already have descriptions.\n\n### Step 3: Identify Changes\n\nCompare the file scan with the existing index:\n\n- **New files** — Standards files without index entries\n- **Deleted files** — Index entries for files that no longer exist\n- **Existing files** — Already indexed, keep as-is\n\n### Step 4: Handle New Files\n\nFor each new standard file that needs an index entry:\n\n1. Read the file to understand its content\n2. Use AskUserQuestion to propose a description:\n\n```\nNew standard needs indexing:\n  File: api/response-format.md\n\nSuggested description: \"API response envelope structure and error format\"\n\nAccept? (yes / or type a better description)\n```\n\nKeep descriptions to **one short sentence** — they're for matching, not documentation.\n\n### Step 5: Handle Deleted Files\n\nIf there are index entries for files that no longer exist:\n\n1. List them for the user\n2. Remove them from the index automatically (no confirmation needed)\n\nReport: \"Removed 2 stale index entries: api/old-pattern.md, testing/deprecated.md\"\n\n### Step 6: Write Updated Index\n\nGenerate `agent-os/standards/index.yml` with this structure:\n\n```yaml\nfolder-name:\n  file-name:\n    description: Brief description here\n```\n\n**Rules:**\n- Alphabetize folders\n- Alphabetize files within each folder\n- File names without `.md` extension\n- One-line descriptions only\n\n**Example:**\n```yaml\nroot:\n  coding-style:\n    description: General coding style, formatting, linting rules\n  naming:\n    description: File naming, variable naming, class naming conventions\n\napi:\n  error-handling:\n    description: Error codes, exception handling, error response format\n  response-format:\n    description: API response envelope structure, status codes, pagination\n\ndatabase:\n  migrations:\n    description: Migration file structure, naming conventions, rollback patterns\n```\n\n**Note:** `root` appears first and contains standards files that live directly in `agent-os/standards/` (not in subfolders).\n\n### Step 7: Report Results\n\nSummarize what changed:\n\n```\nIndex updated:\n  ✓ 2 new entries added\n  ✓ 1 stale entry removed\n  ✓ 8 entries unchanged\n\nTotal: 9 standards indexed\n```\n\n## When to Run\n\n- After manually creating or deleting standards files\n- If `/inject-standards` suggestions seem out of sync\n- To clean up a messy or outdated index\n\n**Note:** `/discover-standards` runs this automatically as its final step, so you usually don't need to call it separately after discovering standards.\n\n## Output\n\nUpdates `agent-os/standards/index.yml`\n\n<!-- File: commands/agent-os/inject-standards.md (Tokens: ~1862 | Category: command-prompt) -->\n# Inject Standards\n\nInject relevant standards into the current context, formatted appropriately for the situation.\n\n## Usage Modes\n\nThis command supports two modes:\n\n### Auto-Suggest Mode (no arguments)\n```\n/inject-standards\n```\nAnalyzes context and suggests relevant standards.\n\n### Explicit Mode (with arguments)\n```\n/inject-standards api                           # All standards in api/\n/inject-standards api/response-format           # Single file\n/inject-standards api/response-format api/auth  # Multiple files\n/inject-standards root                          # All standards in the root folder\n/inject-standards root/naming                   # Single file from root folder\n```\nDirectly injects specified standards without suggestions.\n\n**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder).\n\n## Process\n\n### Step 1: Detect Context Scenario\n\nBefore injecting standards, determine which scenario we're in. Read the current conversation and check if we're in plan mode.\n\n**Three scenarios:**\n\n1. **Conversation** — Regular chat, implementing code, answering questions\n2. **Creating a Skill** — Building a `.claude/skills/` file\n3. **Shaping/Planning** — In plan mode, building a spec, running `/shape-spec`\n\n**Detection logic:**\n\n- If currently in plan mode OR conversation clearly mentions \"spec\", \"plan\", \"shape\" → **Shaping/Planning**\n- If conversation clearly mentions creating a skill, editing `.claude/skills/`, or building a reusable procedure → **Creating a Skill**\n- Otherwise → **Ask to confirm** (do not assume)\n\n**If neither skill nor plan is clearly detected**, use AskUserQuestion to confirm:\n\n```\nI'll inject the relevant standards. How should I format them?\n\n1. **Conversation** — Read standards into our chat (for implementation work)\n2. **Skill** — Output file references to include in a skill you're building\n3. **Plan** — Output file references to include in a plan/spec\n\nWhich scenario? (1, 2, or 3)\n```\n\nAlways ask when uncertain — don't assume conversation by default.\n\n### Step 2: Read the Index (Auto-Suggest Mode)\n\nRead `agent-os/standards/index.yml` to get the list of available standards and their descriptions.\n\nIf index.yml doesn't exist or is empty:\n```\nNo standards index found. Run /discover-standards first to create standards,\nor /index-standards if you have standards files without an index.\n```\n\n### Step 3: Analyze Work Context\n\nLook at the current conversation to understand what the user is working on:\n- What type of work? (API, database, UI, etc.)\n- What technologies mentioned?\n- What's the goal?\n\n### Step 4: Match and Suggest\n\nMatch index descriptions against the context. Use AskUserQuestion to present suggestions:\n\n```\nBased on your task, these standards may be relevant:\n\n1. **api/response-format** — API response envelope structure, status codes\n2. **api/error-handling** — Error codes, exception handling, error responses\n3. **global/naming** — File naming, variable naming conventions\n\nInject these standards? (yes / just 1 and 3 / add: database/migrations / none)\n```\n\nKeep suggestions focused — typically 2-5 standards. Don't overwhelm with too many options.\n\n### Step 5: Inject Based on Scenario\n\nFormat the output differently based on the detected scenario:\n\n---\n\n#### Scenario: Conversation\n\nRead the standards and announce them:\n\n```\nI've read the following standards as they are relevant to what we're working on:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n**Key points:**\n- All API responses use { success, data, error } envelope\n- Error codes follow AUTH_xxx, DB_xxx pattern\n```\n\n---\n\n#### Scenario: Creating a Skill\n\nFirst, use AskUserQuestion to determine how to include the standards:\n\n```\nHow should these standards be included in your skill?\n\n1. **References** — Add @ file paths that point to the standards (keeps skill lightweight, standards stay in sync)\n2. **Copy content** — Paste the full standards content into the skill (self-contained, but won't update if standards change)\n\nWhich approach? (1 or 2)\n```\n\n**If References (option 1):**\n\n```\nBe sure to include references to the following standards files in the appropriate location in the file(s) that make up this skill:\n\n@agent-os/standards/api/response-format.md\n@agent-os/standards/api/error-handling.md\n@agent-os/standards/global/naming.md\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n**If Copy content (option 2):**\n\n```\nInclude the following standards content in your skill:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n---\n\n#### Scenario: Shaping/Planning\n\nFirst, use AskUserQuestion to determine how to include the standards:\n\n```\nHow should these standards be included in your plan?\n\n1. **References** — Add @ file paths that point to the standards (keeps plan lightweight, standards stay in sync)\n2. **Copy content** — Paste the full standards content into the plan (self-contained, but won't update if standards change)\n\nWhich approach? (1 or 2)\n```\n\n**If References (option 1):**\n\n```\nBe sure to include references to the following standards files in the appropriate location in the plan we're building:\n\n@agent-os/standards/api/response-format.md\n@agent-os/standards/api/error-handling.md\n@agent-os/standards/global/naming.md\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n**If Copy content (option 2):**\n\n```\nInclude the following standards content in your plan:\n\n--- Standard: api/response-format ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\n--- Standard: api/error-handling ---\n\n[full content of the standard file]\n\n--- End Standard ---\n\nThese standards cover:\n- API response envelope structure, status codes\n- Error codes, exception handling, error responses\n- File naming, variable naming conventions\n```\n\n---\n\n### Step 6: Surface Related Skills (Conversation scenario only)\n\nWhen in conversation scenario, check if `.claude/skills/` exists and contains related skills:\n\n```\nRelated Skills you might want to use:\n- create-api-endpoint — Scaffolds new API endpoints following these standards\n```\n\nDon't invoke skills automatically — just surface them for awareness.\n\n---\n\n## Explicit Mode\n\nWhen arguments are provided, skip the suggestion step but still detect scenario.\n\n### Step 1: Detect Scenario\n\nSame as auto-suggest mode.\n\n### Step 2: Parse Arguments\n\nArguments can be:\n- **Folder name** — `api` → inject all `.md` files in `agent-os/standards/api/`\n- **Folder/file** — `api/response-format` → inject `agent-os/standards/api/response-format.md`\n- **Root folder** — `root` → inject all `.md` files directly in `agent-os/standards/` (not in subfolders)\n- **Root file** — `root/naming` → inject `agent-os/standards/naming.md`\n\nMultiple arguments inject multiple standards.\n\n### Step 3: Validate\n\nCheck that specified files/folders exist. If not:\n\n```\nStandard not found: api/nonexistent\n\nAvailable standards in api/:\n- response-format\n- error-handling\n- authentication\n\nDid you mean one of these?\n```\n\n### Step 4: Inject Based on Scenario\n\nSame formatting as auto-suggest mode, based on detected scenario.\n\n---\n\n## Tips\n\n- **Run early** — Inject standards at the start of a task, before implementation\n- **Be specific** — If you know which standards apply, use explicit mode\n- **Check the index** — If suggestions seem wrong, run `/index-standards` to rebuild\n- **Keep standards concise** — Injected standards consume tokens; shorter is better\n\n## Integration\n\nThis command is called internally by `/shape-spec` to inject relevant standards during planning. You can also invoke it directly anytime you need standards in context.\n\n<!-- File: commands/agent-os/plan-product.md (Tokens: ~1111 | Category: command-prompt) -->\n# Plan Product\n\nEstablish foundational product documentation through an interactive conversation. Creates mission, roadmap, and tech stack files in `agent-os/product/`.\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Keep it lightweight** — gather enough to create useful docs without over-documenting\n- **One question at a time** — don't overwhelm with multiple questions\n\n## Process\n\n### Step 1: Check for Existing Product Docs\n\nCheck if `agent-os/product/` exists and contains any of these files:\n- `mission.md`\n- `roadmap.md`\n- `tech-stack.md`\n\n**If any files exist**, use AskUserQuestion:\n\n```\nI found existing product documentation:\n- mission.md: [exists/missing]\n- roadmap.md: [exists/missing]\n- tech-stack.md: [exists/missing]\n\nWould you like to:\n1. Start fresh (replace all)\n2. Update specific files\n3. Cancel\n\n(Choose 1, 2, or 3)\n```\n\nIf option 2, ask which files to update and only gather info for those.\nIf option 3, stop here.\n\n**If no files exist**, proceed to Step 2.\n\n### Step 2: Gather Product Vision (for mission.md)\n\nUse AskUserQuestion:\n\n```\nLet's define your product's mission.\n\n**What problem does this product solve?**\n\n(Describe the core problem or pain point you're addressing)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**Who is this product for?**\n\n(Describe your target users or audience)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**What makes your solution unique?**\n\n(What's the key differentiator or approach?)\n```\n\n### Step 3: Gather Roadmap (for roadmap.md)\n\nUse AskUserQuestion:\n\n```\nNow let's outline your development roadmap.\n\n**What are the must-have features for launch (MVP)?**\n\n(List the core features needed for the first usable version)\n```\n\nAfter they respond, use AskUserQuestion:\n\n```\n**What features are planned for after launch?**\n\n(List features you'd like to add in future phases, or say \"none yet\")\n```\n\n### Step 4: Establish Tech Stack (for tech-stack.md)\n\nFirst, check if `agent-os/standards/global/tech-stack.md` exists.\n\n**If the tech-stack standard exists**, read it and use AskUserQuestion:\n\n```\nI found a tech stack standard in your standards:\n\n[Summarize the key technologies from global/tech-stack.md]\n\nDoes this project use the same tech stack, or does it differ?\n\n1. Same as standard (use as-is)\n2. Different (I'll specify)\n\n(Choose 1 or 2)\n```\n\nIf they choose option 1, use the standard's content for tech-stack.md.\nIf they choose option 2, proceed to ask them to specify (see below).\n\n**If no tech-stack standard exists** (or they chose option 2 above), use AskUserQuestion:\n\n```\n**What technologies does this project use?**\n\nPlease describe your tech stack:\n- Frontend: (e.g., React, Vue, vanilla JS, or N/A)\n- Backend: (e.g., Rails, Node, Django, or N/A)\n- Database: (e.g., PostgreSQL, MongoDB, or N/A)\n- Other: (hosting, APIs, tools, etc.)\n```\n\n### Step 5: Generate Files\n\nCreate the `agent-os/product/` directory if it doesn't exist.\n\nGenerate each file based on the information gathered:\n\n#### mission.md\n\n```markdown\n# Product Mission\n\n## Problem\n\n[Insert what problem this product solves - from Step 2]\n\n## Target Users\n\n[Insert who this product is for - from Step 2]\n\n## Solution\n\n[Insert what makes the solution unique - from Step 2]\n```\n\n#### roadmap.md\n\n```markdown\n# Product Roadmap\n\n## Phase 1: MVP\n\n[Insert must-have features for launch - from Step 3]\n\n## Phase 2: Post-Launch\n\n[Insert planned future features - from Step 3, or \"To be determined\" if they said none yet]\n```\n\n#### tech-stack.md\n\n```markdown\n# Tech Stack\n\n[Organize the tech stack information into logical sections]\n\n## Frontend\n\n[Frontend technologies, or \"N/A\" if not applicable]\n\n## Backend\n\n[Backend technologies, or \"N/A\" if not applicable]\n\n## Database\n\n[Database choice, or \"N/A\" if not applicable]\n\n## Other\n\n[Other tools, hosting, services - or omit this section if nothing mentioned]\n```\n\n### Step 6: Confirm Completion\n\nAfter creating all files, output to user:\n\n```\n✓ Product documentation created:\n\n  agent-os/product/mission.md\n  agent-os/product/roadmap.md\n  agent-os/product/tech-stack.md\n\nReview these files to ensure they accurately capture your product vision.\nYou can edit them directly or run /plan-product again to update.\n```\n\n## Tips\n\n- If the user provides very brief answers, that's fine — the docs can be expanded later\n- If they want to skip a section, create the file with a placeholder like \"To be defined\"\n- The `/shape-spec` command will read these files when planning features, so having them populated helps with context\n\n<!-- File: commands/agent-os/shape-spec.md (Tokens: ~1539 | Category: command-prompt) -->\n# Shape Spec\n\nGather context and structure planning for significant work. **Run this command while in plan mode.**\n\n## Important Guidelines\n\n- **Always use AskUserQuestion tool** when asking the user anything\n- **Offer suggestions** — Present options the user can confirm, adjust, or correct\n- **Keep it lightweight** — This is shaping, not exhaustive documentation\n\n## Prerequisites\n\nThis command **must be run in plan mode**.\n\n**Before proceeding, check if you are currently in plan mode.**\n\nIf NOT in plan mode, **stop immediately** and tell the user:\n\n```\nShape-spec must be run in plan mode. Please enter plan mode first, then run /shape-spec again.\n```\n\nDo not proceed with any steps below until confirmed to be in plan mode.\n\n## Process\n\n### Step 1: Clarify What We're Building\n\nUse AskUserQuestion to understand the scope:\n\n```\nWhat are we building? Please describe the feature or change.\n\n(Be as specific as you like — I'll ask follow-up questions if needed)\n```\n\nBased on their response, ask 1-2 clarifying questions if the scope is unclear. Examples:\n- \"Is this a new feature or a change to existing functionality?\"\n- \"What's the expected outcome when this is done?\"\n- \"Are there any constraints or requirements I should know about?\"\n\n### Step 2: Gather Visuals\n\nUse AskUserQuestion:\n\n```\nDo you have any visuals to reference?\n\n- Mockups or wireframes\n- Screenshots of similar features\n- Examples from other apps\n\n(Paste images, share file paths, or say \"none\")\n```\n\nIf visuals are provided, note them for inclusion in the spec folder.\n\n### Step 3: Identify Reference Implementations\n\nUse AskUserQuestion:\n\n```\nIs there similar code in this codebase I should reference?\n\nExamples:\n- \"The comments feature is similar to what we're building\"\n- \"Look at how src/features/notifications/ handles real-time updates\"\n- \"No existing references\"\n\n(Point me to files, folders, or features to study)\n```\n\nIf references are provided, read and analyze them to inform the plan.\n\n### Step 4: Check Product Context\n\nCheck if `agent-os/product/` exists and contains files.\n\nIf it exists, read key files (like `mission.md`, `roadmap.md`, `tech-stack.md`) and use AskUserQuestion:\n\n```\nI found product context in agent-os/product/. Should this feature align with any specific product goals or constraints?\n\nKey points from your product docs:\n- [summarize relevant points]\n\n(Confirm alignment or note any adjustments)\n```\n\nIf no product folder exists, skip this step.\n\n### Step 5: Surface Relevant Standards\n\nRead `agent-os/standards/index.yml` to identify relevant standards based on the feature being built.\n\nUse AskUserQuestion to confirm:\n\n```\nBased on what we're building, these standards may apply:\n\n1. **api/response-format** — API response envelope structure\n2. **api/error-handling** — Error codes and exception handling\n3. **database/migrations** — Migration patterns\n\nShould I include these in the spec? (yes / adjust: remove 3, add frontend/forms)\n```\n\nRead the confirmed standards files to include their content in the plan context.\n\n### Step 6: Generate Spec Folder Name\n\nCreate a folder name using this format:\n```\nYYYY-MM-DD-HHMM-{feature-slug}/\n```\n\nWhere:\n- Date/time is current timestamp\n- Feature slug is derived from the feature description (lowercase, hyphens, max 40 chars)\n\nExample: `2026-01-15-1430-user-comment-system/`\n\n**Note:** If `agent-os/specs/` doesn't exist, create it when saving the spec folder.\n\n### Step 7: Structure the Plan\n\nNow build the plan with **Task 1 always being \"Save spec documentation\"**.\n\nPresent this structure to the user:\n\n```\nHere's the plan structure. Task 1 saves all our shaping work before implementation begins.\n\n---\n\n## Task 1: Save Spec Documentation\n\nCreate `agent-os/specs/{folder-name}/` with:\n\n- **plan.md** — This full plan\n- **shape.md** — Shaping notes (scope, decisions, context from our conversation)\n- **standards.md** — Relevant standards that apply to this work\n- **references.md** — Pointers to reference implementations studied\n- **visuals/** — Any mockups or screenshots provided\n\n## Task 2: [First implementation task]\n\n[Description based on the feature]\n\n## Task 3: [Next task]\n\n...\n\n---\n\nDoes this plan structure look right? I'll fill in the implementation tasks next.\n```\n\n### Step 8: Complete the Plan\n\nAfter Task 1 is confirmed, continue building out the remaining implementation tasks based on:\n- The feature scope from Step 1\n- Patterns from reference implementations (Step 3)\n- Constraints from standards (Step 5)\n\nEach task should be specific and actionable.\n\n### Step 9: Ready for Execution\n\nWhen the full plan is ready:\n\n```\nPlan complete. When you approve and execute:\n\n1. Task 1 will save all spec documentation first\n2. Then implementation tasks will proceed\n\nReady to start? (approve / adjust)\n```\n\n## Output Structure\n\nThe spec folder will contain:\n\n```\nagent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/\n├── plan.md           # The full plan\n├── shape.md          # Shaping decisions and context\n├── standards.md      # Which standards apply and key points\n├── references.md     # Pointers to similar code\n└── visuals/          # Mockups, screenshots (if any)\n```\n\n## shape.md Content\n\nThe shape.md file should capture:\n\n```markdown\n# {Feature Name} — Shaping Notes\n\n## Scope\n\n[What we're building, from Step 1]\n\n## Decisions\n\n- [Key decisions made during shaping]\n- [Constraints or requirements noted]\n\n## Context\n\n- **Visuals:** [List of visuals provided, or \"None\"]\n- **References:** [Code references studied]\n- **Product alignment:** [Notes from product context, or \"N/A\"]\n\n## Standards Applied\n\n- api/response-format — [why it applies]\n- api/error-handling — [why it applies]\n```\n\n## standards.md Content\n\nInclude the full content of each relevant standard:\n\n```markdown\n# Standards for {Feature Name}\n\nThe following standards apply to this work.\n\n---\n\n## api/response-format\n\n[Full content of the standard file]\n\n---\n\n## api/error-handling\n\n[Full content of the standard file]\n```\n\n## references.md Content\n\n```markdown\n# References for {Feature Name}\n\n## Similar Implementations\n\n### {Reference 1 name}\n\n- **Location:** `src/features/comments/`\n- **Relevance:** [Why this is relevant]\n- **Key patterns:** [What to borrow from this]\n\n### {Reference 2 name}\n\n...\n```\n\n## Tips\n\n- **Keep shaping fast** — Don't over-document. Capture enough to start, refine as you build.\n- **Visuals are optional** — Not every feature needs mockups.\n- **Standards guide, not dictate** — They inform the plan but aren't always mandatory.\n- **Specs are discoverable** — Months later, someone can find this spec and understand what was built and why.\n</yakaai_skills>"}