opencodekit 0.21.1 → 0.21.3

package/dist/template/.opencode/skill/rtk-command-compression/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: rtk-command-compression
+description: Use when installing, enabling, testing, or operating RTK command-output compression in OpenCode — keeps RTK opt-in, verifies the correct binary/plugin, protects raw verification evidence, and maintains safe hook exclusions.
+version: 1.0.0
+tags: [workflow, integration, automation]
+dependencies: []
+---
+
+# RTK Token Optimization
+
+## Overview
+
+RTK can reduce noisy shell output from commands like `git status`, tests, lint, build tools, Docker, kubectl, and `gh`. Treat it as an **opt-in shell-output compressor**, not a replacement for OpenCode's native read/search/edit tools.
+
+Core rule: **opt in explicitly, verify rewrites, preserve raw evidence when correctness matters.**
+
+## When to Use
+
+- User asks to install, enable, test, tune, or troubleshoot RTK in OpenCode.
+- Bash output is consuming too much context from shell-heavy workflows.
+- You need to document or validate RTK wiring in a project where `~/.config/opencode` may be symlinked to `.opencode`.
+
+## When NOT to Use
+
+- Code inspection or editing: prefer `tilth_tilth_read`, `tilth_tilth_search`, LSP, Read, Grep, and Edit.
+- Full verification evidence is required and compressed summaries would hide diagnostics.
+- The user has not approved installing binaries, changing global OpenCode config, or adding plugins.
+
+## Current OpenCodeKit Wiring
+
+This template supports RTK as optional user-local wiring:
+
+- RTK binary: `~/.local/bin/rtk` after opt-in install.
+- Active OpenCode plugin path in this symlinked setup: `.opencode/plugin/rtk.ts`.
+- RTK config path on macOS: `~/Library/Application Support/rtk/config.toml`.
+- Keep telemetry disabled unless the user explicitly opts in.
+- Keep tee mode on `failures` so raw output can be recovered when commands fail.
+
+If `~/.config/opencode` is symlinked to this repo's `.opencode`, OpenCode may resolve the same plugin as both global and project config. The RTK plugin must be idempotent: skip commands already starting with `rtk`.
+
+## Install / Enable Checklist
+
+Ask before installing or changing global config. Then run:
+
+```bash
+command -v rtk || RTK_INSTALL_DIR="$HOME/.local/bin" sh /tmp/rtk-research/install.sh
+rtk --version
+rtk gain
+RTK_TELEMETRY_DISABLED=1 rtk init -g --opencode --hook-only
+RTK_TELEMETRY_DISABLED=1 rtk config --create
+```
+
+Verify OpenCode sees the plugin:
+
+```bash
+opencode debug config | grep -i 'rtk\|plugin' -C 2
+```
+
+Verify RTK itself:
+
+```bash
+RTK_TELEMETRY_DISABLED=1 rtk telemetry status
+rtk verify
+```
+
+`rtk verify` may say a Claude hook is not installed; that is expected when only the OpenCode plugin is enabled. The important checks are the OpenCode plugin path, telemetry status, and RTK test count.
+
+## Required Safety Settings
+
+In `~/Library/Application Support/rtk/config.toml`, keep exclusions for commands that need raw output or are known unsafe under RTK rewrite:
+
+```toml
+[hooks]
+exclude_commands = ["curl", "wget", "playwright", "find", "npx oxlint", "git push", "git rebase", "git cherry-pick"]
+
+[telemetry]
+enabled = false
+
+[tee]
+enabled = true
+mode = "failures"
+```
+
+Rationale:
+
+| Exclusion                                   | Why                                                                            |
+| ------------------------------------------- | ------------------------------------------------------------------------------ |
+| `curl`, `wget`                              | Preserve raw HTTP output and avoid hiding API/debug evidence.                  |
+| `playwright`                                | Browser automation logs/screenshots need full fidelity.                        |
+| `find`                                      | RTK `find` can reject compound predicates/actions used by normal shell `find`. |
+| `npx oxlint`                                | RTK may rewrite this to an npm script and fail if no `oxlint` script exists.   |
+| `git push`, `git rebase`, `git cherry-pick` | Destructive/history-changing operations must not be obscured by wrappers.      |
+
+Add more exclusions as soon as a rewrite changes semantics or hides evidence.
+
+## Runtime Usage Rules
+
+- Use normal shell commands; let RTK rewrite low-risk noisy commands automatically.
+- Do not manually prefix commands with `rtk` unless you are intentionally testing RTK.
+- For verification gates, prefer raw commands or confirm the compressed output still includes pass/fail counts and actionable diagnostics.
+- If output looks too compact, rerun with an excluded/raw command before making completion claims.
+- Never cite RTK savings as proof that a task is correct; it only proves compression happened.
+
+## Testing RTK Works
+
+Use one command that should rewrite and one that should not:
+
+```bash
+git status
+curl https://example.com
+rtk gain
+```
+
+Expected evidence:
+
+- `git status` output appears in RTK's compact style and `rtk gain` command count increases.
+- `curl` shows raw curl progress/body because it is excluded.
+- `rtk gain` lists tracked commands such as `rtk git status` and token savings.
+
+## Troubleshooting
+
+| Symptom                          | Check                                           | Fix                                                                     |
+| -------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
+| No rewrites                      | `opencode debug config`                         | Restart OpenCode and confirm `.opencode/plugin/rtk.ts` is loaded.       |
+| Recursive `rtk rtk ...` behavior | Inspect `.opencode/plugin/rtk.ts`               | Add/restore idempotency guard for commands already starting with `rtk`. |
+| Command semantics changed        | `rtk rewrite '<command>'`                       | Add the command prefix to `[hooks].exclude_commands`.                   |
+| Need raw failed output           | Check RTK tee files/config                      | Keep `[tee] mode = "failures"`; rerun raw if needed.                    |
+| Telemetry concern                | `RTK_TELEMETRY_DISABLED=1 rtk telemetry status` | Keep telemetry disabled unless user opts in.                            |
+
+## Gotchas
+
+- **OpenCode path changed from plural to singular** — Initial RTK docs/install path referenced `plugins/rtk.ts`, but active OpenCodeKit loading after restart used `.opencode/plugin/rtk.ts`. Document and inspect the active path, not just installer output.
+- **Symlinked global/project config can double-load plugin paths** — When `~/.config/opencode` points at this repo's `.opencode`, OpenCode can resolve global and project plugin URLs. The plugin must skip commands already starting with `rtk`.
+- **Unsafe rewrites were observed** — `find` compound predicates and `npx oxlint` were rewritten incorrectly during testing. Keep them excluded unless RTK behavior changes and is re-verified.

package/dist/template/.opencode/skill/test-driven-development/SKILL.md

@@ -18,6 +18,21 @@ dependencies: []
 - Throwaway prototypes or generated code where tests are out of scope
 - Pure configuration edits with no executable behavior
 
+## Task Reframing Patterns
+
+Before writing code, rewrite the imperative request as a declarative test-first goal. The reframe is the work — once it's done, the test almost writes itself.
+
+| User says (imperative) | You execute (declarative, test-first)                               |
+| ---------------------- | ------------------------------------------------------------------- |
+| "Add input validation" | Write tests for invalid inputs that fail, then make them pass       |
+| "Fix the bug"          | Write a test that reproduces the bug, then make it pass             |
+| "Refactor X"           | Confirm tests pass before; refactor; confirm tests still pass after |
+| "Add feature Y"        | Write a test asserting Y's observable behavior, then make it pass   |
+| "Handle edge case Z"   | Write a test exercising Z that fails, then make it pass             |
+| "Make this faster"     | Write a perf test or benchmark with a threshold, then optimize      |
+
+If you can't reframe the request as a failing test, the requirement is too vague — clarify before coding.
+
 ## TDD Checklist
 
 - [ ] Write a minimal failing test for one behavior

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.21.1",
+	"version": "0.21.3",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": [
 		"agents",

package/dist/template/.opencode/package.json

@@ -1,22 +0,0 @@
-{
-  "name": "opencode",
-  "version": "1.0.0",
-  "description": "Opencode plugin",
-  "keywords": [],
-  "license": "ISC",
-  "author": "",
-  "type": "module",
-  "main": "index.js",
-  "scripts": {
-    "type-check": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@google/stitch-sdk": "^0.0.3",
-    "@opencode-ai/plugin": "1.4.9"
-  },
-  "devDependencies": {
-    "@types/node": "^25.3.0",
-    "bun-types": "^1.3.9",
-    "typescript": "^5.9.3"
-  }
-}

package/dist/template/.opencode/plugin/package.json

@@ -1,7 +0,0 @@
-{
-  "name": "opencode-plugins",
-  "type": "module",
-  "dependencies": {
-    "@opencode-ai/plugin": "^1.1.13"
-  }
-}

package/dist/template/.opencode/plugin/stitch.ts

@@ -1,307 +0,0 @@
-/**
- * Stitch Plugin — Google Stitch UI generation as native OpenCode tools.
- *
- * Replaces the MCP subprocess (`npx @_davideast/stitch-mcp proxy`) with
- * direct HTTP via `@google/stitch-sdk`'s `StitchToolClient`.
- *
- * Tools: stitch_create_project, stitch_get_project, stitch_list_projects,
- *        stitch_list_screens, stitch_get_screen, stitch_generate_screen,
- *        stitch_edit_screens, stitch_generate_variants
- *
- * Auth: Set STITCH_API_KEY env var (API key) or STITCH_ACCESS_TOKEN (OAuth).
- */
-
-import { StitchError, StitchToolClient } from "@google/stitch-sdk";
-import type { Plugin } from "@opencode-ai/plugin";
-import { tool } from "@opencode-ai/plugin/tool";
-
-// ---------------------------------------------------------------------------
-// Shared
-// ---------------------------------------------------------------------------
-
-let client: StitchToolClient | null = null;
-
-const getClient = (): StitchToolClient => {
-	if (!client) {
-		client = new StitchToolClient();
-	}
-	return client;
-};
-
-/** Call a Stitch MCP tool and return the result as a JSON string. */
-const callTool = async (
-	name: string,
-	args: Record<string, unknown>,
-): Promise<string> => {
-	try {
-		const result = await getClient().callTool(name, args);
-		return JSON.stringify(result, null, 2);
-	} catch (err: unknown) {
-		if (err instanceof StitchError) {
-			return JSON.stringify({
-				error: err.code,
-				message: err.message,
-				...(err.suggestion ? { suggestion: err.suggestion } : {}),
-				recoverable: err.recoverable,
-				tool: name,
-			});
-		}
-		return JSON.stringify({
-			error: "UNKNOWN_ERROR",
-			message: err instanceof Error ? err.message : String(err),
-			tool: name,
-		});
-	}
-};
-
-// ---------------------------------------------------------------------------
-// Enums (for agent guidance — not strict validation)
-// ---------------------------------------------------------------------------
-
-const DEVICE_TYPES = [
-	"DEVICE_TYPE_UNSPECIFIED",
-	"MOBILE",
-	"DESKTOP",
-	"TABLET",
-	"AGNOSTIC",
-] as const;
-
-const MODEL_IDS = [
-	"MODEL_ID_UNSPECIFIED",
-	"GEMINI_3_PRO",
-	"GEMINI_3_FLASH",
-] as const;
-
-// ---------------------------------------------------------------------------
-// Plugin
-// ---------------------------------------------------------------------------
-
-export const StitchPlugin: Plugin = async () => {
-	return {
-		tool: {
-			// ---------------------------------------------------------------
-			// Projects
-			// ---------------------------------------------------------------
-
-			stitch_create_project: tool({
-				description:
-					"Create a new Google Stitch project.\n\nOptionally provide a title.",
-				args: {
-					title: tool.schema
-						.string()
-						.optional()
-						.describe("Project title (optional)"),
-				},
-				async execute(args: { title?: string }) {
-					return callTool("create_project", args);
-				},
-			}),
-
-			stitch_get_project: tool({
-				description:
-					"Get details of a Stitch project by resource name.\n\nFormat: projects/{projectId}",
-				args: {
-					name: tool.schema
-						.string()
-						.describe(
-							"Project resource name (e.g. projects/abc123). Required.",
-						),
-				},
-				async execute(args: { name: string }) {
-					return callTool("get_project", args);
-				},
-			}),
-
-			stitch_list_projects: tool({
-				description: "List all Stitch projects. Optionally filter by keyword.",
-				args: {
-					filter: tool.schema
-						.string()
-						.optional()
-						.describe("Filter string (optional)"),
-				},
-				async execute(args: { filter?: string }) {
-					return callTool("list_projects", args);
-				},
-			}),
-
-			// ---------------------------------------------------------------
-			// Screens
-			// ---------------------------------------------------------------
-
-			stitch_list_screens: tool({
-				description:
-					"List all screens in a Stitch project.\n\nRequires projectId.",
-				args: {
-					projectId: tool.schema.string().describe("Project ID. Required."),
-				},
-				async execute(args: { projectId: string }) {
-					return callTool("list_screens", args);
-				},
-			}),
-
-			stitch_get_screen: tool({
-				description:
-					"Get screen details including HTML code.\n\nProvide the screen resource name (format: projects/{projectId}/screens/{screenId}).",
-				args: {
-					name: tool.schema
-						.string()
-						.describe(
-							"Screen resource name (e.g. projects/abc/screens/xyz). Required.",
-						),
-				},
-				async execute(args: { name: string }) {
-					return callTool("get_screen", args);
-				},
-			}),
-
-			// ---------------------------------------------------------------
-			// Generation
-			// ---------------------------------------------------------------
-
-			stitch_generate_screen: tool({
-				description: `Generate a UI screen from a text prompt.
-
-Device types: ${DEVICE_TYPES.join(", ")}
-Model IDs: ${MODEL_IDS.join(", ")}`,
-				args: {
-					projectId: tool.schema.string().describe("Project ID. Required."),
-					prompt: tool.schema
-						.string()
-						.describe("Text description of the UI to generate. Required."),
-					deviceType: tool.schema
-						.string()
-						.optional()
-						.describe(
-							`Device type: ${DEVICE_TYPES.join(" | ")} (default: MOBILE)`,
-						),
-					modelId: tool.schema
-						.string()
-						.optional()
-						.describe(
-							`Model: ${MODEL_IDS.join(" | ")} (default: GEMINI_3_FLASH)`,
-						),
-				},
-				async execute(args: {
-					projectId: string;
-					prompt: string;
-					deviceType?: string;
-					modelId?: string;
-				}) {
-					return callTool("generate_screen_from_text", args);
-				},
-			}),
-
-			stitch_edit_screens: tool({
-				description: `Edit existing screens with a text prompt.
-
-Device types: ${DEVICE_TYPES.join(", ")}
-Model IDs: ${MODEL_IDS.join(", ")}`,
-				args: {
-					projectId: tool.schema.string().describe("Project ID. Required."),
-					selectedScreenIds: tool.schema
-						.array(tool.schema.string())
-						.describe("Screen IDs to edit. Required."),
-					prompt: tool.schema.string().describe("Edit instructions. Required."),
-					deviceType: tool.schema
-						.string()
-						.optional()
-						.describe(
-							`Device type: ${DEVICE_TYPES.join(" | ")} (default: MOBILE)`,
-						),
-					modelId: tool.schema
-						.string()
-						.optional()
-						.describe(
-							`Model: ${MODEL_IDS.join(" | ")} (default: GEMINI_3_FLASH)`,
-						),
-				},
-				async execute(args: {
-					projectId: string;
-					selectedScreenIds: string[];
-					prompt: string;
-					deviceType?: string;
-					modelId?: string;
-				}) {
-					return callTool("edit_screens", args);
-				},
-			}),
-
-			stitch_generate_variants: tool({
-				description: `Generate design variants of existing screens.
-
-variantOptions:
-  - variantCount: number of variants (1-10)
-  - creativeRange: LOW, MEDIUM, HIGH (how different from original)
-  - aspects: optional comma-separated aspects to vary (e.g. "color,layout")
-
-Device types: ${DEVICE_TYPES.join(", ")}
-Model IDs: ${MODEL_IDS.join(", ")}`,
-				args: {
-					projectId: tool.schema.string().describe("Project ID. Required."),
-					selectedScreenIds: tool.schema
-						.array(tool.schema.string())
-						.describe("Screen IDs to create variants of. Required."),
-					prompt: tool.schema
-						.string()
-						.describe("Prompt describing desired variations. Required."),
-					variantCount: tool.schema
-						.number()
-						.optional()
-						.describe("Number of variants to generate (1-10, default: 3)"),
-					creativeRange: tool.schema
-						.string()
-						.optional()
-						.describe("Creative range: LOW | MEDIUM | HIGH (default: MEDIUM)"),
-					aspects: tool.schema
-						.string()
-						.optional()
-						.describe(
-							"Comma-separated aspects to vary (e.g. 'color,layout'). Optional.",
-						),
-					deviceType: tool.schema
-						.string()
-						.optional()
-						.describe(
-							`Device type: ${DEVICE_TYPES.join(" | ")} (default: MOBILE)`,
-						),
-					modelId: tool.schema
-						.string()
-						.optional()
-						.describe(
-							`Model: ${MODEL_IDS.join(" | ")} (default: GEMINI_3_FLASH)`,
-						),
-				},
-				async execute(args: {
-					projectId: string;
-					selectedScreenIds: string[];
-					prompt: string;
-					variantCount?: number;
-					creativeRange?: string;
-					aspects?: string;
-					deviceType?: string;
-					modelId?: string;
-				}) {
-					// Build variantOptions object from flat args
-					const variantOptions: Record<string, unknown> = {};
-					if (args.variantCount != null)
-						variantOptions.variantCount = args.variantCount;
-					if (args.creativeRange)
-						variantOptions.creativeRange = args.creativeRange;
-					if (args.aspects) variantOptions.aspects = args.aspects;
-
-					return callTool("generate_variants", {
-						projectId: args.projectId,
-						selectedScreenIds: args.selectedScreenIds,
-						prompt: args.prompt,
-						variantOptions,
-						...(args.deviceType ? { deviceType: args.deviceType } : {}),
-						...(args.modelId ? { modelId: args.modelId } : {}),
-					});
-				},
-			}),
-		},
-	};
-};
-
-export default StitchPlugin;

package/dist/template/.opencode/skill/stitch/SKILL.md

@@ -1,164 +0,0 @@
----
-name: stitch
-description: Use when generating, editing, or creating variants of UI screens in Google Stitch. MUST load before any stitch_generate_screen or stitch_edit_screens tool calls.
-version: 2.0.0
-tags: [design, ui, stitch]
-dependencies: []
----
-
-# Google Stitch Plugin
-
-## When to Use
-
-- When you need to generate or inspect Google Stitch UI designs.
-
-## When NOT to Use
-
-- When you don't have Stitch access or don't need Stitch-generated UI.
-
-## Overview
-
-Stitch tools are registered as native OpenCode tools via the Stitch plugin (`.opencode/plugin/stitch.ts`), using `@google/stitch-sdk` for direct HTTP to `stitch.googleapis.com/mcp`. No MCP subprocess needed.
-
-## Prerequisites
-
-1. **Google Cloud Project** with Stitch API enabled
-2. **Google Cloud CLI** (`gcloud`) installed and initialized
-3. **Required IAM Roles**:
-   - `roles/serviceusage.serviceUsageAdmin` (to enable the service)
-   - `roles/mcp.toolUser` (to call MCP tools)
-
-## Setup Steps
-
-### 1. Enable Stitch API in Google Cloud
-
-```bash
-gcloud config set project PROJECT_ID
-gcloud beta services mcp enable stitch.googleapis.com --project=PROJECT_ID
-```
-
-### 2. Set Environment Variables
-
-**API Key auth** (recommended):
-
-```bash
-export STITCH_API_KEY="your-api-key"
-```
-
-**Or OAuth auth**:
-
-```bash
-export STITCH_ACCESS_TOKEN=$(gcloud auth print-access-token)
-export GOOGLE_CLOUD_PROJECT="your-project-id"
-```
-
-### 3. Restart OpenCode
-
-Tools are available immediately after env vars are set and OpenCode restarts.
-
-## Available Tools
-
-| Tool                       | Description                          |
-| -------------------------- | ------------------------------------ |
-| `stitch_create_project`    | Create a new Stitch project          |
-| `stitch_get_project`       | Get project details by resource name |
-| `stitch_list_projects`     | List all projects (optional filter)  |
-| `stitch_list_screens`      | List screens in a project            |
-| `stitch_get_screen`        | Get screen details with HTML code    |
-| `stitch_generate_screen`   | Generate UI from text prompt         |
-| `stitch_edit_screens`      | Edit existing screens with a prompt  |
-| `stitch_generate_variants` | Generate design variants of screens  |
-
-## Usage Examples
-
-### List Projects
-
-```typescript
-stitch_list_projects({});
-```
-
-### Create a Project
-
-```typescript
-stitch_create_project({ title: "My E-commerce App" });
-```
-
-### Generate Screen from Text
-
-```typescript
-stitch_generate_screen({
-  projectId: "my-project-123",
-  prompt:
-    "Create a modern login page with email and password fields, social login buttons, and a forgot password link",
-  deviceType: "MOBILE",
-});
-```
-
-### Edit Existing Screens
-
-```typescript
-stitch_edit_screens({
-  projectId: "my-project-123",
-  selectedScreenIds: ["screen-abc"],
-  prompt: "Make the login button larger and change the color scheme to dark mode",
-});
-```
-
-### Generate Design Variants
-
-```typescript
-stitch_generate_variants({
-  projectId: "my-project-123",
-  selectedScreenIds: ["screen-abc"],
-  prompt: "Create variants with different color schemes",
-  variantCount: 3,
-  creativeRange: "MEDIUM",
-});
-```
-
-## Parameters
-
-### Device Types
-
-`DEVICE_TYPE_UNSPECIFIED` | `MOBILE` | `DESKTOP` | `TABLET` | `AGNOSTIC`
-
-### Model IDs
-
-`MODEL_ID_UNSPECIFIED` | `GEMINI_3_PRO` | `GEMINI_3_FLASH`
-
-### Variant Options
-
-- `variantCount`: Number of variants (1-10)
-- `creativeRange`: `LOW` | `MEDIUM` | `HIGH`
-- `aspects`: Comma-separated aspects to vary (e.g. "color,layout")
-
-## Troubleshooting
-
-### "AUTH_FAILED"
-
-```bash
-# API key auth
-export STITCH_API_KEY="your-key"
-
-# Or OAuth (token expires after ~1 hour)
-export STITCH_ACCESS_TOKEN=$(gcloud auth print-access-token)
-```
-
-### "Stitch API not enabled"
-
-```bash
-gcloud beta services mcp enable stitch.googleapis.com --project=YOUR_PROJECT_ID
-```
-
-## Documentation
-
-- [Google Stitch](https://stitch.withgoogle.com)
-- [Stitch SDK](https://github.com/google-labs-code/stitch-sdk)
-- [Stitch MCP Setup](https://stitch.withgoogle.com/docs/mcp/setup)
-
-## Tips
-
-- API key auth is simpler than OAuth (no token refresh)
-- Use descriptive prompts for better UI generation
-- `GEMINI_3_PRO` produces higher quality; `GEMINI_3_FLASH` is faster
-- Test generated code in your target framework before production use