@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/command/design.md

@@ -0,0 +1,130 @@
+---
+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 → /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
+skill({ name: "ux-quality-gates" }); // IA, forms, recovery, loading, usability gates
+```
+
+---
+
+## Phase 1: Detect Existing Design System
+
+```typescript
+tilth_tilth_files({ pattern: "**/tailwind.config.{js,ts,mjs}" });
+tilth_tilth_files({ pattern: "**/globals.css" });
+tilth_tilth_files({ 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: UX Structure Decisions
+
+Before visual design, define the interaction structure. A beautiful screen with unclear scope, weak recovery, or missing states is still failed design.
+
+State these decisions explicitly:
+
+1. **Primary action** — the one dominant action for the component/page/flow
+2. **User-facing vocabulary** — entity/action names the UI will use consistently
+3. **Scope and relationships** — what this UI affects, where the user is, and what related objects matter
+4. **Dangerous actions** — destructive/bulk/account/security actions and their confirm/undo/recovery pattern
+5. **State model** — empty, loading, error, success, disabled, and optimistic states required
+6. **Pattern selection** — form, table/list/grid, notification, modal, or navigation pattern if applicable
+
+Use the `ux-quality-gates` skill to keep these decisions concrete.
+
+---
+
+## Phase 4: 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
+3. **UX gates satisfied** — primary action, states, recovery, and accessibility baseline
+
+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 5: 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`   |
+| Ship it            | `/ship <bead>` |

package/dist/template/.opencode/command/explore.md

@@ -0,0 +1,170 @@
+---
+description: Think through an idea with structured alternatives before committing to a change
+argument-hint: "<idea or question>"
+agent: plan
+---
+
+# Explore: $ARGUMENTS
+
+Think through an idea, problem, or approach with structured alternatives and tradeoffs — before committing to a bead or plan.
+
+> **Workflow:** **`/explore`** → `/create` (if worth pursuing) or discard
+>
+> Use when you're not sure WHAT to build or HOW to approach it. This is ideation with rigor, not open-ended brainstorming.
+>
+> **When to use:** Before `/create`, when the approach isn't obvious. Skip for clear, well-scoped work.
+
+## Load Skills
+
+```typescript
+skill({ name: "brainstorming" }); // Collaborative refinement
+skill({ name: "memory-grounding" }); // Load past decisions
+```
+
+## Phase 1: Ground
+
+Search for prior art and past decisions:
+
+```typescript
+memory_search({ query: "<topic keywords>", limit: 5 });
+```
+
+```bash
+# What exists in the codebase already?
+git log --oneline -20 | grep -i "<keyword>"
+```
+
+Spawn an explore agent to understand the current state:
+
+```typescript
+task({
+  subagent_type: "explore",
+  description: "Map existing patterns for this area",
+  prompt: `Search the codebase for existing implementations, patterns, and conventions related to: $ARGUMENTS
+
+  Return: what exists today, what patterns are used, what files are involved.`,
+});
+```
+
+## Phase 2: Frame the Problem
+
+Before proposing solutions, state the problem clearly:
+
+1. **What's the goal?** (outcome, not task)
+2. **What constraints exist?** (tech stack, time, compatibility, user preferences)
+3. **What's the risk of doing nothing?** (is this urgent or nice-to-have?)
+
+If the problem isn't clear after reading context, ask the user to clarify — but max 2 questions.
+
+## Phase 3: Generate Alternatives
+
+Produce 2-3 approaches. For each:
+
+| Aspect       | What to Cover                          |
+| ------------ | -------------------------------------- |
+| **Approach** | 1-2 sentence summary                   |
+| **How**      | Key implementation steps (3-5 bullets) |
+| **Pros**     | What this gets right                   |
+| **Cons**     | What this gets wrong or makes harder   |
+| **Effort**   | S (<1h), M (1-3h), L (1-2d), XL (>2d)  |
+| **Risk**     | What could go wrong                    |
+
+**Rules for alternatives:**
+
+- At least one must be the simplest viable option
+- At least one must be different in kind, not just degree (different architecture, not just different library)
+- Don't pad with bad options to make the recommended one look good
+
+## Phase 4: Recommend
+
+Pick one approach and explain why:
+
+```markdown
+## Recommendation
+
+**Approach:** [Name]
+**Effort:** [S/M/L/XL]
+**Why:** [2-3 sentences — why this over the others]
+**When to reconsider:** [What signals would make you switch to an alternative]
+```
+
+## Phase 5: Output Proposal
+
+Write the proposal as a structured document:
+
+```markdown
+# Exploration: [Topic]
+
+## Problem
+
+[What we're trying to solve]
+
+## Constraints
+
+- [Constraint 1]
+- [Constraint 2]
+
+## Alternatives
+
+### Option A: [Name]
+
+- **How:** ...
+- **Pros:** ...
+- **Cons:** ...
+- **Effort:** S/M/L/XL
+
+### Option B: [Name]
+
+- **How:** ...
+- **Pros:** ...
+- **Cons:** ...
+- **Effort:** S/M/L/XL
+
+### Option C: [Name] (if applicable)
+
+...
+
+## Recommendation
+
+**Option [X]** because [reasoning].
+**Reconsider if:** [triggers for switching]
+
+## Next Step
+
+`/create "[description based on chosen approach]"`
+```
+
+**If a bead exists:** Save to `.beads/artifacts/$BEAD_ID/exploration.md`
+**If no bead:** Display inline, don't create files.
+
+## Phase 6: Ask User
+
+Present the proposal and ask:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Approach",
+      question: "Which approach do you want to pursue?",
+      options: [
+        { label: "Option A (Recommended)", description: "[brief]" },
+        { label: "Option B", description: "[brief]" },
+        { label: "Option C", description: "[brief]" },
+        { label: "None — need more research", description: "Spawn scout agents" },
+      ],
+    },
+  ],
+});
+```
+
+If user picks an approach → suggest `/create "[description]"` with the chosen approach baked in.
+If user wants more research → spawn `@scout` for the specific unknowns.
+
+## Related Commands
+
+| Need                      | Command                             |
+| ------------------------- | ----------------------------------- |
+| Commit to an approach     | `/create`                           |
+| Research external options | `/research`                         |
+| Open-ended ideation       | Load `brainstorming` skill directly |

package/dist/template/.opencode/command/handoff.md

@@ -0,0 +1,149 @@
+---
+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
+Read `.beads/artifacts/$ARGUMENTS/` to check existing artifacts.
+```
+
+---
+
+## 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 <specific-files-you-modified>
+git commit -m "WIP: $ARGUMENTS - [brief description of where you stopped]"
+```
+
+**Never use `git add -A` or `git add .`** — stage only the files you modified.
+
+---
+
+## 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
+```