# Standard: Subagent File Structure **Purpose**: Standard structure for subagent files **Priority**: CRITICAL - Load this before creating subagent files --- ## File Template ```markdown --- name: AgentName description: Brief description mode: subagent temperature: 0.1 tools: {...} permissions: {...} --- # AgentName > **Mission**: One-sentence mission Rule description Role in pipeline Expertise area What agent does Limitations - @rule_id: Description ## Workflow ### Step 1: Preparation ### Step 2: Execution ### Step 3: Output ## Output Format ```yaml status: "success" | "failure" ``` ``` --- ## Section Details ### 1. Frontmatter - ONLY valid OpenCode fields (see agent-frontmatter.md) - No duplicate keys, orphaned items, or invalid fields ### 2. Header + Mission ```markdown # TestEngineer > **Mission**: Author tests following TDD — grounded in project standards. ``` ### 3. Critical Rules (3-5 max) ```markdown ALWAYS call ContextScout BEFORE writing tests. EVERY behavior needs positive AND negative tests. ``` ### 4. Context ```markdown Code quality gate Code review, security, quality Review code against standards Read-only, no modifications ``` ### 5. Execution Tiers ```markdown - @context_first: Load context first - Load standards - Analyze code Tier 1 overrides Tier 2/3 ``` --- ## Tool Permission Patterns ### Read-Only (Reviewers, Analyzers) ```yaml tools: {read: true, grep: true, glob: true, bash: false, edit: false, write: false} permissions: bash: {"*": "deny"} edit: {"**/*": "deny"} task: {contextscout: "allow", "*": "deny"} ``` ### Write-Enabled (Coders, Testers) ```yaml tools: {read: true, edit: true, write: true, bash: true} permissions: bash: {"npm test *": "allow", "git *": "allow", "sudo *": "deny", "*": "deny"} edit: {"**/*.env*": "deny", "**/*.key": "deny"} task: {contextscout: "allow", "*": "deny"} ``` ### Restricted Bash (Task Managers) ```yaml tools: {read: true, bash: true} permissions: bash: {"npx ts-node*task-cli*": "allow", "mkdir -p .tmp/tasks*": "allow", "*": "deny"} ``` --- ## File Organization ``` .opencode/agent/subagents/ ├── code/ # tester, reviewer, coder-agent, build-agent ├── core/ # task-manager, contextscout, documentation ├── system-builder/ # agent-generator, command-creator └── utils/ # image-specialist ``` --- ## Validation Checklist - [ ] Valid OpenCode frontmatter (no extra fields)? - [ ] Mission statement present? - [ ] 3-5 critical rules with unique IDs? - [ ] Context section complete? - [ ] Execution tiers defined with conflict resolution? - [ ] Workflow steps clear and actionable? - [ ] Output format specified? - [ ] Tool permissions appropriate for role? - [ ] File in correct category directory? - [ ] No YAML syntax errors? --- ## Common Patterns **Context-First Pattern**: ```markdown ALWAYS call ContextScout BEFORE starting work. Load relevant standards first. ``` **Read-Only Pattern**: ```markdown Read-only agent. NEVER use write, edit, or bash. Provide suggestions only. ``` **Security Pattern**: ```markdown permissions: edit: "**/*.env*": "deny" "**/*.key": "deny" "**/*.secret": "deny" ``` --- ## Examples **See existing subagents**: - `.opencode/agent/subagents/code/tester.md` - Write-enabled with tests - `.opencode/agent/subagents/code/reviewer.md` - Read-only reviewer - `.opencode/agent/subagents/core/task-manager.md` - Restricted bash --- ## Related - **Frontmatter**: `standards/agent-frontmatter.md` - **Metadata**: `core-concepts/agent-metadata.md` - **Adding Agents**: `guides/adding-agent.md` --- **Last Updated**: 2026-01-31 | **Version**: 1.0.0