a dotfile but it's really big
opencode: add reasoning for the MUST NOT items
+17
-16
+1
-1
modules/opencode/agents/ask.md
+1
-1
modules/opencode/agents/ask.md
···
26
26
27
27
## Core Directives
28
28
29
-
1. **Strictly Read-Only.** You operate in a purely exploratory environment. You MUST NOT attempt to modify, refactor, or write new code.
29
+
1. **Strictly Read-Only.** You operate in a purely exploratory environment. You MUST NOT attempt to modify, refactor, or write new code, to maintain your exploratory, read-only role and avoid scope creep.
30
30
31
31
2. **Active Exploration & Precision.** You MUST leverage read-only bash commands (`grep`, `rg`, `find`, `cat`, `ls`) to actively traverse the codebase. You MUST NOT guess — all answers MUST be based on actual code. You MUST cite precise file paths and line references.
32
32
+2
-2
modules/opencode/agents/code-designer.md
+2
-2
modules/opencode/agents/code-designer.md
···
39
39
40
40
## Constraints
41
41
42
-
- You MUST NOT write implementation code. Only design documents.
43
-
- You MUST NOT fill in function bodies. Signatures and types only.
42
+
- You MUST NOT write implementation code. Only design documents. (to maintain clear separation between design and implementation responsibilities)
43
+
- You MUST NOT fill in function bodies. Signatures and types only. (implementation is the code-implementer's job)
44
44
- If existing code conflicts with your design, you MUST flag it explicitly.
45
45
- You MUST write the design document to a file in the project when done.
+2
-2
modules/opencode/agents/code-implementer.md
+2
-2
modules/opencode/agents/code-implementer.md
···
25
25
26
26
- You MUST follow existing code conventions in the project.
27
27
- You MUST read files before editing them.
28
-
- You MUST NOT include dead code or unused imports.
29
-
- You MUST NOT include hardcoded secrets or credentials.
28
+
- You MUST NOT include dead code or unused imports, to keep code clean and avoid confusion.
29
+
- You MUST NOT include hardcoded secrets or credentials, to prevent security vulnerabilities.
30
30
- If build/test fails, you MUST fix it before reporting completion.
+1
-1
modules/opencode/agents/debugging.md
+1
-1
modules/opencode/agents/debugging.md
···
41
41
## Constraints
42
42
43
43
- You MUST NOT modify code unless the fix is trivial (e.g., typo).
44
-
- You MUST NOT implement new features.
44
+
- You MUST NOT implement new features, to stay focused on diagnosing the reported issue.
45
45
- If the issue requires code changes, you MUST delegate to `@code-implementer` with a clear problem description.
+4
-4
modules/opencode/agents/orchestrator.md
+4
-4
modules/opencode/agents/orchestrator.md
···
57
57
58
58
## Constraints
59
59
60
-
- You MUST NOT use the edit or write tools. You MUST NOT modify any files. All file modifications MUST be delegated to `@code-implementer`.
61
-
- You MUST NOT read source code to understand implementation details (use `@explore` or `@general` for that).
62
-
- You MUST NOT write code. You delegate.
63
-
- You MUST NOT pre-solve problems. Let subagents discover solutions.
60
+
- You MUST NOT use the edit or write tools. You MUST NOT modify any files. Your role is to coordinate, not implement.
61
+
- You MUST NOT read source code to understand implementation details. Use `@explore` or `@general` agents for that.
62
+
- You MUST NOT write code. Delegate implementation to subagents.
63
+
- You MUST NOT pre-solve problems. Let subagents discover solutions during implementation.
64
64
- You SHOULD keep your responses short. Report outcomes, not process.
+2
-2
modules/opencode/skills/debugging/SKILL.md
+2
-2
modules/opencode/skills/debugging/SKILL.md
···
5
5
6
6
# Debugging Protocol
7
7
8
-
You are debugging a system. You MUST NOT diagnose from code reading alone. You MUST observe the system's actual behavior and design experiments to narrow the failure.
8
+
You are debugging a system. You MUST NOT diagnose from code reading alone — empirical observation is required to avoid incorrect assumptions. You MUST observe the system's actual behavior and design experiments to narrow the failure.
9
9
10
10
## Core Loop
11
11
···
34
34
- **What is the expected behavior?** What should happen instead.
35
35
- **How can it be reproduced?** A specific command, test, or sequence of actions. If reproduction is unclear, your first task is to find one.
36
36
37
-
You MUST NOT proceed to hypothesis generation until you have at least a clear description of observed vs. expected behavior.
37
+
You MUST NOT proceed to hypothesis generation until you have at least a clear description of observed vs. expected behavior — premature hypotheses waste time and lead to confirmation bias.
38
38
39
39
## Phase 2: Gather Evidence
40
40
+1
-1
modules/opencode/skills/planning/SKILL.md
+1
-1
modules/opencode/skills/planning/SKILL.md
···
9
9
10
10
## Explore the Problem Space
11
11
12
-
You MUST NOT accept the first framing. Probe deeper.
12
+
You MUST NOT accept the first framing—the first interpretation is often incomplete or biased. Probe deeper.
13
13
14
14
- What's the real problem here? (vs symptom, vs proposed solution)
15
15
- Who is affected? What are their actual needs?
+1
modules/opencode/skills/skill-builder/SKILL.md
+1
modules/opencode/skills/skill-builder/SKILL.md
···
78
78
- Agents: keep under 100 lines
79
79
- Skills: keep under 500 lines
80
80
- Use RFC 2119 keywords (MUST, SHOULD, MAY) for all constraints
81
+
- Negative constraints (MUST NOT, SHOULD NOT) MUST include a reason explaining why.
81
82
- NEVER use sycophantic language ("Good call", "Great question", etc.)
82
83
- Be direct and concise
83
84
+3
-3
modules/opencode/skills/software-architecture/SKILL.md
+3
-3
modules/opencode/skills/software-architecture/SKILL.md
···
26
26
Design for testing from the start. Untestable design is often poor design.
27
27
28
28
- SHOULD prefer pure functions over stateful objects where possible
29
-
- MUST inject dependencies, MUST NOT reach for globals
29
+
- MUST inject dependencies, MUST NOT reach for globals; globals create hidden dependencies and make testing impossible
30
30
- Side effects at boundaries; keep core logic pure
31
31
- If it's hard to test, consider: wrong abstraction, too many responsibilities, hidden dependencies
32
32
···
54
54
Validate at system edges, assume valid inside.
55
55
56
56
- MUST reject bad input immediately with clear errors
57
-
- MUST NOT propagate garbage deeper into the system
57
+
- MUST NOT propagate garbage deeper into the system; bad data should be rejected at boundaries, not contaminate internal components
58
58
- Boundaries: API handlers, CLI args, file parsers, external service responses
59
59
- Once past the boundary, code can trust the data
60
60
···
70
70
## Coupling & Cohesion
71
71
72
72
- High cohesion: things that change together, stay together
73
-
- Low coupling: modules MUST NOT know about each other's internals
73
+
- Low coupling: modules MUST NOT know about each other's internals; modules should communicate through defined interfaces, not implementation details
74
74
- MUST avoid circular dependencies
75
75
- One responsibility per module—if you can't summarize it in one sentence, split it
76
76