Create plugin.yaml

plugins/agent-os/extensions/backend/system_prompt/_50_agent_os_context.py

@@ -0,0 +1,9 @@
+from backend.utils.extension import Extension
+
+
+class AgentOsContext(Extension):
+
+    async def execute(self, system_prompt: list[str] = [], **kwargs):
+        prompt = self.agent.read_prompt("fw.agent_os.reference.md")
+        if prompt:
+            system_prompt.append(prompt)

plugins/agent-os/plugin.yaml

@@ -0,0 +1,6 @@
+name: Agent OS
+description: Standards discovery, extraction, and deployment system for AI-assisted development. Keeps agents aligned with project coding conventions.
+version: 1.0.0
+settings_sections: []
+per_project_config: true
+per_agent_config: false

plugins/agent-os/prompts/fw.agent_os.discover_standards.md

@@ -0,0 +1,128 @@
+# Discover Standards
+
+Extract tribal knowledge from your codebase into concise, documented standards.
+
+## Guidelines
+
+- **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. Do not make them think harder than necessary.
+
+## Process
+
+### Step 1: Determine Focus Area
+
+Check if the user specified an area. 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. Present the areas to the user and ask which one to focus on.
+
+Wait for user response before proceeding.
+
+### Step 2: Analyze and 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 would not know without being told
+   - **Consistent** -- Patterns repeated across multiple files
+3. Present findings and let the user select which to document.
+
+### Step 3: Ask Why, Then Draft Each Standard
+
+For each selected standard, complete this full loop before moving to the next:
+
+1. **Ask 1-2 clarifying questions** about the "why" behind the pattern
+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 should not be used?"
+- "What is 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 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 confirm with the user
+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, propose a description
+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
+
+Ask if the user wants to discover standards in another area.
+
+## 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, do not tell
+- **Skip the obvious** -- Do not document what the code already makes clear
+- **One standard per concept** -- Do not combine unrelated patterns
+- **Bullet points over paragraphs** -- Scannable beats readable
+
+**Good example:**
+```markdown
+# Error Responses
+
+Use error codes: `AUTH_001`, `DB_001`, `VAL_001`
+
+{ "success": false, "error": { "code": "AUTH_001", "message": "..." } }
+
+- Always include both code and message
+- Log full error server-side, return safe message to client
+```
+
+**Bad example:**
+Long paragraphs explaining error handling philosophy in prose form. Standards should be scannable, not essays.
+
+## Full Loop Example
+
+1. Present findings for an area
+2. User selects which to document
+3. Ask why for first standard
+4. User explains the reasoning
+5. Draft the standard incorporating their answer
+6. User confirms
+7. Create the file
+8. Move to next standard and repeat
+
+Complete the full ask-draft-confirm-create cycle for each standard before starting the next one.

plugins/agent-os/prompts/fw.agent_os.index_standards.md

@@ -0,0 +1,110 @@
+# 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. Propose a one-sentence description to the user for confirmation
+
+Keep descriptions to **one short sentence** -- they are 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 the removed entries.
+
+### 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:
+- Number of new entries added
+- Number of stale entries removed
+- Number of entries unchanged
+- Total 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 do not need to call it separately after discovering standards.
+
+## Output
+
+Updates `agent-os/standards/index.yml`

plugins/agent-os/prompts/fw.agent_os.inject_standards.md

@@ -0,0 +1,82 @@
+# Inject Standards
+
+Inject relevant standards into the current context, formatted appropriately for the situation.
+
+## Usage Modes
+
+### Auto-Suggest Mode (no arguments)
+Analyzes context and suggests relevant standards.
+
+### Explicit Mode (with arguments)
+Directly injects specified standards without suggestions. Arguments can be:
+- **Folder name** -- `api` injects all `.md` files in `agent-os/standards/api/`
+- **Folder/file** -- `api/response-format` injects `agent-os/standards/api/response-format.md`
+- **Root folder** -- `root` injects all `.md` files directly in `agent-os/standards/` (not in subfolders)
+- **Root file** -- `root/naming` injects `agent-os/standards/naming.md`
+- Multiple arguments inject multiple standards
+
+## Process
+
+### Step 1: Detect Context Scenario
+
+Determine which scenario applies:
+
+1. **Conversation** -- Regular chat, implementing code, answering questions
+2. **Creating a Skill** -- Building a reusable procedure or skill file
+3. **Shaping/Planning** -- Building a spec, planning significant work
+
+If the scenario is not clearly one of these, ask the user to confirm.
+
+### 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 does not exist or is empty, advise the user to run discover-standards first, or index-standards if they have standards files without an index.
+
+### Step 3: Analyze Work Context
+
+Look at the current conversation to understand:
+- What type of work? (API, database, UI, etc.)
+- What technologies mentioned?
+- What is the goal?
+
+### Step 4: Match and Suggest
+
+Match index descriptions against the context. Present 2-5 relevant standards and ask the user to confirm.
+
+### Step 5: Inject Based on Scenario
+
+#### Scenario: Conversation
+Read the standards and present them directly with the full content of each standard file, followed by a summary of key points.
+
+#### Scenario: Creating a Skill
+Ask whether to include standards as file references or full content copy:
+- **References** -- Add file paths that point to the standards (lightweight, stays in sync)
+- **Copy content** -- Paste the full standards content (self-contained, does not update if standards change)
+
+#### Scenario: Shaping/Planning
+Same choice as Creating a Skill -- references or full content copy.
+
+### Step 6: Surface Related Skills (Conversation scenario only)
+
+When in conversation scenario, check if related skills exist and surface them for awareness. Do not invoke skills automatically.
+
+## Explicit Mode
+
+When arguments are provided, skip the suggestion step but still detect scenario.
+
+1. Parse arguments (folder names, folder/file paths, or root keyword)
+2. Validate that specified files/folders exist
+3. If not found, show available standards and suggest alternatives
+4. Inject 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, rebuild the index
+- **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.