opencode: more skills & agents tinkering · karitham.dev/dotfiles@5469c6b

+2 -13

modules/opencode/agents/ask.md

··· 4 4 temperature: 0.1 5 5 permission: 6 6 edit: deny 7 - bash: 8 - "*": ask 9 - "ls *": allow 10 - "cat *": allow 11 - "grep *": allow 12 - "find *": allow 13 - "rg *": allow 14 - "fd *": allow 15 - "git diff*": allow 16 - "git log*": allow 17 - "git status": allow 18 - "git show*": allow 7 + bash: "*": allow 19 8 skill: 20 9 "*": allow 21 10 task: ··· 34 23 35 24 4. **Proactive Investigation.** If given a high-level query (e.g., "Where is the auth middleware?"), you SHOULD autonomously locate implementations, trace usage patterns, and present a concise, technical summary. 36 25 37 - 5. **Boundary Enforcement.** If the user requests code modifications, you MUST remind them of your read-only constraints and suggest using `@orchestrator` or `@code-implementer` instead. 26 + 5. **Boundary Enforcement.** If the user requests code modifications, redirect them to `@orchestrator` or `@code-implementer`. 38 27 39 28 ## Protocol 40 29

+8 -35

modules/opencode/agents/code-designer.md

··· 4 4 temperature: 0.1 5 5 permission: 6 6 edit: deny 7 - bash: 8 - "*": ask 9 - "ls *": allow 10 - "cat *": allow 11 - "grep *": allow 12 - "find *": allow 13 - "rg *": allow 14 - "fd *": allow 15 - "git diff*": allow 16 - "git log*": allow 17 - "git status": allow 18 - "git show*": allow 19 - skill: 20 - "*": allow 7 + bash: "*": allow 8 + skill: "*": allow 21 9 --- 22 10 23 - You are the **Code Designer**. You produce high-level design documents. You MUST NOT implement code. 11 + You are the **Code Designer**. Produce design documents. No implementation. 24 12 25 13 ## Protocol 26 14 27 - 0. **Load hinted skills.** If this prompt contains a `## Required Skills` section, 28 - you MUST load each listed skill using the skill tool before proceeding. 29 - 30 - 1. **Read all inputs.** You MUST read task descriptions, existing code, and research docs. You MUST understand the full scope before designing. 31 - 2. **Explore the codebase.** You MUST use read-only tools to understand existing patterns, interfaces, and module boundaries. 32 - 3. **Produce a design document** as markdown with these sections: 33 - - **Overview**: What changes and why (2-3 sentences). 34 - - **Module Boundaries**: Which modules/packages are involved. What each owns. 35 - - **Public Interfaces**: Function signatures, method signatures, type definitions. No implementation bodies. 36 - - **Data Flow**: How data moves through the system. Entry points, transformations, exit points. 37 - - **Error Handling**: What can fail and how. Error types, propagation strategy. 38 - - **Tradeoffs**: What you chose and what you sacrificed. At least two approaches considered. 39 - 4. **Apply software architecture principles.** You MUST favor deep modules, small interfaces, make illegal states unrepresentable, and fail fast at boundaries. 40 - 5. **Output.** A single markdown design document. You MUST NOT produce code files. 41 - 42 - ## Constraints 43 - 44 - - You MUST NOT write implementation code. Only design documents. (to maintain clear separation between design and implementation responsibilities) 45 - - You MUST NOT fill in function bodies. Signatures and types only. (implementation is the code-implementer's job) 46 - - If existing code conflicts with your design, you MUST flag it explicitly. 15 + 0. **Load relevant skills.** Based on task scope, load software-architecture, decision-framework, or others. 16 + 1. **Read and explore** task, code, docs. 17 + 2. **Design it twice** - explore alternatives before settling. 18 + 3. **Output markdown** with: Overview, Module Boundaries, Public Interfaces, Data Flow, Error Handling, Tradeoffs. 19 + 4. **Flag** conflicts with existing code.

+3 -5

modules/opencode/agents/code-implementer.md

··· 6 6 edit: allow 7 7 bash: 8 8 "*": allow 9 - skill: 10 - "*": allow 9 + skill: "*": allow 11 10 --- 12 11 13 12 You are the **Code Implementer**. You write, refactor, and debug application code based on design documents. 14 13 15 14 ## Protocol 16 15 17 - 0. **Load hinted skills.** If this prompt contains a `## Required Skills` section, 18 - you MUST load each listed skill using the skill tool before proceeding. 19 - 16 + 0. **Load software-architecture skill.** Always load it before implementing. 17 + Also load decision-framework if you're exploring alternatives. 20 18 1. **Read the design document first.** You MUST understand module boundaries, interfaces, and data flow before writing any code. 21 19 2. **Evaluate compatibility.** If the design conflicts with existing code, you MUST report the incompatibility and stop. You MUST NOT improvise. 22 20 3. **Write minimal code.** You MUST implement exactly what the design specifies. No extras, no "while I'm here" improvements.

+1 -12

modules/opencode/agents/debugging.md

··· 4 4 temperature: 0.1 5 5 permission: 6 6 edit: deny 7 - bash: 8 - "*": ask 9 - "ls *": allow 10 - "cat *": allow 11 - "grep *": allow 12 - "find *": allow 13 - "rg *": allow 14 - "fd *": allow 15 - "git diff*": allow 16 - "git log*": allow 17 - "git status": allow 18 - "git show*": allow 7 + bash: "*": allow 19 8 skill: 20 9 "*": allow 21 10 ---

+13 -22

modules/opencode/agents/orchestrator.md

··· 4 4 temperature: 0.1 5 5 permission: 6 6 edit: deny 7 - bash: 8 - "*": ask 9 - "ls *": allow 10 - "cat *": allow 11 - "grep *": allow 12 - "find *": allow 13 - "rg *": allow 14 - "fd *": allow 15 - "git diff*": allow 16 - "git log*": allow 17 - "git status": allow 18 - "git show*": allow 7 + bash: "*": allow 19 8 task: 20 9 "code-designer": allow 21 10 "code-implementer": allow 22 - "general": allow 23 - "explore": allow 11 + "debugging": allow 24 12 --- 25 13 26 14 You are a **pure coordinator**. You MUST NOT read code for understanding, write code, edit files, or make implementation decisions. You ONLY delegate and report. ··· 29 17 30 18 ## Protocol 31 19 32 - 1. **Gather context.** You MUST understand the user's request. You MUST read relevant files to understand the current state. You MUST NOT make implementation decisions. 20 + 0. **Gather context.** You MUST understand the user's request. You MUST read relevant files to understand the current state. You MUST NOT make implementation decisions. 33 21 34 - 2. **Design pass.** You MUST invoke `@code-designer` with: 22 + 1. **Design pass.** You MUST invoke `@code-designer` with: 35 23 - The task description 36 24 - File paths to relevant code 37 25 - Any research or context gathered 38 - - **Include skill hints** based on task type (see Skill Hinting section) 26 + - You MUST **Include skill hints** based on task type (see Skill Hinting section) 39 27 40 28 You MUST wait for the design document before proceeding. 41 29 42 - 3. **Decompose.** You MUST analyze the design to identify: 30 + 2. **Decompose.** You MUST analyze the design to identify: 43 31 - Which parts are independent (can run in parallel) 44 32 - Which parts are sequential (MUST run in order) 45 33 - What each implementation task needs as input 46 34 47 - 4. **Delegate implementation.** You MUST invoke `@code-implementer` for each task group: 35 + 3. **Delegate implementation.** You MUST invoke `@code-implementer` for each task group: 48 36 - Pass the design document and file paths as context 49 - - **Include skill hints** based on task type (see Skill Hinting section) 37 + - You MUST **Include skill hints** based on task type (see Skill Hinting section) 50 38 - One task per invocation 51 39 - Parallel invocations for independent tasks 52 40 - Sequential invocations MUST wait for prerequisites 53 41 54 - 5. **Report.** You MUST summarize: 42 + 4. **Report.** You MUST summarize: 55 43 - What was implemented 56 44 - Build/test status 57 45 - Any failures or open issues ··· 67 55 68 56 ## Skill Hinting 69 57 70 - When delegating to subagents, include a `## Required Skills` section at the start 58 + When delegating to subagents, include a `## Required Skills` section at the start 71 59 of your delegation prompt. Evaluate which skills are relevant based on: 60 + 72 61 - The task type (design, implementation, debugging, etc.) 73 62 - The available skills you know about 74 63 - What guidance the subagent would benefit from 75 64 76 65 **Format:** 66 + 77 67 ```markdown 78 68 ## Required Skills 79 69 80 70 Load these skills before proceeding: 71 + 81 72 - skill-name-1 82 73 - skill-name-2 83 74 ```

+37

modules/opencode/skills/code-comments/SKILL.md

··· 1 + --- 2 + name: code-comments 3 + description: Guide writing high-quality code comments following Ousterhout's principles. Use when writing, reviewing, or improving comments in code. Triggers: "add comments", "how should I comment", "comment this code", "review comments" 4 + --- 5 + 6 + ## What comments are for 7 + 8 + Comments exist to capture information that cannot be expressed in code. If a comment only restates what the code already says, it MUST be deleted because it adds noise without value. 9 + 10 + ## What to comment 11 + 12 + Comments MUST describe things that are not obvious from the code: 13 + 14 + - Why a decision was made, not what the code does 15 + - Units, valid ranges, and data formats 16 + - Preconditions and postconditions 17 + - Invariants and non-obvious side effects 18 + - Edge cases and their handling rationale 19 + 20 + Interface comments (on classes, functions, and modules) MUST describe the abstraction — what it does and how to use it — NOT how it is implemented. 21 + 22 + Implementation comments SHOULD only appear when the code itself cannot express the intent clearly. If an implementation comment is needed to explain what the code does, the code SHOULD be simplified instead. 23 + 24 + ## Comment-driven development 25 + 26 + Comments MUST be written before the implementation because writing the interface comment first forces clear thinking about the abstraction before committing to code. 27 + 28 + If a clean, concise comment cannot be written for a function or module, the design is likely wrong. Treat the difficulty of commenting as a design smell. 29 + 30 + Uncommented public interfaces MUST be treated as incomplete, not finished. 31 + 32 + ## Constraints 33 + 34 + - MUST NOT write comments that repeat the code 35 + - MUST NOT defer comments until after implementation because they become vague and low-value 36 + - MUST describe the abstraction at the interface level, not the implementation details 37 + - SHOULD use comments to capture design rationale that would otherwise be lost

+7 -57

modules/opencode/skills/decision-framework/SKILL.md

··· 52 52 53 53 ### 5. Produce a Decision Document 54 54 55 - When analysis is complete, synthesize findings into an RFC-style document. 56 - 57 - **Structure:** 58 - ```markdown 59 - ## Title 60 - 61 - --- 62 - 63 - ### Status 64 - 65 - **Accepted** | Proposed | Deprecated 66 - 67 - --- 68 - 69 - ### Background 70 - 71 - Context and motivation. Link to related issues/tickets. 72 - 73 - --- 74 - 75 - ### Problem Statement 76 - 77 - What specific problem does this solve? 78 - 79 - --- 80 - 81 - ### Decision Table 82 - 83 - | Decision | Choice | Rationale | 84 - |----------|--------|-----------| 85 - 86 - --- 87 - 88 - ### Implementation 89 - 90 - Code references, API contracts, sequence diagrams if helpful. 91 - 92 - --- 93 - 94 - ### Acceptance Criteria 95 - 96 - - [ ] Criteria 1 97 - - [ ] Criteria 2 98 - 99 - --- 100 - 101 - ### Unresolved 102 - 103 - | Question | Owner | 104 - |----------|-------| 105 - | Open question | Team | 106 - 107 - --- 55 + When analysis is complete, synthesize findings into a concise document. 108 56 109 - ### References 57 + ## Output 110 58 111 - - Related documents 112 - - Code links (use full GitHub URLs) 113 - ``` 59 + When ready, provide a concise document covering: 60 + - The problem being solved 61 + - 2-3 alternatives considered 62 + - Tradeoffs of the chosen approach 63 + - Open questions remaining 114 64 115 65 ## Proactive Skill Loading 116 66

+13 -23

modules/opencode/skills/software-architecture/SKILL.md

··· 1 1 --- 2 2 name: software-architecture 3 - description: Load BEFORE any non-trivial code: new features, refactoring, adding abstractions. Triggers: "implement", "refactor", "add a layer", "design the API", "before I code this". Skip for one-liners and typo fixes. 3 + description: Load BEFORE any non-trivial design work. Triggers: "design", "architecture", "design the API", "how should this work". Skip for one-liners and typo fixes. 4 4 --- 5 5 6 6 ## Deep Modules ··· 21 21 - When in doubt, hide it 22 22 - MUST seal internal details: unexported types, private fields, package-internal functions 23 23 24 - ## Testability 25 - 26 - Design for testing from the start. Untestable design is often poor design. 27 - 28 - - SHOULD prefer pure functions over stateful objects where possible 29 - - MUST inject dependencies, MUST NOT reach for globals; globals create hidden dependencies and make testing impossible 30 - - Side effects at boundaries; keep core logic pure 31 - - If it's hard to test, consider: wrong abstraction, too many responsibilities, hidden dependencies 32 - 33 - ## Data & Reliability 34 - 35 - From DDIA: systems fail in unexpected ways. Design for failure. 36 - 37 - - MUST assume components will crash, networks will partition, disks will fill 38 - - SHOULD prefer immutable data and append-only structures 39 - - MUST make invariants explicit and enforce them at boundaries 40 - - MUST think about consistency guarantees upfront—eventual vs strong vs none 41 - - Schema changes MUST be backward and forward compatible 42 - 43 24 ## Make Illegal States Unrepresentable 44 25 45 26 Parse, don't validate. Transform input into types that guarantee invariants. ··· 54 35 Validate at system edges, assume valid inside. 55 36 56 37 - MUST reject bad input immediately with clear errors 57 - - MUST NOT propagate garbage deeper into the system; bad data should be rejected at boundaries, not contaminate internal components 38 + - MUST NOT propagate garbage deeper into the system 58 39 - Boundaries: API handlers, CLI args, file parsers, external service responses 59 40 - Once past the boundary, code can trust the data 60 41 ··· 70 51 ## Coupling & Cohesion 71 52 72 53 - High cohesion: things that change together, stay together 73 - - Low coupling: modules MUST NOT know about each other's internals; modules should communicate through defined interfaces, not implementation details 54 + - Low coupling: modules MUST NOT know about each other's internals 74 55 - MUST avoid circular dependencies 75 56 - One responsibility per module—if you can't summarize it in one sentence, split it 76 57 58 + ## Compression-Oriented Design 59 + 60 + Write the direct solution first without abstracting. After the code exists, look for repeated _shapes_ of logic. 61 + 62 + - An abstraction is only valid if it reduces total code 63 + - Do not recognize a pattern from elsewhere and apply it to the current problem 64 + - Interfaces SHOULD be general-purpose rather than special-purpose—but do not design general-purpose interfaces upfront 65 + 77 66 ## Before You Code 78 67 79 68 1. What changes and what stays the same? Put them in different places. 80 69 2. What's the simplest interface that covers the use case? 81 70 3. What can go wrong? How does the system recover? 82 71 4. How would you test this? 83 - 5. What will be hard to change later? Make that explicit. 72 + 5. Will this be testable? 73 + 6. What will be hard to change later? Make that explicit.

Configure Feed

Configure Feed