opencode-starterkit 1.0.1

package/baseline/command/start.md

@@ -0,0 +1,158 @@
+---
+description: Start working on a bead - claim it and prepare workspace
+argument-hint: "<bead-id> [--worktree]"
+agent: build
+---
+
+# Start: $ARGUMENTS
+
+Claim a task and prepare workspace. Bridge between specification (`/create`) and implementation (`/ship`).
+
+> **Workflow:** `/create` → **`/start <id>`** → `/ship <id>`
+>
+> ⛔ Bead MUST have `prd.md` (created via `/create`).
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "prd-task" }); // PRD → executable tasks
+```
+
+## Parse Arguments
+
+| Argument     | Default  | Description                  |
+| ------------ | -------- | ---------------------------- |
+| `<bead-id>`  | required | The bead to start            |
+| `--worktree` | false    | Create isolated git worktree |
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                  |
+| ---------- | --------------------------- | ----------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Start that bead         |
+| Path       | File/directory path         | Not supported for start |
+
+## Before You Start
+
+- **Be certain**: Only start beads with valid PRD (check Phase 2)
+- **Check workspace**: Don't start if uncommitted changes exist (Phase 1)
+- **One task at a time**: Warn if other tasks in progress
+- **Validate spec**: Verify prd.md exists and has real content
+- **Ask about workspace**: Let user choose branch/worktree strategy
+
+## Phase 1: Pre-flight
+
+```bash
+git status --porcelain
+git branch --show-current
+br list --status=in_progress
+```
+
+- If uncommitted changes: ask user to stash, commit, or continue
+- If other tasks in progress: warn before claiming another
+
+## Phase 2: Validate Specification
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Verify `prd.md` exists and has real content (not just placeholders). If missing or incomplete, tell user to run `/create` first.
+
+## Phase 3: Claim
+
+```bash
+br update $ARGUMENTS --status in_progress
+```
+
+## Phase 4: Prepare Workspace
+
+Ask user how to handle workspace:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Workspace",
+      question: "How do you want to set up the workspace?",
+      options: [
+        {
+          label: "Create feature branch (Recommended)",
+          description: "git checkout -b feat/<bead-id>-<title>",
+        },
+        {
+          label: "Use current branch",
+          description: "Work on current branch",
+        },
+        {
+          label: "Create worktree",
+          description: "Isolated git worktree for this bead",
+        },
+      ],
+    },
+  ],
+});
+```
+
+**If feature branch selected:**
+
+Map bead type to branch prefix:
+
+| Bead Type | Branch Prefix |
+| --------- | ------------- |
+| feature   | feat          |
+| bug       | fix           |
+| task      | task          |
+| epic      | epic          |
+
+```bash
+PREFIX=$(case "$BEAD_TYPE" in
+  feature) echo "feat" ;;
+  bug) echo "fix" ;;
+  task) echo "task" ;;
+  epic) echo "epic" ;;
+  *) echo "task" ;;
+esac)
+TITLE_SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+git checkout -b $PREFIX/$ARGUMENTS-$TITLE_SLUG
+```
+
+**If worktree selected:**
+
+```typescript
+skill({ name: "using-git-worktrees" });
+```
+
+**If current branch:** Continue without branch creation.
+
+## Phase 5: Convert PRD to Tasks
+
+If `prd.json` doesn't exist yet, use `prd-task` skill to convert PRD markdown → executable JSON.
+
+If `prd.json` already exists, show progress (completed/total tasks).
+
+## Phase 6: Report and Route
+
+Output:
+
+1. Bead type and status
+2. Branch name
+3. Workspace (main or worktree)
+4. Artifact status (prd.md validated, prd.json exists/created)
+5. Next step recommendation
+
+| State              | Next Command             |
+| ------------------ | ------------------------ |
+| Has prd.json       | `/ship $ARGUMENTS`       |
+| Epic with subtasks | `/start <first-subtask>` |
+| Complex task       | `/plan $ARGUMENTS`       |
+
+## Related Commands
+
+| Need                | Command      |
+| ------------------- | ------------ |
+| Create spec first   | `/create`    |
+| Plan implementation | `/plan <id>` |
+| Implement and ship  | `/ship <id>` |

package/baseline/command/status.md

@@ -0,0 +1,117 @@
+---
+description: Show project status - tasks, git state, recent sessions
+argument-hint: "[--git] [--sessions]"
+agent: build
+---
+
+# Status: $ARGUMENTS
+
+Quick project status dashboard. Runs read-only commands and reports state.
+
+> **No arguments required.** Flags are optional filters.
+
+## Parse Arguments
+
+| Argument     | Default | Description             |
+| ------------ | ------- | ----------------------- |
+| `--git`      | false   | Focus on git state only |
+| `--sessions` | false   | Focus on sessions only  |
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+```
+
+## Determine Input Type
+
+| Input Type   | Detection     | Action              |
+| ------------ | ------------- | ------------------- |
+| No arguments | Default       | Show full dashboard |
+| `--git`      | Flag provided | Git state only      |
+| `--sessions` | Flag provided | Sessions only       |
+
+## Before You Status
+
+- **Be certain**: This is a read-only command, no changes are made
+- **Use actual data**: Don't invent data, use real command output
+- **No modifications**: Don't create beads or modify state from status
+- **Single recommendation**: Only suggest ONE next action
+
+## Available Tools
+
+| Tool            | Use When              |
+| --------------- | --------------------- |
+| `br`            | Task status and stats |
+| `git`           | Git state and history |
+| `find_sessions` | Recent sessions       |
+
+## Phase 1: Gather State (Parallel)
+
+Run all checks simultaneously:
+
+```bash
+br stats
+br list --status in_progress
+br ready
+```
+
+```bash
+git status --porcelain
+git branch --show-current
+git log --oneline -5
+```
+
+```typescript
+find_sessions({ query: "today", limit: 5 });
+```
+
+---
+
+## Phase 2: Format Report
+
+Present results in simple sections. Use the actual output from Phase 1 — don't invent data.
+
+```
+Status
+━━━━━━
+
+TASKS
+  In Progress: [list from br list --status in_progress]
+  Ready:       [list from br ready]
+  Stats:       [summary from br stats]
+
+GIT
+  Branch:  [from git branch]
+  Changes: [from git status, or "clean"]
+  Recent:  [from git log]
+
+SESSIONS TODAY
+  [from find_sessions]
+```
+
+---
+
+## Phase 3: Suggest Next Action
+
+Based on gathered state, recommend ONE next step:
+
+| State                        | Suggestion                    |
+| ---------------------------- | ----------------------------- |
+| Has in_progress tasks        | `/ship <id>` (continue work)  |
+| Has ready tasks, none active | `/start <id>` (pick up work)  |
+| Uncommitted changes          | Review and commit             |
+| Nothing active or ready      | `/create "<desc>"` (new work) |
+
+---
+
+## Output
+
+```
+Status
+━━━━━━
+
+[Sections from Phase 2]
+
+Next: [single recommendation from Phase 3]
+```

package/baseline/command/ui-review.md

@@ -0,0 +1,92 @@
+---
+description: Review UI/UX design for quality, aesthetics, and best practices
+argument-hint: "<image-or-component-path> [--responsive] [--dark-mode]"
+agent: vision
+model: proxypal/gemini-3-pro-preview
+---
+
+# UI Review: $ARGUMENTS
+
+## Load Skills
+
+```typescript
+skill({ name: "visual-analysis" }); // Analysis framework
+skill({ name: "accessibility-audit" }); // WCAG checklists
+skill({ name: "frontend-design" }); // Anti-patterns, design quality
+```
+
+## Input
+
+Parse `$ARGUMENTS`:
+
+- **Path** (required): Image, screenshot, or component file
+- **`--responsive`**: Include responsive breakpoint review
+- **`--dark-mode`**: Include dark mode review
+
+## Review Workflow
+
+### 1. Analyze the Input
+
+Use the `visual-analysis` skill to perform deep analysis:
+
+- Content inventory (elements, text, icons)
+- Visual properties (colors, typography, spacing, layout)
+- Design patterns and potential issues
+
+### 2. Score Categories
+
+Rate each 1-10 with brief justification:
+
+| Category               | What to Evaluate                                               |
+| ---------------------- | -------------------------------------------------------------- |
+| **Typography**         | Hierarchy, readability, weight contrast, intentional choices   |
+| **Color**              | Palette cohesion, contrast, semantic usage, no AI slop         |
+| **Layout & Spacing**   | Visual hierarchy, consistency, alignment, white space          |
+| **Interactive States** | Hover, focus, active, disabled, loading coverage               |
+| **Accessibility**      | WCAG AA compliance (use `accessibility-audit` skill checklist) |
+| **Visual Polish**      | Consistency, attention to detail, motion, shadows, icons       |
+
+### 3. Conditional Reviews
+
+**If `--responsive`**: Check at 375px, 768px, 1280px, 1536px+. Flag touch targets, horizontal scroll, text sizing.
+
+**If `--dark-mode`**: Check contrast on dark backgrounds, adapted colors (not just inverted), shadow adjustments, focus visibility.
+
+### 4. Report Findings
+
+Group by severity:
+
+- **Critical (Must Fix)**: Accessibility failures, broken interactions
+- **Warning (Should Fix)**: AI slop patterns, inconsistent spacing, missing states
+- **Info (Nice to Have)**: Polish opportunities
+
+For each finding: location, impact, and recommended fix.
+
+## Output
+
+Deliver:
+
+1. Category scores (1-10 each) with justification
+2. Overall assessment (1-2 sentences)
+3. Findings grouped by severity with actionable fixes
+4. Code fixes for critical issues (if reviewing component code)
+
+## Record Findings
+
+```typescript
+observation({
+  type: "warning",
+  title: "UI: [Component] [issue type]",
+  narrative: "Found [issue] in [location]. Impact: [description]...",
+  concepts: "ui, accessibility, [category]",
+  confidence: "high",
+});
+```
+
+## Related Commands
+
+| Need                 | Command   |
+| -------------------- | --------- |
+| Design from scratch  | `/design` |
+| Start implementation | `/start`  |
+| Ship implementation  | `/ship`   |

package/baseline/command/ui-slop-check.md

@@ -0,0 +1,146 @@
+---
+description: Audit changed UI files for AI slop patterns and design-system violations
+argument-hint: "[path|auto] [--staged] [--since=<ref>] [--full-report]"
+agent: vision
+model: proxypal/gemini-3-pro-preview
+---
+
+# UI Slop Check: $ARGUMENTS
+
+Run a focused anti-slop audit against changed UI files using the frontend-design taxonomy.
+
+## Load Skills
+
+```typescript
+skill({ name: "frontend-design" }); // Anti-pattern taxonomy + design references
+skill({ name: "visual-analysis" }); // Structured visual/code analysis workflow
+skill({ name: "accessibility-audit" }); // Keyboard/focus/contrast checks
+```
+
+## Parse Arguments
+
+| Argument        | Default | Description                                        |
+| --------------- | ------- | -------------------------------------------------- | ----------------------------------------------------------- |
+| `[path          | auto]`  | `auto`                                             | Specific file/dir to audit, or auto-detect changed UI files |
+| `--staged`      | false   | Audit staged changes only (`git diff --cached`)    |
+| `--since=<ref>` | `HEAD`  | Compare against ref (`main`, `HEAD~1`, commit SHA) |
+| `--full-report` | false   | Include all categories even when no issues found   |
+
+## Phase 1: Resolve Target Files
+
+If `[path]` is provided:
+
+- Audit that path directly
+
+If `auto`:
+
+```bash
+# unstaged + staged by default
+git diff --name-only $SINCE_REF -- \
+  '*.tsx' '*.jsx' '*.css' '*.scss' '*.sass' '*.less' '*.html' '*.mdx'
+```
+
+If `--staged`:
+
+```bash
+git diff --cached --name-only -- \
+  '*.tsx' '*.jsx' '*.css' '*.scss' '*.sass' '*.less' '*.html' '*.mdx'
+```
+
+Prioritize files under:
+
+- `src/components/**`
+- `src/app/**`
+- `src/pages/**`
+- `app/**`
+- `components/**`
+
+If no UI files changed, return: **PASS (no changed UI files)**.
+
+## Phase 2: Run AI Slop Checklist
+
+Evaluate each target file (or rendered screenshot if provided) against these checks.
+
+### A) Typography
+
+- Banned default aesthetics (Inter/Roboto/Arial/Open Sans as dominant display voice)
+- Body text uses `rem/em`, not fixed `px`
+- Clear hierarchy (size/weight/spacing), not color-only hierarchy
+- Body line length near readable measure (around 65ch when applicable)
+
+### B) Color and Theming
+
+- No AI default palette tropes (purple-blue gradient defaults, neon-on-dark clichés)
+- No pure `#000` / `#fff` as dominant surfaces
+- Gray text is not placed on saturated backgrounds
+- Semantic tokens are used (not random per-component hardcoded colors)
+- Dark mode is adapted, not simple inversion
+
+### C) Layout and Spatial Rhythm
+
+- No cards-inside-cards without strong information architecture reason
+- No repetitive cookie-cutter card blocks with identical structure
+- Spacing rhythm is consistent (4pt-style cadence), not arbitrary jumps
+- Uses `gap`/layout primitives cleanly; avoids margin hacks when possible
+
+### D) Motion and Interaction
+
+- No bounce/elastic gimmick motion for product UI
+- Animations use transform/opacity (avoid layout-thrashing properties)
+- Reduced motion support exists for meaningful motion
+- States exist: hover, focus-visible, active, disabled, loading/error where relevant
+
+### E) UX Writing
+
+- Buttons are verb + object (e.g. "Save changes")
+- Error copy includes what happened + why + how to fix
+- Empty states include guidance + next action
+- Terminology is consistent (avoid mixed synonyms for same action)
+
+### F) Accessibility Safety Nets
+
+- Keyboard-visible focus treatment (`:focus-visible`)
+- Contrast baseline expectations (WCAG AA)
+- Touch targets reasonable (44x44 context where applicable)
+
+## Phase 3: Severity and Scoring
+
+Group findings by severity:
+
+- **Critical**: accessibility failures, broken interaction states, unreadable contrast
+- **Warning**: strong AI fingerprint/slop patterns, inconsistent design system usage
+- **Info**: polish/consistency opportunities
+
+Score each category 1-10 and include evidence (`file:line` for code audits).
+
+## Phase 4: Output
+
+Return:
+
+1. **Result**: PASS / NEEDS WORK
+2. **Audited files** (list)
+3. **Category scores**
+4. **Findings by severity** with actionable fixes
+5. **Fast remediation plan** (top 3 fixes first)
+
+If `--full-report` is false, omit empty categories.
+
+## Record Findings
+
+```typescript
+observation({
+  type: "warning",
+  title: "UI Slop Check: [scope]",
+  narrative: "Detected [count] critical, [count] warning slop issues in changed UI files.",
+  concepts: "ui, design, anti-patterns, frontend",
+  confidence: "high",
+});
+```
+
+## Related Commands
+
+| Need                                     | Command      |
+| ---------------------------------------- | ------------ |
+| Design from scratch                      | `/design`    |
+| Full UI review (single screen/component) | `/ui-review` |
+| Implementation work                      | `/start`     |

package/baseline/command/verify.md

@@ -0,0 +1,160 @@
+---
+description: Verify implementation completeness, correctness, and coherence
+argument-hint: "<bead-id> [--quick] [--full] [--fix] [--no-cache]"
+agent: review
+---
+
+# Verify: $ARGUMENTS
+
+Check implementation against PRD before shipping.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument     | Default  | Description                                    |
+| ------------ | -------- | ---------------------------------------------- |
+| `<bead-id>`  | required | The bead to verify                             |
+| `--quick`    | false    | Gates only, skip coherence check               |
+| `--full`     | false    | Force full verification mode (non-incremental) |
+| `--fix`      | false    | Auto-fix lint/format issues                    |
+| `--no-cache` | false    | Bypass verification cache, force fresh run     |
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                              |
+| ---------- | --------------------------- | ----------------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Check implementation vs PRD in bead |
+| Path       | File/directory path         | Verify that specific path           |
+| `all`      | Keyword                     | Verify all in-progress work         |
+
+## Before You Verify
+
+- **Be certain**: Only flag issues you can verify with tools
+- **Don't invent problems**: If an edge case isn't in the PRD, don't flag it
+- **Run the gates**: Build, test, lint, typecheck are non-negotiable
+- **Use project conventions**: Check `package.json` scripts first
+
+## Phase 0: Check Verification Cache
+
+Before running any gates, check if a recent verification is still valid:
+
+```bash
+# Compute current state fingerprint (commit hash + full diff + untracked files)
+CURRENT_STAMP=$(printf '%s\n%s\n%s' \
+  "$(git rev-parse HEAD)" \
+  "$(git diff HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx')" \
+  "$(git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx' | xargs cat 2>/dev/null)" \
+  | shasum -a 256 | cut -d' ' -f1)
+LAST_STAMP=$(tail -1 .beads/verify.log 2>/dev/null | awk '{print $1}')
+```
+
+| Condition                                 | Action                                                 |
+| ----------------------------------------- | ------------------------------------------------------ |
+| `--no-cache` or `--full`                  | Skip cache check, run fresh                            |
+| `CURRENT_STAMP == LAST_STAMP`             | Report **cached PASS**, skip to Phase 2 (completeness) |
+| `CURRENT_STAMP != LAST_STAMP` or no cache | Run gates normally                                     |
+
+When cache hits, report:
+
+```text
+Verification: cached PASS (no changes since <timestamp from verify.log>)
+```
+
+## Phase 1: Gather Context
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Read the PRD and any other artifacts (plan.md, research.md, design.md).
+
+**Verify guards:**
+
+- [ ] Bead is `in_progress`
+- [ ] `prd.md` exists
+- [ ] You have read the full PRD
+
+## Phase 2: Completeness
+
+Extract all requirements/tasks from the PRD and verify each is implemented:
+
+- For each requirement: find evidence in the codebase (file:line reference)
+- Mark as: complete, partial, or missing
+- Report completeness score (X/Y requirements met)
+
+## Phase 3: Correctness
+
+Follow the [Verification Protocol](../skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md):
+
+**Default: incremental mode** (changed files only, parallel gates).
+
+| Mode        | When                                      | Behavior                         |
+| ----------- | ----------------------------------------- | -------------------------------- |
+| Incremental | Default, <20 changed files                | Lint changed files, test changed |
+| Full        | `--full` flag, >20 changed files, or ship | Lint all, test all               |
+
+**Execution order:**
+
+1. **Parallel**: typecheck + lint (simultaneously)
+2. **Sequential** (after parallel passes): test, then build (ship only)
+
+Report results with mode column:
+
+```text
+| Gate      | Status | Mode        | Time   |
+|-----------|--------|-------------|--------|
+| Typecheck | PASS   | full        | 2.1s   |
+| Lint      | PASS   | incremental | 0.3s   |
+| Test      | PASS   | incremental | 1.2s   |
+| Build     | SKIP   | —           | —      |
+```
+
+**After all gates pass**, record to verification cache:
+
+```bash
+echo "$CURRENT_STAMP $(date -u +%Y-%m-%dT%H:%M:%SZ) PASS" >> .beads/verify.log
+```
+
+If `--fix` flag provided, run the project's auto-fix command (e.g., `npm run lint:fix`, `ruff check --fix`, `cargo clippy --fix`).
+
+## Phase 4: Coherence (skip with --quick)
+
+Cross-reference artifacts for contradictions:
+
+- PRD vs implementation (does code address all PRD requirements?)
+- Plan vs implementation (did code follow the plan?)
+- Research recommendations vs actual approach (if different, is it justified?)
+
+Flag contradictions with specific file references.
+
+## Phase 5: Report
+
+```bash
+br comments add $ARGUMENTS "Verification: [PASS|PARTIAL|FAIL] - [summary]"
+```
+
+Output:
+
+1. **Result**: READY TO SHIP / NEEDS WORK / BLOCKED
+2. **Completeness**: score and status
+3. **Correctness**: gate results (with mode column)
+4. **Coherence**: contradictions found (if not --quick)
+5. **Blocking issues** to fix before shipping
+6. **Next step**: `/ship $ARGUMENTS` if ready, or list fixes needed
+
+Record significant findings with `observation()`.
+
+## Related Commands
+
+| Need              | Command            |
+| ----------------- | ------------------ |
+| Ship after verify | `/ship <id>`       |
+| Review code       | `/review-codebase` |
+| Check status      | `/status`          |

package/baseline/context/README.md

@@ -0,0 +1,29 @@
+# Project Context
+
+Files in this directory are automatically injected into all AI prompts via the `instructions` array in `opencode.json`.
+
+## Purpose
+
+Put project-specific context here that you want the AI to always know about:
+- Architecture decisions
+- Business domain knowledge  
+- API conventions
+- Team agreements
+- Anything the AI needs as background context
+
+## How it works
+
+1. Add `.md` files to this directory
+2. Add the file path to `opencode.json` → `instructions[]`:
+   ```json
+   "instructions": [
+     ".opencode/context/your-file.md"
+   ]
+   ```
+3. The file content will be injected into every AI prompt
+
+## Important
+
+- This directory is **preserved** during `init --force` and `upgrade`
+- Keep files concise — every token counts in the AI context window
+- Use markdown format for best results