lazyopencode-core 0.0.1

package/dist/skills/lazy/worktree/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: lazy/worktree
+description: Manage Git worktrees as isolated coding lanes for parallel or risky work.
+---
+
+Create, manage, and clean up Git worktrees for isolated coding lanes.
+
+All worktrees live under `.worktrees/<slug>/`.
+
+## Safety rules
+
+Before any Git mutation:
+
+- [ ] Confirm current dir is inside a Git repo
+- [ ] Check current branch, base branch, dirty state
+- [ ] Run `git worktree list` to avoid conflicts
+- [ ] Ensure branch name doesn't already exist locally or remote
+- [ ] Ensure `.worktrees/` is gitignored
+
+**Always ask user confirmation before:**
+
+- `git worktree add` or `remove`
+- Branch creation/deletion
+- Merges, rebases, cherry-picks
+- `git reset --hard`, `git clean`, `git push --force`
+
+## Workflow
+
+### Setup
+
+```bash
+git worktree add -b <branch> .worktrees/<slug> <base>
+```
+
+### Execute
+
+Run sub-agents with `workdir` set to `.worktrees/<slug>`. Do not modify the main checkout for lane work.
+
+### Integrate
+
+1. Run lint + build + tests inside the worktree
+2. Show diff against base branch
+3. Ask user confirmation to merge/cherry-pick
+
+### Cleanup
+
+```bash
+git worktree remove .worktrees/<slug>
+```
+
+### State tracking
+
+If `.worktrees/worktrees.json` exists, update it with lane metadata (slug, branch, path, base, purpose, status).
+
+## When to use
+
+- Risky refactoring that could break the active environment
+- Parallel tasks requiring context switching
+- Prototyping that may be discarded
+- Complex upgrades
+
+## When NOT to use
+
+- Single-file changes or minor bug fixes
+- Documentation updates
+- User didn't ask for it

package/dist/tools/cancel-task.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { BackgroundJobBoard } from "../hooks/background-job-board.js";
+export declare function createCancelTaskTool(jobBoard: BackgroundJobBoard): ToolDefinition;

package/dist/tools/cancel-task.js

@@ -0,0 +1,37 @@
+import { tool } from "@opencode-ai/plugin";
+export function createCancelTaskTool(jobBoard) {
+    return tool({
+        description: "Cancel a running background job by task ID. Use when a subagent is no longer needed or a running lane becomes obsolete.",
+        args: {
+            task_id: tool.schema.string().describe("The task ID of the running job to cancel (e.g. 'lazy-oracle-3' or the session ID shown in the Background Job Board)."),
+            reason: tool.schema.string().optional().describe("Optional reason for cancellation (logged for traceability)."),
+        },
+        execute: async (args, context) => {
+            const { task_id, reason } = args;
+            await context.ask?.({
+                permission: "Cancel a running background job",
+                patterns: ["cancel_task"],
+                always: [],
+                metadata: { task_id, reason },
+            });
+            const job = jobBoard.findJobByTaskID(task_id) ?? jobBoard.findJobByAlias(task_id);
+            if (!job) {
+                return {
+                    output: `No job found with task ID: ${task_id}`,
+                    metadata: { error: true },
+                };
+            }
+            if (job.state !== "running") {
+                return {
+                    output: `Job ${task_id} is already in state: ${job.state} (not running). No action taken.`,
+                    metadata: { state: job.state },
+                };
+            }
+            jobBoard.cancelJob(task_id);
+            return {
+                output: `Cancelled: ${job.alias} (${task_id})${reason ? ` — ${reason}` : ""}`,
+                metadata: { task_id, alias: job.alias, state: "cancelled" },
+            };
+        },
+    });
+}

package/dist/tools/council.d.ts

@@ -0,0 +1,6 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import { type RequiredCouncilConfig } from "../council/index.js";
+export declare function createCouncilTool(client: any, getCouncilConfig: () => RequiredCouncilConfig, getEligibility?: () => {
+    eligible: boolean;
+    reason?: string;
+}): ToolDefinition;

package/dist/tools/council.js

@@ -0,0 +1,41 @@
+import { tool } from "@opencode-ai/plugin";
+import { runCouncil } from "../council/index.js";
+export function createCouncilTool(
+// deno-lint-ignore no-explicit-any
+client, getCouncilConfig, getEligibility) {
+    return tool({
+        description: "Run a multi-LLM council session. Multiple models independently analyze the same question, then return results for synthesis. Use for high-risk decisions, ambiguous bugs, or architectural choices with long-term impact.",
+        args: {
+            prompt: tool.schema.string().describe("The question or task for council members"),
+            preset: tool.schema.string().optional().describe("Council preset name (configured in lazyopencode.council.presets)"),
+        },
+        execute: async (args, context) => {
+            const councilConfig = getCouncilConfig();
+            if (!councilConfig.enabled) {
+                return { output: "Council error: Council is disabled by config", metadata: { error: true } };
+            }
+            const eligibility = getEligibility?.() ?? { eligible: true };
+            if (!eligibility.eligible) {
+                return {
+                    output: eligibility.reason ??
+                        'Council blocked: not eligible for current workflow. Run /lazy start for risk classification, enter debug, or set council.eligibility = "always".',
+                    metadata: { error: true },
+                };
+            }
+            await context.ask?.({
+                permission: "Run a multi-LLM council session",
+                patterns: ["council_session"],
+                always: [],
+                metadata: { preset: args.preset, prompt: args.prompt },
+            });
+            const result = await runCouncil(args.prompt, client, councilConfig, args.preset, context.sessionID, context.abort);
+            if (!result.success) {
+                return {
+                    output: result.formatted || `Council error: ${result.error || "unknown"}`,
+                    metadata: { error: true },
+                };
+            }
+            return { output: result.formatted };
+        },
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+export { createCouncilTool } from "./council.js";
+export { createCancelTaskTool } from "./cancel-task.js";

package/dist/tools/index.js

@@ -0,0 +1,2 @@
+export { createCouncilTool } from "./council.js";
+export { createCancelTaskTool } from "./cancel-task.js";

package/dist/v2.d.ts

@@ -0,0 +1 @@
+export declare const LazyOpenCodeV2Plugin: import("@opencode-ai/plugin/v2/promise").Plugin;

package/dist/v2.js

@@ -0,0 +1,42 @@
+import { define } from "@opencode-ai/plugin/v2/promise";
+import { createAgents } from "./agents/index.js";
+import { getSkillsDir } from "./skills/index.js";
+export const LazyOpenCodeV2Plugin = define({
+    id: "@lazyopencode/core",
+    setup(context) {
+        const ctx = context;
+        ctx.agent?.transform((draft) => {
+            for (const [id, defaults] of Object.entries(createAgents())) {
+                draft.update?.(id, (agent) => {
+                    Object.assign(agent, { ...defaults, ...agent });
+                });
+            }
+            draft.default?.("lazy");
+        });
+        ctx.command?.transform((draft) => {
+            draft.update?.("lazy", (command) => {
+                Object.assign(command, {
+                    template: "Scope-govern a task: start/status/reset/mode/explain/review/simplify/debug/close/doctor/verify/risk/behavior/deepwork",
+                    description: "Classify, gate, track, and close AI coding work",
+                    ...command,
+                });
+            });
+            draft.update?.("deepwork", (command) => {
+                Object.assign(command, {
+                    template: "Alias for /lazy deepwork <task>",
+                    description: "Compatibility alias for lazy deepwork mode",
+                    ...command,
+                });
+            });
+        });
+        ctx.skill?.transform((draft) => {
+            draft.source?.({ type: "local", path: getSkillsDir() });
+        });
+        ctx.reference?.transform((draft) => {
+            draft.add?.("lazyopencode", {
+                type: "local",
+                path: getSkillsDir(),
+            });
+        });
+    },
+});

package/docs/architecture.md

@@ -0,0 +1,47 @@
+# Architecture
+
+LazyOpenCode is an OpenCode plugin with a shared runtime.
+
+## Plugin Entry
+
+The npm package default export uses OpenCode v2 promise registration for agents,
+commands, skills, and references. The named `LazyOpenCodePluginV1` export keeps
+the legacy hook adapter for chat, message, command, permission, and tool
+governance until v2 exposes equivalent hook surfaces.
+
+## Runtime
+
+`LazyRuntime` owns config, scope, job board, workflow trace, OpenCode snapshot,
+close report state, persistence, reset, doctor output, and status formatting.
+
+Default persistence writes to `~/.lazyopencode/state/<scopeID>.json`, never to the project repository unless explicitly configured.
+
+## Token Control
+
+The messages hook keeps context bounded with `lazyopencode.maxMessages` (default `80`), records message-pruning stats for `/lazy status`, strips image payloads into file references for `@lazy-observer`, filters available skills for the `lazy` primary agent, and injects summarized job-board state instead of raw subagent output.
+
+## Hooks
+
+Hooks receive the runtime:
+
+- system transform injects Ponytail and lazy scope-governor behavior
+- messages transform injects job board status and workflow gate nudges
+- permission guard keeps destructive commands at ask
+- task hooks track launches, completions, context files, reuse, and depth
+- session events reconcile, clean up, and record 429 fallback state
+- command hook handles `/lazy`
+
+## Classifier
+
+The workflow classifier is local and rule-based. It emits a `WorkflowDecision` with level, action, required stages, reason, bypass flag, and suggested command.
+
+## Commands
+
+`/lazy start` is the canonical product entry. Other commands are control and
+closure surfaces: status, reset, mode, explain, review, simplify, debug, close,
+doctor, verify, risk, behavior, and deepwork.
+
+## Desktop Distribution
+
+LazyOpenCode Desktop should bundle and enable this plugin by default. Desktop is
+a distribution layer, not a duplicate implementation of runtime governance.

package/docs/council.md

@@ -0,0 +1,200 @@
+# Council — Multi-LLM Parallel Analysis
+
+The **council** system runs multiple independent LLM agents (councillors) on the same
+question in parallel, then returns results for synthesis. It is invoked by the
+`lazy-oracle` agent via the `council_session` tool.
+
+Use council for high-risk decisions, ambiguous bugs, architectural choices with
+long-term impact, or any question where multiple perspectives reduce blind spots.
+
+Council is an optional escalation path, not the default workflow. In the default
+`guarded` mode it only runs for high-risk or ambiguous work, or while the workflow
+stage is `debug`.
+
+---
+
+## How It Works
+
+```
+User question
+  → lazy-oracle agent decides council_session is needed
+    → CouncilManager creates N sessions (one per councillor)
+      → Each councillor runs independently, read-only tools
+    → Results are collected, formatted, returned
+  → lazy-oracle synthesizes a final recommendation
+```
+
+- Each councillor is a separate OpenCode session with the `lazy-councillor` agent
+- Councillors have read-only access (Read, Glob, Grep, list) — no write capability
+- Sessions are parented to the oracle session for traceability
+- Sessions are cleaned up automatically when the council completes
+
+---
+
+## Configuration
+
+Council is configured under `lazyopencode.council` in `opencode.json`:
+
+```jsonc
+{
+  "lazyopencode": {
+    "council": {
+      "enabled": true,
+      "eligibility": "guarded",
+      "default_preset": "code-review",
+      "timeout": 180000,
+      "execution_mode": "parallel",
+      "retries": 2,
+      "maxCouncillors": 3,
+      "presets": {
+        "code-review": {
+          "reasoner": {
+            "model": "openai/o3",
+            "prompt": "寻找逻辑缺陷和边界条件。"
+          },
+          "critic": {
+            "model": "anthropic/claude-opus-4"
+          },
+          "nitpicker": {
+            "model": "openai/gpt-4o-mini",
+            "prompt": "只找代码风格和命名问题。"
+          }
+        },
+        "deep-arch": {
+          "architect": {
+            "model": "openai/o3",
+            "prompt": "Evaluate architectural trade-offs. Focus on coupling, cohesion, and extensibility."
+          },
+          "security": {
+            "model": "anthropic/claude-opus-4",
+            "prompt": "Identify security vulnerabilities and data flow risks."
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Disable council entirely when false |
+| `eligibility` | string | `"guarded"` | `"guarded"` or `"always"` council access |
+| `default_preset` | string | `"default"` | Preset to use when none specified |
+| `timeout` | number | `180000` | Max total council time in ms (3 min) |
+| `execution_mode` | string | `"parallel"` | `"parallel"` or `"serial"` |
+| `retries` | number | `2` | Retries for empty/failed councillor responses |
+| `maxCouncillors` | number | `3` | Hard cap on model calls per council run |
+| `presets` | object | `{}` | Named preset definitions |
+
+### Preset Entry
+
+Each entry in a preset has:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `model` | yes | `"providerID/modelID"` format (e.g. `"openai/gpt-4o"`) |
+| `prompt` | no | Custom system prompt for this councillor |
+
+---
+
+## Execution Modes
+
+### Parallel (default)
+
+All councillors start simultaneously. Results are collected via `Promise.race` with
+a global timeout. Use for independent perspectives where councillors don't need
+each other's output.
+
+### Serial
+
+Councillors run one after another. The council stops if one exceeds the remaining
+time budget. Use when councillors should build on each other's work (future
+feature) or when rate limits are a concern.
+
+---
+
+## Failure Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Session creation fails | Councillor marked `error`, rest continue |
+| Prompt times out (> `timeout`) | Councillor marked `timeout`, council stops |
+| Empty/truncated response | Retries up to `retries` times, then `error` |
+| All councillors fail | `success: false`, error message in formatted output |
+| Preset not found | Falls back to `default_preset`, warns |
+
+---
+
+## Tool API
+
+The `council_session` tool is registered on the `lazy-oracle` agent.
+
+### Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `prompt` | string | yes | The question for council members |
+| `preset` | string | no | Which preset to use (defaults to `default_preset`) |
+
+### Return Value
+
+Returns a formatted string containing:
+
+```
+# Council Results
+
+## Question
+<original question>
+
+## <councillor name>
+Status: success
+<independent analysis>
+
+## <councillor name>
+Status: error
+Error: <details>
+
+## Synthesis Required
+Review each councillor's response and synthesize a final recommendation.
+```
+
+The oracle agent receives this output and is expected to synthesize a final
+recommendation.
+
+---
+
+## Design Decisions
+
+1. **Separate sessions, not sub-agents**: Each councillor gets its own HTTP session.
+   This isolates context and prevents one councillor's output from polluting another.
+
+2. **Read-only councillors**: No write/edit/shell access. Councillors analyze, not
+   modify. This is enforced at the agent prompt level.
+
+3. **Lazy config injection**: The tool uses a getter function to read config at
+   execution time, not at plugin init time. This ensures `opencode.json` config
+   changes are picked up.
+
+4. **Session cleanup in `finally`**: Council sessions are deleted when done,
+   regardless of success or failure. A `catch` on the delete prevents cleanup
+   failures from propagating.
+
+---
+
+## When to Use (for lazy-oracle)
+
+The council is expensive — N councillors consume N model invocations. Use it for:
+
+- **Ambiguous bugs** with multiple possible root causes
+- **Architecture decisions** with long-term cost implications
+- **Security reviews** where missing a finding has real impact
+- **Code review** on critical code (auth, payments, data loss paths)
+
+Do NOT use for:
+
+- Trivial one-line fixes
+- Well-understood refactors
+- Questions answerable by a single Read/Grep

package/docs/desktop-distribution.md

@@ -0,0 +1,36 @@
+# Desktop Distribution
+
+LazyOpenCode Desktop is a preinstalled OpenCode Desktop distribution.
+
+This is the `0.1.0` stage, not the current core hardening stage. The intended
+relationship is OpenCode-native: upstream OpenCode remains the runtime,
+LazyOpenCode Desktop ships the governed defaults and health surface.
+
+## Strategy
+
+The plugin remains the source of truth. Desktop bundles and enables
+`@lazyopencode/core`; it does not duplicate LazyOpenCode governance logic.
+
+## First-Run Defaults
+
+Desktop should merge the defaults from
+`apps/lazyopencode-desktop/lazyopencode.default.jsonc` into the user's generated
+OpenCode config:
+
+- Add `@lazyopencode/core` to `plugin` if absent.
+- Add `lazyopencode` defaults only where the user has not set values.
+- Preserve provider, auth, model, MCP, session, and project settings.
+
+## Branding
+
+- App name: `LazyOpenCode Desktop`
+- Positioning: zero-config governed team runtime for OpenCode
+- Attribution: based on OpenCode; not the official OpenCode project
+
+## Out Of Scope For 0.0.1
+
+- Lazy visual dashboard
+- Deep Desktop workflow fork
+- Provider marketplace
+- MCP marketplace
+- Reimplementing plugin runtime behavior in Desktop

package/docs/opencode-integration.md

@@ -0,0 +1,54 @@
+# OpenCode Integration
+
+LazyOpenCode is an OpenCode-native workflow governor. The plugin should work
+with no `lazyopencode` config block; configuration only customizes defaults.
+
+OpenCode loads `dist/index.js` from the npm package. The default export uses the
+v2 promise registration surface for agents, commands, skills, and references.
+The named `LazyOpenCodePluginV1` export remains available for legacy hook
+registration and existing tests. The legacy adapter stays enabled by default
+because current governance still depends on chat, message, command, permission,
+and tool hooks.
+
+## Hook Boundaries
+
+- `config`: registers lazy agents, skills, commands, and tools without
+  overwriting user-owned config.
+- `permission.ask`: asks before destructive commands when `permissionGuard` is
+  enabled.
+- `command.execute.before`: implements `/lazy` and `/deepwork`.
+- `tool.execute.before/after`: tracks subagent launches, completions, reuse, and
+  error recovery.
+- chat transforms: inject workflow guidance, job-board status, token-control
+  pruning, image redirects, and Ponytail behavior.
+
+## Zero Config
+
+Outside Desktop, users still install/load the plugin through OpenCode's normal
+plugin mechanism. Once loaded, LazyOpenCode defaults are complete:
+
+- `mode: "governor"`
+- `permissionGuard: true`
+- `maxMessages: 80`
+- `workflowGate: true`
+- `council.eligibility: "guarded"`
+- `sdk.mode: "v2"`
+- `sdk.legacyHookAdapter: true`
+- `takeover: "governed"`
+- `opencode.worktreeIsolation: "risky-only"`
+- `closeReport.autoCollect: true`
+
+## Config Merge Contract
+
+LazyOpenCode preserves user config:
+
+- Existing non-lazy agents are untouched.
+- Existing lazy agent overrides win over plugin defaults.
+- Existing commands are not overwritten.
+- Skills paths are deduplicated.
+
+## Permission Guard
+
+`permissionGuard` is intentionally independent from workflow mode. Even
+`mode: "off"` keeps destructive actions at `ask` unless the user explicitly sets
+`permissionGuard: false`.

package/docs/positioning.md

@@ -0,0 +1,44 @@
+# Positioning
+
+LazyOpenCode is a governed team runtime for AI coding in OpenCode.
+
+## Category
+
+OpenCode-native governance plugin now; opinionated OpenCode distribution layer
+next.
+
+OpenCode remains the runtime. LazyOpenCode provides the default team, lifecycle
+rules, risk gates, budget controls, and closure discipline.
+
+## Audience
+
+OpenCode power users who already delegate real coding work to AI and want less drift, less overbuilding, and better closure.
+
+## Enemy
+
+- vague scope
+- overbuilt code
+- unreconciled agents
+- unreviewed output
+- speculative abstractions
+
+## North Star
+
+Make AI coding boring, small, and correct.
+
+## Differentiation
+
+Ponytail gives the philosophy. LazyOpenCode governs execution.
+
+Lightweight agent-routing plugins optimize for delegation. LazyOpenCode includes
+delegation, but its product boundary is the full work lifecycle: classify scope,
+gate risky requests, delegate bounded work, guard destructive permissions, track
+background jobs, budget context/council use, and push review/simplify closure.
+
+Autonomous coding assistants optimize for longer independent runs, memory, and
+self-improvement loops. LazyOpenCode emphasizes governed OpenCode operation:
+small scope, explicit risk gates, budget visibility, and boring closure.
+
+Desktop is a later `0.1.0` task. The current `0.0.1` target is to make
+`@lazyopencode/core` a complete plugin kernel that a Desktop fork can preinstall
+safely.