thomas-agentkit 0.9.0-alpha.0 → 0.9.0-alpha.1

package/templates/design-systems/framer.md

@@ -0,0 +1,95 @@
+# [Project Name] Design — Framer
+
+Design spec for [Project Name]. Map semantic tokens to `[theme stylesheet path, e.g. src/styles.css]` or your Tailwind theme.
+
+## Overview
+
+Dark poster marketing: near-black canvas, oversized white display type with extreme negative tracking, white pill primary CTAs, and gradient spotlight cards as individual showcase tiles — never section backgrounds. Single sky-blue accent for links and focus only.
+
+**Key characteristics:**
+- Dark-only marketing; no light mode
+- `{colors.primary}` = white (CTA fill and ink on dark)
+- `{colors.accent-blue}` — hyperlinks, focus, selection only
+- Gradient spotlight cards (violet, magenta, orange, coral) as scarce atmosphere
+- Inter Variable body with OpenType variants when available
+- Pill CTAs (`{rounded.pill}`); charcoal secondary pills
+
+## Colors
+
+### Brand & Accent
+- `{colors.primary}` — white (CTA, headlines, body on canvas)
+- `{colors.accent-blue}` — signal blue (links, focus ring)
+- `{colors.on-primary}` — text on white pills (dark)
+
+### Surface
+- `{colors.canvas}` — near-black page
+- `{colors.surface-1}`, `{colors.surface-2}` — card and button lifts
+- `{colors.hairline}`, `{colors.hairline-soft}`
+- `{colors.ink}`, `{colors.ink-muted}`
+
+### Gradients (card fills only)
+- `{colors.gradient-violet}`, `{colors.gradient-magenta}`, `{colors.gradient-orange}`, `{colors.gradient-coral}`
+
+## Typography
+
+- Display: GT Walsheim substitute (Mona Sans, Geist, or Inter 600–700 with tight tracking)
+- Body: Inter Variable with `cv01`, `cv05`, `cv09`, `cv11`, `ss03`, `ss07` when supported
+
+| Token | Use |
+|---|---|
+| `{typography.display-xxl}` | 110px hero |
+| `{typography.display-xl}` | 85px section |
+| `{typography.body}` | 15px default |
+| `{typography.button}` | Pill labels |
+
+### Principles
+- Tracking scales hard with size (-5.5px at largest display)
+- Weight band: 400 body, 500 display/buttons
+- Tight line-heights (~1.30 body)
+
+## Layout
+
+- Base 5px increments; `{spacing.section}` 96px
+- Max ~1199px; card grids 2-up → 1-up below 810px
+
+## Elevation
+
+Surface lift (canvas → surface-1 → surface-2). Light-edge shadow on floating mockup cards. Blue ring for focus.
+
+## Shapes
+
+| Token | Use |
+|---|---|
+| `{rounded.pill}` 100px | All text CTAs |
+| `{rounded.xl}` 20px | Pricing, mockup tiles |
+| `{rounded.xxl}` 30px | Gradient spotlight cards |
+
+## Components
+
+- `{components.button-primary}` — white pill
+- `{components.button-secondary}` — charcoal pill
+- `{components.gradient-spotlight-card}` — atmospheric variant tiles
+- `{components.pricing-card}`, `{components.template-card}`, `{components.product-mockup-tile}`
+- `{components.top-nav}`, `{components.footer}`
+
+## Do's and Don'ts
+
+### Do
+- Push negative display tracking aggressively
+- Use accent blue only for links and focus
+- Limit gradient spotlight cards to 1–2 per long page
+- Keep CTAs pill-shaped
+
+### Don't
+- Don't use accent blue as CTA fill
+- Don't apply gradients to whole sections
+- Don't ship light mode
+- Don't square off CTAs
+
+## Responsive Behavior
+
+Nav hamburger below 810px. Display scales 110→62→32px. Pricing table becomes accordion on mobile.
+
+## Token Mapping
+
+Bind roles in `[theme stylesheet path, e.g. src/styles.css]`.

package/templates/design-systems/linear.md

@@ -1,229 +1,117 @@
-# [Project Name] Design System - Linear-Inspired Foundations
+# [Project Name] Design — Linear
+
+Design spec for [Project Name]. Map every `{colors.*}`, `{typography.*}`, `{spacing.*}`, and `{rounded.*}` token to semantic roles in `[theme stylesheet path, e.g. src/styles.css]` or your Tailwind theme. Do not hardcode literal hex values in components.
+
+## Overview
+
+Dark-canvas marketing system: near-black canvas with a faint cool tint, light gray ink, and a single lavender-blue accent used scarcely on brand mark, focus rings, and primary CTAs. Hierarchy comes from a four-step surface ladder and hairline borders — not shadows. Product UI screenshots dominate section composition.
+
+**Key characteristics:**
+- Dark canvas anchor; no light-mode marketing variant
+- Single chromatic accent (`{colors.primary}`) — no second brand color
+- Surface ladder: canvas → surface-1 → surface-2 → surface-3 → surface-4
+- Aggressive negative letter-spacing on display sizes
+- Cards: `{rounded.lg}` with 1px hairlines; product panels `{rounded.xl}`
+- No atmospheric gradients or spotlight cards
 
-This design system codifies the visual and interaction principles for [Project Name].
+## Colors
 
-It is the default source of truth for app shell layout, navigation, lists, controls, and page chrome in this repository.
+### Brand & Accent
+- `{colors.primary}` — signature accent (CTA, brand mark, link emphasis, focus tint)
+- `{colors.primary-hover}` — lighter hover state for primary CTA
+- `{colors.primary-focus}` — focus-ring tint
+- `{colors.on-primary}` — text on primary fills
 
-All colors, typography families, and radii must be consumed through semantic tokens in `[theme stylesheet path, e.g. src/styles.css]` or a dedicated theme stylesheet imported there. Components must not hardcode literal color values or font family names.
+### Surface
+- `{colors.canvas}` — default page background (deepest dark)
+- `{colors.surface-1}` through `{colors.surface-4}` — stepped lifts for cards, panels, sub-nav
+- `{colors.hairline}`, `{colors.hairline-strong}`, `{colors.hairline-tertiary}` — 1px borders
+- `{colors.inverse-canvas}`, `{colors.inverse-surface-1}`, `{colors.inverse-surface-2}` — inverse pill surfaces
 
-## 1) Surface And Color
+### Text
+- `{colors.ink}` — headlines and emphasized body
+- `{colors.ink-muted}`, `{colors.ink-subtle}`, `{colors.ink-tertiary}` — secondary through quaternary
 
-### Philosophy
+### Semantic
+- `{colors.semantic-success}` — status pills only
+- `{colors.semantic-overlay}` — modal scrim
 
-The interface is a single continuous canvas. Separation comes from spacing, typography, and occasional structural seams, not stacked containers.
+## Typography
 
-### Token Roles
+### Font Family
+- Display/body sans with tight tracking at large sizes; mono for code in product screenshots only
+- Substitute: Inter or system UI stack; JetBrains Mono or Geist Mono for mono
 
-Define semantic CSS custom properties and map them to the project's theme tokens:
+### Hierarchy (map sizes to your scale)
 
-- `--background`: app canvas
-- `--foreground`: primary text
-- `--muted-foreground`: secondary/meta text
-- `--border`: structural seams
-- `--card`: elevated container for dialogs/popovers only
-- `--popover`: overlay surfaces
-- `--accent`: subtle hover/active in content areas
-- `--sidebar`: sidebar canvas
-- `--sidebar-accent`: hover/active in sidebar
-- `--primary`: brand and primary CTA
-- `--destructive`: danger actions
-- `--ring`: focus ring
+| Token | Use |
+|---|---|
+| `{typography.display-xl}` | Largest hero headline |
+| `{typography.display-lg}` | Section openers |
+| `{typography.display-md}` | Sub-section headlines |
+| `{typography.headline}` | Pricing tier titles, CTA banners |
+| `{typography.card-title}` | Feature card titles |
+| `{typography.subhead}` | Lead body |
+| `{typography.body-lg}` | Hero subhead |
+| `{typography.body}` | Default body |
+| `{typography.body-sm}` | Card body, footer |
+| `{typography.caption}` | Meta, status |
+| `{typography.button}` | Button labels |
+| `{typography.eyebrow}` | Section eyebrow (slight positive tracking) |
+| `{typography.mono}` | Code in screenshots |
 
-### Rules
+### Principles
+- Negative tracking scales with display size; body near zero
+- Display weight 600; body 400
+- Mono only in code contexts inside mockups
 
-- No layered cards for routine content.
-- No decorative gradients on product surfaces.
-- Use one accent color, `--primary`, for brand and primary actions.
-- Prefer spacing over background differentiation.
-- Keep all colors tokenized and theme-ready for light and dark modes.
+## Layout
 
-## 2) Typography
+- Base unit: 4px (`{spacing.xxs}` 4 · `{spacing.xs}` 8 · `{spacing.sm}` 12 · `{spacing.md}` 16 · `{spacing.lg}` 24 · `{spacing.xl}` 32 · `{spacing.xxl}` 48 · `{spacing.section}` 96)
+- Max content ~1280px; card grids 3-up → 2-up → 1-up
+- Product screenshot panels span full content width
 
-### Families
+## Elevation & Depth
 
-- Interface text: `font-sans` backed by `--font-sans`.
-- Code, IDs, and timestamps: `font-mono` backed by `--font-mono`.
+Surface ladder + hairlines only. No drop shadows on dark marketing surfaces. Focus: 2px `{colors.primary-focus}` outline at reduced opacity.
 
-Do not reference literal font families in component files.
+## Shapes
 
-### Scale
+| Token | Typical use |
+|---|---|
+| `{rounded.xs}` 4px | Chips, badges |
+| `{rounded.md}` 8px | Buttons, inputs |
+| `{rounded.lg}` 12px | Cards |
+| `{rounded.xl}` 16px | Screenshot panels |
+| `{rounded.pill}` | Pricing tabs, status pills |
 
-- Page heading: `text-xl`, `font-semibold`
-- Section heading: `text-base`, `font-semibold`
-- Body / row label: `text-xs`, `font-normal` to `font-medium`
-- Meta / secondary: `text-[11px]`, `font-normal`
-- Nav section label: `text-[11px] uppercase tracking-wide`, `font-medium`
-- Tiny helper: `text-[10px]`, `font-normal`
+## Components
 
-### Rules
+- `{components.button-primary}` — primary CTA on `{colors.primary}`
+- `{components.button-secondary}` — charcoal surface-1 + hairline
+- `{components.button-tertiary}` — plain text on canvas
+- `{components.pricing-card}`, `{components.feature-card}`, `{components.product-screenshot-card}` — surface-1 + hairline + `{rounded.lg}` or `{rounded.xl}`
+- `{components.top-nav}` — sticky dark bar, 56px
+- `{components.text-input}` — surface-1, focus ring on `{colors.primary-focus}`
 
-- Headlines are quiet and utilitarian.
-- Keep line height tight with `leading-tight` or `leading-snug` for dense UI.
-- Reserve uppercase for nav labels and compact metadata.
+## Do's and Don'ts
 
-## 3) Navigation
+### Do
+- Reserve `{colors.primary}` for brand mark, primary CTA, focus, links
+- Use the surface ladder sequentially
+- Lead sections with product UI screenshots
+- Use `{rounded.md}` for CTAs
 
-### Structure
+### Don't
+- Don't ship light-mode marketing
+- Don't use lavender as section background
+- Don't add atmospheric gradients or second chromatic accents
+- Don't pill-round primary CTAs (use `{rounded.md}`)
+
+## Responsive Behavior
+
+Breakpoints: desktop 1280px · tablet 1024px · mobile-lg 768px · mobile 480px. Nav hamburger below 768px. Display type scales down on mobile while preserving negative tracking ratio.
+
+## Token Mapping
 
-1. Header row: identity, search, and create action.
-2. Primary links.
-3. Collapsible grouped links.
-4. Lightweight footer affordance for help or docs.
-
-### Item Styling
-
-- Default: `text-xs`, muted foreground.
-- Hover: subtle `sidebar-accent` background.
-- Active: full-width pill, medium weight.
-- Icon size: 12px.
-- Nav pill baseline: `rounded-full h-7 px-2.5`.
-
-### Collapse Behavior
-
-- Expanded width: `15rem` or 240px.
-- Collapsed width: `3rem` or 48px, icon-only with tooltip.
-- Mobile: sheet/drawer using expanded width.
-- Keyboard shortcut: support the project's standard sidebar toggle shortcut, e.g. `Cmd+B`.
-
-## 4) Layout Regions
-
-### App Shell
-
-- Sidebar: fixed left, full viewport height, right seam border.
-- Content: `flex-1 min-w-0`, same background canvas.
-- Optional inspector: right panel, `22rem` to `28rem`, collapsible.
-
-### Common Page Patterns
-
-- List workspace: toolbar plus scrollable list.
-- Detail view: breadcrumbs/title plus body and optional inspector.
-- Editor split: left rail plus center editor.
-- Settings split: nav plus forms.
-
-### Toolbar Strip
-
-- Height: `h-10` to `h-12`.
-- Bottom seam: `border-b border-border/50`.
-- No separate background block.
-
-## 5) Interactive Elements
-
-### Buttons
-
-- Primary: solid `primary`.
-- Secondary: neutral fill.
-- Ghost: transparent with subtle hover fill.
-- Destructive: `destructive` only for dangerous confirms.
-- Icon-only: `size-8`, ghost, tooltip.
-
-Rules:
-
-- Default radius uses the tokenized radius scale.
-- No shadows on standard buttons.
-- Primary buttons are intentionally sparse.
-
-### Inputs
-
-- Compact defaults: `h-8`; dense contexts: `h-7`.
-- Tokenized input background and border.
-- Visible focus ring: `ring-2 ring-ring`.
-- Labels above fields. Do not use floating labels by default.
-
-### Menus / Popovers / Dialogs
-
-- Tokenized `popover` surface and subtle border.
-- Tight typography: `text-xs`.
-- Compact spacing.
-- Dialog actions align right: secondary then primary.
-
-## 6) Lists And Data
-
-### Row Anatomy
-
-- Compact, single-line by default.
-- Hover uses subtle accent fill.
-- Selected row uses stronger accent fill and medium weight.
-- Avoid per-row borders; separate by spacing and padding rhythm.
-
-### Grouping And Tables
-
-- Group labels are muted; children are indented.
-- Table headers use uppercase compact meta style.
-- No zebra striping or heavy gridlines.
-
-## 7) Status And Feedback
-
-- Status: small dots or icons with semantic meaning.
-- Loading: skeletons for content, spinners only for inline actions.
-- Toasts: non-intrusive, auto-dismiss.
-- Empty states: icon, short message, and optional single CTA.
-
-## 8) Motion
-
-- Motion confirms state changes; it is never decorative.
-- Micro interactions: about 150ms.
-- Layout shifts: about 200-250ms.
-- Preferred easing: `cubic-bezier(0.16, 1, 0.3, 1)`.
-- Respect `prefers-reduced-motion` with near-instant transitions.
-
-## 9) Spacing System
-
-Base unit is 4px, using the project's spacing scale.
-
-- `p-1` or 4px: tight internals.
-- `p-2` or 8px: compact section padding.
-- `p-3` or 12px: dense content blocks.
-- `p-4` or 16px: page-level rhythm.
-
-Density guidelines:
-
-- Sidebar: dense, `h-7` rows.
-- Content: moderate, `h-8` to `h-10` rows.
-- Forms/settings: relaxed, `h-10` to `h-12` rows.
-
-## 10) Accessibility
-
-- Full keyboard navigation for all controls.
-- Consistent visible focus styles.
-- Semantic landmarks such as `nav` and `main`.
-- Collapsibles expose `aria-expanded`.
-- Ensure WCAG AA contrast in both themes.
-
-## 11) Anti-Patterns
-
-- Do not wrap normal content in elevated cards.
-- Do not introduce multiple accent colors.
-- Do not add decorative gradients behind core product surfaces.
-- Do not stack multiple competing toolbars.
-- Do not color-code nav icons.
-- Do not hardcode colors or font families in components.
-
-## 12) Applying This System
-
-### Where Values Live
-
-- Theme tokens and base layer: `[theme stylesheet path, e.g. src/styles.css]`.
-- App shell composition: `[route/layout path, e.g. src/routes or app]`.
-- Reusable UI primitives: `[components path, e.g. src/components/ui]`.
-
-### New Component Checklist
-
-1. Sits on canvas, not card-first?
-2. Uses 2-3 text hierarchy levels max?
-3. Has subtle hover and clear active states?
-4. Uses primary color only where needed?
-5. Uses spacing rhythm in 4px increments?
-6. Has complete keyboard and focus behavior?
-7. Uses token-driven colors and fonts?
-8. Works in light and dark themes?
-
-### For Coding Agents
-
-- Read this file before changing UI, layout, navigation, styling, or components.
-- Prefer existing UI primitives and local layout patterns.
-- Do not introduce new visual language without documenting the reason in the implementation brief or PR.
-- Before handoff, check responsive behavior, focus states, text overflow, loading states, empty states, and token usage.
-
-### Working Rule
-
-Default to these principles unless a deliberate exception is documented in a feature-specific spec.
+Bind each `{colors.*}` role to your theme (e.g. Tailwind `@theme` or CSS custom properties). Repo theme file: `[theme stylesheet path, e.g. src/styles.css]`.

package/templates/design-systems/notion.md

@@ -0,0 +1,94 @@
+# [Project Name] Design — Notion
+
+Design spec for [Project Name]. Map semantic tokens to `[theme stylesheet path, e.g. src/styles.css]` or your Tailwind theme.
+
+## Overview
+
+Document-like daylight system: warm paper-soft canvas, near-black ink, single Notion Blue for structure, and a decorative sticker palette for illustrations only. One optional dark indigo hero band inverts the otherwise light rhythm.
+
+**Key characteristics:**
+- `{colors.canvas-soft}` warm page floor; `{colors.surface}` white for cards
+- Single structural accent `{colors.primary}` (blue) for CTAs and links
+- Sticker colors (`accent-purple`, `accent-pink`, etc.) — decoration only
+- Pill marketing CTAs vs 8px utility buttons
+- Barely-there layered micro-shadows
+- Optional `{colors.secondary}` night hero band
+
+## Colors
+
+### Brand & Accent
+- `{colors.primary}`, `{colors.primary-active}`, `{colors.on-primary}`
+- `{colors.secondary}` — dark hero band only
+
+### Sticker palette (decorative only)
+- `{colors.accent-sky}`, `{colors.accent-purple}`, `{colors.accent-pink}`, `{colors.accent-orange}`, `{colors.accent-teal}`, `{colors.accent-green}`
+
+### Surface
+- `{colors.canvas}` / `{colors.surface}` — white cards
+- `{colors.canvas-soft}` — warm page and footer
+- `{colors.hairline}` — borders
+
+### Text
+- `{colors.ink}`, `{colors.ink-secondary}`, `{colors.ink-muted}`, `{colors.ink-faint}`
+
+## Typography
+
+- NotionInter substitute: Inter with explicit negative tracking on display
+- Weight 700 headlines; 400 body; 600 titles
+
+| Token | Use |
+|---|---|
+| `{typography.display-1}` | Hero (64px) |
+| `{typography.heading-1}` | Section headlines |
+| `{typography.body-md}` | Default body (16px) |
+| `{typography.button}` | Button labels |
+| `{typography.eyebrow}` | Pill badges |
+
+## Layout
+
+- Base 8px; max width ~1080–1300px
+- Section gaps over rules; card padding `{spacing.lg}` 24px
+
+## Elevation
+
+Level 0: hairline only. Level 1: multi-layer micro-shadow. Level 2: modals and elevated pills on dark hero.
+
+## Shapes
+
+| Token | Use |
+|---|---|
+| `{rounded.xs}` 4px | Inputs |
+| `{rounded.md}` 8px | Utility buttons |
+| `{rounded.lg}` 12px | Feature cards |
+| `{rounded.full}` | Marketing pill CTAs |
+
+## Components
+
+- `{components.button-primary}` — blue pill CTA
+- `{components.button-secondary}` — white pill with soft shadow
+- `{components.button-utility}` — nav/plan select, `{rounded.md}`
+- `{components.feature-card}`, `{components.pricing-plan-card}`
+- `{components.hero-band}` — optional dark inverted hero
+- `{components.nav-bar}`, `{components.footer}`
+
+## Do's and Don'ts
+
+### Do
+- Reserve blue for actions and links only
+- Use sticker palette in illustrations and dots only
+- Apply negative tracking on display explicitly
+- Use warm canvas for full pages
+
+### Don't
+- Don't paint CTAs in sticker colors
+- Don't use pill radius on form fields
+- Don't add heavy drop shadows
+- Don't repeat dark hero bands
+
+## Responsive Behavior
+
+Nav hamburger below tablet. Grids collapse to single column. Touch targets ≥44px.
+
+## Token Mapping
+
+Bind roles in `[theme stylesheet path, e.g. src/styles.css]`.

package/templates/design-systems/warp.md

@@ -0,0 +1,89 @@
+# [Project Name] Design — Warp
+
+Design spec for [Project Name]. Map semantic tokens to `[theme stylesheet path, e.g. src/styles.css]` or your Tailwind theme.
+
+## Overview
+
+Warm dark terminal brand: brown-beige canvas (not pure black), off-white as the only "primary" — no chromatic accent. Terminal mockups carry decoration. Extremely tight 3–4px button radii. Inter for narrative, DM Mono for code.
+
+**Key characteristics:**
+- `{colors.primary}` = warm off-white (CTA fill AND default text) — not a hue
+- `{colors.canvas}` warm dark (#2b2622 family) — warmth is identity
+- Tight radii: `{rounded.sm}` 3px, `{rounded.md}` 4px for CTAs
+- Hero display weight 400, quietly confident
+- Hairline + surface contrast only; no drop shadows
+- Terminal screenshots as sole decorative system
+
+## Colors
+
+### Brand (no chromatic accent)
+- `{colors.primary}` — off-white (button fill, ink on canvas)
+- `{colors.on-primary}` — warm dark text on off-white buttons
+
+### Surface
+- `{colors.canvas}` — warm dark page
+- `{colors.canvas-soft}` — cards, mockup chrome, partner tiles
+- `{colors.hairline}` — dividers
+
+### Text
+- `{colors.ink}` — same off-white as primary on canvas
+- `{colors.body-strong}`, `{colors.body}`, `{colors.mute}` — stepped emphasis
+
+## Typography
+
+- Inter 400/500 for UI; DM Mono 400 for terminal/code; Instrument Serif optional for rare editorial italics
+- Negative tracking on display (-1.6px at 64px hero)
+
+| Token | Use |
+|---|---|
+| `{typography.display-xl}` | Hero 64px / 400 |
+| `{typography.body-md}` | Default body 16px |
+| `{typography.code}` | Terminal mockup body |
+| `{typography.button-md}` | Button labels |
+
+## Layout
+
+- Base 4px; `{spacing.5xl}` 96px section padding; max ~1200px
+- Hero 2-column terminal split; download tiles 3-up
+
+## Elevation
+
+Flat hero; hairline borders on `{colors.canvas-soft}` cards. No shadows.
+
+## Shapes
+
+| Token | Use |
+|---|---|
+| `{rounded.sm}` 3px | Primary buttons |
+| `{rounded.md}` 4px | Cards |
+| `{rounded.full}` | Icon circles only |
+
+## Components
+
+- `{components.button-primary}` — off-white on dark, `{rounded.sm}`
+- `{components.button-secondary-ghost}` — ghost nav actions
+- `{components.card-mockup}`, `{components.download-tile}`, `{components.partner-logo-tile}`
+- `{components.hero-band}` — display-xl + terminal split
+- `{components.nav-bar}`, `{components.footer}`
+
+## Do's and Don'ts
+
+### Do
+- Keep canvas warm dark — not neutral gray or pure black
+- Use 3–4px button radii
+- Pair Inter with DM Mono for technical surfaces
+- Set hero at weight 400
+
+### Don't
+- Don't introduce a chromatic brand accent
+- Don't use generous pill CTAs
+- Don't use heavy display weights (700+)
+- Don't add card drop shadows
+
+## Responsive Behavior
+
+Nav hamburger below 768px. Hero mockups stack vertically. Touch targets padded to 44px on mobile.
+
+## Token Mapping
+
+Bind roles in `[theme stylesheet path, e.g. src/styles.css]`.

package/templates/skills/agentkit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentkit
-description: Use when creating, syncing, auditing, repairing, or learning AgentKit-managed repository guidance and codebase changes in an agent session, especially after `agentkit skill install`, when `/agentkit init`, `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, or `/agentkit learn` is requested, or when AGENTS.md, STACK.md, companion guides, managed blocks, commands, placeholders, AI tool adapters, recent diffs, or completed changes need context-aware maintenance or explanation.
+description: Use when creating, syncing, auditing, repairing, or learning AgentKit-managed repository guidance and codebase changes in an agent session, especially after `agentkit skill install`, when `/agentkit init`, `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, `/agentkit learn`, or `/agentkit design` is requested, or when AGENTS.md, DESIGN.md, STACK.md, companion guides, managed blocks, commands, placeholders, AI tool adapters, recent diffs, or completed changes need context-aware maintenance or explanation.
 compatibility: Requires agentkit CLI and agentkit.config.json with installMode skill, or existing AgentKit-managed files with block markers.
 metadata:
   author: thomas-agentkit
@@ -14,11 +14,12 @@ Create, sync, audit, repair, and teach AgentKit-managed repository guidance and
 ## When to use
 
 - User ran `agentkit skill install`
-- User asks `/agentkit init`, `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, or `/agentkit learn`
-- `AGENTS.md`, `STACK.md`, companion guides, or AI adapters are missing
+- User asks `/agentkit init`, `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, `/agentkit learn`, or `/agentkit design`
+- `AGENTS.md`, `DESIGN.md`, `STACK.md`, companion guides, or AI adapters are missing
 - Guidance has stale commands, stack details, project paths, placeholders, or broken references
 - Managed blocks need context-aware update, audit, or repair
 - User wants to understand recent codebase changes, a completed implementation, a diff, a bug fix, or the session
+- User wants to create or refresh `DESIGN.md` from a design baseline
 
 ## When not to use
 
@@ -47,12 +48,16 @@ Always read `references/file-contract.md` before editing or auditing AgentKit-ma
 5. User asks to **learn**, **understand recent changes**, **explain the session**, **teach me what changed**, **ELI5**, **ELI14**, **explain like an intern**, or **check my understanding**
    → `references/learn.md`
 
-6. Unsure which workflow applies
+6. User asks to **design**, set up **DESIGN.md**, choose a design baseline, or customize design language
+   → `references/design.md`
+
+7. Unsure which workflow applies
    → If no guidance files exist: `references/init.md`
    → If guidance exists but commands, stack, files, placeholders, adapters, or references are stale: `references/update.md`
    → If user wants audit, doctor, health check, diagnosis, or review: `references/doctor.md`
    → If managed blocks are malformed or unmanaged files need conversion: `references/repair.md`
    → If user wants to understand completed changes or a session: `references/learn.md`
+   → If user wants `DESIGN.md` or design baseline selection: `references/design.md`
 
 ## Non-negotiables
 
@@ -77,9 +82,10 @@ Always read `references/file-contract.md` before editing or auditing AgentKit-ma
 | `templateSet: full` | Full guidance docs; adapters still follow `aiTools` |
 | AI tool adapters | Thin pointers to `AGENTS.md`; never duplicate full guidance |
 | `STACK.md` | Create/update when preset is configured, user asks, or stack is confidently inferred |
+| `DESIGN.md` | Comes from bundled baseline in `designSystem` config or `/agentkit design`; map tokens to project theme |
 | Existing unmanaged files | Skip unless user asks to convert |
 | Malformed managed blocks | Use `/agentkit repair` before update/refresh |
-| Learning workflow | `/agentkit learn` teaches from diffs and code; it does not create notes or files by default |
+| Learning workflow | `/agentkit learn` is read-only by default and should not create Markdown notes unless the user explicitly asks |
 | Docs-only guidance workflow | Does not require running project tests/builds |
 
 ## Quick reference
@@ -91,4 +97,5 @@ Always read `references/file-contract.md` before editing or auditing AgentKit-ma
 | "/agentkit doctor" / "audit AgentKit guidance" | `references/doctor.md` |
 | "/agentkit repair" / "fix managed blocks" | `references/repair.md` |
 | "/agentkit learn" / "teach me what changed" | `references/learn.md` |
+| "/agentkit design" / "create DESIGN.md" | `references/design.md` |
 | Before any file edit | `references/file-contract.md` |