opencode-starterkit 1.0.1

package/baseline/command/create.md

@@ -0,0 +1,213 @@
+---
+description: Create a bead with specification from a description
+argument-hint: "<description> [--type epic|feature|task|bug]"
+agent: build
+---
+
+# Create: $ARGUMENTS
+
+Create a bead and its specification (PRD) from a description.
+
+> **Workflow:** **`/create`** → `/start <id>` → `/ship <id>`
+>
+> ⛔ This command creates the specification ONLY. Do NOT write any implementation code.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "prd" }); // PRD template guidance
+```
+
+## Parse Arguments
+
+| Argument        | Default       | Description                        |
+| --------------- | ------------- | ---------------------------------- |
+| `<description>` | required      | What to build/fix (quoted string)  |
+| `--type`        | auto-detected | Override: epic, feature, task, bug |
+
+## Determine Input Type
+
+| Input Type  | Detection            | Action                        |
+| ----------- | -------------------- | ----------------------------- |
+| Quoted text | `"description here"` | Create PRD from description   |
+| Short form  | Simple string        | Ask for more detail if needed |
+| `--type`    | Flag provided        | Use provided type             |
+
+## Before You Create
+
+- **Be certain**: Only create beads you're confident have clear scope
+- **Don't over-spec**: If the description is vague, ask clarifying questions first
+- **Check duplicates**: Always run Phase 1 duplicate check
+- **No implementation**: This command creates specs only, don't write code
+- **Verify PRD**: Before saving, verify all sections are filled (no placeholders)
+
+## Available Tools
+
+| Tool      | Use When                                     |
+| --------- | -------------------------------------------- |
+| `explore` | Finding patterns in codebase, affected files |
+| `scout`   | External research, best practices            |
+| `br`      | Creating and managing beads                  |
+
+## Phase 1: Duplicate Check
+
+```bash
+br list --status=open --status=in_progress
+```
+
+If a matching bead exists, stop and tell the user to use `/start <id>` instead.
+
+## Phase 2: Classify Type
+
+If `--type` was provided, use it directly. Otherwise, suggest a type based on the description and ask the user to confirm:
+
+- **epic**: Multi-session, cross-domain (redesign, migrate, overhaul)
+- **feature**: New capability, scoped (add, implement, build, integrate)
+- **bug**: Something broken (fix, error, crash, not working)
+- **task**: Tactical change, clear scope (everything else)
+
+## Phase 3: Choose Research Depth
+
+Ask user before spawning agents:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Research Depth",
+      question: "How much codebase research do you need?",
+      options: [
+        {
+          label: "Deep (Recommended for complex work)",
+          description: "3-5 agents: patterns, tests, deps, best practices (~2 min)",
+        },
+        {
+          label: "Standard",
+          description: "2 agents: patterns + tests (~1 min)",
+        },
+        {
+          label: "Minimal",
+          description: "1 agent: quick file scan (~30 sec)",
+        },
+        {
+          label: "Skip",
+          description: "I know the codebase, use existing knowledge",
+        },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 4: Gather Context
+
+Based on research depth choice, spawn agents:
+
+**If Deep:**
+
+- 3x `explore` (patterns, tests, deps)
+- 1x `scout` (feature/epic)
+- 1x `review` (epic)
+
+**If Standard:**
+
+- 2x `explore` (patterns, tests)
+- 1x `scout` (feature/epic only)
+
+**If Minimal:**
+
+- 1x `explore` (patterns)
+
+**If Skip:**
+
+- No agents, use existing AGENTS.md context
+
+**While agents run**, ask clarifying questions if the description lacks scope or expected outcome. For bugs, also ask for reproduction steps and expected vs actual behavior.
+
+## Phase 5: Create Bead
+
+Extract bead title and description from `$ARGUMENTS` before creating the bead.
+
+- If user provided a single line, use it for both title and description.
+- If user provided multiple lines, use first line as title and full text as description.
+
+```bash
+TITLE=$(echo "$ARGUMENTS" | head -n1)
+DESCRIPTION=$(echo "$ARGUMENTS")
+
+if [ "$TITLE" = "$DESCRIPTION" ]; then
+  DESCRIPTION="$TITLE"
+fi
+
+BEAD_ID=$(br create --title "$TITLE" --description "$DESCRIPTION" --type $BEAD_TYPE --json | jq -r '.id')
+mkdir -p ".beads/artifacts/$BEAD_ID"
+```
+
+## Phase 6: Write PRD
+
+Copy and fill the PRD template using context from Phase 3:
+
+```bash
+cp .opencode/memory/_templates/prd.md ".beads/artifacts/$BEAD_ID/prd.md"
+```
+
+### Required Sections
+
+| Section           | Source                                                     | Required          |
+| ----------------- | ---------------------------------------------------------- | ----------------- |
+| Problem Statement | User description + clarifying questions                    | Always            |
+| Scope (In/Out)    | User input + codebase exploration                          | Always            |
+| Proposed Solution | Codebase patterns + user intent                            | Always            |
+| Success Criteria  | User verification + test commands (must include `Verify:`) | Always            |
+| Technical Context | Explore agent findings                                     | Always            |
+| Affected Files    | Explore agent findings (real paths from Phase 3)           | Always            |
+| Tasks             | Derived from scope + solution                              | Always            |
+| Risks             | Codebase exploration                                       | Feature/epic only |
+| Open Questions    | Unresolved items from Phase 3                              | If any exist      |
+
+### Task Format
+
+Tasks must follow the `prd-task` skill format:
+
+- Title with `[category]` tag
+- One-sentence **end state** description (not step-by-step)
+- Metadata block: `depends_on`, `parallel`, `conflicts_with`, `files`
+- At least one verification command per task
+
+## Phase 7: Validate PRD
+
+Before saving, verify:
+
+- [ ] No placeholder text remains (e.g., "[Clear description", "[List what's allowed]")
+- [ ] Success criteria include `Verify:` commands
+- [ ] Technical context references actual `src/` paths from exploration
+- [ ] Affected files list real paths
+- [ ] Tasks have `[category]` headings
+- [ ] Each task has verification
+- [ ] No implementation code in the PRD
+
+If any check fails, fix it — don't ask the user.
+
+## Phase 8: Report
+
+Output:
+
+1. Bead ID and type
+2. PRD location (`.beads/artifacts/$BEAD_ID/prd.md`)
+3. Summary: task count, success criteria count, affected files count
+4. Next steps: `/start $BEAD_ID` or `/plan $BEAD_ID`
+
+```bash
+br comments add $BEAD_ID "Created prd.md with [N] tasks, [M] success criteria"
+```
+
+---
+
+## Related Commands
+
+| Need            | Command       |
+| --------------- | ------------- |
+| Research first  | `/research`   |
+| Plan after spec | `/plan <id>`  |
+| Start working   | `/start <id>` |

package/baseline/command/design.md

@@ -0,0 +1,112 @@
+---
+description: UI/UX visual design with aesthetic direction and code output
+argument-hint: "<component|page|system> [topic] [--quick]"
+agent: vision
+---
+
+# Design: $ARGUMENTS
+
+Design a component, page, or design system with a clear aesthetic point of view.
+
+> **Design track (optional):** Not part of the core `/create → /start → /ship` workflow.
+> Use when you need visual design guidance before or during implementation.
+
+## Parse Arguments
+
+| Argument    | Default  | Description                                 |
+| ----------- | -------- | ------------------------------------------- |
+| `component` | —        | Design a specific component                 |
+| `page`      | —        | Design a page layout                        |
+| `system`    | —        | Create or extend a design system            |
+| `[topic]`   | required | What to design (e.g. "button", "dashboard") |
+| `--quick`   | false    | High-level direction only, skip code        |
+
+## Load Skills
+
+```typescript
+skill({ name: "frontend-design" }); // Design system guidance, anti-patterns, references
+```
+
+---
+
+## Phase 1: Detect Existing Design System
+
+```typescript
+glob({ pattern: "**/tailwind.config.{js,ts,mjs}" });
+glob({ pattern: "**/globals.css" });
+glob({ pattern: "**/components.json" }); // shadcn
+```
+
+Read what exists. Don't design in a vacuum — build on the project's current system.
+
+---
+
+## Phase 2: Check Memory
+
+```typescript
+memory_search({ query: "[topic] design UI", limit: 3 });
+memory_search({ query: "design system colors typography", limit: 3 });
+```
+
+Reuse existing aesthetic decisions. Don't contradict previous design choices unless the user asks.
+
+---
+
+## Phase 3: Design
+
+The `frontend-design` skill provides all reference material:
+
+- Aesthetic directions and design philosophy
+- Typography and font pairing guidance
+- Color systems (OKLCH)
+- Animation patterns (Motion + Tailwind)
+- Anti-patterns and AI slop avoidance
+- shadcn/ui component patterns
+- Tailwind v4 configuration
+
+**Before designing, state:**
+
+1. **Aesthetic direction** — which style and why
+2. **Key characteristics** — 3 specific elements you'll apply
+
+Then produce the design:
+
+| Task Type   | Output                                |
+| ----------- | ------------------------------------- |
+| `component` | Spec (variants, sizes, states) + code |
+| `page`      | Layout structure + section breakdown  |
+| `system`    | Tokens (CSS variables) + guidelines   |
+
+For `--quick`: Skip code output. Provide direction + key decisions only.
+
+---
+
+## Phase 4: Record Decision
+
+```typescript
+observation({
+  type: "decision",
+  title: "Design: [topic]",
+  narrative: "Chose [direction] because [rationale]. Key tokens: [colors, fonts].",
+  concepts: "design, ui, [topic]",
+  confidence: "high",
+});
+```
+
+---
+
+## Examples
+
+```bash
+/design component button           # Full component design with code
+/design page landing --quick       # High-level page direction only
+/design system                     # Create/extend design system tokens
+```
+
+## Related Commands
+
+| Need               | Command         |
+| ------------------ | --------------- |
+| Review existing UI | `/ui-review`    |
+| Start building     | `/start <bead>` |
+| Ship it            | `/ship <bead>`  |

package/baseline/command/handoff.md

@@ -0,0 +1,147 @@
+---
+description: Save progress and context for next session
+argument-hint: "<bead-id> [instructions]"
+agent: build
+---
+
+# Handoff: $ARGUMENTS
+
+Save state so the next session can pick up cleanly.
+
+> **Workflow:** Run this when pausing work. Resume with `/resume $ARGUMENTS`.
+
+## Parse Arguments
+
+| Argument         | Default  | Description                        |
+| ---------------- | -------- | ---------------------------------- |
+| `<bead-id>`      | required | The bead to hand off               |
+| `[instructions]` | none     | Extra context for the next session |
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "memory-system" });
+```
+
+---
+
+## Phase 1: Gather State (Parallel)
+
+```bash
+br show $ARGUMENTS
+git status --porcelain
+git branch --show-current
+git rev-parse --short HEAD
+ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null
+```
+
+---
+
+## Phase 2: Handle Uncommitted Changes
+
+If `git status` shows uncommitted changes, ask the user:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Uncommitted work",
+      question: "You have uncommitted changes. What should we do?",
+      options: [
+        { label: "Commit as WIP (Recommended)", description: "git commit -m 'WIP: $ARGUMENTS'" },
+        { label: "Leave uncommitted", description: "Skip commit, just write handoff" },
+      ],
+    },
+  ],
+});
+```
+
+If user chooses commit:
+
+```bash
+git add -A
+git commit -m "WIP: $ARGUMENTS - [brief description of where you stopped]"
+```
+
+---
+
+## Phase 3: Write Handoff
+
+Write the handoff to the memory system:
+
+```typescript
+memory_update({
+  file: "handoffs/$ARGUMENTS",
+  content: `# Handoff: $ARGUMENTS
+
+**Date:** [timestamp]
+**Branch:** [from git branch]
+**Commit:** [from git rev-parse]
+
+## Done
+- [completed work]
+
+## In Progress
+- [current step] — stopped because [reason]
+
+## Remaining
+- [next steps]
+
+## Files Touched
+- \`path/to/file.ts\` — [what changed]
+
+## Decisions
+- [decision]: [why]
+
+## Blockers
+[any blockers, or "None"]
+
+## Resume Instructions
+1. [first thing to do]
+2. [second thing to do]
+
+Resume with: \`/resume $ARGUMENTS\`
+`,
+  mode: "replace",
+});
+```
+
+---
+
+## Phase 4: Record Learnings (If Any)
+
+If you discovered patterns or gotchas worth remembering:
+
+```typescript
+observation({
+  type: "learning",
+  title: "[concise, searchable title]",
+  narrative: "[what you learned — specific and actionable]",
+  bead_id: "$ARGUMENTS",
+  concepts: "[keywords for search]",
+});
+```
+
+---
+
+## Phase 5: Sync
+
+```bash
+br sync --flush-only
+```
+
+---
+
+## Output
+
+```
+Handoff: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━
+
+Branch: [branch]
+Commit: [hash]
+Saved:  handoffs/$ARGUMENTS (memory system)
+
+Next session: /resume $ARGUMENTS
+```