modelstudio-sdk 0.0.0.dev0__tar.gz

modelstudio_sdk-0.0.0.dev0/.claude/commands/agent-os/discover-standards.md

@@ -0,0 +1,261 @@
+# 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.

modelstudio_sdk-0.0.0.dev0/.claude/commands/agent-os/index-standards.md

@@ -0,0 +1,124 @@
+# 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`

modelstudio_sdk-0.0.0.dev0/.claude/commands/agent-os/inject-standards.md

@@ -0,0 +1,291 @@
+# 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.