refactor(workflow): idiot-proof the workflow end to end

.agents/skills/kilo-design-cloud/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: kilo-design-cloud
+description: Kilo Cloud web UI overlay and pilot pattern recipes. Use when editing or reviewing Kilo Cloud UI paths such as apps/web/src/**, or when the Cloud repo path-scoped trigger requests Kilo design guidance.
+---
+
+# Kilo Design Cloud
+
+This is the first agent-facing adapter for the Kilo design system. It covers Kilo Cloud's web app and the first Cloud pattern recipes.
+
+## Run Order
+
+1. If the task has a target Cloud file, read it first. For components, also read the matching primitive in `apps/web/src/components/ui/`.
+2. If the task asks for a standalone mockup, prototype, or self-contained HTML with no target Cloud file, use Standalone Generation Mode.
+3. Load `overlay.md` for all Cloud UI work.
+4. Load one internal reference only when the task needs it: product judgment, brand, token architecture, voice, or interaction quality.
+5. Load at most one matching recipe unless the task clearly spans multiple patterns.
+6. If no recipe exists, use the overlay plus current Cloud code and report a coverage gap.
+7. Keep broad product cleanup out of focused tasks.
+8. Do not use playground specimen UI as a Cloud Canonical Example.
+
+Completion criterion: the answer or change names the loaded overlay/recipe, follows real Cloud code, and does not normalize unrelated UI.
+
+## Token Contract
+
+- Cloud's generated token artifact is `src/tokens.cloud.ts`.
+- Cloud UI code maps token values through `apps/web/src/app/globals.css` and semantic roles such as `--primary`, `--background`, and `--ring`.
+- Do not use `src/tokens.landing.css` or `src/tokens.extension-host-map.md` as Cloud UI sources.
+
+## Recipe Router
+
+| Prompt or file signal | Load |
+|---|---|
+| primary action, CTA, button hierarchy, blue button drift | `patterns/cloud-web/primary-actions.md` |
+| tabs, segmented navigation, Radix tabs, active tab state | `patterns/cloud-web/tabs.md` |
+| tokens, globals.css, semantic mapping | `reference/token-architecture.md`; record that Cloud token adoption is `VVV-130` |
+| copy, empty states, labels, errors, confirmations | `reference/voice.md` |
+| forms, focus, keyboard, overlays, responsive layout, touch targets, loading, disabled, motion | `reference/interaction-quality.md` |
+| badges, alerts, dialogs, sidebar, empty states | `overlay.md`; report coverage gap if a rule is missing |
+| standalone mockup, prototype, generated HTML, arena pass, no target Cloud file | Standalone Generation Mode |
+| login, auth, workspace slug, returning team, security status | `reference/brand.md`; `reference/voice.md`; `reference/token-architecture.md`; `reference/interaction-quality.md`; `patterns/cloud-web/primary-actions.md` |
+
+## Standalone Generation Mode
+
+Use this mode only when the task asks for generated UI without a real Cloud source file to read. The goal is a product-faithful Kilo Cloud surface, not a generic SaaS screen with Kilo labels.
+
+Load these before designing:
+
+1. `overlay.md`
+2. `reference/brand.md`
+3. `reference/voice.md`
+4. `reference/token-architecture.md`
+5. `reference/interaction-quality.md` when the surface includes forms, auth, overlays, responsive behavior, loading, disabled, error, or success states
+6. One matching pattern recipe when available
+
+Allowed read-only product artifact: `src/tokens.cloud.ts` when exact token values are needed.
+
+Generated standalone HTML should:
+
+- Define semantic CSS roles such as `--background`, `--foreground`, `--card`, `--muted-foreground`, `--primary`, `--primary-foreground`, `--border`, `--input`, and `--ring`.
+- Resolve `--primary` to Kilo brand primary and `--primary-foreground` to Kilo brand foreground when writing self-contained CSS.
+- Use Kilo Cloud product nouns from the prompt: workspaces, teams, agent runs, tool calls, changed files, billing, subscriptions, KiloClaw, security, or operational status.
+- Stay compact, dark-first, technical, and task-oriented.
+- Keep generated product UI free of guidance notes, gap reports, arena labels, skill labels, or comparison text.
+
+## Non-Goals
+
+- Do not build Landing, Editor, Console, Mobile, JetBrains, or CLI guidance here.
+- Do not recreate a Cloud `DESIGN.md`.
+- Do not migrate every hardcoded blue button unless the task is `primary-actions` implementation.
+- Do not invent recipes without a real Canonical Example in shipped Cloud code.
+- Do not copy UI structures from `playground/`; it previews token behavior only.
+
+## Reference Map
+
+- `overlay.md`: Cloud product overlay and known drift.
+- `reference/product-judgment.md`: modes, authority order, and coverage gaps.
+- `reference/brand.md`: Cloud use of Kilo brand language.
+- `reference/token-architecture.md`: how Cloud agents should read product-facing token artifacts.
+- `reference/voice.md`: Kilo Cloud UI copy rules.
+- `reference/interaction-quality.md`: interaction states, form behavior, overlays, responsive checks, touch, and motion.
+- `patterns/cloud-web/primary-actions.md`: primary CTA and button hierarchy recipe.
+- `patterns/cloud-web/tabs.md`: Cloud tab recipe.

.agents/skills/kilo-design-cloud/overlay.md

@@ -0,0 +1,72 @@
+# Kilo Cloud Overlay
+
+Cloud is the pilot product for Kilo's agent-consumable design system. It is a dense, dark-first infrastructure console built with Next.js, React, Tailwind, shadcn/ui, Radix, and `lucide-react`.
+
+## Product Intent
+
+- Help teams understand workspaces, billing, subscriptions, KiloClaw, and operational status without marketing noise.
+- Stay compact and task-oriented. Cloud can be visually polished, but it should not feel like a landing page.
+- Make one action obvious per surface. Surrounding actions should be secondary, ghost, outline, or links.
+
+## Code Sources To Read First
+
+| Concern | Cloud path |
+|---|---|
+| Base theme and Tailwind tokens | `apps/web/src/app/globals.css` |
+| Font variables | `apps/web/src/app/layout.tsx` |
+| shadcn config | `apps/web/components.json` |
+| UI primitives | `apps/web/src/components/ui/*.tsx` |
+| Legacy button drift | `apps/web/src/components/Button.tsx` |
+
+## Token Mapping
+
+Use semantic roles, not raw values:
+
+| Role | Cloud token |
+|---|---|
+| Page background | `--background` / `bg-background` |
+| Default text | `--foreground` / `text-foreground` |
+| Raised surface | `--card`, `--popover` |
+| Secondary surface | `--secondary`, `--muted`, `--accent` |
+| Muted text | `--muted-foreground` |
+| Primary action | `--primary` / `bg-primary` |
+| Primary action text | `--primary-foreground` / `text-primary-foreground` |
+| Border and focus | `--border`, `--input`, `--ring` |
+
+Known drift: Cloud token adoption is tracked by `VVV-130`. Until that lands, recipe guidance should still point agents at semantic roles, not hardcoded replacements.
+
+## Cloud Rhythm
+
+- Controls are compact: `h-8`, `h-9`, `h-10`; icons are usually `size-4`.
+- Cards and dialogs use existing shadcn primitives before custom containers.
+- Prefer `gap-*` and grouped spacing over dividers between every row.
+- Keep status color as small signals: badges, inline text, rings, or charts. Do not let status hues become the UI palette.
+- Use Inter for UI and Roboto Mono for code, identifiers, token names, and tabular data.
+- Treat focus, disabled, loading, error, and responsive states as part of the surface, not follow-up polish.
+
+## Cloud Anti-Patterns
+
+- Blue button fills as primary actions.
+- Yellow-green applied to multiple unrelated controls.
+- Equal-card dashboard grids when the task has one focal action.
+- New component libraries or new design primitives when shadcn/Radix already exists.
+- Marketing copy, fake slogans, avatars, decorative AI stars, glass panels, or gradient text inside product UI.
+- Hover-only required actions, missing focus-visible states, or custom overlay behavior that bypasses Radix.
+- Large implementation sweeps before the matching recipe exists.
+
+## Current Coverage
+
+Covered now:
+
+- Primary actions.
+- Tabs.
+
+Known gaps:
+
+- Status badges.
+- Alerts and feedback banners.
+- Dialogs and destructive confirmations.
+- Sidebar/topbar chrome.
+- Empty states.
+
+When a gap appears in real work, use the nearest shipped code and report the missing recipe instead of adding broad rules.

.agents/skills/kilo-design-cloud/patterns/cloud-web/primary-actions.md

@@ -0,0 +1,44 @@
+# Cloud Web Pattern: Primary Actions
+
+Pattern ID: `cloud-web.primary-actions`
+
+## When To Use
+
+Use this recipe when a Cloud surface has a main CTA, button hierarchy, primary button drift, or hardcoded blue button background.
+
+## Rule
+
+Each surface gets one primary action. It uses the semantic primary action role, not a color name. Secondary choices use secondary, outline, ghost, destructive, or link variants.
+
+## Canonical Example
+
+Real code to copy:
+
+- `apps/web/src/components/ui/button.tsx`
+- The current shared `Button` primitive and its current variant source in the Cloud repo.
+- Primary action styling should resolve to semantic `primary` and `primary-foreground` tokens.
+
+Before adopting this recipe in Cloud, verify the exact current variant file and class string from the active Cloud branch. Do not copy legacy color variants when building new Cloud UI.
+
+## Implementation Rules
+
+- Use `<Button>` with the default variant for the primary action.
+- Use `variant="secondary"`, `variant="outline"`, `variant="ghost"`, or `variant="link"` for lower-emphasis actions.
+- Use `variant="destructive"` only for destructive actions.
+- Do not create new color variants for one-off product needs.
+- Do not use blue backgrounds for CTAs. Blue is acceptable for inline links and legacy drift only.
+- Keep labels specific: `Create workspace`, `Save changes`, `Delete project`.
+- Include disabled, loading, focus-visible, and responsive behavior when the surrounding component owns those states.
+
+## Review Checklist
+
+- Is there only one primary action in the visible decision area?
+- Does the primary action use semantic `primary` tokens?
+- Are secondary actions visually subordinate?
+- Are hardcoded blue CTA fills removed or explicitly called out as drift?
+- Does the label name the action and object?
+
+## Known Drift
+
+- Legacy Cloud button variants may still exist outside the shared primitive; verify on the active Cloud branch before migration.
+- Cloud token adoption in `globals.css` is tracked separately by `VVV-130`.

.agents/skills/kilo-design-cloud/patterns/cloud-web/tabs.md

@@ -0,0 +1,41 @@
+# Cloud Web Pattern: Tabs
+
+Pattern ID: `cloud-web.tabs`
+
+## When To Use
+
+Use this recipe for Cloud tab bars, segmented navigation, Radix tab groups, and active tab state review.
+
+## Rule
+
+Use the Cloud shadcn/Radix tabs primitive. Tabs are compact, neutral, and structural. They should not compete with the page's primary action.
+
+## Canonical Example
+
+Real code to copy:
+
+- `apps/web/src/components/ui/tabs.tsx`
+- `TabsList`: `bg-muted text-muted-foreground inline-flex h-9 ... rounded-lg p-1`
+- `TabsTrigger`: compact trigger with active `text-foreground`, border, transparent fill, and shadow
+
+## Implementation Rules
+
+- Import `Tabs`, `TabsList`, `TabsTrigger`, and `TabsContent` from `@/components/ui/tabs`.
+- Do not hand-roll tabs with buttons, anchors, or custom state when Radix tabs fit.
+- Keep tab lists compact: `h-9`, `p-1`, `rounded-lg`.
+- Use neutral active states. Do not use brand primary or status colors for normal active tabs.
+- Keep labels short and scannable. Avoid invented category names.
+- Preserve keyboard behavior by using the Radix wrapper.
+- Keep tab content spacing connected to the tab list; do not turn every panel into a nested card.
+
+## Review Checklist
+
+- Does the surface use the shared tabs primitive?
+- Is the active state neutral and readable?
+- Is keyboard behavior preserved?
+- Are tab labels short and concrete?
+- Is the tab group subordinate to the page's main task?
+
+## Known Drift
+
+The current primitive is the Canonical Example. If a future Cloud surface needs a different tab density or orientation, record the need as a coverage gap before creating another tab style.

.agents/skills/kilo-design-cloud/reference/brand.md

@@ -0,0 +1,48 @@
+# Kilo Brand For Cloud
+
+Kilo Cloud is dark-first, precise, calm, technical, and compact. It should feel like engineering infrastructure software, not a marketing page.
+
+## Shared Defaults
+
+- Dark-only surfaces: near-black canvas, raised charcoal panels, muted gray secondary text.
+- Typography: Inter for UI, Roboto Mono for code and identifiers.
+- Shape: compact radii, rounded controls, existing shadcn/Radix primitives.
+- Motion: short and functional. Brand flourish is punctuation, not a default.
+- Primary action: one semantic primary action per visible decision area.
+
+## Brand Primary
+
+`tokens.json` defines the source values:
+
+```text
+color.brand.primary = #F7F586
+color.brand.foreground = #1F1F1F
+```
+
+In daily Cloud work, say `primary action token`, not `#F7F586`, unless editing token source or generated artifact docs.
+
+In standalone generated HTML, define the semantic primary role from these values:
+
+```text
+--primary = #F7F586
+--primary-foreground = #1F1F1F
+```
+
+## Product Signals
+
+Kilo Cloud should be recognizable through product structure, not decorative branding.
+
+- Use real Cloud nouns when relevant: workspace, team, agent run, tool call, changed files, token usage, billing, subscription, security status, KiloClaw.
+- Treat workspace identifiers, slugs, run IDs, file paths, and usage numbers as technical data; use monospace sparingly for those values.
+- Keep the brand mark compact and utilitarian. Do not make a large logo lockup the main composition.
+- Primary actions use the brand primary token. Secondary actions stay neutral.
+- Status colors stay small: badges, inline text, rings, or compact indicators.
+
+## Reject
+
+- Neutral or gray primary actions.
+- Blue button fills used as primary CTAs.
+- Yellow-green applied to many unrelated controls.
+- Purple gradient heroes, glass panels, glossy surfaces, or decorative AI sparkle language.
+- New font families outside Cloud's contract.
+- Light-mode-only Cloud designs.

.agents/skills/kilo-design-cloud/reference/interaction-quality.md

@@ -0,0 +1,56 @@
+# Interaction Quality
+
+This reference is for Cloud UI tasks where behavior, accessibility, responsive layout, forms, overlays, touch, or motion are part of the change.
+
+## Load When
+
+- The task touches forms, inputs, validation, focus, keyboard behavior, overlays, dialogs, dropdowns, popovers, tabs, tooltips, or sheets.
+- The task changes responsive layout, touch behavior, loading states, disabled states, error states, success states, or animation.
+- A review asks whether a surface feels usable, shippable, accessible, or polished.
+
+## Interactive States
+
+Changed interactive controls account for the states they can enter: default, hover, focus-visible, active, disabled, loading, error, and success.
+
+- Hover is never the only way to reach a required action.
+- Disabled and loading states preserve layout and explain blocked progress when the reason is not obvious.
+- Focus-visible states use the existing ring/token system. Do not remove browser or Radix focus behavior to make a design look cleaner.
+- Icon-only controls need an `aria-label` that names the action.
+
+## Forms
+
+- Use visible labels. Placeholder text is not a label.
+- Put field errors next to the field and connect help or error text with `aria-describedby` where the component supports it.
+- Validate on blur for ordinary fields. Password strength can update while typing.
+- Use the correct input type and autocomplete attributes for common fields.
+- Error copy says what failed, why if knowable, and what to try next.
+
+## Overlays
+
+- Use existing shadcn/Radix wrappers for dialogs, dropdowns, popovers, selects, tabs, tooltips, and sheets.
+- Do not hand-roll positioning, focus traps, Escape behavior, outside-click behavior, or arrow-key navigation.
+- Preserve Radix keyboard semantics when styling trigger, content, and item states.
+- Destructive confirmations are for irreversible or high-stakes actions. Prefer undoable feedback for reversible actions.
+
+## Responsive And Touch
+
+- Check at least 375px, 768-1024px, and 1440px+ when the task changes layout.
+- Long workspace names, emails, plan names, token labels, and billing values must wrap, truncate, or collapse intentionally.
+- Cards, forms, and tables reflow before hiding important controls.
+- Touch targets should reach 44px even when the visual control is compact.
+- Use the existing Cloud sidebar and navigation behavior before inventing a mobile-specific nav.
+
+## Motion
+
+- Product motion is short and functional: 100-200ms for direct feedback, 200-300ms for larger state changes.
+- Prefer opacity and transform. Do not casually animate width, height, top, left, or grid placement.
+- Respect `prefers-reduced-motion` for anything beyond trivial hover or focus feedback.
+- Do not add bouncy, elastic, or playful easing to infrastructure UI.
+- Do not hand-animate Radix overlays when the existing primitive already handles entry and exit behavior.
+
+## Layout Discipline
+
+- Use 4px-aligned spacing and `gap-*` before ad hoc margins.
+- Do not nest cards inside cards. Use spacing, headings, dividers, or muted sections to separate related content.
+- Use surface roles for dark-mode depth, not heavy shadows.
+- Use tabular numbers for billing, usage, quota, and table values.

.agents/skills/kilo-design-cloud/reference/product-judgment.md

@@ -0,0 +1,40 @@
+# Product Judgment
+
+This reference is for agent behavior inside Cloud UI work. It is not product code guidance by itself.
+
+## Modes
+
+| Mode | Do | Done when |
+|---|---|---|
+| Shape | Clarify a flow, hierarchy, states, and tradeoffs. Do not edit. | The recommendation is concrete enough to implement. |
+| Implement | Make the smallest coherent Cloud code change. | Changed code matches the overlay or recipe, or calls out a gap. |
+| Review | Inspect code/screens and report findings. Do not edit. | Findings cite paths, severity, rule, fix, and relevant interaction or responsive gaps. |
+| Copy | Improve labels, empty states, errors, and confirmations. | Copy says what happened and what to do next. |
+
+## Authority Order
+
+Use this order when sources disagree:
+
+1. User's explicit goal.
+2. Real Cloud behavior and constraints.
+3. Product-facing assets: `tokens.json`, generated `src/` artifacts, and host map.
+4. This skill's Cloud overlay.
+5. Matching Pattern Recipe.
+6. Canonical Example in shipped Cloud code.
+7. Nearby shipped UI.
+8. General interface heuristics.
+
+Token values are prescriptive. Shipped Cloud code that disagrees with `tokens.json` is Drift.
+
+The playground is not in the authority order for Cloud implementation. Its specimens can help spot token problems, but they are not product code and must not be cited as Canonical Examples.
+
+## Coverage Gaps
+
+If no overlay rule or recipe exists:
+
+- Use current Cloud code and product-facing assets for the smallest safe choice.
+- Say which guidance is missing.
+- Do not invent a new recipe unless repeated drift proves the need.
+- Do not block unrelated work because a recipe is missing.
+
+For UI reviews, include interaction quality only when relevant to the changed surface: focus-visible behavior, keyboard behavior, responsive breakpoints, reduced motion, and loading, disabled, error, or success states.