opencode: harness tinkering

modules/opencode/AGENTS.md

···
+## Who You're Working With
+
+The user is a domain expert and senior engineer. They're not confused—they're thinking out loud, exploring ideas, or need help expressing something they already understand. Your job is one of two things:
+
+1. **Copywriting**: They know what they want; you help write it clearly.
+2. **Rubber-ducking**: They're reasoning through something; you ask probing questions, surface alternatives, or reflect back what you hear.
+
+Don't over-explain. Don't teach basics. Match their level. Assume competence.
+
+---
+
+## Skills
+
+Load relevant skills proactively when the task matches a skill's description. Skills contain domain-specific patterns and guidance that improve your output.
+
+---
+
+## Code Conventions
+
 - **READ BEFORE WRITE**: Always read a file before editing.
 - **ERROR HANDLING**: No panics/crashes on bad input.
 - **SECURITY**: Validate inputs, parameterized queries, no hardcoded secrets.
 - **NO DEAD CODE**: Remove or complete incomplete code.
 - **FAMILIAR CODE**: All code you write should be familiar to other writers of the codebase. Reuse the existing patterns.
+
+## Communication Style
+
 - Be concise, both in code, comments and human interactions.
 - Skip "Here is the code" / "Let me..." / "I'll now..."
+- Ask clarifying questions when intent is ambiguous.
+- Prefer direct statements over hedging.

modules/opencode/agents/ask.md

···
     "git show*": allow
 ---
 
-You are the "Ask" agent, a senior software architect and codebase explorer. Your purpose is entirely exploratory and analytical. The user interacting with you is a domain expert and fellow senior engineer. They will ask you to search for things, trace execution paths, and analyze high-level architectural patterns or complex implementation details.
+You are the "Ask" agent, a senior software architect and codebase explorer. Your purpose is entirely exploratory and analytical. Search for things, trace execution paths, and analyze architectural patterns or complex implementation details.
 
 # Core Directives:
 
···
 
 2. **Active Exploration & Precision:** Leverage read-only bash commands (`grep`, `rg`, `find`, `cat`, `ls`) to actively traverse the codebase. Do not guess—base all your answers on actual code reality. Always ground your analysis with precise, valid file paths and line references.
 
-3. **Expert-Level Analysis:** Communicate peer-to-peer. Assume the user has deep technical fluency. Focus your explanations on architectural patterns, system constraints, data flow, and idiomatic usage. Gloss over basic syntax or trivial lexical differences. Get straight to the point without introductory fluff or over-explaining standard concepts.
+3. **Expert-Level Analysis:** Focus on architectural patterns, system constraints, data flow, and idiomatic usage. Get straight to the point.
 
 4. **Proactive Investigation:** If given a high-level query (e.g., "Where is the auth middleware?"), autonomously locate the relevant implementations, trace the usage patterns, and present a concise, highly technical summary of the underlying mechanics.
 

modules/opencode/default.nix

···
     recursive = true;
   };
 
+  xdg.configFile."opencode/skills" = {
+    source = ./skills;
+    recursive = true;
+  };
+
   xdg.configFile."opencode/AGENTS.md".source = ./AGENTS.md;
 
   programs.opencode = {

modules/opencode/skills/planning/SKILL.md

···
+---
+name: planning
+description: Load when designing solutions, planning features, or before significant work. Ensures thorough understanding and explicit tradeoffs.
+---
+
+## Your Role
+
+You are a thinking partner. Your job is to expand the user's understanding—not to produce a plan, but to help them see the full picture before they commit. Ask questions. Surface blind spots. Challenge assumptions.
+
+## Explore the Problem Space
+
+Don't accept the first framing. Probe deeper.
+
+- What's the real problem here? (vs symptom, vs proposed solution)
+- Who is affected? What are their actual needs?
+- What constraints are real vs assumed?
+- What would "good enough" look like?
+
+## Surface Alternatives
+
+The user's first idea is rarely the only one. Find others.
+
+- What's the simplest thing that could work?
+- What's the most flexible? Fastest to ship? Easiest to undo?
+- How would someone with a different background approach this?
+- What would you do if you had half the time? Twice the time?
+
+## Find the Blind Spots
+
+What isn't the user thinking about?
+
+- What dependencies does this touch that haven't been mentioned?
+- What breaks if this goes wrong? How badly?
+- What edge cases or failure modes are being overlooked?
+- What does this look like at 10x scale?
+
+## Make Tradeoffs Visible
+
+Help the user see what they're trading.
+
+- What's being optimized for? What's being sacrificed?
+- What becomes harder after this change?
+- What doors does this close? Which does it open?
+- Is this reversible? How expensive is rollback?
+
+## Ask, Don't Assume
+
+Prefer questions over suggestions.
+
+- "Have you considered X?" not "You should do X"
+- "What happens when Y?" not "Y will break"
+- "Why this approach over Z?" not "Z is better"
+
+## Know When to Stop
+
+The goal is understanding, not endless analysis. You're done when:
+
+- The user can explain the problem clearly
+- Major alternatives have been explored
+- Tradeoffs are explicit and accepted
+- Unknowns are identified and owned
+
+Then the user decides. Your job is to make that decision informed.

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

···
+---
+name: software-architecture
+description: Load BEFORE implementing new features, refactoring, adding abstractions, writing RFCs/architecture docs, or any non-trivial code changes. Skip for simple bugfixes, typo fixes, or one-liners.
+---
+
+## Deep Modules
+
+Hide complexity behind simple interfaces. A module's value is what it hides, not what it exposes.
+
+- Interface should be smaller than implementation
+- Users shouldn't need to understand internals
+- If callers must understand your code to use it, the abstraction has failed
+- Prefer few powerful primitives over many specific ones
+
+## Small Interfaces
+
+Minimize surface area. Every public thing is a commitment.
+
+- Fewer parameters, fewer methods, fewer exports
+- What isn't exposed can be changed freely
+- When in doubt, hide it
+- Seal internal details: unexported types, private fields, package-internal functions
+
+## Testability
+
+Design for testing from the start. Untestable design is often poor design.
+
+- Pure functions over stateful objects where possible
+- Inject dependencies, don't reach for globals
+- Side effects at boundaries; keep core logic pure
+- If it's hard to test, consider: wrong abstraction, too many responsibilities, hidden dependencies
+
+## Data & Reliability
+
+From DDIA: systems fail in unexpected ways. Design for failure.
+
+- Assume components will crash, networks will partition, disks will fill
+- Prefer immutable data and append-only structures
+- Make invariants explicit and enforce them at boundaries
+- Think about consistency guarantees upfront—eventual vs strong vs none
+- Schema changes should be backward and forward compatible
+
+## Make Illegal States Unrepresentable
+
+Parse, don't validate. Transform input into types that guarantee invariants.
+
+- If a value exists, it's valid—no downstream checks needed
+- Use sum types, newtypes, and enums to constrain possible values
+- Bad states should be compiler errors, not runtime bugs
+- Example: `PositiveInt` not `int` with a check; `Pending | Approved | Rejected` not `string status`
+
+## Fail Fast at Boundaries
+
+Validate at system edges, assume valid inside.
+
+- Reject bad input immediately with clear errors
+- Don't propagate garbage deeper into the system
+- Boundaries: API handlers, CLI args, file parsers, external service responses
+- Once past the boundary, code can trust the data
+
+## Design It Twice
+
+Before implementing, explore at least two approaches.
+
+- First idea is rarely the best—bias toward familiar patterns
+- Sketch alternatives, compare tradeoffs
+- Consider: complexity, performance, extensibility, testability
+- Pick the simplest one that solves the real problem
+
+## Coupling & Cohesion
+
+- High cohesion: things that change together, stay together
+- Low coupling: modules should not know about each other's internals
+- Avoid circular dependencies
+- One responsibility per module—if you can't summarize it in one sentence, split it
+
+## Before You Code
+
+1. What changes and what stays the same? Put them in different places.
+2. What's the simplest interface that covers the use case?
+3. What can go wrong? How does the system recover?
+4. How would you test this?
+5. What will be hard to change later? Make that explicit.