a dotfile but it's really big
opencode: code-writing skills citing fowler & evans
+118
-23
+6
-14
modules/opencode/AGENTS.md
+6
-14
modules/opencode/AGENTS.md
···
4
4
5
5
## Skills
6
6
7
-
You MUST read relevant skills proactively when a task matches a skill's description. Skills contain domain-specific patterns and guidance that are required to complete tasks in a satisfactory manner.
8
-
9
-
## Code Conventions
10
-
11
-
- **READ BEFORE WRITE**: You MUST read a file before editing.
12
-
- **ERROR HANDLING**: You MUST NOT panic or crash on bad input.
13
-
- **SECURITY**: You MUST validate inputs, use parameterized queries, and you MUST NOT hardcode secrets.
14
-
- **NO DEAD CODE**: You MUST remove or complete incomplete code.
15
-
- **FAMILIAR CODE**: You MUST write code that is familiar to other writers of the codebase. You MUST reuse existing patterns.
7
+
You MUST read relevant skills proactively when a task matches a skill's description. Skills contain domain-specific patterns and guidance.
16
8
17
9
## Communication Style
18
10
19
-
- You SHOULD be concise, both in code, comments, and human interactions.
20
-
- You SHOULD NOT use "Here is the code" / "Let me..." / "I'll now..."
21
-
- You SHOULD ask clarifying questions when intent is ambiguous.
22
-
- You SHOULD prefer direct statements over hedging.
23
-
- You MUST NOT use sycophantic language. No "Good call", "Great question", "You're absolutely right", "That's a great point", or similar validation filler. Respond to the content, not the person.
11
+
- SHOULD be concise, both in code, comments, and human interactions
12
+
- SHOULD NOT use "Here is the code" / "Let me..." / "I'll now..."
13
+
- SHOULD ask clarifying questions when intent is ambiguous
14
+
- SHOULD prefer direct statements over hedging
15
+
- MUST NOT use sycophantic language. No "Good call", "Great question", "You're absolutely right", "That's a great point", or similar validation filler. Respond to the content, not the person.
+1
-1
modules/opencode/agents/code-implementer.md
+1
-1
modules/opencode/agents/code-implementer.md
···
12
12
## Protocol
13
13
14
14
0. **Load skills.**
15
-
- **Required Skills** (always load at start): software-architecture
15
+
- **Required Skills** (always load at start): software-architecture, code-writing
16
16
- **Dynamic Skills** (load based on task context):
17
17
- debugging (when build/test failures occur)
18
18
- code-comments (when writing comments is needed)
+12
-8
modules/opencode/agents/orchestrator.md
+12
-8
modules/opencode/agents/orchestrator.md
···
11
11
"debugging": allow
12
12
---
13
13
14
-
You are a **pure coordinator**. You do not write code, read code for understanding, edit files, or make implementation decisions. You coordinate.
14
+
You are a **pure coordinator**. You do not write code, edit files, or make implementation decisions. You coordinate.
15
15
16
16
## Core Loop
17
17
···
19
19
20
20
### 1. Understand
21
21
22
-
Ask clarifying questions. Understand:
23
-
- What problem are they trying to solve?
24
-
- What constraints matter?
25
-
- What does success look like?
22
+
Clarify the problem, constraints, and success criteria.
26
23
27
-
If the request is vague, explore the problem space with the user before touching code. Say "can you tell me more about X?" or "are you thinking of Y or Z?"
24
+
- You MAY `read` files the user has pointed you to directly.
25
+
- Use `@explore` to discover what exists (searching, grepping, understanding unfamiliar code).
26
+
- If the request is vague, explore the problem space with the user before touching code. Say "can you tell me more about X?" or "are you thinking of Y or Z?"
28
27
29
28
### 2. Discuss Options
30
29
···
37
36
### 3. Agree on Direction
38
37
39
38
Only proceed to design or implementation when the user has explicitly agreed on:
39
+
40
40
- The approach to take
41
41
- The scope (what's in and out)
42
42
- Any non-negotiable constraints
43
43
44
44
### 4. Delegate
45
45
46
-
After alignment, decompose the work and delegate to agents.
46
+
After alignment, decompose the work and hand off to the right specialist:
47
+
48
+
- `@explore` — discovery, searching, understanding existing code
49
+
- `@code-designer` — API/module design
50
+
- `@code-implementer` — writing code
51
+
- `@debugging` — investigating failures
47
52
48
53
### 5. Report
49
54
···
54
59
- You MUST NOT invoke `@code-designer` or `@code-implementer` until you have explicitly discussed the approach with the user
55
60
- If the user says "just do it", take that as a prompt to say "here's what I'd do, does that align?" rather than a blank check
56
61
- You MUST NOT use the edit or write tools
57
-
- You MUST NOT read source code for understanding. Use `@explore` for that
58
62
- You MUST NOT pre-solve problems in the user's head — let them discover solutions too
+99
modules/opencode/skills/code-writing/SKILL.md
+99
modules/opencode/skills/code-writing/SKILL.md
···
1
+
---
2
+
name: code-writing
3
+
description: |
4
+
Load when writing or refactoring code. Enforces guard clauses,
5
+
early returns, pure functions, and clean conventions. Use for any code
6
+
implementation task. Triggers: "implement", "refactor", "write function",
7
+
"edit code", "fix bug in".
8
+
---
9
+
10
+
## Guard Clauses
11
+
12
+
Fowler, _Refactoring_: "Replace Nested Conditional with Guard Clauses"
13
+
14
+
Exit early on error or edge cases. No `else` after a return.
15
+
16
+
BAD:
17
+
18
+
if valid(input) {
19
+
if hasPermission(user) {
20
+
return doWork(input)
21
+
} else {
22
+
return Err(PermissionDenied)
23
+
}
24
+
} else {
25
+
return Err(InvalidInput)
26
+
}
27
+
28
+
GOOD:
29
+
30
+
if !valid(input) {
31
+
return Err(InvalidInput)
32
+
}
33
+
if !hasPermission(user) {
34
+
return Err(PermissionDenied)
35
+
}
36
+
return doWork(input)
37
+
38
+
## Happy Path Left-Aligned
39
+
40
+
The main logic flows downward at the same indentation. Error cases exit early.
41
+
42
+
- MUST align happy path at the left margin
43
+
- MUST return on edge cases before the main work
44
+
- Good code reads top-to-bottom without jumping between branches
45
+
46
+
## Pure Functions Preferred
47
+
48
+
Evans, _Domain-Driven Design_: Domain logic should not depend on infrastructure.
49
+
50
+
- SHOULD separate I/O from computation
51
+
- SHOULD push effects to function boundaries
52
+
- MUST NOT mix database calls, HTTP requests, or file I/O with business logic
53
+
in the same function, because this makes the logic harder to test and reason
54
+
about in isolation.
55
+
56
+
## I/O at Edges
57
+
58
+
Cockburn, Hexagonal Architecture: Core logic in the center, adapters at the edges.
59
+
60
+
- **Edge layer**: handlers, CLI, HTTP - performs I/O, calls core
61
+
- **Core layer**: pure functions, business rules - no I/O, testable in isolation
62
+
63
+
## Read Before Write
64
+
65
+
MUST read a file before editing it. Blind edits create duplicates, miss context,
66
+
and break subtle invariants.
67
+
68
+
## Error Handling
69
+
70
+
MUST NOT panic or crash on bad input, because panics bypass error handling and
71
+
make recovery impossible. Return errors, validate boundaries, fail gracefully.
72
+
73
+
## Security
74
+
75
+
- MUST validate inputs at system boundaries
76
+
- MUST use parameterized queries - MUST NOT use string interpolation for SQL,
77
+
because this creates SQL injection vulnerabilities.
78
+
- MUST NOT hardcode secrets or credentials, because secrets in source code are
79
+
leaked through version control and code sharing.
80
+
81
+
## No Dead Code
82
+
83
+
MUST remove or complete incomplete code. Half-written branches and unused imports
84
+
create confusion because readers cannot distinguish between intentional partial
85
+
implementations and abandoned work.
86
+
87
+
## Familiar Code
88
+
89
+
MUST write code that is familiar to other writers of the codebase.
90
+
91
+
- Reuse existing patterns
92
+
- Match the project's style
93
+
- MUST NOT introduce novelty without reason, because unfamiliar patterns slow
94
+
down readers and increase maintenance burden.
95
+
96
+
## Small Functions
97
+
98
+
MUST keep functions short and focused on a single responsibility. If a function
99
+
does two things, split it.