Semih Mutlu

agent-memory

Consult Semih's AgentMemory vault on demand when explicit historical context, past architectural decisions, earlier experiment rationale, or cross-project state is needed. Do not use for normal coding tasks.

• SKILL.md (2.7 KB)

  ---
  name: agent-memory
  description: Consult Semih's AgentMemory vault on demand when explicit historical context, past architectural decisions, earlier experiment rationale, or cross-project state is needed. Do not use for normal coding tasks.
  ---
  
  # AgentMemory On-Demand Consultation Skill
  
  This skill defines the cheapest explicit retrieval model for querying the personal knowledge vault at `/home/semihmutlu/AgentMemory`.
  
  ## When to Use (Trigger)
  - **Activate ONLY when:**
    - The user explicitly asks for historical background, past architectural decisions, or prior experiment rationale.
    - Cross-project patterns or documented personal workflow conventions are explicitly needed to unblock a decision.
  - **DO NOT activate for:**
    - Standard coding, debugging, refactoring, or testing tasks.
    - Determining the current state of a repo (inspect the active repo instead).
  
  ## Core Precedence & Safety Boundaries
  1. **Verified Repo/Runtime State Beats Memory:**
     - Active disk files, git commits, running processes, and test results in the current repository are the single source of truth.
     - AgentMemory may explain *why* an earlier choice was considered, but never dictates *what is current*.
  2. **Task Queues Are Defunct:**
     - `projects/wayfinder.md` was liquidated on 2026-09-07 (`decisions/2026-09-07-wayfinder-tasfiye-ve-yeniden-yon.md`).
     - `pending-actions.md`, `ledger.md`, and `projects/active-pending-work.md` are frozen historical records.
     - Never reopen tasks or generate task queues from AgentMemory.
  3. **Never Inject the Whole Vault:**
     - Retrieve narrowly (1–3 relevant notes maximum). Never read entire directories or load multiple unrelated notes into context.
  
  ## Narrow Retrieval Workflow
  
  ### Step 1: Lexical / Semantic Search with QMD
  Use the local `qmd` tool to find exact matching notes:
  
  ```bash
  # Fast keyword / BM25 search (returns top 5 matching files):
  qmd search "<keywords>" -c agentmemory --format files -n 5
  ```
  
  For nuanced questions, use a structured query:
  ```bash
  qmd query $'intent: <what to find, what to avoid>\nlex: <exact keywords>\nvec: <semantic description>' -c agentmemory --no-rerank --format files -n 5
  ```
  
  ### Step 2: Read Only the Target Note
  Once the specific note path is identified:
  - View the file using `view_file` on `/home/semihmutlu/AgentMemory/<relative-path>` (or run `qmd get "qmd://agentmemory/<relative-path>"`).
  - Target files in `decisions/` (approved decisions) and `learning/` (reusable technical lessons) first.
  - Treat `sessions/` and `archive/` strictly as historical context, not active policies.
  
  ### Step 3: Present Findings Concisely
  - Cite the file path and date of the decision/learning.
  - Summarize only the specific rationale relevant to the user's inquiry.
  

agents-sdk

Build, debug, or review Cloudflare Agents SDK applications using the agents package.

analyze-sessions

Analyze past omp and pi agent sessions stored under ~/.omp/agent/sessions and ~/.pi/agent/sessions. Use when the user asks about cost (totals, per project, per model, per day), wants to mine prompting patterns from past prompts, view a specific past session, or search across session transcripts.

apple-ui

Apple HIG-inspired UI skill for React/Next.js/Tailwind. NEVER trigger automatically. Use ONLY when user explicitly says "Apple style", "Apple HIG", "Apple UI", or "/apple-ui". Two modes — BUILD (fikir → UI plan + component skeleton) and REVIEW (mevcut UI → S1–S10 smell analysis + score/10). Steve skill handles philosophy (why); this handles execution (how).

• SKILL.md (2.6 KB)

  ---
  name: apple-ui
  description: Apple HIG-inspired UI skill for React/Next.js/Tailwind. NEVER trigger automatically. Use ONLY when user explicitly says "Apple style", "Apple HIG", "Apple UI", or "/apple-ui". Two modes — BUILD (fikir → UI plan + component skeleton) and REVIEW (mevcut UI → S1–S10 smell analysis + score/10). Steve skill handles philosophy (why); this handles execution (how).
  license: MIT
  ---
  
  # Apple UI Skill
  
  > The interface fades behind the user's task.
  > One primary action. One visual weight. One thing this screen does.
  
  ---
  
  ## Dispatch
  
  Read the user input and pick one mode:
  
  | Input type | Mode |
  |-----------|------|
  | Feature idea, rough description, "build me", "design a" | **BUILD** |
  | Code snippet, screenshot, design description for review | **REVIEW** |
  | Ambiguous | Ask: "Build a new screen or review an existing one?" |
  
  Then follow the mode protocol below.
  
  ---
  
  ## BUILD mode
  
  Load `references/builder.md` and execute it in full.
  
  Short version if references/ is unavailable:
  1. Extract core interaction (what is the primary action?)
  2. Apply defaults: light+dark, 8pt grid, system font, one accent + gray
  3. Output: Overview → Layout diagram → Component tree → Data flow → States → Responsive → Code sketch
  
  Constraints (always apply):
  - One primary CTA per viewport
  - 8pt spacing scale only
  - ≤3 font sizes, ≤2 weights, ≤2 accent colors
  - All touch targets ≥44×44px
  - Every component handles: loading, empty, error, success
  
  ---
  
  ## REVIEW mode
  
  Load `references/reviewer.md` for full protocol and `references/checklist.md` for scoring.
  
  Short version if references/ is unavailable:
  Run S1–S10 smell detector, output top 5 issues with exact fixes, score /10.
  
  **S1–S10 quick reference:**
  - S1 Too Many Visual Weights
  - S2 Weak Hierarchy
  - S3 Fake Premium Aesthetic
  - S4 Low Information Density
  - S5 Unclear Primary Action
  - S6 Component Soup
  - S7 Spacing Inconsistency
  - S8 Decorative Motion
  - S9 Inaccessible Contrast
  - S10 Content Hidden Behind Pretty UI
  
  ---
  
  ## Reference files
  
  Load on demand — only read what the active mode needs:
  
  - `references/builder.md` — full BUILD protocol with output format
  - `references/reviewer.md` — full REVIEW protocol with smell taxonomy
  - `references/skillset.md` — Apple HIG heuristics (principles, layout, interaction, components, a11y)
  - `references/playbook.md` — practical patterns (dashboards, share cards, onboarding, testing tools)
  - `references/checklist.md` — L/H/I/A/C/M checklist for pre-ship review
  
  ---
  
  > Pair with `/steve` for philosophy. This skill handles execution.
  

• references/builder.md (4.0 KB)

  You are a UI designer specialized in building Apple-inspired web interfaces using React/Next.js and Tailwind CSS.
  
  The user will give you a rough product idea (a sentence, a description, a feature list). Your job is to produce a concrete UI plan.
  
  ## Process
  
  1. **Extract the core interaction** — What is the primary action the user takes? What is the information they need most?
  2. **Assume reasonable defaults** — If the user didn't specify:
     - Dark or light mode → light with dark mode support
     - Breakpoints → 375px / 768px / 1024px / 1440px
     - Spacing → 8‑point grid
     - Font → system font stack (Inter or system-ui)
     - Color → one accent + neutral gray
  3. **Only ask when truly ambiguous** — If the given info is missing a critical constraint (e.g., "this is for mobile only" vs "responsive required"), ask one clear question. Otherwise, proceed.
  4. **Produce the plan.**
  
  ## Output Format
  
  ### Overview
  - What this screen does (1 sentence)
  - Key interaction pattern
  
  ### Layout Structure
  ```
  ┌─────────────────────────────────────────┐
  │  Navigation (title + 1 action)          │
  ├─────────────────────────────────────────┤
  │  Primary content area                    │
  │  ┌───────────┐  ┌───────────────────┐   │
  │  │ Widget A  │  │  Main data view   │   │
  │  │ Metric    │  │  (list/grid/table) │   │
  │  │ Sparkline │  │                    │   │
  │  └───────────┘  └───────────────────┘   │
  ├─────────────────────────────────────────┤
  │  Bottom action bar (mobile)             │
  └─────────────────────────────────────────┘
  ```
  
  ### Component Tree
  ```
  <Page>
    <NavBar title="..." action={<Button />} />
    <Content>
      <MetricCard label="..." value="..." />
      <DataList items={...} />
    </Content>
    <BottomBar>
      <Button variant="primary">CTA</Button>
    </BottomBar>
  </Page>
  ```
  
  ### Data Flow
  - What data is needed
  - Where it comes from (props, fetch, state)
  - Loading / empty / error states for each
  
  ### States to Handle
  | State | What renders |
  |-------|-------------|
  | Loading | Skeleton cards, shimmer |
  | Empty | Illustration + "No items yet" + CTA |
  | Error | Inline error + retry button |
  | Success | Content with subtle entrance animation |
  
  ### Responsive Behavior
  - Mobile (375px): single column, full-width inputs, bottom action bar
  - Tablet (768px): 2‑column grid, side panels
  - Desktop (1280px): multi-column, sidebars, keyboard shortcuts
  
  ### Accessibility Checklist
  - Focus order follows visual layout
  - Color not the only indicator
  - Touch targets ≥ 44×44px
  - Screen reader labels on all interactive elements
  - `prefers-reduced-motion` respected
  
  ### Code Sketch (React/Tailwind)
  ```tsx
  // Key component skeleton — not full implementation, just the structural decisions
  export function MetricCard({ label, value, trend }: MetricCardProps) {
    return (
      <div className="rounded-xl border border-gray-200 bg-white p-4 shadow-sm">
        <p className="text-sm text-gray-500">{label}</p>
        <p className="mt-1 text-2xl font-semibold text-gray-900">{value}</p>
        {trend && <TrendIndicator direction={trend.direction} />}
      </div>
    )
  }
  ```
  
  ## Design Constraints
  - One primary CTA per viewport. No competition.
  - 8‑point spacing scale only.
  - 3 font sizes max, 2 weights max, 2 accent colors max.
  - All interactive elements ≥ 44×44px.
  - No decorative motion. Every animation has a purpose.
  - Content in plain view — no tooltip-only info for critical data.
  - Max 3 onboarding steps. Max 5 tab bar items.
  
  ---
  
  Provide the UI plan now.
  

• references/checklist.md (4.9 KB)

  # Apple UI Review Checklist
  
  > For each screen, mark Pass / Fail / N/A. A screen passes if all items in the relevant group pass.
  
  ---
  
  ## Layout
  
  | # | Check | How to test |
  |---|-------|-------------|
  | L1 | Content area is ≤1200px wide on desktop | Measure at 1920px viewport |
  | L2 | 8‑point spacing scale is used consistently | Inspect gaps: only 4, 8, 12, 16, 24, 32, 48, 64 |
  | L3 | No content is clipped or overlapped at 375px, 768px, 1280px | Resize browser to each breakpoint |
  | L4 | Touch targets are ≥44×44px with ≥8px between them | Inspect computed size of all buttons, links, inputs |
  | L5 | Safe area insets applied (notch, home indicator) | Test in iOS Safari / Simulator |
  | L6 | Page is scrollable in one direction only | No horizontal scroll at any breakpoint |
  | L7 | Form inputs and buttons are full-width on mobile | Check at 375px width |
  
  ## Visual Hierarchy
  
  | # | Check | How to test |
  |---|-------|-------------|
  | H1 | The page purpose is clear within 3 seconds of looking at it | Cover the title, can you tell the purpose? |
  | H2 | One primary action per viewport | Count filled/high-contrast buttons. Should be ≤1 |
  | H3 | Font hierarchy uses ≤3 sizes, ≤2 weights, ≤2 accent colors | Inspect all text nodes |
  | H4 | The most important element is the most visually dominant | Eyes naturally land on it first |
  | H5 | Secondary info is visually muted (lower weight, smaller, gray) | Compare against primary text |
  | H6 | Links are distinguishable from body text (underline or color) | Toggle `text-decoration: none` — can you still tell? |
  
  ## Interaction & Feedback
  
  | # | Check | How to test |
  |---|-------|-------------|
  | I1 | Every clickable element has hover/active state (desktop) | Hover each button, link, icon |
  | I2 | Click/tap produces visible feedback within 100ms | Record slo-mo video or use DevTools Performance |
  | I3 | Disabled buttons are visually muted (not removed) | Check `disabled` attribute styling |
  | I4 | Loading states appear within 200ms for async operations | Slow network in DevTools, observe skeleton/spinner |
  | I5 | Keyboard navigation works: Tab → Enter/Space → Escape | Tab through entire page |
  | I6 | Focus ring is visible (≥2px, high contrast) | Tab through all interactive elements |
  | I7 | Destructive actions have confirmation or undo | Trigger delete/remove, observe |
  | I8 | Empty states have a message + action (not blank) | Clear all data, observe screen |
  | I9 | Error messages are inline, specific, and below the input | Submit invalid form |
  
  ## Accessibility
  
  | # | Check | How to test |
  |---|-------|-------------|
  | A1 | Body text contrast ≥ 4.5:1 | DevTools contrast checker or axe DevTools |
  | A2 | Large text contrast ≥ 3:1 | Same |
  | A3 | UI component contrast ≥ 3:1 (borders, icons, focus) | Same |
  | A4 | All images have `alt` text (or `aria-label` for icons) | axe DevTools or scan `img` tags |
  | A5 | Buttons and links describe action, not just appearance | "Close dialog", not "X" |
  | A6 | Heading hierarchy is correct (h1 → h2 → h3, no skipping) | `document.querySelectorAll('h1,h2,h3,h4,h5,h6')` |
  | A7 | Page uses `<nav>`, `<main>`, `<aside>` landmarks | axe DevTools |
  | A8 | Text can be resized to 200% without breaking layout | Zoom browser to 200% |
  | A9 | Pinch-zoom is not disabled (no `user-scalable=no`) | Check `<meta name="viewport">` |
  | A10 | Screen reader can complete all tasks | VoiceOver / TalkBack full flow test |
  | A11 | `prefers-reduced-motion` is respected | Enable in OS settings, check animations |
  
  ## Copy & Content
  
  | # | Check | How to test |
  |---|-------|-------------|
  | C1 | Every heading describes the content below it | Read headings in isolation |
  | C2 | Error messages are human-readable, not technical | "Something went wrong. Please try again." not "Error 0x87e5000b" |
  | C3 | CTAs use verbs ("Create account", "Save changes") | "Submit", "OK", "Click here" fail |
  | C4 | No placeholder text substitutes for a label | Labels are visible above/next to fields |
  | C5 | Numbers and dates are formatted for locale | Check currency, date format, decimal separator |
  | C6| No jargon unless the user is technical | "Authenticate", "Onboard", "Execute" fail for consumer apps |
  
  ## Motion & Animation
  
  | # | Check | How to test |
  |---|-------|-------------|
  | M1 | Every animation has a functional purpose | Remove animation — is anything broken? If not, remove it |
  | M2 | Duration ≤ 300ms for micro-interactions | Record and measure |
  | M3 | No parallax, auto-play video, or large decorative animations | Check with `prefers-reduced-motion: reduce` |
  | M4 | Page transitions are smooth (no jank, no white flash) | Navigate with slow CPU throttling |
  | M5 | Skeleton screens appear before content, not after | Observe loading sequence |
  
  ---
  
  ## Scoring
  
  - **All groups pass** → Ship it.
  - **1–2 failures in Layout, Hierarchy, or Interaction** → Fix before shipping.
  - **Any failure in Accessibility** → Blocking. Fix before shipping.
  - **3+ failures total** → Redesign pass needed.
  

• references/playbook.md (11 KB)

  # Apple UI Playbook — Practical Design Heuristics
  
  > Generalized from Apple HIG philosophy for web apps, dashboards, onboarding flows, share-cards, and product testing tools.
  
  ---
  
  ## 1. Core Principles
  
  | # | Principle | What it means for web UI |
  |---|-----------|--------------------------|
  | 1 | **Clarity over decoration** | Every element earns its place. If it doesn't inform or enable an action, remove it. |
  | 2 | **Content-first layout** | Start with the data/user goal. Add UI around it, not the other way. |
  | 3 | **Deference** | The interface disappears when the user is focused. No chrome competes with content. |
  | 4 | **Progressive disclosure** | Show the essential now, the rest on demand. Don't dump everything on one screen. |
  | 5 | **Friction is a feature** | Make destructive/irreversible actions intentionally harder. Make primary actions frictionless. |
  | 6 | **Direct manipulation** | Let users interact with the thing itself, not a control panel for the thing. |
  | 7 | **Consistent mental model** | Same pattern = same behavior everywhere. Surprises erode trust. |
  
  **Good decision:** A dashboard card that shows key metric, trend sparkline, and one CTA button. Everything else is one click away.
  
  **Bad decision:** A dashboard card with 3 tabs, 2 dropdowns, an info icon with a tooltip, a settings gear, and an "edit" pencil — all visible at once.
  
  ---
  
  ## 2. Web-App Layout Rules
  
  ### Grid & Spacing
  - Use an 8‑point baseline grid. Margins, padding, gap — all multiples of 8 (or 4 for dense content).
  - 12‑column flexible grid for layouts wider than 768px. Collapse to 4 or 6 columns on tablet, 2 on mobile.
  - Content area max-width: 640–720px for reading, 1200px for dashboards.
  - Gutter: 24px (desktop), 16px (tablet), 16px (mobile).
  
  ### Safe Areas
  - `env(safe-area-inset-*)` for notch/home indicator on iOS WebView.
  - Sticky headers and bottom bars inset by safe area.
  - No critical content in the outer 16px on mobile (thumb zone).
  
  ### Touch Targets
  - Minimum 44×44px. 48×48px preferred.
  - Spacing between targets ≥ 8px.
  - For icon-only buttons, add invisible padding to hit 44×44 minimum.
  
  ### Visual Rhythm
  - Place primary action at bottom-right (mobile) or top-right (desktop).
  - Group related controls together. Separate unrelated controls with visible whitespace, not lines.
  - Scan direction: top-to-bottom, left-to-right. Place the most important content at top-left.
  
  **Good:** A share-card layout with hero image → metric → attribution → CTA, one after another, 24px gaps.
  
  **Bad:** A share-card with CTA at top-left, metric in the middle, hero overlapping text, and attribution in a tiny font at the bottom.
  
  ---
  
  ## 3. Design Smell Detector
  
  ### S1: Too Many Visual Weights
  - **Detect:** Count distinct font sizes, colors, and font weights on screen. If >3 of any, you have a problem.
  - **Why it hurts:** User can't tell what matters. Everything shouts = nothing shouts.
  - **Fix:** Max 3 sizes (primary, secondary, caption). Max 2 weights (regular + semibold). Max 2 accent colors + neutral.
  - **Tailwind hint:** Extract to `theme.extend.fontSize` and `theme.extend.colors`. Restrict yourself to what's in the config. If you need a new size, justify it.
  
  ### S2: Weak Hierarchy
  - **Detect:** Cover the screen title. Can you still tell what the page is about from remaining elements? If not, hierarchy failed.
  - **Why it hurts:** Scanning is slower. Users miss the point.
  - **Fix:** One hero element (headline or data point) → supporting context → secondary info → tertiary details/tools.
  - **React hint:** Render as a single `<Stack>` per section with consistent `<Heading />`, `<Body />`, `<Caption />` components. No inline style overrides.
  
  ### S3: Fake Premium Aesthetic
  - **Detect:** Over-used gradients, heavy drop shadows, multiple glassmorphism layers, bevels, and unnecessary 3D transforms on content.
  - **Why it hurts:** Looks dated and distracts from function. Users associate it with scam/marketing sites.
  - **Fix:** Flat color + one subtle shadow (elevation) per layer. One gradient accent maximum, used sparingly. Glassmorphism only on overlays, never on content cards.
  - **Tailwind hint:** Stick to `shadow-sm`, `shadow-md`, `shadow-lg`. No custom blur/gradient combos unless the brand demands it. Use `backdrop-blur-sm` at most.
  
  ### S4: Low Information Density
  - **Detect:** On a 1920px screen, content occupies <40% of the viewport width while sidebars, padding, and empty chrome take the rest.
  - **Why it hurts:** Forces scrolling for no reason. User can't get an overview.
  - **Fix:** Wider content area (up to 1200px). Reduce horizontal padding from 48px to 24px. Use multi-column layouts for data. Remove decorative sidebars.
  - **React hint:** Use a responsive grid. `grid-cols-1 md:grid-cols-2 lg:grid-cols-3` instead of a single-column stack. Test at 1280px width.
  
  ### S5: Unclear Primary Action
  - **Detect:** Ask "what should the user do on this screen?" If the answer isn't immediately obvious from the UI, primary action is unclear.
  - **Why it hurts:** Users hesitate. Conversion drops. Users click secondary/tertiary actions by mistake.
  - **Fix:** One primary CTA per viewport. Use filled/high-contrast button for it. Make it the most visually dominant interactive element. If multiple equal actions exist, the view needs restructuring.
  - **Tailwind hint:** Primary button = `bg-blue-600 text-white hover:bg-blue-700`. Secondary = `border border-gray-300`. Never two `bg-blue-600` on the same screen.
  
  ### S6: Component Soup
  - **Detect:** Same page has a table, a card grid, an accordion, tabs, a carousel, and a list — all showing similar data.
  - **Why it hurts:** Inconsistent interaction patterns. User can't build a reliable mental model of how to browse data.
  - **Fix:** Pick one container pattern per page. If data is comparable, use the same component everywhere. Differentiate only by purpose, not by visual variety.
  - **React hint:** Extract a single `<DataContainer>` component. Pass `variant="table"|"grid"|"list"` as a prop. Never mix two variants on the same page.
  
  ### S7: Spacing Inconsistency
  - **Detect:** Measure gaps between elements. If you find 8px, 12px, 14px, 20px, 32px across the same page, spacing is inconsistent.
  - **Why it hurts:** Feels sloppy. Users subconsciously perceive lower quality.
  - **Fix:** Use a spacing scale: 4, 8, 12, 16, 24, 32, 48, 64. Never use unlisted values. Apply `gap` for grid/flex, not individual margins.
  - **Tailwind hint:** Stick to `gap-2`, `gap-4`, `gap-6`, `gap-8`. Consider a lint rule banning arbitrary `m-[*]`, `p-[*]`, `gap-[*]`.
  
  ### S8: Decorative Motion
  - **Detect:** Elements animate in, bounce, spin, or pulse with no functional purpose. Especially problematic: parallax on hero images, spinning logos, auto-advancing carousels.
  - **Why it hurts:** Triggers vestibular disorders. Competes for attention. Feels unprofessional.
  - **Fix:** Every animation must serve 1 of 3 purposes: communicate state change, focus attention, or provide spatial context. If it doesn't, remove it. Respect `prefers-reduced-motion`.
  - **React hint:** Use Framer Motion's `useReducedMotion()`. Wrap decorative animations in a `<motion.div>` that checks the preference. Turn carousel auto-advance off.
  
  ### S9: Inaccessible Contrast
  - **Detect:** Run any contrast checker. Text on backgrounds below 4.5:1 fails. Large text (≥18px bold or ≥24px regular) below 3:1 fails. Interactive elements below 3:1 fail.
  - **Why it hurts:** Users with low vision can't read the screen. Legal liability in accessibility-regulated markets.
  - **Fix:** Use high-contrast text colors (`gray-900` on `white`, not `gray-500` on `white`). Never use `gray-400` or lighter for body text. Provide a dark mode that also passes contrast.
  - **Tailwind hint:** Body text = `text-gray-900 dark:text-gray-100`. Caption = `text-gray-500` minimum. Interactive elements: use `ring-offset-2 ring-blue-500` for focus, not color-only indicators.
  
  ### S10: Content Hidden Behind Pretty UI
  - **Detect:** Critical info (price, dates, status, errors) is inside expandable sections, tooltips, modals, or behind hover-only reveals.
  - **Why it hurts:** Increases cognitive load. Mobile users can't hover. Users miss critical info.
  - **Fix:** Put essential info in plain view. Use progressive disclosure for secondary/optional details only. Never hide: primary action label, cost, error messages, timestamps, confirmation state.
  - **React hint:** Always render the primary label/state visibly. Use a `title` attribute or `<span className="sr-only">` for supplementary info, never for essential content.
  
  ---
  
  ## 4. Component Decision Guide
  
  | Component | Good practice | Bad practice |
  |-----------|--------------|--------------|
  | **Primary button** | Filled, high contrast, one per viewport | Ghost button for critical action |
  | **Secondary button** | Outlined, same height as primary | Text link pretending to be a button |
  | **Navigation bar** | Title + back + one action | Breadcrumbs, search, avatar, 3 icons, and a dropdown |
  | **Tab bar** | 3–5 tabs, label + icon | 7+ tabs, icons only, no labels |
  | **Card** | Consistent elevation, full-area tappable | Random shadows, mixed corner radius, partial click target |
  | **Modal** | Single task, clear dismiss (X + Escape) | Stacked modals, no backdrop dismiss, 3+ inputs |
  | **Switch/toggle** | Immediate effect, no save button | "Save settings" required after toggle |
  | **Empty state** | Illustration + message + action | Blank screen or spinner that never ends |
  | **Error message** | Inline, specific, below the input | Toast that disappears, "An error occurred" |
  | **Search** | Autocomplete, visible input, clear button | Hidden behind icon, no suggestions, no way to clear |
  
  ---
  
  ## 5. Practical Patterns for Your Projects
  
  ### Dashboards
  - One KPI card per row on mobile, 2–3 per row on desktop.
  - Sparkline + number + one-word label. No legend unless interactive.
  - Chart tooltip: show value + label + change. Hide gridlines.
  
  ### Share/Wrapped Cards
  - Card ratio: 3:4 or 9:16 (Instagram/Story friendly).
  - Hero graphic → stat → caption → branding. No CTA inside the card.
  - Text must be readable at 320px width (the message preview size).
  
  ### Onboarding Flows
  - Max 3 steps. Each step = one concept + one action.
  - Progress bar at top. Skip link if skippable.
  - No account-required gate until the user has seen value.
  
  ### Product Testing Tools
  - Side-by-side comparison layout. Left = control, Right = variant.
  - Floating action bar at bottom: Approve / Reject / Comments.
  - Keyboard shortcuts: J/K for navigate, A/R for approve/reject.
  
  ---
  
  > Use this playbook as a reference when building UI. Pick the principle or smell that matches your current problem and apply the fix pattern.
  

• references/reviewer.md (2.8 KB)

  You are a UI reviewer trained on Apple Human Interface Guidelines, specialized in React/Next.js/Tailwind CSS applications.
  
  Review the provided screen (code, screenshot, or description). Be concrete — no vague "make it cleaner" advice.
  
  ## Output Format
  
  ### A) Top 5 Issues
  List exactly 5 issues ranked by impact. For each:
  - **Issue**: one-line description
  - **Smell tag**: reference from Design Smell Detector (S1–S10)
  - **Severity**: critical / high / medium / low
  - **Why it hurts**: 1 sentence on user impact
  - **Evidence**: what you see on screen that confirms this issue
  
  ### B) Exact Visual Fixes
  For each issue, give an exact fix:
  - Before → After description
  - Key measurement (spacing, color, size, contrast ratio)
  - Component/selector to change
  
  ### C) Code-Level Suggestions
  React/Tailwind specifics when applicable:
  - Replace `<div className="flex...">` with `<Stack gap={4}>`
  - Extract hardcoded colors to `theme.extend.colors`
  - Add `useReducedMotion()` for animations
  - Add `sr-only` for missing labels
  - Add `focus:ring-2 focus:ring-blue-500` for focus states
  - Replace inline `style` with Tailwind utility classes
  
  ### D) What to Remove
  List elements that should be deleted, not fixed:
  - Decorative elements with no function
  - Duplicate CTAs
  - Unused state indicators
  - Redundant labels
  - Empty wrappers
  
  ### E) Final Score /10
  - 10: Apple-level polish. Ship it.
  - 8–9: Minor issues. Fix and ship.
  - 6–7: Needs rework before shipping.
  - 4–5: Major redesign needed.
  - 0–3: Start over.
  
  Include a 1-sentence justification for the score.
  
  ## Reference: Design Smell Detector
  
  Use these tags in your analysis:
  
  - **S1 Too Many Visual Weights** — >3 font sizes, >2 font weights, >2 accent colors on one screen
  - **S2 Weak Hierarchy** — page purpose unclear within 3 seconds of scanning
  - **S3 Fake Premium Aesthetic** — overused gradients, heavy shadows, glassmorphism on content cards
  - **S4 Low Information Density** — content occupies <40% of viewport at 1920px
  - **S5 Unclear Primary Action** — no dominant CTA, or multiple competing primary buttons
  - **S6 Component Soup** — multiple container patterns (table + grid + accordion) for similar data
  - **S7 Spacing Inconsistency** — gaps outside the 4/8/12/16/24/32/48/64 scale
  - **S8 Decorative Motion** — animation with no functional purpose
  - **S9 Inaccessible Contrast** — text/UI below WCAG AA thresholds
  - **S10 Content Hidden Behind Pretty UI** — critical info inside expandable/hover-only/reveal elements
  
  ## Constraints
  - Do not copy Apple wording verbatim. Use generalized heuristics.
  - Every suggestion must be actionable at code level. If you can't write the CSS/React prop for it, don't suggest it.
  - When in doubt, prefer removal over addition. Less UI solves more problems.
  
  ---
  
  Provide the review now.
  

• references/skillset.md (14 KB)

  Here is a reusable design skillset derived from Apple’s Human Interface Guidelines, generalized for web and product design. Each section is a standalone heuristic or checklist you can apply directly.
  
  ---
  
  ## 1. Apple-Inspired UI Principles
  
  - **Clarity** – Content comes first. Every element (text, icon, control) must have a clear purpose. Avoid decorative clutter; use visual hierarchy to lead the eye.
  - **Deference** – The interface fades behind the user’s task. Transitions are smooth, controls are subtle, and content breathes with ample white space.
  - **Depth** – Use layers and motion to communicate spatial relationships. Subtle shadows, parallax, and smooth transitions help users understand where they are and what to expect next.
  - **Consistency** – Reuse familiar patterns (e.g., navigation bars, tab bars, modals) so users don’t have to relearn interactions.
  - **Direct Manipulation** – Let users touch, drag, swipe, or tap content directly. Avoid intermediary menus when a gesture or direct action is more intuitive.
  - **Feedback** – Every action should have an immediate, visible response (e.g., button highlight, state change, haptic or sound cue on mobile).
  - **Metaphor** – Use real-world analogues (e.g., a page curl, a trash can, a toggle switch) to make digital actions feel familiar.
  - **User Control** – Users initiate and control actions; avoid unexpected outcomes. Always provide an obvious way to undo or cancel.
  
  ---
  
  ## 2. Layout Rules for Web Apps
  
  - **Safe Zones** – Place critical content (actions, navigation, inputs) inside the safe area (avoid browser chrome, scrollbars, sticky headers/footers). On mobile, respect notch and home indicator areas.
  - **Responsive Spacing** – Use a consistent 8‑point grid system. Margins and padding should scale in multiples of 8 (or 4 for tight spaces). Breakpoints at 320‑480‑768‑1024‑1440px.
  - **Content‑First Width** – Text columns should be 600‑800px max for readability on large screens. Use a 12‑column flexible grid for complex layouts.
  - **Alignment** – Left‑align text for most languages; center only for short, isolated elements (headlines, buttons). Avoid right‑alignment in multi‑column layouts.
  - **Touch Targets** – Minimum 44×44px for any interactive element (buttons, links, inputs). Space between touch targets ≥ 8px.
  - **Visual Hierarchy** – Use size, weight, and color to show importance. The most important action should be the largest or most colorful (e.g., primary button).
  - **Scrolling vs. Pagination** – Prefer vertical scrolling for content feeds. Use pagination only when content is finite and navigation benefits from clear landmarks (e.g., step‑by‑step forms).
  - **Avoid Dead Zones** – Every part of the screen should either be interactive, informative, or clearly inactive. Large empty spaces without purpose confuse users.
  
  ---
  
  ## 3. Interaction and Feedback Rules
  
  - **Instant Visual Feedback** – Every tap, click, or gesture must trigger an immediate state change (hover highlight, press dim, active color). Delay >0.1s feels broken.
  - **Touch‑Friendly Gestures** – Support swipe to go back, pull‑to‑refresh, long‑press for context menus. Ensure single‑tap remains the primary action.
  - **Error Prevention & Undo** – Before destructive actions, show a confirmation or provide a short undo window (e.g., “Item deleted – Undo” toast). Don’t rely on alerts that block interaction.
  - **Loading States** – Show skeleton screens or progress indicators within 200ms. For operations >1s, show a progress bar or percentage. Never leave a user waiting without feedback.
  - **Keyboard Accessibility** – All interactive elements must be reachable and activatable via Tab, Enter, Space, and Escape. Focus order should follow visual layout.
  - **Hover States** – On desktop, provide hover tooltips for truncated text or icon meanings. Do not rely on hover for primary actions (they don’t work on touch).
  - **Drag‑and‑Drop** – Provide a clear visual indication of the dragged item, a drop target highlight, and the ability to cancel by pressing Escape or dropping outside the target.
  - **Touch and Hold** – Use for secondary actions (e.g., peek, copy, add to playlist). Provide haptic (or visual) feedback if supported.
  
  ---
  
  ## 4. Component Heuristics
  
  - **Navigation Bars** – Always show the current screen title. Use a back arrow (for iOS‑like apps) or breadcrumbs for deeper hierarchies. Keep actions limited to one primary action per bar.
  - **Tab Bars** – Place at bottom (mobile) or top (desktop). Limit to 5 tabs. Do not include “Settings” as a tab unless it’s a core function; use a gear icon in the navigation bar instead.
  - **Buttons** – Clearly differentiate primary (filled, high contrast), secondary (outlined), and tertiary (text‑only) buttons. Disabled buttons should be visually muted, not removed.
  - **Text Fields** – Show placeholder text inside the field. Use a visible label above or beside the field. Provide clear error messages in‑line (not in a toast) and keep them concise.
  - **Switches / Toggles** – Use a physical switch metaphor. Immediate action on toggle; do not require a “Save” button for toggle changes.
  - **Sliders** – Always show the current value as a number or icon. Allow tapping on a specific point to jump there, not just dragging.
  - **Cards** – Use consistent elevation (shadow) to indicate grouping. Cards should be tappable as a whole when they represent a single action or navigation target.
  - **Modals / Sheets** – Use for focused tasks (e.g., login, share, compose). Must have a clear dismiss (X, Cancel, or swipe down). Avoid stacking modals.
  - **Alerts** – Reserve for critical information that requires a decision (e.g., “Delete – Cancel”). Do not use for confirmations of non‑destructive actions (use toast or inline banner instead).
  - **Tooltips / Popovers** – Appear on hover/focus, disappear on escape or blur. Keep content short. Do not place interactive elements inside tooltips.
  
  ---
  
  ## 5. Accessibility Checklist
  
  - **Color Contrast** – All text and interactive elements must meet WCAG AA (4.5:1 for text, 3:1 for large text and UI components). Test with grayscale mode.
  - **Scalable Text** – Use relative units (rem, em) so text can be resized up to 200% without breaking layout. Never disable pinch‑zoom on mobile.
  - **Screen Reader Labels** – Every image must have `alt` text (or `aria‑label` for icons). Buttons and links must describe their action (e.g., “Close dialog” not just “X”).
  - **Focus Indicators** – Provide a visible focus ring (outline) for keyboard navigation. Custom focus styles must be at least 2px wide and high contrast.
  - **Touch Targets** – Minimum 44×44px, even for small icons. Provide extra padding or a larger invisible hit area.
  - **Headings & Landmarks** – Use proper HTML heading hierarchy (h1–h6) and `<nav>`, `<main>`, `<aside>` landmarks for screen reader navigation.
  - **Motion Reduction** – Respect `prefers‑reduced‑motion`. Turn off auto‑play video, parallax, and large animations. Use `transform` and `opacity` for performant, accessible transitions.
  - **VoiceOver / TalkBack** – Test all flows with screen reader on. Ensure custom controls (switches, sliders, drag‑and‑drop) are announced and operable with gestures.
  - **High Contrast / Dark Mode** – Support system‑level appearance settings. Invert colors or provide a separate high‑contrast theme.
  - **Error Announcements** – Use `aria-live` regions to announce dynamic validation errors to screen readers without losing focus.
  
  ---
  
  ## 6. Product Review Checklist
  
  1. **Purpose & Clarity** – Does every screen have a clear primary goal? Can a new user understand what to do in <5 seconds?
  2. **Visual Consistency** – Check typography, color palette, spacing, icon style across all screens. Are all elements using the same design tokens?
  3. **Responsiveness** – Test on three breakpoints: mobile (375px), tablet (768px), desktop (1280px). Any overlapping, hidden, or misaligned elements?
  4. **Navigation Flow** – Can the user complete the main task (e.g., purchase, sign up, search) in ≤3 taps/clicks? Is there a clear “home” or escape?
  5. **Loading & Empty States** – Are skeletons/placeholders shown? What happens when a list is empty (friendly message + action)?
  6. **Error Handling** – What appears when network fails? Are error messages helpful and non‑technical (“Oops, something went wrong. Please try again.”)?
  7. **Forms & Inputs** – Are validation errors shown inline? Are required fields marked? Is autocomplete enabled for common fields (email, phone)?
  8. **Feedback & Haptics** – Does every action produce immediate visual feedback? On mobile, are haptic patterns used for success, error, and selection?
  9. **Performance** – Do major interactions feel instant (<100ms)? Are images lazy‑loaded? Does scrolling feel smooth (no jank)?
  10. **Accessibility** – Run through checklist #5. Can all tasks be completed using only keyboard and screen reader?
  
  ---
  
  ## 7. React/Next.js Implementation Advice
  
  - **Use a Design System** – Implement Apple‑inspired components as a library (Storybook / Bit) with shared tokens (spacing, colors, typography). Use Tailwind CSS or CSS‑in‑JS to enforce consistency.
  - **Safe Area Handling** – Use `env(safe-area-inset-*)` in CSS for notch / home indicator. In Next.js, apply via a `safeArea` utility class on `body`.
  - **Layout Components** – Create reusable `<SafeAreaView>`, `<Stack>` (flex column), `<HStack>` (flex row), `<Spacer>` wrappers with consistent margin/padding based on 8px grid.
  - **Motion Library** – Use Framer Motion for transitions (page transitions, modal slides, skeleton shimmer). Respect `prefers-reduced-motion` with `useReducedMotion()`.
  - **Keyboard Navigation** – Add `tabIndex` to custom components. Use `useFocusWithin` or `useEventListener` for managing focus traps in modals.
  - **Server Components** – Keep interactive UI (buttons, inputs, modals) as client components. Use server components for static content (layout headers, product lists) to improve performance.
  - **Progressive Enhancement** – Ensure the app works without JavaScript (basic HTML forms, links, static content). Use `<noscript>` fallbacks and meta refresh for legacy browsers.
  - **Image Optimization** – Use Next.js `next/image` with `priority` on above‑the‑fold images. Implement lazy loading for the rest. Provide `alt` text automatically from content.
  - **Accessibility Hooks** – Create a `useAriaLive()` hook for dynamic announcements. Wrap actions in `aria-live=“polite”` when needed. Use `@radix-ui/react-dialog` for accessible modals (focus trap, escape dismiss).
  - **Testing** – Use Playwright or Testing Library to simulate keyboard and screen reader flows. Write tests for every interactive component (focus, click, screen reader label).
  
  ---
  
  ## 8. “Bad UI Smell” List
  
  - **Over‑crowded screens** – More than 5 interactive elements in a single row without clear grouping. Too many text styles or colors.
  - **No visible feedback** – Buttons that don’t change state on click. Forms that submit without any success/error signal.
  - **Hidden navigation** – No back button, no breadcrumbs, no indication of where the user is in the app hierarchy.
  - **Tiny touch targets** – Buttons or links smaller than 44×44px, especially next to each other.
  - **Unclear “sign off”** – No log out, delete account, or profile exit path. Users feel trapped.
  - **Placebo “Save” buttons** – A “Save” button that doesn’t save automatically when toggles or switches change state (unless explicitly required by UX).
  - **Inconsistent iconography** – Same icon used for two different actions (e.g., a star for both favorites and ratings).
  - **Alerts for everything** – Warnings popping up for trivial actions (like “Are you sure you want to go back?” on a form with empty fields).
  - **Disappearing elements** – Tooltips or dropdowns that close when you move the cursor slightly off them.
  - **Missing loading states** – No skeleton, spinner, or progress bar for operations taking >200ms. Blank screen while data loads.
  - **No keyboard support** – Unable to Tab through a form, or pressing Enter doesn’t submit. Focus ring invisible or missing.
  - **Over‑engineered gestures** – Swipe left to delete, swipe right to reorder, long‑press to edit, pinch to zoom – but no visual cues or discoverability.
  - **Color as only indicator** – Using only red/green to show success/error without text or icon. Accessibility nightmare.
  - **Infinite scroll without progress** – User scrolls forever but never knows how many items remain or where they are.
  - **Mode without exit** – A full‑screen onboarding, tutorial, or full‑screen modal that cannot be dismissed (no X or back).
  
  ---
  
  ## 9. Reusable Agent Prompt for Reviewing Screens
  
  ```
  You are a UI reviewer trained on Apple Human Interface Guidelines. Review the provided screen design (image or code) and produce a critique using the following structure:
  
  1. **Overall Impression** (1 sentence): Is the UI clear, clean, and well‑organized?  
  2. **Layout & Alignment** (bullet list):  
     - Check safe area, spacing, grid consistency, responsive breakpoints.  
     - Is content prioritized with visual hierarchy?  
  3. **Interaction & Feedback** (bullet list):  
     - Identify missing or delayed feedback on actions.  
     - Are touch targets ≥44px? Are gestures discoverable?  
  4. **Component Usage** (bullet list):  
     - Are buttons, navigation, modals, and alerts used appropriately?  
     - Check for inconsistencies (e.g., primary button vs. link).  
  5. **Accessibility** (bullet list):  
     - Color contrast, focus indicators, screen reader labels, keyboard navigation.  
  6. **Bad Smells**: List any of the “Bad UI Smells” present.  
  7. **Top 3 Improvements**: Prioritize the most impactful changes.
  
  Always reference Apple‑inspired principles (Clarity, Deference, Depth, Direct Manipulation) when explaining why something works or fails.
  ```
  
  ---
  
  This skillset can be used as a living document, adapted for any web or product design team. The heuristics are intentionally general (not tied to iOS) but carry the core philosophy of Apple’s HIG: **design with the user’s mental model, not the system’s.**

architect

Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape.

• SKILL.md (5.5 KB)

  ---
  name: architect
  description: "Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape."
  disable-model-invocation: true
  ---
  
  # Architect
  
  Design before implementing. Sketch types, function signatures, class shapes, and module boundaries with `not implemented` bodies and pseudocode. Synthesize across multiple model perspectives, then fill in code against the chosen sketch. If implementation proves the sketch wrong, throw it out and redesign.
  
  ## Start
  
  Open a todolist with one entry per phase before starting.
  
  1. Ground
  2. Sketch
  3. Agree
  4. Implement
  5. Scrap
  
  ## Phase A: Ground the problem
  
  Build a real mental model of every system the new code touches. Run the **how** skill over the relevant subsystems.
  
  Naming a file isn't grounding. Produce the traced model `how` prescribes. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess.
  
  Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.
  
  ## Phase B: Sketch
  
  Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts. Pass `references/runner-prompt.md` as each runner's prompt. Each candidate produces a design package shaped per `references/rationale-template.md`.
  
  Take the runners from the `architect runners` line in the `pstack-models.mdc` rule, in place of the `arena runners` line. If the rule or that line is missing, use `claude-opus-5-5-xhigh` and `grok-4.7-xhigh-fast`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.
  
  Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape.
  
  Screen every candidate against [`references/design-red-flags.md`](references/design-red-flags.md) before synthesis. Assume the next contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Prefer the design where a change that looks right from one file is right for the whole repo.
  
  Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers.
  
  Arena returns one synthesized design package. The synthesis decision populates the rationale's "Synthesis decision" section.
  
  ## Phase C: Agree (opt-in)
  
  Default: proceed directly to implementation with the synthesized design. No human checkpoint.
  
  Opt in to a checkpoint when the invoker explicitly asks: "/architect with checkpoint," "stop and show me before implementing," or similar. Then surface the synthesized design and pause for sign-off.
  
  The synthesis can ship as its own commit either way, as the "scaffold first" mode of the **foundational-thinking** principle skill. Planned and scoped breakage during fill-in is fine, per the **outcome-oriented-execution** principle skill. For adversarial pressure on the design before implementing, run the **interrogate** skill on the synthesized sketch.
  
  If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence. Re-ground and re-run Phase B before writing more code.
  
  ## Phase D: Implement against the sketch
  
  Replace `not implemented` bodies with code, pseudocode with logic. The synthesized sketch is the contract.
  
  Deviations from the sketch are signal worth surfacing, not friction to absorb silently. If a function needs a parameter the sketch didn't anticipate, ask whether the sketch was wrong, the requirement was missed, or the implementation is overreaching.
  
  ## Phase E: Scrap when the architecture is wrong
  
  If implementation keeps producing friction the sketch can't absorb, throw the sketch out. Don't bolt fixes onto a wrong design, per the **redesign-from-first-principles** and **fix-root-causes** principle skills.
  
  The signal is a *pattern*, not single instances. Tells:
  
  - The same shape of workaround appearing repeatedly across unrelated code.
  - Multiple unrelated edge cases that all need special-case branches.
  - Types that need escape hatches (`any`, casts, optional fields always set in practice) to compile.
  - The "we need a lock" reflex when the sketch said the state wasn't shared.
  - Callers having to know the abstraction's internal rules to use it.
  - Two or more independent Phase D deviations of the same shape across the implementation.
  
  Use judgment. A few edge cases don't condemn an architecture. Some problems are legitimately complex. Complexity in the data is not complexity in the design.
  
  When you scrap:
  
  1. Re-run the **how** skill over what's been built.
  2. Redesign as if the new constraints had been day-one assumptions, per redesign-from-first-principles.
  3. Subtract before adding, per the **subtract-before-you-add** principle skill. The new sketch should be smaller than the old one before it grows.
  4. Return to Phase B and re-run arena.
  
  ## Outputs
  
  The caller's usage is written first and the type sketch derived from it. One file with new types and signatures for small changes. Module map plus type definitions for larger work. The rationale ships alongside, shaped per `references/rationale-template.md`, including the usage sketch and the synthesis decision.
  

• references/design-red-flags.md (2.9 KB)

  # Design red flags
  
  Screen every candidate before synthesis. A red flag is a reason to revise or reject the shape.
  
  ## Shallow module
  
  A shallow module exposes a large interface while hiding little complexity. Judge depth by the capability and policy hidden behind the public surface relative to the size of that surface. Prefer a simple interface backed by substantial behavior.
  
  Do not confuse a deep module with a deep call chain. A deep call chain scatters understanding across layers. A deep module concentrates capability behind one interface.
  
  Look for these signs:
  
  - Callers coordinate several methods to complete one operation.
  - Public options expose internal stages or implementation choices.
  - Learning the interface does not save the caller from learning the implementation.
  
  ## Information leakage
  
  Information leakage makes multiple modules depend on the same internal decision. A representation, policy, or protocol detail appears in more than one place, so changing it requires coordinated edits.
  
  Public re-exports of transport or wire types are leakage. Parse external data into domain types behind the interface. Keep storage schemas, framework objects, and protocol details private.
  
  ## Temporal decomposition
  
  Temporal decomposition organizes modules by execution order instead of the knowledge they own. Separate load, validate, transform, and save stages often repeat one representation and its invariants across several boundaries.
  
  Group code around domain knowledge and ownership. Methods that run at different times can still belong to one module when they protect the same decisions.
  
  ## Pass-through method
  
  A pass-through method forwards the same arguments to another method with the same shape. It adds a layer without hiding complexity.
  
  Remove it or move responsibility to the module that can complete the operation. Keep a forwarding boundary only when it adds policy, adaptation, or a distinct abstraction.
  
  ## Split ownership
  
  More than one module writes the same state or keeps its own copy of it. An agent that edits one writer can't see the others, so their rules diverge.
  
  Give each piece of state one owner. Other modules read it or ask the owner to change it.
  
  ## Two ways to do one task
  
  The design supports more than one way to do the same task. An agent copies whichever way it finds first, so every way keeps gaining callers.
  
  Keep one way. Move callers off the others and delete them in the same change.
  
  ## Importable internals
  
  A caller can import a module's internals. An agent takes the shortest path that compiles, so it imports them directly and they become part of the interface.
  
  Make internals unreachable from outside the module, so an import from outside fails the build.
  
  ## Hand-synced list
  
  Two or more places list the same items, and adding an item means editing every list. An agent that sees one list updates only that one.
  
  Keep one list and derive the others from it. If a list can't be derived, make the build fail when the lists disagree.
  

• references/rationale-template.md (3.0 KB)

  # Rationale template
  
  The prose that ships alongside the type sketch. One page. Sentence-case headings, no boilerplate. Replace the italic notes with actual content.
  
  ## Problem
  
  *One paragraph. What we're trying to do, and what about the existing system or constraints makes the shape non-obvious. If [Phase A](../SKILL.md#phase-a-ground-the-problem) surfaced constraints the design must honor (existing types to interop with, callers we can't break, invariants that crossed our boundary), name them here so the reader sees the same constraints you saw.*
  
  ## Usage (caller's view)
  
  *Write this first, before the type sketch. Show the README or quickstart the consumer reads, plus two or three realistic call sites in their own code. What they import, what they call, what comes back. The type sketch in [Shape](#shape) is derived from this. The two must agree. When they diverge, reconcile the sketch to the usage, not the reverse. The caller's experience is the spec. The types serve it.*
  
  ## Shape
  
  *The recommended architecture. Data structures first. Then how data flows through the signatures. Name the load-bearing decisions. State which invariants are encoded in types, where validation lives, and what the system deliberately does not do. Judge interface depth explicitly. State what complexity the public surface hides, what remains exposed to callers, and why the interface is no larger than needed. Cite the principle behind each decision (e.g., `per boundary-discipline`). Don't restate it.*
  
  ## Synthesis decision
  
  *Filled in by [arena](../../arena/SKILL.md). Records which candidate became the base and why, what was adapted from each of the others, and what was rejected and why.*
  
  ## Tradeoffs accepted
  
  *One bullet per tradeoff the chosen shape makes. Form: "we accept X in exchange for Y." Name anything a future reader might mistake for an oversight, including things that look like premature optimization or premature simplification.*
  
  ## Alternatives considered
  
  *Required. Name at least one concrete alternative shape, with one line on why it lost. Judge each alternative on interface depth, not implementation simplicity alone. Name the complexity it exposes to callers and the complexity it hides. Two or three alternatives belong here when the design space had real contenders. One is fine when the constraints forced the answer, with the conclusion phrased as "this was the only viable shape because..." Avoid listing flavors of the same shape. This section covers design alternatives the chosen shape considered and rejected, not other runner candidates.*
  
  ## Open questions and risks
  
  *Things you noticed during the sketch that the human needs to weigh in on, and risks worth flagging before implementation starts. Phrase as questions, not assertions, so the human's answer is the resolution rather than a comment.*
  
  ## Next implementation step
  
  *The first thing to build against the sketch. One sentence. What you'd start writing immediately after synthesis (or after Phase D sign-off, if a checkpoint was opted into).*
  

• references/runner-prompt.md (3.0 KB)

  # Architect runner prompt
  
  The orchestrator passes this file through to every parallel candidate runner during Phase B and fills in the variable inputs around it: the task, the Phase A grounding artifacts, the isolated working directory, and the path to write outputs. The working directory is a git worktree when available, otherwise a per-runner subdirectory under the sketch dir. What matters is independence between candidates.
  
  You are producing one candidate design in architect's parallel exploration. Read the **architect** skill in full first. That's the workflow you're inside. Output a candidate design package: type sketch, function signatures, module map, and prose rationale shaped per [`rationale-template.md`](rationale-template.md).
  
  Apply the following discipline. The orchestrator compares candidates on these axes to pick a base.
  
  - Caller's usage first. Write the README-style usage and two or three real call sites before the types, then derive the type sketch from them. The usage is the spec. The two must agree, so reconcile the sketch to the usage, not the reverse.
  - Data structures first. Get the core types right and the code becomes obvious. Trace each dominant access pattern through the proposed structure. If the answer is "we'll add a map / index / cache later," the structure is wrong.
  - Interface depth. Compare the capability hidden behind the public surface relative to the size of that surface. Prefer a simple interface that pulls complexity into the callee, even when the implementation becomes less simple. Do not put transport or wire types on the public API. Parse into domain types behind the interface.
  - Shared state: if two actors might both write, ask "what happens?" If the answer isn't "nothing," default to per-actor state with a merge at the read boundary, per the **separate-before-serializing-shared-state** principle skill.
  - Make boundaries visible. `not implemented` errors for bodies, `// TODO` pseudocode for tricky logic, doc comments stating intent and invariants. A reader should trace data from input to output by reading types and signatures alone.
  - Encode invariants in types: hard-to-misuse types > runtime checks > prose comments, per the **encode-lessons-in-structure** principle skill.
  - Validate at boundaries, trust types inside, per the **boundary-discipline** principle skill. Business logic as pure functions. The shell stays thin.
  - Single source of truth per invariant. Derive instead of sync.
  - Idempotent state transitions where applicable, per the **make-operations-idempotent** principle skill. Ask what happens if the operation runs twice or crashes halfway.
  - Short call chains. If tracing the flow needs more than three files, flatten the hierarchy, per the **laziness-protocol** and **minimize-reader-load** principle skills.
  
  You are one of the parallel runners, each on a different model. Produce the best design your model can make. Don't hedge against the others. Differences between candidates are the signal used to pick a base and graft. Converging on a safe-looking middle defeats the exploration.
  

claude:hooks

• herdr-agent-state.sh (3.0 KB)

  #!/bin/sh
  # installed by herdr
  # managed by herdr; reinstalling or updating the integration overwrites this file.
  # add custom hooks beside this file instead of editing it.
  # HERDR_INTEGRATION_ID=claude
  # HERDR_INTEGRATION_VERSION=10
  
  set -eu
  
  action="${1:-}"
  hook_input_file="$(mktemp "${TMPDIR:-/tmp}/herdr-claude-hook.XXXXXX")" || exit 0
  trap 'rm -f "$hook_input_file"' EXIT HUP INT TERM
  cat >"$hook_input_file" 2>/dev/null || true
  
  case "$action" in
    session) ;;
    *) exit 0 ;;
  esac
  
  [ "${HERDR_ENV:-}" = "1" ] || exit 0
  [ -n "${HERDR_SOCKET_PATH:-}" ] || exit 0
  [ -n "${HERDR_PANE_ID:-}" ] || exit 0
  command -v python3 >/dev/null 2>&1 || exit 0
  
  HERDR_ACTION="$action" HERDR_HOOK_INPUT_FILE="$hook_input_file" python3 - <<'PY'
  import json
  import os
  import random
  import socket
  import time
  
  source = "herdr:claude"
  action = os.environ.get("HERDR_ACTION", "")
  pane_id = os.environ.get("HERDR_PANE_ID")
  socket_path = os.environ.get("HERDR_SOCKET_PATH")
  hook_input_file = os.environ.get("HERDR_HOOK_INPUT_FILE")
  
  if not pane_id or not socket_path:
      raise SystemExit(0)
  
  hook_input = {}
  if hook_input_file:
      try:
          with open(hook_input_file, encoding="utf-8") as handle:
              content = handle.read()
          if content.strip():
              hook_input = json.loads(content)
      except Exception:
          hook_input = {}
  
  if "CURSOR_VERSION" in os.environ or "cursor_version" in hook_input:
      raise SystemExit(0)
  hook_event_name = str(hook_input.get("hook_event_name") or "")
  if hook_event_name != "SessionStart":
      raise SystemExit(0)
  is_subagent = bool(hook_input.get("agent_id"))
  if is_subagent:
      raise SystemExit(0)
  request_id = f"{source}:{int(time.time() * 1000)}:{random.randrange(1_000_000):06d}"
  report_seq = time.time_ns()
  session_id = hook_input.get("session_id")
  agent_session_id = session_id if isinstance(session_id, str) and session_id else None
  transcript_path = hook_input.get("transcript_path")
  agent_session_path = transcript_path if isinstance(transcript_path, str) and transcript_path else None
  session_start_source = hook_input.get("source") if hook_event_name == "SessionStart" else None
  if not isinstance(session_start_source, str) or not session_start_source:
      session_start_source = None
  if agent_session_id:
      params = {
          "pane_id": pane_id,
          "source": source,
          "agent": "claude",
          "seq": report_seq,
          "agent_session_id": agent_session_id,
      }
      if agent_session_path:
          params["agent_session_path"] = agent_session_path
      if session_start_source:
          params["session_start_source"] = session_start_source
      request = {
          "id": request_id,
          "method": "pane.report_agent_session",
          "params": params,
      }
  else:
      raise SystemExit(0)
  
  try:
      client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
      client.settimeout(0.5)
      client.connect(socket_path)
      client.sendall((json.dumps(request) + "\n").encode())
      try:
          client.recv(4096)
      except Exception:
          pass
      client.close()
  except Exception:
      pass
  PY
  

claude:keybindings.json

• keybindings.json (346 B)

  {
    "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
    "$docs": "https://code.claude.com/docs/en/keybindings",
    "bindings": [
      {
        "context": "Global",
        "bindings": {
          "escape": null
        }
      },
      {
        "context": "Chat",
        "bindings": {
          "escape": null
        }
      }
    ]
  }

codex:rules

• default.rules (2.5 KB)

  prefix_rule(pattern=["pi", "--print", "--no-session", "--no-extensions", "--no-skills", "--no-prompt-templates", "--tools", "read,grep,find,ls", "@/tmp/pi-recent-sessions-brief.md"], decision="allow")
  prefix_rule(pattern=["node", "/home/semihmutlu/dev/summer-2026/presentation/verify.cjs"], decision="allow")
  prefix_rule(pattern=["node", "/home/semihmutlu/dev/summer-2026/yaz-masasi/verify.cjs"], decision="allow")
  prefix_rule(pattern=["codex", "--version"], decision="allow")
  prefix_rule(pattern=["/home/semihmutlu/.local/share/mise/installs/codex/0.158.0/bin/codex", "doctor"], decision="allow")
  prefix_rule(pattern=["omarchy-shell", "media", "status"], decision="allow")
  prefix_rule(pattern=["python", "/tmp/fix-default-codex.py", "--apply"], decision="allow")
  prefix_rule(pattern=["bash", "/tmp/omarchy-widget-upgrade/install-media.sh"], decision="allow")
  prefix_rule(pattern=["omarchy", "pkg", "add", "gnome-calendar", "gnome-online-accounts-gtk"], decision="allow")
  prefix_rule(pattern=["systemctl", "--failed", "--no-pager"], decision="allow")
  prefix_rule(pattern=["ps", "-eo", "pid,ppid,stat,pcpu,pmem,rss,etime,comm", "--sort=-pcpu"], decision="allow")
  prefix_rule(pattern=["/usr/bin/bash", "-lc", "herdr status; herdr workspace list; herdr api snapshot; herdr session list; herdr pane read --help; herdr pane process-info --help; herdr --version; /usr/bin/time -f 'snapshot_elapsed=%e' herdr api snapshot >/dev/null"], decision="allow")
  prefix_rule(pattern=["/usr/bin/bash", "-lc", "for pane in w7X:p1 w84:p1 w85:p1 w86:p1; do herdr pane process-info --pane \"$pane\"; herdr pane read \"$pane\" --lines 22 --format text; done; for attempt in 1 2 3; do time herdr workspace list >/dev/null; done; vmstat 1 4; ps -eo pid,ppid,stat,pcpu,pmem,rss,etime,comm --sort=-pcpu | head -15"], decision="allow")
  prefix_rule(pattern=["herdr", "status"], decision="allow")
  prefix_rule(pattern=["omarchy-shell", "shell", "listPlugins"], decision="allow")
  prefix_rule(pattern=["env", "OMARCHY_PATH=/usr/share/omarchy", "omarchy-shell", "shell", "listPlugins"], decision="allow")
  prefix_rule(pattern=["env", "OMARCHY_PATH=/usr/share/omarchy", "omarchy-shell", "semihmutlu.ghost", "probe"], decision="allow")
  prefix_rule(pattern=["grim", "/tmp/ghost-desktop-audit-20261012.png"], decision="allow")
  prefix_rule(pattern=["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=8", "-o", "StrictHostKeyChecking=yes", "desktop", "hostname; omarchy version; omarchy theme current; fc-match sans-serif; fc-match serif; fc-match monospace"], decision="allow")
  

cursor:hooks

• global-rules.sh (307 B)

  #!/bin/bash
  # Injects ~/.cursor/rules/*.mdc bodies as session context (CLI ignores ~/.cursor/rules).
  cat >/dev/null
  body=$(for f in "$HOME"/.cursor/rules/*.mdc; do awk 'BEGIN{n=0} /^---$/{n++; next} n>=2' "$f"; done)
  jq -n --arg c "User global rules (from ~/.cursor/rules):
  $body" '{additional_context:$c}'
  

cursor:rules

• global.mdc (1.0 KB)

  ---
  description: Semih global rules
  alwaysApply: true
  ---
  - Start every nontrivial task with /poteto-mode (skill poteto-mode) and pick the matching playbook.
  - Never block on the human for reversible work: do it, verify it, show proof. Ask only before irreversible or external actions (publish, send, buy, deploy, delete).
  - Resuming work: use session-pickup. Stopping: use pause-safely.
  - Do not change model or routing settings.
  - Canary word: KIRAZ-370.
  
  ## Notion workspace
  
  When working with the user's projects, tasks, notes or
  persistent knowledge, first read:
  
  https://app.notion.com/p/3f84b6f58b3b8154a46ddd4bb6605958
  
  Use the existing Notion databases defined there.
  
  - Search before creating anything.
  - Prefer updating an existing record.
  - Do not save every conversation automatically.
  - Keep code and raw execution logs in their original sources.
  - Never delete, merge, or move records without approval.
  - Verify Notion writes before reporting completion.
  
  If Notion MCP is unavailable, report the limitation.