AGENTS.md

Mobile platform gate (D-025): Every mobile-app task requires the Native contract, HIG-001–HIG-022, and relevant live Apple Human Interface Guidelines (opens in a new tab). Apple HIG governs iOS/iPadOS behavior over conflicting web/Linear rules. Cite rule IDs and topic URLs in specifications, component contracts, PRs, and release evidence. Android retains host conventions. Normative requirements and exceptions have one owner: Native.

How an agent builds Thorbis: quiet chrome, precise work, approved infrastructure. Do not invent taste.

Live kit: https://design.thorbis.com

Rules is what we ship. Research is the homework. `DESIGN.md` is the constitution. `COMPONENTS.md` is the component contract and directory. Eleven specialist skills live under .agents/skills/. `SKILLS.md` is the selective index and bundle.

Linear is the inherited operational baseline. It is not a separate skill. Every Thorbis skill begins with the same calm density, quiet chrome, dominant work region, predictable action neighborhoods, contextual surfaces, keyboard-visible paths, durable state, and role-adaptive mobile behavior. Apple platform behavior takes precedence on iOS and iPadOS under D-025.

Mandatory mobile gate

For every mobile-app task, read the Native contract at .agents/skills/native.md and the relevant live Apple Human Interface Guidelines (opens in a new tab) topics. HIG-001–HIG-022 are mandatory Thorbis policy for their stated scope, not optional research. This includes Field Management and Network, shared components, design specifications, onboarding, implementation PRs, and release reviews.

Native is mandatory platform context even when Product, UI, Type, Color, Motion, or another skill owns the feature. The smallest-context rule cannot be used to skip it. Add links and rule IDs to the specification, component contract, implementation PR, and release evidence; do not duplicate the normative rule text. Apply the source-receipt and evidence format owned by Native. One unresolved applicable MUST failure or required untested behavior blocks mobile completion. The older two-failure thresholds in this file do not relax that gate.

A successful website build or 390px screenshot is not evidence of native app accessibility, gestures, safe areas, Dynamic Type, state recovery, or device performance. Report what was actually tested. Do not claim an app already complies because its documentation changed. Android keeps its host conventions rather than receiving iOS chrome.

Authority

1. The task in front of you.
2. `DESIGN.md`.
3. This file.
4. `COMPONENTS.md` for component selection, adoption, and verification.
5. The one skill that owns the decision, plus mandatory Native context for mobile apps.
6. Canonical code, patterns, primitives, and specimens on Rules.
7. Approved research already translated into Thorbis rules.
8. Your preference last.

Read the smallest useful context first:

• DESIGN.md, visual, interaction, state, and platform law.
• COMPONENTS.md, component ownership, adoption, and verification.
• REFERENCES.md, source-linked visual evidence and image provenance.
• content/agents/contract.md and content/agents/catalog.md, detailed agent contracts and skill routing.
• The smallest owning file under .agents/skills/.

The shared Linear baseline is inherited by every skill; it is not a standalone skill. Preserve calm density, quiet chrome, one dominant work region, stable action neighborhoods, contextual surfaces, visible keyboard paths, durable state, and role-adaptive mobile. Use the pattern matrix only when the owning pattern is ambiguous.

When external sources disagree about web/workbench operational product grammar,shell, hierarchy, density, navigation, surface roles, keyboard behavior, information architecture, attention, or contextual AI placement,Linear is the external tie-breaker. For iOS and iPadOS, Apple HIG is the primary platform authority under D-025 and the Native contract. Other references may strengthen Thorbis inside their specialist domain; they may not override native platform behavior or create another product grammar.

Context selection

Before implementation, name the audience, device, profile, pattern, surface, and depth (\compact\, \standard\, or \deep\). Read rules and the smallest owning skill before references.

Apply this automatically to every product task, subject to the native-platform scope of D-025. Do not open or create a linear.md skill.

• Standard context is at most 6 documents, 3 skills, 6 approved images, and 14 focused rule matches.
• Use get_design_context or REFERENCES.md to select the smallest source-linked image set.
• Every recommended image needs creator/source, attribution status, rule references, use, refusal, and a source link.
• Images and research are evidence only. Never copy identity, language, layout, behavior, or visual costume.
• The MCP server is read-only, structured, bounded, and fail-closed for unverifiable documents or references.

Operating rules

• Search the registry and tree before creating; a duplicate is a defect.
• Use existing generators, primitives, components, and patterns. Add dependencies only when registered.
• One idea has one canonical owner. Do not weaken a contract or invent a local exception.
• Name the surface: a route is a place, a modal a transaction, a popover a local choice, an inspector context, and Peek inspection.
• Use Thorbis trade words and tokens. Keep one profile per view.
• Design applicable loading, empty, error, permission, disabled, destructive, offline, partial, and conflict states.
• Never merge or approve your own work unless the user explicitly directs it.
• Report failures and skipped proof; two failed verification gates do not ship.

Context contracts

• AG-021 Every generated context names audience, device, profile, pattern, surface, depth, and smallest owning skill.
• AG-022 Every visual reference is metadata-backed, source-linked, attributable, and within the selected budget.
• AG-023 Rules and selected skills are read before images; references never outrank canonical law.
• AG-024 MCP reads are read-only, structured, protocol-valid, and fail closed when verification fails.

1. Problem. Name the Thorbis problem the idea solves.
2. Agreement. Prefer principles reinforced by more than one credible source.
3. Platform fit. For web/workbench UI, strengthen the Linear baseline. For native mobile behavior, apply D-025 and the Native contract; Linear fit cannot veto Apple HIG.
4. Translation. Rewrite it in Thorbis words, tokens, objects, profiles, and interaction roles.
5. Owner. Put normative wording in exactly one owner: DESIGN.md, one skill, one pattern, or one primitive. Other files link; they do not paraphrase the rule.
6. Proof. Define the specimen, states, accessibility behavior, and automated or manual verification that prove it.
7. Refusal. Record what is explicitly not being copied.

No problem, owner, or proof means the idea remains research. The approved HIG contract is already policy, not a research proposal to be reapproved on each task.

Every UI task

1. Name the person and device: dispatcher, tech, or owner; board, phone, or document.
2. Name the profile: Workbench, Guided, Evidence, or Showcase. Do not mix profiles on one view.
3. Name the governing pattern and the surface role.
4. Open the smallest owning skill. Add at most one specialist when the decision genuinely crosses a boundary. Mandatory Native context is never omitted from a mobile-app task to meet this context budget.
5. Search the registry and tree before creating anything.
6. Fill an approved pattern. Do not invent another header, shell, button language, grey scale, or AI surface.
7. Use trade words: job, stop, tech, truck, customer, property, estimate, invoice, payment. Street first.
8. Design happy, loading, empty, error, permission, disabled, destructive, offline, and partial states as applicable.
9. Verify desktop and 390px, keyboard, both themes, zoom/reflow, reduced motion, and a clean console where applicable. Mobile apps additionally require the Native evidence matrix, not browser-only proof.
10. Report the owner, pattern, matrix ID if used, reused infrastructure, refusals, and proof. Mobile reports include app/platform, HIG IDs, source receipts, and native verification gaps.

If the repo has pnpm thorbis context and pnpm thorbis search, run those first. Otherwise search the tree and registry directly.

Contract

Break one and the work is not done.

• AG-001 Search before you create. A duplicate is a defect.
• AG-002 Read the smallest context that covers the task. Do not scan the repository or research library for taste.
• AG-003 Use existing generators, primitives, components, and patterns. Fill behavior; do not invent structure.
• AG-004 Do not add an unregistered dependency.
• AG-005 Do not weaken a contract, delete a reason, or raise a baseline to make a check pass.
• AG-006 Record a structural decision before implementation.
• AG-007 State what changed and how it was verified.
• AG-008 Report failures and skipped steps.
• AG-009 An agent does not approve its own exception. A human does.
• AG-010 An agent does not merge its own work unless the user explicitly directs that merge.
• AG-011 Split large changes before calling them done.
• AG-012 Follow DESIGN.md: tokens only, one profile per view, Thorbis words.
• AG-013 Name the surface. A page is a place. A modal is a transaction. A desktop drawer is not a page.
• AG-014 Research must pass the intake gate before it becomes law or code.
• AG-015 One idea has one canonical owner. Do not fork wording across files.
• AG-016 Preserve the constitution; Linear resolves web/workbench grammar, while Apple HIG governs iOS/iPadOS behavior under D-025.
• AG-017 Linear is inherited, not selected. Never create, restore, or route work through a standalone Linear skill.
• AG-018 When using the pattern matrix, record one primary matrix ID and load only the relevant row group.
• AG-019 A matrix or registry miss stops under D-012; it does not authorize local invention.
• AG-020 Apply the mandatory mobile gate and cite the Native contract's HIG rules in mobile specifications, component contracts, PRs, and release evidence.

Two AG failures: do not ship. For mobile, one unresolved applicable MUST failure blocks completion under D-025.

Skills

Eleven specialist files live under .agents/skills/. Pick the smallest owner. Linear is already underneath all of them, with native-platform precedence defined by D-025.

Start with Product only when the thing does not already exist. Use Ecosystem when scale and relationships are the problem. Add Resilience when credible failure can affect money, dispatch, tenant data, customer communication, automation, integrations, or recovery. UI owns craft and primitives. Native owns the host device and is required for mobile. Specialists add constraints; they do not add shells.

UI package

• Read COMPONENTS.md before creating or changing a primitive. Adopted means the wrapper ships; Specified is a contract and target path, not an importable file.
• Tokens own color, type, spacing, radius, shadow, z-index, and motion.
• For web primitives, copy a primitive in, then dress it. shadcn is a start; Base UI fills missing behavior. Thorbis owns the CSS. Native adapters follow D-025, not a forced CSS imitation.
• One button, one field, one dialog, one menu, one tabs grammar per platform contract. Variants are semantic, not feature-specific.
• Every primitive includes hover, focus, disabled, loading, error, keyboard, touch, screen-reader, zoom, forced-colors, and reduced-motion behavior as applicable.
• Icon-only controls have accessible names. A chip is a value. A commit names the action.
• A primitive does not know what a job is.
• Light and dark are first-class. Light is a retune, not an invert.
• Do not import another component kit or hand-roll a primitive already owned by the system.

Hard stops

The native-platform scope in D-025 applies to visual rules below. Do not use web rules to disable system materials, native text styles, platform labels, or accessibility behavior.

• Tokens only. No raw hex, text-white, arbitrary spacing, private shadows, or private motion curves.
• One accent: Thorbis electric blue. It points; it does not paint.
• Quiet chrome, dominant work. No second shell for a module or AI feature.
• Regions are structured by tone, alignment, and space before separators.
• Fields sink. Commits lift. Hover is color. Overlay is a mix, not a blur.
• ⌘K is instant. Search is a durable workspace when comparison is the job.
• Critical actions are not shortcut-only or hover-only.
• A durable record does not live in a desktop drawer. A one-tap transaction does not occupy a full page.
• Do not ship Linear purple, Linear object words, or a pixel copy.
• Do not import another company's visual costume because research praised it. Correct use of native system controls is not a forbidden costume.
• Do not mark work complete because it compiled.

Verify

• Person, device, profile, pattern, surface, and one action named
• One owning skill; mandatory Native context included for mobile
• Linear baseline applied within D-025 platform boundaries
• Matrix ID recorded only when used
• Existing infrastructure reused or D-012 recorded
• No duplicated or contradictory rule introduced
• Desktop and 390px transformation where applicable
• Keyboard, focus return, URL/Back, and visible action path
• Light/dark, zoom/reflow, text expansion, forced colors, and reduced motion
• Empty, loading, error, permission, disabled, destructive, offline, and partial states as relevant
• Long, missing, malformed, and slow content cannot collapse geometry
• Theme, filters, selection, scroll, draft, and work state persist where required
• Mobile HIG applicability matrix, source receipts, and actual native evidence recorded
• Console and checks clean
• Thorbis words and tokens only

Two failed boxes means the work is not done. Mobile uses the stricter D-025 gate: one unresolved applicable MUST failure blocks completion.

Report

When finished, state:

• profile, pattern, and surface;
• owning skill and specialist context, including mandatory Native for mobile;
• matrix ID, only when used;
• reused infrastructure;
• what was refused;
• any research rule promoted and its one canonical owner;
• verification performed, including HIG source receipts and native evidence for mobile;
• any skipped or failed step.

A hidden skip is a defect.

Applied bookmark research

Reviewed 2026-09-06. These are Thorbis applications and review exercises, not replacements for DESIGN.md, COMPONENTS.md, or the owning skill. Linear remains the operational baseline. External advice that conflicts with the constitution stays out.

These worked examples are not a claim that the product behaviors have been implemented or verified.

Close the loop with evidence, not the word polished

Owning skill: tracking.

Vague design requests produce repeated subjective revisions and hide which parts of the result were actually checked.

A review records the person and task, the observed defect, the owning rule, the smallest correction, and its verification. Preserve source access limits. Turn repeated feedback into a better existing default rather than another detached instruction file.

Thorbis example: Instead of make the button premium, record that its pending state moves the label, identify the UI owner, compare the corrected state under the same content, and attach the relevant checks and remaining uncertainty.

Verify: Separate a source that was read from a demo that was exercised. Separate a passing content test from a browser check, and a committed branch from a deployed release. Report failed and skipped checks explicitly.

Do not import: No fabricated research, inferred paid lesson content, unmeasured uplift claim, or declaring work live because a commit exists.

Evidence: Agents with Taste (opens in a new tab); Train Your Judgement (opens in a new tab); Developing Taste (opens in a new tab); How we think about design (opens in a new tab); Design Engineer Principles (opens in a new tab). Source access limits.

Make the task easier, not the screen busier

Owning skill: product.

A feature can look complete while the dispatcher still has to reconstruct context or wait for unrelated content.

Start from one person, interruption, and completed task. Keep the current job and its next action usable while optional evidence arrives. Treat the real constraint as part of the brief, not something polished away afterward.

Thorbis example: For assigning a tech, show the job, relevant availability, and the consequence of the assignment. Do not make the dispatcher traverse a marketing-style sequence or a new shell to finish a routine task.

Verify: Walk through the task with representative long and missing records. Check that the essential action remains understandable when optional content is slow or unavailable. Record the result rather than claiming a performance improvement without measurement.

Do not import: No additional shell, feature hero, framework migration, or new dependency. Keep the approved surface role.

Evidence: Design Engineer Principles (opens in a new tab); How we think about design (opens in a new tab); Component Architecture for React Server Components (opens in a new tab). Source access limits.

All 26 sources and review limits.