opencode-starterkit 1.0.1

package/baseline/skill/visual-analysis/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: visual-analysis
+description: Use when analyzing images, screenshots, UI mockups, or visual content for extracting information, comparing designs, or assessing visual properties like colors, typography, and layout
+version: 1.0.0
+tags: [design, research]
+dependencies: []
+---
+
+# Visual Analysis Skill
+
+> **Replaces** guessing at visual properties from code alone — direct inspection of rendered output for colors, layout, spacing, and typography
+
+## When to Use
+
+- Analyzing UI mockups or screenshots
+- Extracting information from images
+- Comparing visual designs
+- Quick visual assessments
+
+## When NOT to Use
+
+- Pure text/code review without any visual assets.
+
+## Workflow
+
+1. **Capture** — Get the image (screenshot, mockup, or user-provided)
+2. **Analyze** — Use vision agent to extract specific properties (colors as hex, font sizes, spacing in px/rem)
+3. **Compare** — Cross-reference extracted values against design tokens and existing CSS
+4. **Report** — List discrepancies with specific values and file locations
+
+## Quick Mode
+
+Fast, focused analysis for specific questions.
+
+**Prompt pattern:**
+
+```
+Analyze this image: [attach image]
+[specific question]
+```
+
+**Examples:**
+
+- "What text is visible in this UI?"
+- "List all colors used with their hex values"
+- "Identify all interactive elements"
+
+## Deep Mode
+
+Comprehensive analysis with structured output.
+
+**Prompt pattern:**
+
+```
+Analyze this image comprehensively:
+
+1. CONTENT INVENTORY
+   - All UI elements present
+   - Text content
+   - Icons and imagery
+
+2. VISUAL PROPERTIES
+   - Color palette (hex values)
+   - Typography (fonts, sizes, weights)
+   - Spacing patterns
+   - Layout structure
+
+3. OBSERVATIONS
+   - Design patterns used
+   - Potential issues
+   - Notable features
+
+Output as structured markdown.
+```
+
+## Common Analysis Patterns
+
+### UI Component Analysis
+
+```
+Analyze this UI component:
+
+1. Component type and purpose
+2. Visual states (hover, focus, disabled)
+3. Accessibility considerations
+4. Props/variants needed
+5. Similar patterns in common UI libraries
+```
+
+### Screenshot Comparison
+
+```
+Compare these two images:
+
+1. Visual differences (be specific about location)
+2. Missing elements
+3. Spacing/sizing discrepancies
+4. Color accuracy
+5. Priority fixes ranked by visual impact
+```
+
+### Color Extraction
+
+```
+Extract all colors from this image.
+
+Output as JSON:
+{
+  "primary": ["#hex1", "#hex2"],
+  "secondary": ["#hex3"],
+  "neutral": ["#hex4", "#hex5"],
+  "accent": ["#hex6"]
+}
+
+Include approximate usage percentage for each color.
+```
+
+### Layout Analysis
+
+```
+Analyze the layout structure:
+
+1. Grid system (columns, gutters)
+2. Container widths
+3. Section divisions
+4. Responsive breakpoint hints
+5. Flexbox vs Grid recommendations
+
+Output CSS/Tailwind structure.
+```
+
+## Output Formats
+
+- **Markdown** (default): Structured text
+- **JSON**: For design tokens
+- **Code**: Direct implementation
+
+## Storage
+
+Save findings to `.opencode/memory/design/analysis/`
+
+## Anti-Patterns
+
+| Anti-Pattern                                                                   | Why It Fails                                                                 | Instead                                                                     |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Describing layout vaguely ("looks good") instead of extracting specific values | Feedback is non-actionable and hard to validate                              | Report measurable values (hex, px/rem, font size/weight) with locations     |
+| Not comparing against existing design tokens                                   | Findings drift from system standards and create inconsistent recommendations | Map extracted values to tokens first, then flag true mismatches             |
+| Analyzing low-resolution screenshots (artifacts mislead analysis)              | Compression/noise causes false readings for spacing and color                | Request higher-resolution captures or zoomed crops before final conclusions |
+
+## See Also
+
+- `mockup-to-code`
+- `design-system-audit`
+- `accessibility-audit`

package/baseline/skill/web-design-guidelines/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+version: 1.0.0
+tags: [ui, design]
+dependencies: []
+---
+
+# Web Interface Guidelines
+
+## When to Use
+
+- Reviewing UI files against Web Interface Guidelines for UX/design compliance.
+
+## When NOT to Use
+
+- Non-UI code reviews or when no files/pattern are provided.
+
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/baseline/skill/writing-plans/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: writing-plans
+description: Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming engineer has minimal domain knowledge
+version: 1.0.0
+tags: [planning, documentation]
+dependencies: []
+---
+
+# Writing Plans
+
+> **Replaces** vague implementation plans that assume the engineer knows the codebase — produces zero-ambiguity plans with exact file paths and complete code examples
+## When to Use
+
+- Design/PRD is complete and you need a detailed, step-by-step implementation plan
+- You need a plan for engineers with minimal codebase context and explicit file paths
+
+## When NOT to Use
+
+- Requirements are still being defined (use brainstorming or prd)
+- You already have a vetted plan and only need execution (use executing-plans)
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use skill({ name: "executing-plans" }) to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+### Goal-Backward Section (REQUIRED)
+
+Document the reasoning that produced this plan using goal-backward methodology:
+
+```markdown
+## Must-Haves
+
+**Goal:** [Outcome-shaped goal from PRD]
+
+### Observable Truths
+
+(What must be TRUE for the goal to be achieved?)
+
+1. [Truth 1: User can...]
+2. [Truth 2: User can...]
+3. [Truth 3: User can...]
+
+### Required Artifacts
+
+(What must EXIST for truths to be true?)
+| Artifact | Provides | Path |
+|----------|----------|------|
+| [File/component] | [What it does] | `src/path/to/file.ts` |
+
+### Key Links
+
+(Where is this most likely to break?)
+| From | To | Via | Risk |
+|------|-----|-----|------|
+| [Component] | [API] | `fetch` | [Why it might fail] |
+```
+
+### Dependency Graph
+
+```markdown
+### Task Dependencies
+```
+
+Task A (User model): needs nothing, creates src/models/user.ts
+Task B (Product model): needs nothing, creates src/models/product.ts
+Task C (User API): needs Task A, creates src/api/users.ts
+
+Wave 1: A, B (parallel)
+Wave 2: C (after Wave 1)
+
+````
+
+## Tiered Task Hierarchy
+
+For multi-agent execution at scale (10+ agents), use explicit tier declarations. This prevents flat decomposition that fails when many agents work in parallel.
+
+### Tier Definitions
+
+| Tier | Role | Description | Example |
+|------|------|-------------|---------|
+| **planner** | Lead orchestrator | Analyzes scope, decomposes into sub-tasks, coordinates workers | "Design auth system" |
+| **sub-planner** | Mid-level coordinator | Takes planner output, further decomposes, assigns to workers | "Break auth into API, model, middleware" |
+| **worker** | Execution agent | Executes assigned work, reports progress | "Implement auth service" |
+
+### When to Use Tiers
+
+- **<10 agents**: Optional - flat decomposition works
+- **10-50 agents**: Recommended - planner + workers
+- **50+ agents**: Required - planner + sub-planners + workers
+
+### Tier Declaration Format
+
+Add tier metadata to each task:
+
+```markdown
+### Task 1: Design Auth System
+
+**Tier:** planner
+
+**Files:**
+- Create: `docs/auth-design.md`
+
+This task decomposes the auth feature into sub-tasks for implementation.
+````
+
+### Handoff Contracts
+
+Tasks must declare what they produce for downstream tasks:
+
+```markdown
+### Handoff Contract
+
+**Produces:**
+
+- `docs/auth-design.md` - Architecture decision document
+
+**Consumed By:**
+
+- Task 2: Implement Auth Service
+- Task 3: Add Auth Tests
+```
+
+### Tier Enforcement in Plans
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **Tier Structure:**
+>
+> - **Planners (2):** Task 1, Task 5
+> - **Workers (6):** Tasks 2,3,4,6,7,8
+
+## Task Hierarchy
+
+### Tier 1: Planner Tasks (Orchestration)
+
+### Task 1: [Planner] Design Auth System
+
+### Task 5: [Planner] Design API Layer
+
+### Tier 2: Worker Tasks (Execution)
+
+### Task 2: [Worker] Implement Auth Service
+
+### Task 3: [Worker] Add Auth Middleware
+
+### Task 4: [Worker] Write Auth Tests
+```
+
+### Wave Execution with Tiers
+
+When executing with tiers:
+
+1. **Planner waves** execute first (scope definition)
+2. **Worker waves** execute after planner output is ready
+3. **Sub-planners** sit between, bridging planner → worker
+
+```markdown
+Wave 1 (Planners): Task 1, Task 5
+Wave 2 (Workers): Tasks 2, 3, 4 (after Task 1)
+Wave 3 (Workers): Tasks 6, 7, 8 (after Task 5)
+```
+
+### Anti-Pattern: Flat Decomposition at Scale
+
+Without tiers, 20 agents get 20 flat tasks → chaos:
+
+- Workers step on each other
+- No coordination between related work
+- Merge conflicts everywhere
+
+With tiers, the structure emerges:
+
+```
+Planner → Sub-planner A → Worker 1, 2, 3
+                     → Worker 4, 5
+        Sub-planner B → Worker 6, 7
+```
+
+This mirrors real engineering orgs: lead → tech lead → IC.
+
+`````
+
+## Context Budget
+
+Target: ~50% context per plan execution
+Maximum: 2-3 tasks per plan
+
+| Task Complexity | Max Tasks | Typical Context |
+| --------------- | --------- | --------------- |
+| Simple (CRUD)   | 3         | ~30-45%         |
+| Complex (auth)  | 2         | ~40-50%         |
+| Very complex    | 1-2       | ~30-50%         |
+
+**Split signals:**
+
+- More than 3 tasks → Create child plans
+- Multiple subsystems → Separate plans
+- Any task with >5 file modifications → Split
+- Checkpoint + implementation → Split
+- Discovery + implementation → Split
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+`````
+
+````
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+
+```
+
+## Remember
+- Exact file paths always
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- Reference relevant skills with @ syntax
+- DRY, YAGNI, TDD, frequent commits
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete and saved to `.beads/artifacts/<bead-id>/plan.md`. Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- **REQUIRED SUB-SKILL:** Use skill({ name: "subagent-driven-development" })
+- Stay in this session
+- Fresh subagent per task + code review
+
+**If Parallel Session chosen:**
+- Guide them to open new session in worktree
+- **REQUIRED SUB-SKILL:** New session uses skill({ name: "executing-plans" })
+```
+````
+
+## See Also
+
+- `executing-plans` - Execute vetted plans in controlled batches with checkpoints
+- `prd` - Convert validated design into explicit behavioral requirements
+- `brainstorming` - Refine rough ideas and constraints before specification/planning