opencode-starterkit 1.0.1

package/baseline/skill/source-code-research/references/anti-patterns.md

@@ -0,0 +1,36 @@
+# Anti-Patterns
+
+## ❌ Don't: Fetch Entire Ecosystem
+
+```bash
+# Bad: Fetching everything
+npx opensrc react
+npx opensrc react-dom
+npx opensrc react-router
+npx opensrc react-query
+# ... (too much code)
+```
+
+**Do:** Fetch only what you need to answer specific question.
+
+## ❌ Don't: Read Random Files
+
+```typescript
+// Bad: Reading without purpose
+read({ filePath: "opensrc/.../index.ts" });
+read({ filePath: "opensrc/.../utils.ts" });
+read({ filePath: "opensrc/.../helpers.ts" });
+// ... (unfocused exploration)
+```
+
+**Do:** Use grep to find relevant code first, then read.
+
+## ❌ Don't: Ignore Version Mismatch
+
+```bash
+# Bad: Fetching latest when project uses old version
+npx opensrc zod  # Fetches 3.23.x
+# But project uses zod@3.20.0 (different behavior)
+```
+
+**Do:** Specify version matching your lockfile, or let opensrc auto-detect.

package/baseline/skill/source-code-research/references/common-patterns.md

@@ -0,0 +1,57 @@
+# Common Patterns
+
+## Pattern 1: Understanding Error Handling
+
+```typescript
+// 1. Fetch package
+// bash: npx opensrc zod
+
+// 2. Find error classes
+grep({ pattern: "class.*Error", path: "opensrc/", include: "*.ts" });
+
+// 3. Read error implementation
+read({ filePath: "opensrc/repos/.../errors.ts" });
+
+// 4. Find where errors are thrown
+grep({ pattern: "throw new", path: "opensrc/", include: "*.ts" });
+```
+
+## Pattern 2: Tracing Function Behavior
+
+```typescript
+// 1. Fetch source
+// bash: npx opensrc react-hook-form
+
+// 2. Find function definition
+grep({
+  pattern: "export function useForm",
+  path: "opensrc/",
+  include: "*.ts",
+});
+
+// 3. Read implementation
+read({ filePath: "opensrc/.../useForm.ts" });
+
+// 4. Find dependencies
+grep({ pattern: "import.*from", path: "opensrc/.../useForm.ts" });
+```
+
+## Pattern 3: Evaluating Library Quality
+
+```typescript
+// 1. Fetch source
+// bash: npx opensrc candidate-library
+
+// 2. Check test coverage
+glob({ pattern: "opensrc/**/*.test.ts" });
+glob({ pattern: "opensrc/**/*.spec.ts" });
+
+// 3. Read tests for usage patterns
+read({ filePath: "opensrc/.../feature.test.ts" });
+
+// 4. Check for TypeScript usage
+glob({ pattern: "opensrc/**/tsconfig.json" });
+
+// 5. Review package.json for dependencies
+read({ filePath: "opensrc/.../package.json" });
+```

package/baseline/skill/source-code-research/references/example-workflow.md

@@ -0,0 +1,60 @@
+# Example: Complete Workflow
+
+**Scenario:** Need to understand how zod handles async refinements.
+
+```bash
+# 1. Fetch source
+npx opensrc zod
+```
+
+```typescript
+// 2. Find refinement code
+grep({
+  pattern: "refine.*async",
+  path: "opensrc/",
+  include: "*.ts",
+});
+
+// 3. Locate implementation
+ast_grep({
+  pattern: "refine($$$) { $$$ }",
+  path: "opensrc/repos/github.com/colinhacks/zod/",
+});
+
+// 4. Read the implementation
+read({
+  filePath: "opensrc/repos/github.com/colinhacks/zod/src/types.ts",
+  offset: 500,
+  limit: 100,
+});
+
+// 5. Check tests for usage examples
+glob({
+  pattern: "opensrc/**/zod/**/*.test.ts",
+});
+
+read({
+  filePath: "opensrc/repos/.../async.test.ts",
+});
+
+// 6. Document findings
+write({
+  filePath: ".beads/artifacts/br-xxx/research.md",
+  content: `# Zod Async Refinements
+
+**Finding:** Async refinements use \`parseAsync()\` not \`parse()\`
+
+**Evidence:** \`src/types.ts:842-856\`
+
+Async refinements return Promise<Output> and require:
+- Use \`.parseAsync()\` method
+- Refinement function must return Promise<boolean>
+- Errors handled via Promise rejection
+
+**Code snippet:**
+[paste relevant code]
+
+**Recommendation:** Use \`.refine(async (val) => {...})\` with \`.parseAsync()\`
+`,
+});
+```

package/baseline/skill/source-code-research/references/further-reading.md

@@ -0,0 +1,5 @@
+# Further Reading
+
+- OpenSrc Docs: https://github.com/vercel-labs/opensrc
+- When to read source vs docs: https://danluu.com/read-code/
+- Code reading techniques: https://www.codeproject.com/Articles/10/Code-Reading

package/baseline/skill/source-code-research/references/source-structure.md

@@ -0,0 +1,45 @@
+# Source Structure Guide
+
+## npm Packages
+
+```
+opensrc/
+└── repos/
+    └── github.com/              # npm packages resolve to GitHub
+        └── owner/
+            └── repo/
+                ├── src/         # Source code (usually)
+                ├── dist/        # Built output (ignore)
+                ├── test/        # Tests (useful for examples)
+                ├── package.json # Dependencies, scripts
+                └── README.md    # Often has examples
+```
+
+## Python Packages (PyPI)
+
+```
+opensrc/
+└── repos/
+    └── github.com/              # Most PyPI packages on GitHub
+        └── owner/
+            └── repo/
+                ├── src/         # or package_name/
+                ├── tests/       # Python tests
+                ├── setup.py     # Package config
+                └── pyproject.toml
+```
+
+## Rust Crates
+
+```
+opensrc/
+└── repos/
+    └── github.com/
+        └── owner/
+            └── repo/
+                ├── src/
+                │   └── lib.rs   # Main library file
+                ├── tests/
+                ├── Cargo.toml   # Dependencies
+                └── examples/    # Usage examples
+```

package/baseline/skill/stitch/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: stitch
+description: Google Stitch MCP for AI-powered UI design. Extract design context, generate code from designs, and create screens from descriptions. Use when working with Stitch designs and UI generation.
+version: 1.0.0
+tags: [design, mcp, ui]
+dependencies: []
+---
+
+# Google Stitch MCP
+
+## When to Use
+
+- When you need to generate or inspect Google Stitch UI designs via MCP.
+
+## When NOT to Use
+
+- When you don't have Stitch access or don't need Stitch-generated UI.
+
+
+## Overview
+
+Stitch MCP is Google's official Model Context Protocol server for interacting with Google Stitch designs. It allows AI agents to extract design context (colors, typography, spacing), generate production-ready code from designs, and create new designs from text descriptions.
+
+## Endpoint
+
+**MCP Server URL**: `https://stitch.googleapis.com/mcp`
+
+**Authentication**: Google Cloud credentials with Bearer token and project ID header
+
+## 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
+# Set your Google Cloud project
+gcloud config set project PROJECT_ID
+
+# Enable the Stitch MCP service
+gcloud beta services mcp enable stitch.googleapis.com --project=PROJECT_ID
+```
+
+### 2. Get Your Access Token
+
+```bash
+# Authenticate with Google Cloud
+gcloud auth login
+
+# Get your access token
+gcloud auth print-access-token
+```
+
+### 3. Set Environment Variables
+
+```bash
+# Set your Google Cloud project ID
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+
+# Get and set your access token
+export STITCH_ACCESS_TOKEN=$(gcloud auth print-access-token)
+```
+
+### 4. Configuration
+
+Stitch MCP is pre-configured in `opencode.json` as a default MCP server. Once environment variables are set, restart OpenCode and the tools will be available.
+
+## Available Tools
+
+Once configured, the Stitch MCP exposes the following tools:
+
+| Tool                               | Description                       |
+| ---------------------------------- | --------------------------------- |
+| `stitch_list_projects`             | List all your Stitch projects     |
+| `stitch_create_project`            | Create a new UI design project    |
+| `stitch_get_project`               | Get project details               |
+| `stitch_list_screens`              | List screens in a project         |
+| `stitch_get_screen`                | Get screen details with HTML code |
+| `stitch_generate_screen_from_text` | Generate UI from text prompt      |
+
+## 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_from_text({
+  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",
+});
+```
+
+## Troubleshooting
+
+### "Stitch API not enabled"
+
+```bash
+gcloud beta services mcp enable stitch.googleapis.com --project=YOUR_PROJECT_ID
+```
+
+### "Authentication failed"
+
+```bash
+# Refresh your access token (expires after ~1 hour)
+export STITCH_ACCESS_TOKEN=$(gcloud auth print-access-token)
+# Restart OpenCode
+```
+
+### "Project not set"
+
+```bash
+gcloud config set project YOUR_PROJECT_ID
+export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
+```
+
+## Documentation
+
+- [Google Stitch](https://stitch.withgoogle.com)
+- [Stitch MCP Setup](https://stitch.withgoogle.com/docs/mcp/setup)
+- [Google Cloud MCP Overview](https://docs.cloud.google.com/mcp/overview)
+
+## Tips
+
+- Access tokens expire after ~1 hour, refresh with `gcloud auth print-access-token`
+- Use descriptive prompts for better UI generation results
+- Test generated code in your target framework before production use

package/baseline/skill/stitch/mcp.json

@@ -0,0 +1,9 @@
+{
+	"stitch": {
+		"serverUrl": "https://stitch.googleapis.com/mcp",
+		"headers": {
+			"Authorization": "Bearer ${STITCH_ACCESS_TOKEN}",
+			"X-Goog-User-Project": "${GOOGLE_CLOUD_PROJECT}"
+		}
+	}
+}

package/baseline/skill/structured-edit/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: structured-edit
+description: Use when editing files to reduce str_replace failures - combines LSP location with read-verify-edit pattern for reliable edits
+version: 1.0.0
+tags: [code-quality, workflow]
+dependencies: []
+---
+
+# Structured Edit Protocol
+
+## When to Use
+
+- Editing files where exact string matches are error-prone (e.g., str_replace failures)
+- Making targeted changes that require precise location and verification
+
+## When NOT to Use
+
+- One-line edits where a direct edit is safe and unambiguous
+- Large refactors better served by full rewrites or file splits
+
+## Overview
+
+The `str_replace` edit tool is the #1 source of failures in LLM coding. Models reproduce content with subtle differences (whitespace, encoding, line endings) causing "string not found" errors.
+
+**Core principle:** Don't guess content — locate, read, verify, then edit.
+
+## Why This Exists
+
+`str_replace` failures happen when:
+
+| Cause                | Example                                    |
+| -------------------- | ------------------------------------------ |
+| Whitespace mismatch  | Tabs vs spaces, trailing spaces            |
+| Content changed      | File modified since last read              |
+| Multiple matches     | Same string appears twice in file          |
+| Encoding differences | Line endings (CRLF vs LF), invisible chars |
+| Stale context        | Editing from memory instead of fresh read  |
+
+**Result:** Wasted tokens on retries, frustrated developers, broken workflows.
+
+## The Protocol
+
+### Step 1: LOCATE
+
+Use LSP to find exact positions instead of guessing:
+
+```typescript
+// Find where a function is defined
+lsp({ operation: "goToDefinition", filePath, line, character });
+
+// Find all references to a symbol
+lsp({ operation: "findReferences", filePath, line, character });
+
+// Get all symbols in a file
+lsp({ operation: "documentSymbol", filePath, line: 1, character: 1 });
+
+// Search for symbol across workspace
+lsp({ operation: "workspaceSymbol", filePath, line: 1, character: 1 });
+```
+
+### Step 2: READ
+
+Get fresh file content at the located position:
+
+```typescript
+// Read context around target line
+read({ filePath, offset: line - 10, limit: 30 });
+```
+
+**Always include context** — don't just read the target line.
+
+### Step 3: VERIFY
+
+Confirm expected content exists at the location:
+
+```typescript
+// Check that what you expect is actually there
+if (!content.includes(expectedSubstring)) {
+  // STOP — investigate before proceeding
+}
+```
+
+### Step 4: EDIT
+
+Apply minimal, scoped change with unique context:
+
+```typescript
+// Include enough surrounding lines for uniqueness
+edit({
+  filePath,
+  oldString: "  // unique context before\n  targetLine\n  // unique context after",
+  newString: "  // unique context before\n  modifiedLine\n  // unique context after",
+});
+```
+
+**Guidelines:**
+
+- Include 2-3 lines before/after for uniqueness
+- Never use just the target line
+- Keep oldString minimal but unique
+
+### Step 5: CONFIRM
+
+Verify the edit succeeded:
+
+```typescript
+// Read back the modified section
+read({ filePath, offset: line - 5, limit: 15 });
+
+// Confirm content matches intent
+```
+
+## Red Flags — STOP
+
+If you catch yourself:
+
+- Editing without reading first
+- Assuming content hasn't changed
+- Using large multi-line oldString values
+- Skipping the verify step
+- Guessing line numbers without LSP
+
+**STOP.** Return to Step 1.
+
+## Best Practices
+
+### File Size Matters
+
+From research on the "harness problem":
+
+| File Size     | Strategy                                   |
+| ------------- | ------------------------------------------ |
+| < 100 lines   | Full rewrite often easier than str_replace |
+| 100-400 lines | Structured edit with good context          |
+| > 400 lines   | Strongly prefer structured edits           |
+
+**Prefer smaller files** — composition over monoliths.
+
+### Unique Context Selection
+
+```typescript
+// BAD: Non-unique, whitespace-sensitive
+oldString: "return result;";
+
+// GOOD: Unique with surrounding context
+oldString: "  // Calculate final value\n  const result = compute(input);\n  return result;";
+```
+
+### When to Use LSP vs Direct
+
+| Scenario                  | Approach              |
+| ------------------------- | --------------------- |
+| Finding function/class    | LSP goToDefinition    |
+| Finding all usages        | LSP findReferences    |
+| Modifying specific symbol | LSP + structured edit |
+| Large refactoring         | Consider full rewrite |
+| Simple one-line change    | Direct edit OK        |
+
+## Integration with Other Skills
+
+**Use with:**
+
+- `verification-before-completion` — Always verify edits succeeded
+- `systematic-debugging` — When edit failures indicate deeper issues
+- `defense-in-depth` — Add validation after structural changes
+
+## Quick Reference
+
+```
+LOCATE  → lsp({ operation: "goToDefinition" | "findReferences", ... })
+READ    → read({ filePath, offset: line-10, limit: 30 })
+VERIFY  → Check expected content exists
+EDIT    → edit({ oldString: "...unique context...", newString: "..." })
+CONFIRM → read() again to verify success
+```
+
+## The Bottom Line
+
+**Don't trust your memory. Don't guess content. Locate, read, verify, edit, confirm.**
+
+This protocol eliminates the #1 source of LLM coding failures.