An OpenCode plugin that converts unstructured text into structured, consistent formats using speech act theory.
Add the plugin to your opencode.json and restart OpenCode:
{
"plugin": ["opencode-speech-act-theory"]
}Then just tell OpenCode what you want:
Rewrite my instruction files
Add a rule about using early returns
Unstructured or voice-transcribed input can be structured into a clear task hierarchy using the prompt tools.
For the theory behind the plugin, see Theoretical Foundation.
The plugin provides 7 tools organized into two pipelines.
Discovers, parses, formats, and writes instruction rules. The LLM drives each step.
discover-rules -> parse-rules -> format-rules -> rewrite-rules
-> add-rules
Reads instruction files from your opencode.json configuration. Accepts an optional files string of comma-separated paths to read specific files instead of running discovery.
Structures instruction file content or user input into validated rules JSON. The LLM decomposes the input into rule objects, the tool validates the structure. Call after discover-rules and before format-rules.
Converts parsed rules into human-readable formatted rule strings. Accepts an optional mode (verbose, balanced, or concise, default balanced). Validates the formatted rules and returns validated JSON. Call after parse-rules and before rewrite-rules or add-rules.
Writes formatted rule strings to instruction files, replacing existing content. Accepts an optional mode and an optional files string of comma-separated paths. Call after format-rules.
Appends formatted rule strings to an instruction file without rewriting existing content. Accepts an optional mode and an optional file path (defaults to the first discovered instruction file). Call after format-rules.
rewrite-rules [mode=concise]
rewrite-rules [files=a.md,b.md, mode=verbose]
add-rules [mode=concise]
Input:
Always use return await when returning promises from async functions. This provides
better stack traces and error handling. Arrow functions are the standard function
syntax. Do not use function declarations or function expressions because arrow
functions provide lexical this binding and a more compact syntax.
verbose - Full Rule/Reason pairs for every rule.
Rule: Use return await when returning promises from async functions.
Reason: Provides better stack traces and error handling.
Rule: Use arrow functions as the standard function syntax.
Reason: Arrow functions provide lexical this binding and a more compact syntax.
Rule: Do not use function declarations or function expressions.
Reason: Arrow functions are the standard syntax for the project.
balanced (default) - The LLM decides which rules need reasons.
Rule: Use return await when returning promises from async functions.
Reason: Provides better stack traces and error handling.
Rule: Use arrow functions as the standard function syntax.
Rule: Do not use function declarations or function expressions.
Reason: Arrow functions provide lexical this binding and a more compact syntax.
concise - Bullet list of directives only, no reasons.
- Use return await when returning promises from async functions.
- Use arrow functions as the standard function syntax.
- Do not use function declarations or function expressions.
Structures unstructured or voice-transcribed user input into a clear task hierarchy.
parse-prompt -> format-prompt
Structures user input into a validated task hierarchy. The LLM decomposes the input into tasks, the tool validates the structure.
Renders validated tasks from parse-prompt into a formatted markdown tree view.
parse-prompt [input=refactor the search module add guards to each provider make sure bsky and wiki get validated then run the tests]
Output:
┌ 1. Refactor the search module
│ > Targets: src/search.ts, src/providers/
│ > Constraints: use safeAsync, no optional chaining
│ > Context: Current error handling is inconsistent
│
├──┬ 2. Add guards to providers
│ │ > Targets: src/providers/
│ │ > Constraints: use isRecord helper
│ │
│ ├─── 3. Validate bsky responses
│ │ > Targets: bsky-search.ts
│ │
│ └─── 4. Validate wiki responses
│ > Targets: wiki-search.ts
│
├─── 5. Update error handling
│ > Targets: src/utils/safe.ts
│
└─── 6. Run the tests
> Constraints: fix any failures
The plugin is built on speech act theory (Austin, Searle). All instructions are directives: speech acts that get the hearer to do something. But directives come in two forms, and each needs a different formal framework.
Rules constrain ongoing behavior. They are standing obligations, prohibitions, and permissions that persist across all future actions. The formal framework is deontic logic: what is obligatory, forbidden, and permissible.
The LLM structures rule text into components, and the plugin validates:
type ParsedRule = {
strength: 'obligatory' | 'forbidden' | 'permissible' | 'optional' | 'supererogatory' | 'indifferent' | 'omissible'
action: string
target: string
context?: string
reason: string
}The strength field maps to deontic operators. The critical relationship is F(A) = O(not-A): a forbidden action must be negated in expression.
| Strength | Operator | Expression |
|---|---|---|
| obligatory | O(A) | positive imperative: "use consistent whitespace" |
| forbidden | F(A) = O(not-A) | negate with "do not": "do not use non-null assertions" |
| permissible | P(A) | prefix with "may": "may use type assertions when necessary" |
| optional | P(A) and P(not-A) | prefix with "may choose to": "may choose to add commit body" |
| supererogatory | beyond O(A) | prefix with "ideally": "ideally provide comprehensive documentation" |
| indifferent | P(A) and P(not-A) | prefix with "either way is fine": "either way is fine for naming style" |
| omissible | P(not-A) | prefix with "may omit": "may omit post-task explanations" |
Prompts request a specific one-shot action. They are not standing rules but immediate instructions. The formal framework is closer to action languages from AI planning (STRIPS, ADL, HTN): what the goal is, what must be true before acting, and what changes after.
A messy user prompt typically mixes three levels together:
- Goal (desired end state): "I want search results to show up in chat"
- Tasks (what to do): "add a postResult call, update the providers"
- Constraints (conditions/preferences): "don't break existing tests, use safeAsync"
The plugin parses raw input into structured components:
type ParsedTask = {
intent: string
targets: Array<string>
constraints: Array<string>
context?: string
subtasks: Array<ParsedTask>
}The schema is recursive. A ParsedTask can contain subtasks, which can contain their own subtasks. This follows the HTN (Hierarchical Task Network) model where compound tasks decompose into subtask trees.
I'm not an NLP expert. I stumbled onto speech act theory and deontic logic while researching NLP and thought it could be a good fit for structuring instructions. The implementation may not perfectly align with academic definitions, but the goal is practical utility.
MIT