diff --git a/.agents/commands/agent-os/discover-standards.md b/.agents/commands/agent-os/discover-standards.md deleted file mode 100644 index b5de63e..0000000 --- a/.agents/commands/agent-os/discover-standards.md +++ /dev/null @@ -1,261 +0,0 @@ -# Discover Standards - -Extract tribal knowledge from your codebase into concise, documented standards. - -## Important Guidelines - -- **Always use AskUserQuestion tool** when asking the user anything -- **Write concise standards** — Use minimal words. Standards must be scannable by AI agents without bloating context windows. -- **Offer suggestions** — Present options the user can confirm, choose between, or correct. Don't make them think harder than necessary. - -## Process - -### Step 1: Determine Focus Area - -Check if the user specified an area when running this command. If they did, skip to Step 2. - -If no area was specified: - -1. Analyze the codebase structure (folders, file types, patterns) -2. Identify 3-5 major areas. Examples: - - **Frontend areas:** UI components, styling/CSS, state management, forms, routing - - **Backend areas:** API routes, database/models, authentication, background jobs - - **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure -3. Use AskUserQuestion to present the areas: - -``` -I've identified these areas in your codebase: - -1. **API Routes** (src/api/) — Request handling, response formats -2. **Database** (src/models/, src/db/) — Models, queries, migrations -3. **React Components** (src/components/) — UI patterns, props, state -4. **Authentication** (src/auth/) — Login, sessions, permissions - -Which area should we focus on for discovering standards? (Pick one, or suggest a different area) -``` - -Wait for user response before proceeding. - -### Step 2: Analyze & Present Findings - -Once an area is determined: - -1. Read key files in that area (5-10 representative files) -2. Look for patterns that are: - - **Unusual or unconventional** — Not standard framework/library patterns - - **Opinionated** — Specific choices that could have gone differently - - **Tribal** — Things a new developer wouldn't know without being told - - **Consistent** — Patterns repeated across multiple files - -3. Use AskUserQuestion to present findings and let user select: - -``` -I analyzed [area] and found these potential standards worth documenting: - -1. **API Response Envelope** — All responses use { success, data, error } structure -2. **Error Codes** — Custom error codes like AUTH_001, DB_002 with specific meanings -3. **Pagination Pattern** — Cursor-based pagination with consistent param names - -Which would you like to document? - -Options: -- "Yes, all of them" -- "Just 1 and 3" -- "Add: [your suggestion]" -- "Skip this area" -``` - -Wait for user selection before proceeding. - -### Step 3: Ask Why, Then Draft Each Standard - -**IMPORTANT:** For each selected standard, you MUST complete this full loop before moving to the next standard: - -1. **Ask 1-2 clarifying questions** about the "why" behind the pattern. Use your AskUserQuestion tool for this. -2. **Wait for user response** -3. **Draft the standard** incorporating their answer -4. **Confirm with user** before creating the file -5. **Create the file** if approved - -Example questions to ask (adapt based on the specific standard): - -- "What problem does this pattern solve? Why not use the default/common approach?" -- "Are there exceptions where this pattern shouldn't be used?" -- "What's the most common mistake a developer or agent makes with this?" - -**Do NOT batch all questions upfront.** Process one standard at a time through the full loop. - -### Step 4: Create the Standard File - -For each standard (after completing Step 3's Q&A): - -1. Determine the appropriate folder (create if needed): - - `api/`, `database/`, `javascript/`, `css/`, `backend/`, `testing/`, `global/` - -2. Check if a related standard file already exists — append to it if so - -3. Draft the content and use AskUserQuestion to confirm: - -``` -Here's the draft for api/response-format.md: - ---- -# API Response Format - -All API responses use this envelope: - -\`\`\`json -{ "success": true, "data": { ... } } -{ "success": false, "error": { "code": "...", "message": "..." } } -\`\`\` - -- Never return raw data without the envelope -- Error responses must include both code and message -- Success responses omit the error field entirely ---- - -Create this file? (yes / edit: [your changes] / skip) -``` - -4. Create or update the file in `agent-os/standards/[folder]/` -5. **Then repeat Steps 3-4 for the next selected standard** - -### Step 5: Update the Index - -After all standards are created: - -1. Scan `agent-os/standards/` for all `.md` files -2. For each new file without an index entry, use AskUserQuestion: - -``` -New standard needs an index entry: - File: api/response-format.md - -Suggested description: "API response envelope structure and error format" - -Accept this description? (yes / or type a better one) -``` - -3. Update `agent-os/standards/index.yml`: - -```yaml -api: - response-format: - description: API response envelope structure and error format -``` - -Alphabetize by folder, then by filename. - -### Step 6: Offer to Continue - -Use AskUserQuestion: - -``` -Standards created for [area]: -- api/response-format.md -- api/error-codes.md - -Would you like to discover standards in another area, or are we done? -``` - -## Output Location - -All standards: `agent-os/standards/[folder]/[standard].md` -Index file: `agent-os/standards/index.yml` - -## Writing Concise Standards - -Standards will be injected into AI context windows. Every word costs tokens. Follow these rules: - -- **Lead with the rule** — State what to do first, explain why second (if needed) -- **Use code examples** — Show, don't tell -- **Skip the obvious** — Don't document what the code already makes clear -- **One standard per concept** — Don't combine unrelated patterns -- **Bullet points over paragraphs** — Scannable beats readable - -**Good:** -```markdown -# Error Responses - -Use error codes: `AUTH_001`, `DB_001`, `VAL_001` - -\`\`\`json -{ "success": false, "error": { "code": "AUTH_001", "message": "..." } } -\`\`\` - -- Always include both code and message -- Log full error server-side, return safe message to client -``` - -**Bad:** -```markdown -# Error Handling Guidelines - -When 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... -[continues for 3 more paragraphs] -``` - -## Example: Full Loop for One Standard - -Here's how to process a single standard through the complete workflow: - -**1. Present findings (Step 2):** -``` -I found these patterns in your API code: -1. **Response Envelope** — All responses use { success, data, error } -2. **Error Codes** — Custom codes like AUTH_001 - -Which would you like to document? -``` - -User: "Both" - -**2. Ask why for first standard (Step 3):** -``` -For the Response Envelope pattern: -- What problem does this solve? Why not return raw data? -- Are there any endpoints that don't use this pattern? -``` - -User: "We use it so the frontend always knows where to find the data. All endpoints use it, no exceptions." - -**3. Draft first standard (Step 3 continued):** -``` -Here's the draft for api/response-envelope.md: - ---- -# Response Envelope - -All API responses use this structure: -\`\`\`json -{ "success": true, "data": { ... } } -{ "success": false, "error": { ... } } -\`\`\` - -- Frontend always checks `success` first, then reads `data` or `error` -- No exceptions — every endpoint uses this format ---- - -Create this file? -``` - -User: "Yes" - -**4. Create file, then move to next standard:** - -[Create the file] - -**5. Ask why for second standard (back to Step 3):** -``` -For the Error Codes pattern: -- What's the naming convention for codes? -- Where should new error codes be documented? -``` - -User: "Format is AREA_NUMBER like AUTH_001. We keep a list in the wiki." - -**6. Draft second standard, confirm, create file...** - -[Continue until all selected standards are done] - -**Key point:** Complete the full ask → draft → confirm → create cycle for each standard before starting the next one. diff --git a/.agents/commands/agent-os/index-standards.md b/.agents/commands/agent-os/index-standards.md deleted file mode 100644 index 7967c6f..0000000 --- a/.agents/commands/agent-os/index-standards.md +++ /dev/null @@ -1,124 +0,0 @@ -# Index Standards - -Rebuild and maintain the standards index file (`index.yml`). - -## Purpose - -The index enables `/inject-standards` to suggest relevant standards without reading all files. It maps each standard to a brief description for quick matching. - -## Process - -### Step 1: Scan for Standards Files - -1. List all `.md` files in `agent-os/standards/` and its subfolders -2. Build a list of all standards organized by folder: - ``` - root/coding-style.md # Files in standards/ root use "root" as the folder name - root/naming.md - api/response-format.md - api/error-handling.md - database/migrations.md - ``` - -**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". - -### Step 2: Load Existing Index - -Read `agent-os/standards/index.yml` if it exists. Note which entries already have descriptions. - -### Step 3: Identify Changes - -Compare the file scan with the existing index: - -- **New files** — Standards files without index entries -- **Deleted files** — Index entries for files that no longer exist -- **Existing files** — Already indexed, keep as-is - -### Step 4: Handle New Files - -For each new standard file that needs an index entry: - -1. Read the file to understand its content -2. Use AskUserQuestion to propose a description: - -``` -New standard needs indexing: - File: api/response-format.md - -Suggested description: "API response envelope structure and error format" - -Accept? (yes / or type a better description) -``` - -Keep descriptions to **one short sentence** — they're for matching, not documentation. - -### Step 5: Handle Deleted Files - -If there are index entries for files that no longer exist: - -1. List them for the user -2. Remove them from the index automatically (no confirmation needed) - -Report: "Removed 2 stale index entries: api/old-pattern.md, testing/deprecated.md" - -### Step 6: Write Updated Index - -Generate `agent-os/standards/index.yml` with this structure: - -```yaml -folder-name: - file-name: - description: Brief description here -``` - -**Rules:** -- Alphabetize folders -- Alphabetize files within each folder -- File names without `.md` extension -- One-line descriptions only - -**Example:** -```yaml -root: - coding-style: - description: General coding style, formatting, linting rules - naming: - description: File naming, variable naming, class naming conventions - -api: - error-handling: - description: Error codes, exception handling, error response format - response-format: - description: API response envelope structure, status codes, pagination - -database: - migrations: - description: Migration file structure, naming conventions, rollback patterns -``` - -**Note:** `root` appears first and contains standards files that live directly in `agent-os/standards/` (not in subfolders). - -### Step 7: Report Results - -Summarize what changed: - -``` -Index updated: - ✓ 2 new entries added - ✓ 1 stale entry removed - ✓ 8 entries unchanged - -Total: 9 standards indexed -``` - -## When to Run - -- After manually creating or deleting standards files -- If `/inject-standards` suggestions seem out of sync -- To clean up a messy or outdated index - -**Note:** `/discover-standards` runs this automatically as its final step, so you usually don't need to call it separately after discovering standards. - -## Output - -Updates `agent-os/standards/index.yml` diff --git a/.agents/commands/agent-os/inject-standards.md b/.agents/commands/agent-os/inject-standards.md deleted file mode 100644 index f7875a6..0000000 --- a/.agents/commands/agent-os/inject-standards.md +++ /dev/null @@ -1,291 +0,0 @@ -# Inject Standards - -Inject relevant standards into the current context, formatted appropriately for the situation. - -## Usage Modes - -This command supports two modes: - -### Auto-Suggest Mode (no arguments) -``` -/inject-standards -``` -Analyzes context and suggests relevant standards. - -### Explicit Mode (with arguments) -``` -/inject-standards api # All standards in api/ -/inject-standards api/response-format # Single file -/inject-standards api/response-format api/auth # Multiple files -/inject-standards root # All standards in the root folder -/inject-standards root/naming # Single file from root folder -``` -Directly injects specified standards without suggestions. - -**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder). - -## Process - -### Step 1: Detect Context Scenario - -Before injecting standards, determine which scenario we're in. Read the current conversation and check if we're in plan mode. - -**Three scenarios:** - -1. **Conversation** — Regular chat, implementing code, answering questions -2. **Creating a Skill** — Building a `.claude/skills/` file -3. **Shaping/Planning** — In plan mode, building a spec, running `/shape-spec` - -**Detection logic:** - -- If currently in plan mode OR conversation clearly mentions "spec", "plan", "shape" → **Shaping/Planning** -- If conversation clearly mentions creating a skill, editing `.claude/skills/`, or building a reusable procedure → **Creating a Skill** -- Otherwise → **Ask to confirm** (do not assume) - -**If neither skill nor plan is clearly detected**, use AskUserQuestion to confirm: - -``` -I'll inject the relevant standards. How should I format them? - -1. **Conversation** — Read standards into our chat (for implementation work) -2. **Skill** — Output file references to include in a skill you're building -3. **Plan** — Output file references to include in a plan/spec - -Which scenario? (1, 2, or 3) -``` - -Always ask when uncertain — don't assume conversation by default. - -### Step 2: Read the Index (Auto-Suggest Mode) - -Read `agent-os/standards/index.yml` to get the list of available standards and their descriptions. - -If index.yml doesn't exist or is empty: -``` -No standards index found. Run /discover-standards first to create standards, -or /index-standards if you have standards files without an index. -``` - -### Step 3: Analyze Work Context - -Look at the current conversation to understand what the user is working on: -- What type of work? (API, database, UI, etc.) -- What technologies mentioned? -- What's the goal? - -### Step 4: Match and Suggest - -Match index descriptions against the context. Use AskUserQuestion to present suggestions: - -``` -Based on your task, these standards may be relevant: - -1. **api/response-format** — API response envelope structure, status codes -2. **api/error-handling** — Error codes, exception handling, error responses -3. **global/naming** — File naming, variable naming conventions - -Inject these standards? (yes / just 1 and 3 / add: database/migrations / none) -``` - -Keep suggestions focused — typically 2-5 standards. Don't overwhelm with too many options. - -### Step 5: Inject Based on Scenario - -Format the output differently based on the detected scenario: - ---- - -#### Scenario: Conversation - -Read the standards and announce them: - -``` -I've read the following standards as they are relevant to what we're working on: - ---- Standard: api/response-format --- - -[full content of the standard file] - ---- End Standard --- - ---- Standard: api/error-handling --- - -[full content of the standard file] - ---- End Standard --- - -**Key points:** -- All API responses use { success, data, error } envelope -- Error codes follow AUTH_xxx, DB_xxx pattern -``` - ---- - -#### Scenario: Creating a Skill - -First, use AskUserQuestion to determine how to include the standards: - -``` -How should these standards be included in your skill? - -1. **References** — Add @ file paths that point to the standards (keeps skill lightweight, standards stay in sync) -2. **Copy content** — Paste the full standards content into the skill (self-contained, but won't update if standards change) - -Which approach? (1 or 2) -``` - -**If References (option 1):** - -``` -Be sure to include references to the following standards files in the appropriate location in the file(s) that make up this skill: - -@agent-os/standards/api/response-format.md -@agent-os/standards/api/error-handling.md -@agent-os/standards/global/naming.md - -These standards cover: -- API response envelope structure, status codes -- Error codes, exception handling, error responses -- File naming, variable naming conventions -``` - -**If Copy content (option 2):** - -``` -Include the following standards content in your skill: - ---- Standard: api/response-format --- - -[full content of the standard file] - ---- End Standard --- - ---- Standard: api/error-handling --- - -[full content of the standard file] - ---- End Standard --- - -These standards cover: -- API response envelope structure, status codes -- Error codes, exception handling, error responses -- File naming, variable naming conventions -``` - ---- - -#### Scenario: Shaping/Planning - -First, use AskUserQuestion to determine how to include the standards: - -``` -How should these standards be included in your plan? - -1. **References** — Add @ file paths that point to the standards (keeps plan lightweight, standards stay in sync) -2. **Copy content** — Paste the full standards content into the plan (self-contained, but won't update if standards change) - -Which approach? (1 or 2) -``` - -**If References (option 1):** - -``` -Be sure to include references to the following standards files in the appropriate location in the plan we're building: - -@agent-os/standards/api/response-format.md -@agent-os/standards/api/error-handling.md -@agent-os/standards/global/naming.md - -These standards cover: -- API response envelope structure, status codes -- Error codes, exception handling, error responses -- File naming, variable naming conventions -``` - -**If Copy content (option 2):** - -``` -Include the following standards content in your plan: - ---- Standard: api/response-format --- - -[full content of the standard file] - ---- End Standard --- - ---- Standard: api/error-handling --- - -[full content of the standard file] - ---- End Standard --- - -These standards cover: -- API response envelope structure, status codes -- Error codes, exception handling, error responses -- File naming, variable naming conventions -``` - ---- - -### Step 6: Surface Related Skills (Conversation scenario only) - -When in conversation scenario, check if `.claude/skills/` exists and contains related skills: - -``` -Related Skills you might want to use: -- create-api-endpoint — Scaffolds new API endpoints following these standards -``` - -Don't invoke skills automatically — just surface them for awareness. - ---- - -## Explicit Mode - -When arguments are provided, skip the suggestion step but still detect scenario. - -### Step 1: Detect Scenario - -Same as auto-suggest mode. - -### Step 2: Parse Arguments - -Arguments can be: -- **Folder name** — `api` → inject all `.md` files in `agent-os/standards/api/` -- **Folder/file** — `api/response-format` → inject `agent-os/standards/api/response-format.md` -- **Root folder** — `root` → inject all `.md` files directly in `agent-os/standards/` (not in subfolders) -- **Root file** — `root/naming` → inject `agent-os/standards/naming.md` - -Multiple arguments inject multiple standards. - -### Step 3: Validate - -Check that specified files/folders exist. If not: - -``` -Standard not found: api/nonexistent - -Available standards in api/: -- response-format -- error-handling -- authentication - -Did you mean one of these? -``` - -### Step 4: Inject Based on Scenario - -Same formatting as auto-suggest mode, based on detected scenario. - ---- - -## Tips - -- **Run early** — Inject standards at the start of a task, before implementation -- **Be specific** — If you know which standards apply, use explicit mode -- **Check the index** — If suggestions seem wrong, run `/index-standards` to rebuild -- **Keep standards concise** — Injected standards consume tokens; shorter is better - -## Integration - -This 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. diff --git a/.agents/commands/agent-os/plan-product.md b/.agents/commands/agent-os/plan-product.md deleted file mode 100644 index bd8bf16..0000000 --- a/.agents/commands/agent-os/plan-product.md +++ /dev/null @@ -1,204 +0,0 @@ -# Plan Product - -Establish foundational product documentation through an interactive conversation. Creates mission, roadmap, and tech stack files in `agent-os/product/`. - -## Important Guidelines - -- **Always use AskUserQuestion tool** when asking the user anything -- **Keep it lightweight** — gather enough to create useful docs without over-documenting -- **One question at a time** — don't overwhelm with multiple questions - -## Process - -### Step 1: Check for Existing Product Docs - -Check if `agent-os/product/` exists and contains any of these files: -- `mission.md` -- `roadmap.md` -- `tech-stack.md` - -**If any files exist**, use AskUserQuestion: - -``` -I found existing product documentation: -- mission.md: [exists/missing] -- roadmap.md: [exists/missing] -- tech-stack.md: [exists/missing] - -Would you like to: -1. Start fresh (replace all) -2. Update specific files -3. Cancel - -(Choose 1, 2, or 3) -``` - -If option 2, ask which files to update and only gather info for those. -If option 3, stop here. - -**If no files exist**, proceed to Step 2. - -### Step 2: Gather Product Vision (for mission.md) - -Use AskUserQuestion: - -``` -Let's define your product's mission. - -**What problem does this product solve?** - -(Describe the core problem or pain point you're addressing) -``` - -After they respond, use AskUserQuestion: - -``` -**Who is this product for?** - -(Describe your target users or audience) -``` - -After they respond, use AskUserQuestion: - -``` -**What makes your solution unique?** - -(What's the key differentiator or approach?) -``` - -### Step 3: Gather Roadmap (for roadmap.md) - -Use AskUserQuestion: - -``` -Now let's outline your development roadmap. - -**What are the must-have features for launch (MVP)?** - -(List the core features needed for the first usable version) -``` - -After they respond, use AskUserQuestion: - -``` -**What features are planned for after launch?** - -(List features you'd like to add in future phases, or say "none yet") -``` - -### Step 4: Establish Tech Stack (for tech-stack.md) - -First, check if `agent-os/standards/global/tech-stack.md` exists. - -**If the tech-stack standard exists**, read it and use AskUserQuestion: - -``` -I found a tech stack standard in your standards: - -[Summarize the key technologies from global/tech-stack.md] - -Does this project use the same tech stack, or does it differ? - -1. Same as standard (use as-is) -2. Different (I'll specify) - -(Choose 1 or 2) -``` - -If they choose option 1, use the standard's content for tech-stack.md. -If they choose option 2, proceed to ask them to specify (see below). - -**If no tech-stack standard exists** (or they chose option 2 above), use AskUserQuestion: - -``` -**What technologies does this project use?** - -Please describe your tech stack: -- Frontend: (e.g., React, Vue, vanilla JS, or N/A) -- Backend: (e.g., Rails, Node, Django, or N/A) -- Database: (e.g., PostgreSQL, MongoDB, or N/A) -- Other: (hosting, APIs, tools, etc.) -``` - -### Step 5: Generate Files - -Create the `agent-os/product/` directory if it doesn't exist. - -Generate each file based on the information gathered: - -#### mission.md - -```markdown -# Product Mission - -## Problem - -[Insert what problem this product solves - from Step 2] - -## Target Users - -[Insert who this product is for - from Step 2] - -## Solution - -[Insert what makes the solution unique - from Step 2] -``` - -#### roadmap.md - -```markdown -# Product Roadmap - -## Phase 1: MVP - -[Insert must-have features for launch - from Step 3] - -## Phase 2: Post-Launch - -[Insert planned future features - from Step 3, or "To be determined" if they said none yet] -``` - -#### tech-stack.md - -```markdown -# Tech Stack - -[Organize the tech stack information into logical sections] - -## Frontend - -[Frontend technologies, or "N/A" if not applicable] - -## Backend - -[Backend technologies, or "N/A" if not applicable] - -## Database - -[Database choice, or "N/A" if not applicable] - -## Other - -[Other tools, hosting, services - or omit this section if nothing mentioned] -``` - -### Step 6: Confirm Completion - -After creating all files, output to user: - -``` -✓ Product documentation created: - - agent-os/product/mission.md - agent-os/product/roadmap.md - agent-os/product/tech-stack.md - -Review these files to ensure they accurately capture your product vision. -You can edit them directly or run /plan-product again to update. -``` - -## Tips - -- If the user provides very brief answers, that's fine — the docs can be expanded later -- If they want to skip a section, create the file with a placeholder like "To be defined" -- The `/shape-spec` command will read these files when planning features, so having them populated helps with context diff --git a/.agents/commands/agent-os/shape-spec.md b/.agents/commands/agent-os/shape-spec.md deleted file mode 100644 index e06d485..0000000 --- a/.agents/commands/agent-os/shape-spec.md +++ /dev/null @@ -1,267 +0,0 @@ -# Shape Spec - -Gather context and structure planning for significant work. **Run this command while in plan mode.** - -## Important Guidelines - -- **Always use AskUserQuestion tool** when asking the user anything -- **Offer suggestions** — Present options the user can confirm, adjust, or correct -- **Keep it lightweight** — This is shaping, not exhaustive documentation - -## Prerequisites - -This command **must be run in plan mode**. - -**Before proceeding, check if you are currently in plan mode.** - -If NOT in plan mode, **stop immediately** and tell the user: - -``` -Shape-spec must be run in plan mode. Please enter plan mode first, then run /shape-spec again. -``` - -Do not proceed with any steps below until confirmed to be in plan mode. - -## Process - -### Step 1: Clarify What We're Building - -Use AskUserQuestion to understand the scope: - -``` -What are we building? Please describe the feature or change. - -(Be as specific as you like — I'll ask follow-up questions if needed) -``` - -Based on their response, ask 1-2 clarifying questions if the scope is unclear. Examples: -- "Is this a new feature or a change to existing functionality?" -- "What's the expected outcome when this is done?" -- "Are there any constraints or requirements I should know about?" - -### Step 2: Gather Visuals - -Use AskUserQuestion: - -``` -Do you have any visuals to reference? - -- Mockups or wireframes -- Screenshots of similar features -- Examples from other apps - -(Paste images, share file paths, or say "none") -``` - -If visuals are provided, note them for inclusion in the spec folder. - -### Step 3: Identify Reference Implementations - -Use AskUserQuestion: - -``` -Is there similar code in this codebase I should reference? - -Examples: -- "The comments feature is similar to what we're building" -- "Look at how src/features/notifications/ handles real-time updates" -- "No existing references" - -(Point me to files, folders, or features to study) -``` - -If references are provided, read and analyze them to inform the plan. - -### Step 4: Check Product Context - -Check if `agent-os/product/` exists and contains files. - -If it exists, read key files (like `mission.md`, `roadmap.md`, `tech-stack.md`) and use AskUserQuestion: - -``` -I found product context in agent-os/product/. Should this feature align with any specific product goals or constraints? - -Key points from your product docs: -- [summarize relevant points] - -(Confirm alignment or note any adjustments) -``` - -If no product folder exists, skip this step. - -### Step 5: Surface Relevant Standards - -Read `agent-os/standards/index.yml` to identify relevant standards based on the feature being built. - -Use AskUserQuestion to confirm: - -``` -Based on what we're building, these standards may apply: - -1. **api/response-format** — API response envelope structure -2. **api/error-handling** — Error codes and exception handling -3. **database/migrations** — Migration patterns - -Should I include these in the spec? (yes / adjust: remove 3, add frontend/forms) -``` - -Read the confirmed standards files to include their content in the plan context. - -### Step 6: Generate Spec Folder Name - -Create a folder name using this format: -``` -YYYY-MM-DD-HHMM-{feature-slug}/ -``` - -Where: -- Date/time is current timestamp -- Feature slug is derived from the feature description (lowercase, hyphens, max 40 chars) - -Example: `2026-01-15-1430-user-comment-system/` - -**Note:** If `agent-os/specs/` doesn't exist, create it when saving the spec folder. - -### Step 7: Structure the Plan - -Now build the plan with **Task 1 always being "Save spec documentation"**. - -Present this structure to the user: - -``` -Here's the plan structure. Task 1 saves all our shaping work before implementation begins. - ---- - -## Task 1: Save Spec Documentation - -Create `agent-os/specs/{folder-name}/` with: - -- **plan.md** — This full plan -- **shape.md** — Shaping notes (scope, decisions, context from our conversation) -- **standards.md** — Relevant standards that apply to this work -- **references.md** — Pointers to reference implementations studied -- **visuals/** — Any mockups or screenshots provided - -## Task 2: [First implementation task] - -[Description based on the feature] - -## Task 3: [Next task] - -... - ---- - -Does this plan structure look right? I'll fill in the implementation tasks next. -``` - -### Step 8: Complete the Plan - -After Task 1 is confirmed, continue building out the remaining implementation tasks based on: -- The feature scope from Step 1 -- Patterns from reference implementations (Step 3) -- Constraints from standards (Step 5) - -Each task should be specific and actionable. - -### Step 9: Ready for Execution - -When the full plan is ready: - -``` -Plan complete. When you approve and execute: - -1. Task 1 will save all spec documentation first -2. Then implementation tasks will proceed - -Ready to start? (approve / adjust) -``` - -## Output Structure - -The spec folder will contain: - -``` -agent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/ -├── plan.md # The full plan -├── shape.md # Shaping decisions and context -├── standards.md # Which standards apply and key points -├── references.md # Pointers to similar code -└── visuals/ # Mockups, screenshots (if any) -``` - -## shape.md Content - -The shape.md file should capture: - -```markdown -# {Feature Name} — Shaping Notes - -## Scope - -[What we're building, from Step 1] - -## Decisions - -- [Key decisions made during shaping] -- [Constraints or requirements noted] - -## Context - -- **Visuals:** [List of visuals provided, or "None"] -- **References:** [Code references studied] -- **Product alignment:** [Notes from product context, or "N/A"] - -## Standards Applied - -- api/response-format — [why it applies] -- api/error-handling — [why it applies] -``` - -## standards.md Content - -Include the full content of each relevant standard: - -```markdown -# Standards for {Feature Name} - -The following standards apply to this work. - ---- - -## api/response-format - -[Full content of the standard file] - ---- - -## api/error-handling - -[Full content of the standard file] -``` - -## references.md Content - -```markdown -# References for {Feature Name} - -## Similar Implementations - -### {Reference 1 name} - -- **Location:** `src/features/comments/` -- **Relevance:** [Why this is relevant] -- **Key patterns:** [What to borrow from this] - -### {Reference 2 name} - -... -``` - -## Tips - -- **Keep shaping fast** — Don't over-document. Capture enough to start, refine as you build. -- **Visuals are optional** — Not every feature needs mockups. -- **Standards guide, not dictate** — They inform the plan but aren't always mandatory. -- **Specs are discoverable** — Months later, someone can find this spec and understand what was built and why. diff --git a/.gitignore b/.gitignore index 33c634e..160842a 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,11 @@ composer.lock .vscode composer.local.json composer.local.lock + +# ringside generated files +/docs/agent/standards.index.yml +/docs/agent/standards.summary.md +/.claude/skills/ring-master-*/ +/.claude/agents/ring-master-*.md +/.agents/skills/ring-master-*/ +/.agents/agents/ring-master-*.md diff --git a/AGENTS.md b/AGENTS.md index b09a58f..0c21aaf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ This repository is a Laravel package. Keep the package focused, idiomatic, and e ## Layout -The package follows the mono domain-module layout, described in `agent-os/standards/backend/domain-modules.md`. Code lives in `src/Domains/{VirtualAgent,ConcreteAgent,Tool,ConcreteServer,RedirectDomain}` (namespace `RefactorCircus\Cortex\Domains\{Domain}`), each with its own `{Domain}ServiceProvider` registered by `Domains\DomainServiceProvider`. Models are named `{Entity}Model`. The Atrium screens span every domain and live in `src/Atrium`; package-wide pieces (`Cortex`, the facade, the base requests, `Mcp\CortexServer`, `Support\`) stay at the top level. `config/cortex.php` stays one file. +The package follows the mono domain-module layout, described in the global standard `architecture/domain-modules` and in `docs/agent/standards/cortex/domains.md`. Code lives in `src/Domains/{VirtualAgent,ConcreteAgent,Tool,ConcreteServer,RedirectDomain}` (namespace `RefactorCircus\Cortex\Domains\{Domain}`), each with its own `{Domain}ServiceProvider` registered by `Domains\DomainServiceProvider`. Models are named `{Entity}Model`. The Atrium screens span every domain and live in `src/Atrium`; package-wide pieces (`Cortex`, the facade, the base requests, `Mcp\CortexServer`, `Support\`) stay at the top level. `config/cortex.php` stays one file. ## Keystone @@ -21,6 +21,7 @@ Cortex stands on `refactor-circus/keystone`, the shared runtime of the Refactor - `CortexServiceProvider` extends `RefactorCircus\Keystone\Support\PackageServiceProvider`. `definition()` describes the package (`cortex`, `RefactorCircus\Cortex`, `CortexServer`); `register()` merges the config, calls `registerPackage()`, then registers the domain providers. `boot()` uses `registerPolicies()`, `registerNotFoundResponses()`, `registerAtriumPlugin()`, `registerMcpServer()` and `loadHistoryRoutes()`. The history route and tool are offered only while Cortex audits (Keystone's `Package::audits()`: refactor-circus/keen installed and `cortex.audit.enabled` on); Cortex has no audit code of its own. It does not call `registerCortex()`: Cortex registers its own server with its own registry, and its management tools are not offered to agents. - Domain providers extend `RefactorCircus\Keystone\Support\ServiceProvider`; routes load through `loadApiRoutesFrom()`, gated by `cortex.routes.enabled`. - Events implement `RefactorCircus\Keystone\Contracts\{ActionStartingEvent,ActionFinishedEvent,ModelLifecycleEvent}`; every Action dispatches its starting event, does its writes inside one `DB::transaction()` and dispatches its finished event after it (cache invalidation waits for the commit with `DB::afterCommit()`). Models use `RefactorCircus\Keystone\Models\Concerns\DispatchesModelEvents` with a `{Entity}{Hook}Event` for every Eloquent hook and resolve their table with `getTable()` from `Support\Tables` (`cortex.tables`); migrations, pivots, `Rule::unique`/`exists` (by model class) and raw queries use the same keys, never literal `cortex_*` names. Every model has a policy (`Domains/{Domain}/Policies`, on `Support\Policies\Policy`, registered from `cortex.policies` by `registerPolicies()`). `tests/ArchTest.php` checks action events, transactions, model events, literal table names (`literalTableNames()`) and models without policies (`modelsWithoutPolicies()`) with Keystone's `Testing\Arch`; `tests/Modes/RenamedTables` re-runs representative flows with every table renamed. +- Actions extend `RefactorCircus\Keystone\Actions\Action`: callers use `execute()`, each action implements a `protected handle()` with a concrete return type, and `tests/ArchTest.php` checks the base. Every exception extends the abstract `RefactorCircus\Cortex\Exceptions\CortexException` (on Keystone's `PackageException`), also checked by `tests/ArchTest.php`; never throw a raw SPL exception. - Action input is a `final readonly` `{Action}Data` in the domain's `Data/` (on `RefactorCircus\Keystone\Data\Data`), never an array: fields are promoted constructor properties (camelCase of the input keys; `T|Missing = new Missing` for partial updates), `rules()` lives on the Data (with any context args, e.g. `UpdateConcreteAgentToolsData::rules($agent)`), and the starting/finished events that took input carry the Data. List Data expose `pagination()` (Keystone's `Pagination`) and add its rules; their tools add `ListXData::pagination()->schema($schema)`. HTTP and MCP requests validate once: their `rules()` return the identifier rules (`agentRules()`, `versionRules()`, `serverRules()`, `ownerRules()`, `domainRules()` on the MCP and redirect-domain bases) plus `XData::rules(...)`, and `persist()`/`handle()` build with `XData::fromValidated($this->validated() / $validated)` - never `XData::from()` in a request (ArchTest). Atrium controllers use `XData::from($request->all(), ...context)`, which validates; code that vouches for its values uses `new XData(...)`. - API resources extend `RefactorCircus\Keystone\Http\Resources\JsonResource` and declare `schema(JsonSchema $schema)` next to `toArray()` (always-present fields `required()`, conditional ones not, `nullable()` where null is possible). MCP requests answer with `(new XResource($m))->toStructuredResponse()` / `XResource::collection($page)->toStructuredResponse()`, and each tool that answers with structured content declares `outputSchema()` as `XResource::structuredSchema($schema)` / `collectionSchema($schema, ListXData::pagination())` (unpaginated lists declare `data` alone). `mcpTool()` in tests is Keystone's `Testing\McpTools::call()`, which checks every structured answer against the tool's schema, and `tests/Feature/Mcp/OutputSchemaTest.php` requires the declaration. - `Http\Request` and `Mcp\Request` extend Keystone's request bases but keep Cortex's authorization: every check goes to the Gate, as the signed-in user or as a guest, and the bundled policies allow guests. Do not switch them to Keystone's `authorization` switch. A guest refused over HTTP gets 401 (Keystone's base), a signed-in user 403. `ConcreteAgentMcpRequest` and `ServerMcpRequest` throw `ModelNotFoundException` for unknown names on purpose, so they answer the base request's `Not found.`. @@ -28,7 +29,7 @@ Cortex stands on `refactor-circus/keystone`, the shared runtime of the Refactor ## Frontend -Atrium owns every component and style; Cortex ships no `resources/css`, no `Atrium::css()` call and no component namespace. See `agent-os/standards/frontend/atrium-screens.md`. +Atrium owns every component and style; Cortex ships no `resources/css`, no `Atrium::css()` call and no component namespace. See `docs/agent/standards/cortex/atrium-screens.md`. - Views use only `x-atrium::*` components and the utilities Atrium safelists. No `