@skilly-hand/skilly-hand 0.14.0 → 0.15.1

package/catalog/skills/frontend-design/agents/visual-refiner.md

@@ -0,0 +1,137 @@
+# Visual Refiner
+
+## Precondition
+
+**Run only after `component-designer` has produced output.**
+
+This agent evaluates what was just generated — not what the user wants next. Its job is to close the quality gap between "technically correct" and "ready to ship."
+
+---
+
+## When to Use
+
+Use this agent when:
+
+- A component or page has been generated and needs a quality check before the user moves on.
+- The user asks "does this look right?", "can you improve this?", or "polish this."
+- The generated output feels generic or inconsistent — even if it technically matches the stack.
+- You want to verify all interactive states are handled before handoff.
+
+Do not use this agent when:
+
+- Stack detection has not yet been run.
+- No component has been generated in this session yet.
+- The user has explicitly said "it's fine as-is."
+
+---
+
+## Evaluation Protocol
+
+Run all four checks. Do not skip any. Report findings grouped by check — do not interleave.
+
+---
+
+### Check 1 — AI Slop Detection
+
+Look for generic patterns that signal uncontextualized AI output. Flag each one found.
+
+**Visual tells to catch:**
+
+- Glassmorphism (backdrop-filter: blur + semi-transparent backgrounds with no established project precedent)
+- Default Inter font with no project declaration
+- Standard hero + cards + CTA layout with no project-specific rationale
+- Pure `#000000` or `#ffffff` for text/backgrounds instead of project tokens
+- Generic card shadows (`box-shadow: 0 2px 8px rgba(0,0,0,0.1)`) not derived from project tokens
+- Gradient text (`background-clip: text`) used decoratively without project precedent
+- Icon + title + description card grids as default empty-state filler
+- Identical padding and border-radius across every element (uniform blandness)
+
+For each flag: name the pattern, show the line, and suggest a project-derived alternative.
+
+---
+
+### Check 2 — Interaction State Coverage
+
+Verify every interactive element has all required states. Missing states are incomplete work, not optional polish.
+
+**Required states per element type:**
+
+| Element | Required States |
+| ------- | --------------- |
+| Button (primary) | default, hover, focus-visible, active, disabled, loading |
+| Button (secondary/ghost) | default, hover, focus-visible, active, disabled |
+| Input / Textarea | default, focus, filled, error, disabled |
+| Select / Dropdown | default, open, selected, disabled |
+| Link | default, hover, visited, focus-visible |
+| Checkbox / Radio | unchecked, checked, indeterminate (checkbox), focus, disabled |
+| Toggle / Switch | on, off, focus, disabled |
+| Card (interactive) | default, hover, focus, selected |
+
+For each missing state: name the element, name the missing state, and provide the implementation using confirmed project tokens.
+
+---
+
+### Check 3 — Nielsen's Heuristics (abbreviated)
+
+Score only the heuristics relevant to a component-level review. Skip system-level heuristics.
+
+| Heuristic | Check |
+| --------- | ----- |
+| Visibility of system status | Does loading/processing state communicate progress? |
+| Match between system and world | Do labels use plain language the user would recognize? |
+| Error prevention | Does the component validate or guard against bad input? |
+| Recognition over recall | Are actions visible, not hidden behind hover/guess? |
+| Consistency and standards | Does this match patterns established elsewhere in the project? |
+| Aesthetic and minimalist design | Is every element present earning its space? |
+
+Rate each: **Pass**, **Minor issue**, or **Blocker**. Provide a one-line note for anything not Pass.
+
+---
+
+### Check 4 — Directional Assessment
+
+After the three checks above, ask the user to choose a direction:
+
+> The component is functionally solid. Here are three directions to take the refinement:
+>
+> **A — Polish**: Fix the flagged issues and fill missing states. No visual changes beyond corrections.
+>
+> **B — Bolder**: Increase visual impact. Larger type jumps, stronger contrast, more distinctive spacing rhythm. Still uses project tokens.
+>
+> **C — Quieter**: Reduce visual weight. More whitespace, softer contrast, subtler hierarchy. Still uses project tokens.
+>
+> Which direction, or a combination? (Or say "done" to accept as-is.)
+
+Do not apply any directional changes without the user's explicit choice. Fixes from Check 1–3 are always applied.
+
+---
+
+## Refinement Rules
+
+When applying any refinement:
+
+1. Use only tokens confirmed by stack detection or declared in `DESIGN.md`.
+2. Do not introduce new dependencies.
+3. Do not change the component's public API (props, events, slots) unless the user asks.
+4. Do not add animation in this agent — hand off to `motion-designer` for that.
+5. One round of refinement per invocation. If the user wants another pass, re-invoke this agent.
+
+---
+
+## Output Format
+
+```text
+VISUAL REFINER REPORT
+---------------------
+AI Slop Check:    [N flags found / Clean]
+State Coverage:   [N states missing / Complete]
+Heuristics:       [N issues / All pass]
+
+FINDINGS:
+[grouped list of findings with suggested fixes]
+
+RECOMMENDED ACTION:
+[Polish only / Polish + Direction A/B/C / No changes needed]
+```
+
+After applying fixes, summarize what changed in 2–3 bullet points. Do not narrate every line edited.

package/catalog/skills/frontend-design/assets/aesthetic-archetypes.md

@@ -0,0 +1,155 @@
+# Aesthetic Archetypes
+
+Reference card for greenfield projects or when a user asks for design direction with no existing codebase to read from.
+
+Each archetype describes a coherent visual personality using framework-agnostic, implementation-neutral language. No library names, no specific color values, no font names — those are determined by the project's actual stack after the archetype is chosen.
+
+**How to use:**
+
+1. Present 2–3 options that best match the user's brand personality adjectives from `DESIGN.md`.
+2. Let the user choose or mix.
+3. Translate their choice into stack-specific tokens only after the stack is confirmed.
+
+---
+
+## 1. Refined Minimal
+
+**Character**: Quiet confidence. Less is deliberate, not lazy.
+
+**Typography**: Small, tight type scale. Generous leading. Weight does the work — one bold statement surrounded by light body. No more than two font roles.
+
+**Color**: Near-monochromatic. One neutral family (warm or cool), one restrained accent used sparingly. Near-black text, near-white backgrounds, or their dark-mode inversion.
+
+**Spacing**: Generous. Breathing room is the dominant visual element. Consistent, predictable rhythm.
+
+**Motion**: Subtle. Fade and micro-translate on interaction. Nothing draws attention to itself.
+
+**Avoid**: Decorative dividers, rounded corners exceeding the system's established radius, anything that shouts.
+
+---
+
+## 2. Editorial
+
+**Character**: Print-informed. Content is the design.
+
+**Typography**: Dramatic scale jumps. Display-size headings, small caption text. Mix of weights within a single family, or intentional contrast between a display and body face.
+
+**Color**: High contrast. Often near-black + near-white + one ink-like accent. Color is used to mark, not decorate.
+
+**Spacing**: Asymmetric. Grid-breaking is intentional. Vertical rhythm anchors the layout.
+
+**Motion**: Minimal — content should feel immediate. Scroll-driven reveals acceptable.
+
+**Avoid**: Card-heavy layouts, rounded blobs, friendly pastels.
+
+---
+
+## 3. Brutalist
+
+**Character**: Uncompromising. Honesty over comfort.
+
+**Typography**: System stack or intentionally unglamorous. Oversized. Unkerned when intentional. All-caps statements.
+
+**Color**: High contrast. Black, white, and one harsh accent (or pure black and white only). No gradients.
+
+**Spacing**: Structural — not generous, not cramped. Grid is exposed.
+
+**Motion**: Instant or near-instant. Snap, not glide.
+
+**Avoid**: Soft shadows, border-radius, anything "friendly."
+
+---
+
+## 4. Retro-Futuristic
+
+**Character**: Technology filtered through nostalgia.
+
+**Typography**: Geometric or monospace. Tight tracking. All-caps labels. Clear grid hierarchy.
+
+**Color**: Deep backgrounds (near-black or dark navy), bright accent (neon-adjacent — high chroma, not true neon). Subtle scanline or grid texture acceptable.
+
+**Spacing**: Dense with breathing room only at macro level. Sections feel packed but orderly.
+
+**Motion**: Purposeful. Reveal effects, typewriter entrances, scan-line wipes. All must have reduced-motion fallbacks.
+
+**Avoid**: Glassmorphism, light-mode defaults, organic shapes.
+
+---
+
+## 5. Organic
+
+**Character**: Human-made, unhurried.
+
+**Typography**: Humanist or transitional — faces with visible calligraphic origin. Variable weight welcomed. Generous leading.
+
+**Color**: Earth-adjacent. Warm neutrals, muted greens, terracotta, dusty indigo. Nothing fully saturated.
+
+**Spacing**: Flowing. Sections breathe into each other. Asymmetry that feels natural, not forced.
+
+**Motion**: Eases that feel physical — spring or custom cubic-bezier that overshoots slightly. Gentle.
+
+**Avoid**: Sharp corners, high-tech palettes, monospace.
+
+---
+
+## 6. Luxury
+
+**Character**: Restraint signals value.
+
+**Typography**: Elegant — thin weights, generous tracking on headings. Serif display for brand moments, clean sans for utility.
+
+**Color**: Muted, sophisticated. Champagne, slate, obsidian, aged gold. Saturation deliberately low. One metallic or warm-neutral accent.
+
+**Spacing**: Very generous. White space is a premium material.
+
+**Motion**: Slow and deliberate. 400–600ms entrances. Ease-out only — nothing bounces.
+
+**Avoid**: Bright colors, heavy weights, any pattern that reads as cheap or casual.
+
+---
+
+## 7. Playful
+
+**Character**: Fun is a feature, not a compromise.
+
+**Typography**: Rounded or friendly. Variable weight for expression. Larger scale than strictly necessary.
+
+**Color**: Multi-hue. 3–4 colors with clear semantic roles. Saturated but not harsh — use perceptual uniformity to keep brightness balanced.
+
+**Spacing**: Responsive to content, not rigid. Cards can be different sizes. Grid can breathe unevenly.
+
+**Motion**: Expressive micro-interactions. Confirmation states feel satisfying. Always reduced-motion safe.
+
+**Avoid**: Pure black text, sharp corners, anything that reads as corporate or cold.
+
+---
+
+## 8. Industrial
+
+**Character**: Form follows function. No apology for complexity.
+
+**Typography**: Utilitarian sans-serif. Dense but readable. Tabular figures for data. Weight for hierarchy, not decoration.
+
+**Color**: Neutral-forward. Grays, steel, occasionally safety-signal accent (amber, red) for state only. Not decorative.
+
+**Spacing**: Dense. Information-rich layouts. Tables, grids, dashboards. Whitespace is used to separate data, not to decorate.
+
+**Motion**: Minimal. State changes are instant or near-instant. Loading indicators, not entrances.
+
+**Avoid**: Rounded blobs, decorative gradients, anything that prioritizes aesthetics over clarity.
+
+---
+
+## Mixing Archetypes
+
+Users often want combinations. Common pairings:
+
+| Combination | Character |
+| ----------- | --------- |
+| Refined Minimal + Editorial | High-end content publishing |
+| Industrial + Retro-Futuristic | Developer tools with personality |
+| Organic + Luxury | Premium wellness or lifestyle |
+| Playful + Refined Minimal | Consumer product with restraint |
+| Brutalist + Editorial | Independent media, strong POV |
+
+When mixing, one archetype leads (governs spacing and color) and the other accents (contributes a single element — e.g., typography from Editorial onto a Refined Minimal base).

package/catalog/skills/frontend-design/manifest.json

@@ -1,27 +1,31 @@
 {
   "id": "frontend-design",
   "title": "Frontend Design",
-  "description": "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work.",
+  "description": "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases.",
   "portable": true,
-  "tags": ["frontend", "design", "workflow", "ui"],
+  "tags": ["frontend", "design", "workflow", "ui", "motion", "greenfield"],
   "detectors": ["always"],
   "detectionTriggers": ["manual"],
   "installsFor": ["all"],
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-04",
+    "last-edit": "2026-04-05",
     "license": "Apache-2.0",
-    "version": "1.0.0",
-    "changelog": "Initial frontend-design skill; enforces stack-detection-first workflow before any UI component generation; affects catalog skill coverage for frontend and design workflows",
-    "auto-invoke": "Designing or generating UI components, pages, or layouts in a web or mobile project",
+    "version": "1.1.0",
+    "changelog": "v1.1.0: Added design-context-setter agent for greenfield/DESIGN.md workflow; added visual-refiner agent for post-generation quality evaluation; added motion-designer agent for stack-aware micro-interactions; added aesthetic-archetypes reference asset; expanded SKILL.md routing map with optional motion and refinement phases; upgraded component-designer with interaction states checklist and aesthetic principles",
+    "auto-invoke": "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; adding motion or micro-interactions to existing UI; refining or polishing generated UI output",
     "allowed-tools": ["Read", "Grep", "Glob", "Bash", "Edit", "Write"]
   },
   "files": [
     { "path": "SKILL.md", "kind": "instruction" },
     { "path": "agents/stack-detector.md", "kind": "asset" },
+    { "path": "agents/design-context-setter.md", "kind": "asset" },
     { "path": "agents/component-designer.md", "kind": "asset" },
-    { "path": "assets/stack-scan-checklist.md", "kind": "asset" }
+    { "path": "agents/motion-designer.md", "kind": "asset" },
+    { "path": "agents/visual-refiner.md", "kind": "asset" },
+    { "path": "assets/stack-scan-checklist.md", "kind": "asset" },
+    { "path": "assets/aesthetic-archetypes.md", "kind": "asset" }
   ],
   "dependencies": []
 }

package/catalog/skills/output-optimizer/SKILL.md

@@ -0,0 +1,159 @@
+# Output Optimizer Guide
+
+## When to Use
+
+Use this skill when:
+
+- You want compact responses to reduce output token usage.
+- You need deterministic output formats for repeated workflows.
+- You need concise communication without losing core clarity.
+- You want controlled detail expansion only when risk or ambiguity requires it.
+
+Do not use this skill for:
+
+- Cases where the user explicitly asks for long-form teaching or narrative detail.
+- Tasks that require extensive legal, medical, or compliance explanation by default.
+- Situations where a fixed external output schema already overrides style choices.
+
+---
+
+## Critical Patterns
+
+### Pattern 1: Activation and Precedence
+
+Apply modes in this order:
+
+1. If user writes `mode: <name>`, use that mode.
+2. If no explicit mode, infer from phrasing:
+- "keywords only" -> `machine`
+- "yes or no" / "binary" -> `binary-decision`
+- "json" / "structured output" -> `json-compact`
+- "step by step, concise" -> `step-brief`
+- "command style" / "minimal commands" -> `neandertal`
+- "toon format" -> `toon`
+3. If no strong signal, default to `step-brief` for human-readable compact output.
+
+Explicit mode always wins over inferred mode.
+
+### Pattern 2: Mode Contracts
+
+| Mode | Contract | Token Profile |
+| --- | --- | --- |
+| `neandertal` | Imperative command-like short phrases, no filler, minimal connectors. | Lowest human-readable |
+| `machine` | Keywords only, grouped by labels, no prose sentences. | Ultra-low |
+| `step-brief` | Numbered steps, each step max 3-4 short phrases. | Low with clarity |
+| `toon` | Exactly 4 blocks: `Title`, `Objective`, `Output`, `Next`. | Low and stable |
+| `json-compact` | Minimal stable JSON keys and short scalar values. | Low + parseable |
+| `binary-decision` | `yes` or `no` plus one short reason. | Ultra-low for triage |
+
+### Pattern 3: Complexity + Confidence Guard
+
+Default to compact output. Expand only when:
+
+1. Task complexity is moderate/high and concise output may cause mistakes.
+2. Requirements are ambiguous and short output cannot preserve correctness.
+3. Risk is elevated (security, production impact, irreversible operations).
+4. User explicitly asks for more detail.
+
+When expanding, keep structure compact and scoped to the needed clarification.
+
+### Pattern 4: Compression Rules
+
+Always prefer:
+
+- Specific nouns over long explanations.
+- One-pass direct answer over repeated restatement.
+- Bounded lists over paragraphs.
+- Deterministic templates where possible.
+
+Avoid:
+
+- Polite filler and redundant transitions.
+- Repeating the prompt unless needed for disambiguation.
+- Verbose caveats when risk is low.
+
+---
+
+## Decision Tree
+
+```text
+User provided `mode: <name>`?                 -> Use explicit mode
+No explicit mode, strong phrasing signal?     -> Infer mode from signal
+No explicit mode and no signal?               -> step-brief
+Task complexity/ambiguity/risk is high?       -> Expand within selected mode
+User asks for detail/clarification?           -> Expand within selected mode
+Otherwise                                     -> Keep compact output
+```
+
+---
+
+## Output Examples
+
+### Example 1: `neandertal`
+
+```text
+Check logs. Find error. Patch file. Run tests. Report result.
+```
+
+### Example 2: `machine`
+
+```text
+status:blocked
+cause:missing-env
+action:set-token,retry
+```
+
+### Example 3: `step-brief`
+
+```text
+1. Open config file. Find auth block. Confirm token key.
+2. Add missing key. Save file. Re-run command.
+3. Verify success output. Capture result. Share summary.
+```
+
+### Example 4: `toon`
+
+```text
+Title: Auth Fix
+Objective: Restore CLI login flow
+Output: Config key added, login passes
+Next: Run smoke check
+```
+
+### Example 5: `json-compact`
+
+```json
+{"status":"ok","mode":"json-compact","next":"deploy"}
+```
+
+### Example 6: `binary-decision`
+
+```text
+yes: tests pass on required suite
+```
+
+---
+
+## Prompt Patterns
+
+These are prompt fragments, not terminal commands.
+
+```text
+mode: neandertal
+mode: machine
+mode: step-brief
+mode: toon
+mode: json-compact
+mode: binary-decision
+```
+
+```text
+explain in detail
+```
+
+---
+
+## Resources
+
+- Mode protocol reference: [references/mode-protocols.md](references/mode-protocols.md)
+- Related complexity control: [../token-optimizer/SKILL.md](../token-optimizer/SKILL.md)

package/catalog/skills/output-optimizer/manifest.json

@@ -0,0 +1,33 @@
+{
+  "id": "output-optimizer",
+  "title": "Output Optimizer",
+  "description": "Optimize output token consumption through compact interpreter modes with controlled expansion when complexity, ambiguity, or risk requires more detail. Trigger: minimizing response verbosity while preserving clarity and correctness.",
+  "portable": true,
+  "tags": ["core", "workflow", "efficiency", "communication"],
+  "detectors": ["always"],
+  "detectionTriggers": ["always"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-07",
+    "license": "Apache-2.0",
+    "version": "1.0.0",
+    "changelog": "Added a new portable output compression skill with deterministic interpreter modes and guarded detail expansion; reduces response token costs while preserving safety and clarity; affects response shaping workflows and catalog routing",
+    "auto-invoke": "When minimizing output verbosity or selecting compact communication modes",
+    "allowed-tools": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "Task"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "references/mode-protocols.md", "kind": "reference" }
+  ],
+  "dependencies": []
+}

package/catalog/skills/output-optimizer/references/mode-protocols.md

@@ -0,0 +1,76 @@
+# Output Optimizer Mode Protocols
+
+## Activation Protocol
+
+- Explicit selector format: `mode: <name>`
+- Canonical names:
+  - `neandertal`
+  - `machine`
+  - `step-brief`
+  - `toon`
+  - `json-compact`
+  - `binary-decision`
+- Resolution precedence:
+1. explicit mode
+2. inferred mode from wording
+3. default `step-brief`
+
+## TOON Protocol (Strict)
+
+Always output these four blocks in this exact order:
+
+1. `Title`
+2. `Objective`
+3. `Output`
+4. `Next`
+
+Constraints:
+
+- One short line per block.
+- No extra blocks.
+- No decorative or comic phrasing requirement.
+
+## `json-compact` Protocol
+
+Use compact JSON with minimal stable keys:
+
+```json
+{"status":"<value>","mode":"json-compact","next":"<value>"}
+```
+
+Rules:
+
+- Keep keys short and predictable.
+- Keep values concise.
+- No explanatory prose outside JSON.
+
+## `binary-decision` Protocol
+
+Output contract:
+
+```text
+yes: <short reason>
+```
+
+or
+
+```text
+no: <short reason>
+```
+
+Rules:
+
+- Exactly one decision token: `yes` or `no`.
+- Exactly one brief reason.
+- No extra paragraphs.
+
+## Expansion Guard
+
+Expand output only if one or more apply:
+
+- Complexity threatens correctness.
+- Ambiguity prevents safe execution.
+- Risk is material.
+- User explicitly asks for detail.
+
+When expanded, preserve the selected mode shape as much as possible.