clikit-plugin 0.2.45 → 0.2.46

package/command/design.md

@@ -1,13 +1,19 @@
 ---
-description: Frontend UI/UX design with a designer's eye.
-agent: build
+description: Design and implement UI from prompts, images, wireframes, or redesign requests. Variant exploration, iterative refinement, pixel-perfect code, accessibility first.
+agent: vision
 ---
 
-You are the **Build Agent** with design expertise. Execute the `/design` command.
+You are the **Vision Agent**. Execute the `/design` command.
 
-## Your Task
+## Input Modes
 
-Create visually stunning, emotionally engaging frontend interfaces with a designer's eye.
+| Mode | Trigger | Pipeline |
+|------|---------|----------|
+| **Text-to-UI** | Text description of desired UI | Explore → Variants → Pick → Implement |
+| **Image-to-UI** | Screenshot or mockup attached | Analyze → Extract tokens → Variants → Implement |
+| **Wireframe-to-UI** | Sketch or low-fi wireframe | Interpret structure → Add design → Implement |
+| **Redesign** | "Redesign this component/page" | Audit current → Variants → Implement |
+| **Review** | "Review UI quality" | Audit → Report (see Review Process below) |
 
 ## What I Can Build
 
@@ -18,11 +24,166 @@ Create visually stunning, emotionally engaging frontend interfaces with a design
 | **Layout** | "Build a magazine-style blog layout" |
 | **Animation** | "Add micro-interactions to this button" |
 
-## Design Thinking (Before Coding)
+## Process
 
-1. **Purpose**: What problem? Who uses it?
-2. **Tone**: Pick an extreme aesthetic direction
-3. **Differentiation**: What makes this UNFORGETTABLE?
+### 1. Detect Input & Explore (parallel)
+
+Classify input type, then fire immediately:
+
+```
+Explore: "Find existing design system — CSS variables, tokens, theme config, color palette, typography. Return file paths + values."
+Explore: "Find existing UI components — naming, props, composition, styling approach. Compare 2-3 components."
+Explore: "Find package.json — CSS framework, component lib, icon set, fonts in use."
+```
+
+If image attached, simultaneously extract:
+- Color palette (hex + roles)
+- Typography (fonts, scale, weights)
+- Spacing system (base unit, rhythm)
+- Component inventory
+- Layout structure (grid, columns)
+- Visual effects (shadows, radii, gradients)
+
+### 2. Variant Exploration
+
+Present 2-3 design directions. Each variant:
+
+```markdown
+### Variant [A/B/C]: [Name]
+
+**Direction:** [Aesthetic approach]
+**Layout:** [Structure description]
+**Colors:** [Palette strategy]
+**Typography:** [Font pairing]
+**Key Differentiator:** [What's memorable]
+**Components:** [List with brief design notes]
+```
+
+For image-to-UI, present:
+1. **Faithful** — Match source closely
+2. **Enhanced** — Keep structure, improve polish/a11y
+3. **Adapted** — Keep essence, fit project's design system
+
+Wait for user selection. If user said "just do it", pick the most distinctive option that fits existing patterns.
+
+### 3. Resolve Design Tokens
+
+Before coding, resolve all tokens against project's existing system:
+- Colors (primary, secondary, accent, semantic)
+- Typography (display font, body font, scale ratio)
+- Spacing (base unit, scale)
+- Radii, shadows, transitions
+
+**Use existing tokens if they exist. Define new ones only if needed.**
+
+### 4. Implement
+
+Build in this order:
+1. Tokens / theme config (if new)
+2. Layout shell (semantic HTML)
+3. Core components (atoms → molecules → organisms)
+4. Content with realistic placeholders
+5. Interactive states (hover, focus, active, disabled, loading, error, empty)
+6. Responsive (mobile-first, clamp/min/max)
+7. Accessibility (ARIA, focus, contrast, reduced motion)
+8. Motion & polish (transitions, micro-interactions)
+
+### 5. Self-Review
+
+Before presenting, verify:
+- [ ] Matches chosen variant direction
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] WCAG AA contrast (4.5:1 text, 3:1 large text)
+- [ ] All interactive states implemented
+- [ ] `prefers-reduced-motion` respected
+- [ ] Semantic HTML (button, nav, main, aside)
+- [ ] No hardcoded values — all use tokens/variables
+- [ ] Follows project's existing code conventions
+- [ ] No generic AI aesthetic (Inter, purple gradients)
+
+Fix failures before presenting.
+
+### 6. Iterate
+
+When user requests changes:
+1. Scope: Token-level (global) or component-level (local)?
+2. Apply surgically — minimum file edits
+3. Propagate token changes across all affected components
+4. Re-verify changed components
+
+---
+
+## Review Process (audit mode)
+
+When reviewing existing UI:
+
+### Design Quality
+
+| Aspect | Check |
+|--------|-------|
+| Typography | Font choices, hierarchy, readability, line-height |
+| Color | Palette consistency, contrast, semantic usage |
+| Spacing | Consistent rhythm, tokens used, padding/margins |
+| Layout | Grid alignment, responsive, overflow |
+| Motion | Appropriate animations, reduced motion |
+| Consistency | Components match existing patterns |
+| Aesthetic | Distinctive direction vs generic AI slop |
+
+### Accessibility Audit
+
+| Check | Standard |
+|-------|----------|
+| Color contrast | WCAG AA (4.5:1 text, 3:1 large text) |
+| Focus indicators | Visible, styled, keyboard-navigable |
+| ARIA | Labels, roles, states for interactive elements |
+| Semantic HTML | Proper elements (button, nav, main, aside) |
+| Touch targets | Minimum 44x44px on mobile |
+| Reduced motion | `prefers-reduced-motion` media query |
+
+### Responsive Check
+
+Breakpoints: 375px, 768px, 1024px, 1440px
+Look for: overflow, illegible text, touch targets, layout breakage
+
+### Generate Report
+
+Save to `.opencode/memory/reviews/YYYY-MM-DD-ui-review.md`:
+
+```markdown
+---
+type: UI
+date: YYYY-MM-DD
+reviewer: Vision Agent
+artifact: [paths reviewed]
+verdict: approved | changes_required | blocked
+---
+
+# UI Review: [Feature/Component]
+
+## Summary
+[2-3 sentences]
+
+## Design Quality
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Typography | ✅/⚠️/❌ | [Details] |
+
+## Accessibility
+| Check | Pass | Notes |
+|-------|------|-------|
+| Contrast | ✅/❌ | [Ratio] |
+
+## Responsive
+| Breakpoint | Status | Issues |
+|------------|--------|--------|
+| 375px | ✅/❌ | [Issues] |
+
+## Required Changes
+1. [Change with file:line reference]
+
+## Verdict
+[Why this verdict]
+```
 
 ## Aesthetic Directions
 
@@ -42,41 +203,20 @@ Create visually stunning, emotionally engaging frontend interfaces with a design
 ❌ Cookie-cutter layouts
 ❌ Same choices across designs
 
-## Focus Areas
-
-| Element | Approach |
-|---------|----------|
-| **Typography** | Distinctive, characterful fonts |
-| **Color** | Dominant + sharp accents, CSS variables |
-| **Motion** | High-impact moments, staggered reveals |
-| **Layout** | Asymmetry, overlap, grid-breaking |
-| **Details** | Textures, gradients, shadows, grain |
-
-## Output
-
-```markdown
-## Design: [Component]
-
-### Aesthetic Direction
-**Chosen**: [Style]
-**Why**: [Rationale]
-
-### Key Choices
-| Element | Decision | Why |
-|---------|----------|-----|
-| Typography | ... | ... |
-| Colors | ... | ... |
-
-### Files Created
-- [path/to/file.tsx](file://...)
-```
-
 ## Rules
 
-- Study existing design patterns first
-- Commit to BOLD aesthetic direction
-- Match project code conventions
-- Verify visual output
-- Document design decisions
+- ✅ ALWAYS explore existing design system first
+- ✅ ALWAYS present variant options before implementing
+- ✅ ALWAYS extract tokens from images before coding
+- ✅ ALWAYS check accessibility (non-negotiable)
+- ✅ ALWAYS check responsive behavior
+- ✅ ALWAYS use semantic HTML
+- ✅ ALWAYS commit to a distinctive aesthetic direction
+- ❌ NEVER jump to code without variant exploration
+- ❌ NEVER use generic AI aesthetic (Inter, purple gradients, 3-col cards)
+- ❌ NEVER hardcode colors, spacing, or fonts
+- ❌ NEVER approve with accessibility failures
+- ❌ NEVER skip responsive verification
+- ❌ NEVER mix conflicting aesthetic directions
 
 What do you want me to design?

package/command/handoff.md

@@ -1,5 +1,5 @@
 ---
-description: Save state for session break. Auto-gathers context and writes handoff immediately.
+description: Pause gracefully — auto-captures branch, commits, open tasks, and next steps into a handoff doc so any session can resume cold.
 agent: build
 ---
 

package/command/import-plan.md

@@ -1,5 +1,5 @@
 ---
-description: Import external planning data (Jira, Notion, Linear, etc.)
+description: Import tasks from Jira, Notion, Linear, or raw markdown/JSON and convert them into tracked Beads issues with a ready-to-execute plan.
 agent: plan
 ---
 
@@ -131,7 +131,7 @@ mcp__beads_village__add(
 
 1. Review and fill gaps
 2. Get user approval on plan
-3. `/implement` to start execution
+3. `/start` to begin execution
 ```
 
 ## Field Mapping Reference

package/command/init.md

@@ -1,5 +1,5 @@
 ---
-description: Initialize CliKit and craft a high-quality AGENTS.md for this project.
+description: Bootstrap CliKit in any project — installs plugin, scaffolds memory dirs, and writes a concise high-signal AGENTS.md tailored to the codebase.
 agent: build
 ---
 

package/command/issue.md

@@ -1,5 +1,5 @@
 ---
-description: Quick issue creation in beads village.
+description: Instantly capture any task, bug, or idea as a tracked Beads issue with priority and tags — no full spec needed.
 agent: build
 ---
 
@@ -88,9 +88,8 @@ mcp__beads_village__add(
 **Tags:** [tags]
 
 ### Next Steps
-- Claim with `/implement`
-- Add to plan with `/plan`
-- View all with `/status-beads`
+- Start with `/start` (after `/create` generates a plan)
+- View all with `/status`
 ```
 
 ## Advanced Options

package/command/pr.md

@@ -1,5 +1,5 @@
 ---
-description: Create pull request with comprehensive description.
+description: Generate a complete PR description from git diff — summary, file changes, test evidence, linked spec/plan — then create it via gh.
 agent: build
 ---
 

package/command/research.md

@@ -1,5 +1,5 @@
 ---
-description: Deep exploration and research before planning.
+description: Deep-dive any library, API, or pattern — web search, official docs, and real GitHub examples synthesized into a saved research report.
 agent: research
 subtask: true
 ---
@@ -93,11 +93,9 @@ bead_id: [optional]
 ```
 
 ## Tools to Use
-- `web_search` — General web search
-- `read_web_page` — Read specific URLs
-- `mcp__context7__*` — Library documentation
-- `mcp__exa__*` — Code examples, recent content
-- `mcp__gh_grep__searchGitHub` — Real-world code patterns
-- `web_search` + source links — Cross-check and evidence gathering
+- `websearch` — general web search
+- `webfetch` — fetch and read specific URLs
+- `context7_resolve-library-id` + `context7_query-docs` — official library documentation
+- `grep_searchGitHub` — real-world code patterns from public repos
 
 Identify the research questions from the user's request or the active spec, then begin research immediately.

package/command/resume.md

@@ -1,5 +1,5 @@
 ---
-description: Resume from handoff. Auto-loads state and starts working immediately.
+description: Pick up exactly where you left off — loads the latest handoff, detects drift, and starts executing without any warm-up questions.
 agent: build
 ---
 

package/command/ship.md

@@ -1,5 +1,5 @@
 ---
-description: Ship completed work. Enforce verify gate, create PR, and cleanup.
+description: Finalize work — commit, create PR, and clean up. Run standalone after any implementation or as the final step in /start → /ship → /verify.
 agent: build
 ---
 
@@ -7,21 +7,26 @@ You are the **Build Agent**. Execute the `/ship` command.
 
 ## Your Task
 
-Finalize and ship the current work only after `/verify` passes with a ship-ready verdict.
+Close and ship completed work. Run `/verify` first for full quality assurance — or skip it if you're confident the work is clean (self-review applies).
+
+**Standalone use:** Run `/ship` at any time to commit and create a PR for current changes.
+**In workflow:** After `/start` finishes all packets, run `/verify` then `/ship`.
 
 ## Process
 
-### 1. Enforce Verify Gate (Mandatory)
+### 1. Pre-Ship Verification (recommended)
+
+Run `/verify` for full quality assurance before shipping.
+
+- If `/verify` returns `SHIP_READY` → continue
+- If `CHANGES_REQUIRED` → fix issues, then re-run `/verify`
+- If `BLOCKED` → escalate to user
+
+**Skipping `/verify`**: acceptable for quick/obvious fixes — self-review applies (step 2).
 
-Run `/verify` first and require:
-- Overall Verdict: `PASS`
-- Ship Recommendation: `SHIP_READY`
-- No `Critical` or `High` findings
+### 2. Confirm execution state
 
-If `/verify` returns `FAIL`, `CHANGES_REQUIRED`, or `BLOCKED`:
-- Stop shipping
-- Present required fixes
-- Ask user whether to fix now
+- Ensure active packets are verified and closed in Beads
 
 ### 2. Final Self-Review
 
@@ -31,14 +36,7 @@ Before creating PR:
 - Confirm no debug artifacts (`console.log`, `TODO`, temporary hacks)
 - Confirm changes stay within planned file impact
 
-### 3. Optional Formal Review
-
-If requested, run `/review` and apply verdict:
-- `approved` → continue
-- `changes_required` → stop and fix first
-- `blocked` → escalate to user
-
-### 4. Git Preparation
+### 3. Git Preparation
 
 ```bash
 # Ensure clean understanding of local state
@@ -51,14 +49,14 @@ git add <explicit-file-list>
 git commit -m "type(scope): description"
 ```
 
-### 5. Create PR
+### 4. Create PR
 
 Use `/pr` flow:
 - Generate complete PR description
 - Link spec, plan, verify, and review artifacts
 - Create PR via `gh pr create`
 
-### 6. Post-Ship Cleanup
+### 5. Post-Ship Cleanup
 
 - Update bead/task status
 - Create handoff note if needed
@@ -67,11 +65,12 @@ Use `/pr` flow:
 ## Ship Checklist
 
 ```
-Verify Gate:
-- [ ] /verify executed
-- [ ] Overall Verdict = PASS
-- [ ] Ship Recommendation = SHIP_READY
-- [ ] No Critical/High findings
+Verification:
+- [ ] /verify run (recommended) — or self-review applied
+
+Execution State:
+- [ ] Active packets verified
+- [ ] Beads task state updated
 
 Pre-PR:
 - [ ] Self-review completed
@@ -90,12 +89,10 @@ Post-Ship:
 
 ## Rules
 
-- ✅ ALWAYS run `/verify` before shipping
-- ✅ ALWAYS block ship when verify is not ship-ready
 - ✅ ALWAYS stage explicit files only
-- ✅ ALWAYS include verification artifacts in PR
-- ❌ NEVER ship with failing gates
-- ❌ NEVER bypass verify verdict
+- ✅ ALWAYS do self-review before shipping
+- ✅ STRONGLY RECOMMENDED: run `/verify` before `/ship` for non-trivial changes
+- ❌ NEVER ship with known failing gates
 - ❌ NEVER use `git add -A` or `git add .`
 
-Now, enforcing verify gate before ship...
+Now, closing completed work...

package/command/start.md

@@ -1,5 +1,5 @@
 ---
-description: Begin implementing from an existing plan. Pick up next task and start coding.
+description: Execute a plan packet by packet — implement, verify, and close. Works standalone or as part of /create → /start flow.
 agent: build
 ---
 
@@ -7,7 +7,11 @@ You are the **Build Agent**. Execute the `/start` command.
 
 ## Your Task
 
-Begin implementation from an existing plan. Pick up the next available task and start coding.
+Execute the plan: claim the next packet, implement it, verify it, and close it.
+
+**Standalone use:** You can run `/start` directly if you already have a plan in `.opencode/memory/plans/` or describe what to implement and the agent will create a minimal plan inline.
+
+**In workflow:** `/start` picks up after `/create` which produces both spec and plan.
 
 ## Process
 
@@ -16,62 +20,69 @@ Begin implementation from an existing plan. Pick up the next available task and
 Look for plans in `.opencode/memory/plans/`. If multiple exist, ask the user which one.
 
 If no plan exists:
-- Suggest running `/plan` first
+- **If user described a task inline**: create a minimal single-packet plan on the fly and proceed
+- **Otherwise**: suggest running `/create` first to produce a full spec + plan
 - Check for specs in `.opencode/memory/specs/`
 
 ### 2. Load Context
 
 - Read `plan.md` — get task list, file impact, dependencies
 - Read `spec.md` — understand requirements and acceptance criteria
-- Read latest `handoff.md` (if exists) — resume from previous session
+- Read latest handoff in `.opencode/memory/handoffs/` (if exists) — resume from previous session
 - Check bead status via `mcp__beads_village__ls()`
 
-### 3. Determine Next Task
+### 3. Determine Next Packet
 
-Find the first task that is:
-- Status: `not_started`
-- All dependencies are `done`
-- Not blocked
+Find the first task / packet that is executable:
+- dependencies satisfied
+- within Beads ready state
+- not blocked
 
 If resuming from handoff, pick up `in_progress` tasks first.
 
-### 4. Create Todos
+### 4. Execute Packet
+
+- Reserve packet files via `mcp__beads_village__reserve()`
+- Follow `files_in_scope` strictly
+- Implement only the active packet
+
+### 5. Verify Before Done (execution-loop verify)
 
-Break the task into detailed, trackable todos using the TodoWrite tool.
+Run per-packet verification:
+- `lsp_diagnostics`
+- packet verification commands
+- lint/build when relevant
 
-### 5. Begin Implementation
+This is a **per-packet** check. For the full pre-ship gate, run `/verify` after all packets are done.
 
-- Reserve files via `mcp__beads_village__reserve()`
-- Follow the plan's file impact strictly
-- Implement incrementally — edit, verify, mark complete, repeat
+If verification fails twice, stop and escalate.
 
-### 6. Verify Each Task
+### 6. Close Packet
 
-After completing each task:
-- Run targeted checks (typecheck, tests, lint)
-- Verify acceptance criteria
-- Mark task as `done` in plan
-- Move to next task
+- Mark Beads task done
+- Report evidence
+- Continue only if another ready packet exists and the user asked to keep going
 
 ## Quick Start Checklist
 
 ```
-1. ✅ Plan exists and is approved
+1. ✅ Plan exists and is approved (created by /create)
 2. ✅ Context loaded (spec, plan, handoff)
 3. ✅ Next task identified
-4. ✅ Todos created
+4. ✅ Packet selected
 5. ✅ Files reserved
-6. 🔄 Implementation in progress
+6. 🔄 Execute + verify loop in progress
 ```
 
 ## Rules
 
 - ✅ ALWAYS load plan and spec before starting
 - ✅ ALWAYS check for existing handoff to resume
-- ✅ ALWAYS create todos before coding
-- ✅ ALWAYS verify each task before moving on
+- ✅ ALWAYS execute one packet at a time
+- ✅ ALWAYS verify before marking packet done
 - ✅ ALWAYS respect file impact boundaries
 - ❌ NEVER skip verification gates
 - ❌ NEVER implement without an approved plan
+- ❌ If no plan exists, suggest `/create` — NOT `/plan`
 
-Now, let me find your plan and start implementing...
+Now, run the next packet.

package/command/{status-beads.md → status.md}

@@ -1,5 +1,5 @@
 ---
-description: Current state overview of workspace and beads.
+description: Instant workspace snapshot — active Beads tasks, ready work, git state, and all memory artifacts in one view.
 agent: build
 ---
 
@@ -95,7 +95,6 @@ Look for:
 | Start new feature | `/create` |
 | Begin implementing | `/start` |
 | Resume paused work | `/resume` |
-| Review changes | `/review` |
 | Ship & merge | `/ship` |
 | Commit changes | `/commit` |
 
@@ -114,7 +113,7 @@ Look for:
 |------|------|
 | Beads | `mcp__beads_village__status()` |
 | Tasks | `mcp__beads_village__ls()` |
-| Ready tasks | `mcp__beads_village__ready()` |
+| Ready tasks | `mcp__beads_village__ls(status="ready")` |
 | Reservations | `mcp__beads_village__reservations()` |
 | Messages | `mcp__beads_village__inbox()` |
 | Git | `git status`, `git log` |