opencode-overclock 0.5.0 → 0.5.1

package/README.md

@@ -13,17 +13,17 @@ opencode plugin -g opencode-overclock    # every project
 
 ## What you get
 
-| Module      | What it does                                                                                                                                                           | Tools it adds                                       |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| `workflow`  | 5 lifecycle commands (`/define`, `/plan`, `/build`, `/diagnose`, `/ship`), 9 sandboxed subagents, and 9 bundled engineering skills (`tdd`, `grilling`, `doubt`, etc.). | —                                                   |
-| `safety`    | Blocks destructive git operations (`git reset --hard`, force-push, `clean -f`, `branch -D`, `stash drop`) in `bash` tool calls before they run.                        | —                                                   |
-| `tasks`     | Run shell commands in the background. The agent gets the result posted back into the session when they finish, and a nudge if one blocks on a prompt.                  | `task_run` `task_status` `task_output` `task_kill`  |
-| `sched`     | Recurring prompts on a cron expression or an interval (`"5m"`). Survives restarts; an interval on the current session makes a loop.                                    | `schedule_create` `schedule_list` `schedule_delete` |
-| `guard`     | Your own quality gates: run a command after the agent edits files, feed failures back on idle, edit recovery hints, and `floorGuard` anti-bypass protection.           | —                                                   |
-| `recovery`  | Automatically heal provider errors (missing tool results, thinking block sequencing, context limit) and auto-resume sessions.                                          | —                                                   |
-| `truncator` | Context-protecting smart output truncation for high-volume tools (`task_output`, `bash`, `grep`, `glob`, `webfetch`) preserving header & tail diagnostics.             | —                                                   |
-| `usage`     | Per-day and per-session cost and token totals, collected from the event bus (accessible via TUI `/oc-usage`).                                                          | —                                                   |
-| `buddy`     | An ASCII pet next to the prompt that reacts to what the session is doing. Purely cosmetic.                                                                             | —                                                   |
+| Module      | What it does                                                                                                                                                                                   | Tools it adds                                       |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `workflow`  | 5 lifecycle commands (`/define`, `/plan`, `/build`, `/diagnose`, `/ship`), 11 agents (interactive & sandboxed subagents), and 9 bundled engineering skills (`tdd`, `grilling`, `doubt`, etc.). | —                                                   |
+| `safety`    | Blocks destructive git operations (`git reset --hard`, force-push, `clean -f`, `branch -D`, `stash drop`) in `bash` tool calls before they run.                                                | —                                                   |
+| `tasks`     | Run shell commands in the background. The agent gets the result posted back into the session when they finish, and a nudge if one blocks on a prompt.                                          | `task_run` `task_status` `task_output` `task_kill`  |
+| `sched`     | Recurring prompts on a cron expression or an interval (`"5m"`). Survives restarts; an interval on the current session makes a loop.                                                            | `schedule_create` `schedule_list` `schedule_delete` |
+| `guard`     | Your own quality gates: run a command after the agent edits files, feed failures back on idle, edit recovery hints, and `floorGuard` anti-bypass protection.                                   | —                                                   |
+| `recovery`  | Automatically heal provider errors (missing tool results, thinking block sequencing, context limit) and auto-resume sessions.                                                                  | —                                                   |
+| `truncator` | Context-protecting smart output truncation for high-volume tools (`task_output`, `bash`, `grep`, `glob`, `webfetch`) preserving header & tail diagnostics.                                     | —                                                   |
+| `usage`     | Per-day and per-session cost and token totals, collected from the event bus (accessible via TUI `/oc-usage`).                                                                                  | —                                                   |
+| `buddy`     | An ASCII pet next to the prompt that reacts to what the session is doing. Purely cosmetic.                                                                                                     | —                                                   |
 
 On top of the tools, the TUI side adds desktop notifications when a turn finishes or the agent
 needs you, plus `/oc-tasks`, `/oc-usage`, `/oc-schedules`, `/oc-buddy` (pet), `/oc-buddy-switch` (choose species), and `/oc-buddy-cycle` (next species).
@@ -129,19 +129,28 @@ Auto-discovered by opencode's `skill` tool when relevant:
 - `doubt`: Adversarial verification where artifacts are audited against contracts without author confirmation bias.
 - `source-discipline`: Grounding framework code in official, version-matched documentation.
 
-#### 3. Sandboxed Worker Subagents (The "Who")
+#### 3. Workflow Agents (The "Who")
 
-Specialized leaf subagents invoked via the `task` tool with **enforced read-only tool sandboxing** (`tools: { write: false, edit: false }`, `permission: { edit: "deny" }`):
+Specialized agents available interactively in the TUI (`Tab`) and delegable via the `task` tool:
+
+##### Interactive & Subagent Agents (`mode: "all"`)
+
+- `craftsman`: Disciplined implementation agent enforcing TDD (public seam first), minimal vertical slices, and zero compromises on code quality.
+- `doc-writer`: Technical writer synthesizing accurate documentation, API references, ADRs, and user guides grounded directly in codebase evidence.
+- `engineering-coach`: Elite staff mentor providing Socratic debugging guidance, mental models, and architectural critique (read-only sandboxed).
+- `design-explorer`: Architect formulating contrasting minimalist vs extensible interface proposals ("Design It Twice", read-only sandboxed).
+- `codebase-researcher`: Scout tracing call graphs, seams, and dependencies without cluttering context (read-only sandboxed).
+- `doubt-reviewer`: Adversarial verifier probing race conditions, error bounds, and silent assumptions (read-only sandboxed).
+
+##### Sandboxed Audit Subagents (`mode: "subagent"`)
+
+Leaf subagents invoked via the `task` tool with **enforced read-only tool sandboxing** (`tools: { write: false, edit: false }`, `permission: { edit: "deny" }`):
 
-- `codebase-researcher`: Scout tracing call graphs, seams, and dependencies without cluttering orchestrator context.
-- `design-explorer`: Architect formulating contrasting minimalist vs extensible interface proposals ("Design It Twice").
-- `doubt-reviewer`: Adversarial verifier probing race conditions, error bounds, and silent assumptions.
 - `standards-reviewer`: Senior reviewer auditing code diffs against Martin Fowler's code smells and repo idioms.
 - `spec-reviewer`: Product reviewer ensuring strict compliance with `SPEC.md` and zero unrequested scope creep.
 - `security-auditor`: Adversarial security engineer auditing diffs for OWASP Top 10 flaws and secret hygiene.
 - `test-engineer`: QA engineer assessing test coverage gaps, assertion quality, and mocking boundaries.
 - `performance-auditor`: Performance engineer identifying N+1 queries, unbounded memory, and latency bottlenecks.
-- `engineering-coach`: Elite staff mentor providing Socratic debugging guidance and architectural critique.
 
 ### Quality gates (`guard`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-overclock",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Power-ups for opencode: background tasks, cron scheduling, quality-gate hooks, usage telemetry, and companion. Modular, toggleable.",
   "type": "module",
   "repository": {

package/src/features/workflow.ts

@@ -16,6 +16,8 @@ import { DOUBT_REVIEWER_PROMPT } from "../workflow/agents/doubt-reviewer.ts"
 import { CODEBASE_RESEARCHER_PROMPT } from "../workflow/agents/codebase-researcher.ts"
 import { DESIGN_EXPLORER_PROMPT } from "../workflow/agents/design-explorer.ts"
 import { ENGINEERING_COACH_PROMPT } from "../workflow/agents/engineering-coach.ts"
+import { CRAFTSMAN_PROMPT } from "../workflow/agents/craftsman.ts"
+import { DOC_WRITER_PROMPT } from "../workflow/agents/doc-writer.ts"
 
 function getBundledSkillsDir(customPath?: string): string {
   if (customPath) return customPath
@@ -109,7 +111,7 @@ export const WORKFLOW_AGENTS = {
     },
   },
   "doubt-reviewer": {
-    mode: "subagent" as const,
+    mode: "all" as const,
     description: "Adversarial Verification Engineer evaluating artifacts without author bias",
     prompt: DOUBT_REVIEWER_PROMPT,
     tools: {
@@ -121,7 +123,7 @@ export const WORKFLOW_AGENTS = {
     },
   },
   "codebase-researcher": {
-    mode: "subagent" as const,
+    mode: "all" as const,
     description: "Scout Agent tracing seams, dependencies, and call graphs without polluting context",
     prompt: CODEBASE_RESEARCHER_PROMPT,
     tools: {
@@ -133,7 +135,7 @@ export const WORKFLOW_AGENTS = {
     },
   },
   "design-explorer": {
-    mode: "subagent" as const,
+    mode: "all" as const,
     description: "Principal Architect producing contrasting 'Design It Twice' interface proposals",
     prompt: DESIGN_EXPLORER_PROMPT,
     tools: {
@@ -145,7 +147,7 @@ export const WORKFLOW_AGENTS = {
     },
   },
   "engineering-coach": {
-    mode: "subagent" as const,
+    mode: "all" as const,
     description: "Elite Staff Mentor providing Socratic debugging guidance and design critique",
     prompt: ENGINEERING_COACH_PROMPT,
     tools: {
@@ -156,6 +158,18 @@ export const WORKFLOW_AGENTS = {
       edit: "deny" as const,
     },
   },
+  craftsman: {
+    mode: "all" as const,
+    description:
+      "Disciplined software craftsman enforcing TDD, minimal vertical slices, and clean architecture",
+    prompt: CRAFTSMAN_PROMPT,
+  },
+  "doc-writer": {
+    mode: "all" as const,
+    description:
+      "Technical writer synthesizing accurate documentation, API references, and architecture records from code",
+    prompt: DOC_WRITER_PROMPT,
+  },
 }
 
 export const workflow: FeatureModule = {
@@ -222,7 +236,7 @@ export const workflow: FeatureModule = {
             current.mode = current.mode ?? ag.mode
             current.description = current.description ?? ag.description
             current.system = current.system ?? ag.prompt
-            if (ag.permission?.edit === "deny") {
+            if ("permission" in ag && ag.permission?.edit === "deny") {
               const perms = (current.permissions as any[]) ?? []
               const hasDenyEdit = perms.some((p: any) => p.action === "edit" && p.effect === "deny")
               if (!hasDenyEdit) {

package/src/workflow/agents/craftsman.ts

@@ -0,0 +1,26 @@
+export const CRAFTSMAN_PROMPT = `You are an elite Software Craftsman and Implementation Engineer.
+Your sole responsibility is executing high-leverage, production-grade implementations and refactorings with extreme discipline, test-driven rigor, and architectural clarity.
+
+Core Disciplines:
+1. Test-Driven Development (Red -> Green -> Refactor):
+   - Always establish a failing automated test at the public seam before touching implementation code.
+   - Use independent test oracles: never mirror production code logic inside test assertions.
+   - For bug fixes, write a test reproducing the defect first (Prove-It pattern) before applying the fix.
+   - Write the absolute minimal production code necessary to pass the test clean.
+   - Refactor only when green; keep the test suite green after every change.
+
+2. Minimal Vertical Slices:
+   - Slice work into context-sized vertical increments that cut through logic, interfaces, and tests.
+   - Avoid massive speculative layer-by-layer rewrites.
+   - Deliver working, independently verifiable software at each step.
+
+3. Deep Modules & Information Hiding:
+   - Adhere to John Ousterhout's principles: simple public interfaces hiding significant implementation depth.
+   - Never leak internal data structures, raw vendor types, or transient states through public seams.
+   - Design interfaces to be hard to misuse.
+
+4. Zero Compromises on Quality:
+   - Never use compiler warning/error suppressions, lint overrides, or disabled tests.
+   - Never catch and swallow errors silently.
+   - Always run project linters, typecheckers, and test suites to verify zero regressions.
+`

package/src/workflow/agents/doc-writer.ts

@@ -0,0 +1,24 @@
+export const DOC_WRITER_PROMPT = `You are a Principal Technical Writer and Documentation Architect.
+Your sole responsibility is synthesizing clear, accurate, and high-leverage technical documentation, API references, architecture decision records (ADRs), and user guides grounded directly in codebase evidence.
+
+Core Disciplines:
+1. Grounded in Code Truth:
+   - Never speculate or invent API signatures, behavior, or configuration options.
+   - Always inspect source files, type definitions, exports, and tests using read/grep/glob to verify reality before documenting.
+   - Ensure code examples in documentation are syntactically valid and match actual project conventions.
+
+2. Clear Structure & Progressive Disclosure:
+   - Design documentation for rapid scanning and discoverability.
+   - Start with a clear mental model and high-level concepts before diving into details.
+   - Provide minimal, copy-pasteable, working quickstart examples first.
+   - Structure reference documentation with explicit parameter tables, defaults, return types, and failure modes.
+
+3. Architectural Documentation:
+   - Document "why" decisions were made, trade-offs accepted, and invariants enforced.
+   - Keep ADRs (Architecture Decision Records) concise: Context, Decision, Consequences.
+   - Maintain ubiquitous domain terminology consistent with the codebase.
+
+4. Scope:
+   - Focus exclusively on documentation files (Markdown, README, docs/, API specs).
+   - Do not modify production application code or logic.
+`