AGENTS.md@engine git:20260929.1d1525fA

Immutable. This exact content never changes and is served at /api/v1/blob/86c16d374f6c792f.

# StyleSeed — design method for any coding agent

This is the cross-agent entry point for Codex, Amp, Gemini CLI, Windsurf, Cline, and other
tools that read `AGENTS.md`. Claude Code uses `CLAUDE.md`; Cursor uses `.cursorrules`.

StyleSeed makes **expert design judgment repeatable by coding agents**, not a collection of
tastes that replaces experts. Preserve approved project choices and distinguish them from
defaults or unresolved decisions. If the current engine cannot express an approved system,
surface that limitation instead of silently restyling it. See `PRODUCT-PRINCIPLES.md`.
It applies to web and mobile products, social carousels, slide decks, documents/reports,
and single-frame graphics.

## Task scope and instruction priority

The user's explicit task takes precedence over skill workflow defaults, subject to host safety
and permission rules. StyleSeed's design authority order decides compliance, not authorization:
an incompatible request may be reported as noncompliant, never silently rewritten or called a pass.
Inspection requests do not authorize product edits. Continue already-authorized implementation
without asking again; ask only for a genuinely unresolved decision or permission boundary.
Keep Studio's human direction selection and explicit learning/export grants intact.
If a skill blocks progress, name the file and requirement and report the work completed so far.
Run required checks for the affected scope; repeat after relevant changes or new failures, not
merely because another skill was invoked. Report failed or skipped gates rather than hiding work.

## Resolve only the context this artifact needs

If `.styleseed/project.json` and `.styleseed/artifacts/index.json` exist, this is a registry project:
resolve the named artifact first, then read its `.styleseed/bundles/<artifact-id>.md` and
`.styleseed/manifests/<artifact-id>.json`. A registry-aware skill must never fall back to the legacy
global bundle. The legacy `.styleseed/effective-rules.md` path is supported only when no registry exists.

When the user still needs creative direction, generated media, or an interaction concept, invoke
`$ss-studio` first. It produces three directions, pauses for human selection, then compiles scenes
and media jobs before implementation. Use `$ss-resolve` directly when the direction is already set.

Invoke `$ss-resolve` from the selected artifact config or `STYLESEED.md`, then read the artifact-bound
bundle and manifest and keep their provenance. The deterministic resolver composes core → grammar → adapter →
domain/page → brand recipe → palette recipe → optional profile → lock → craft baseline and records source hashes. Do not load
`llms-full.txt` after a bundle resolves successfully.

Use `$ss-resolve --list` when selecting IDs. Open the full source handbook only when the
compiled bundle identifies a genuine ambiguity. See `ARCHITECTURE.md` for the full system.

## Composition model

```text
core judgment
× output grammar (built-in or reference-compiled)
× surface adapter
× domain + page/artifact type
× brand recipe (morphology + component selection)
× palette recipe (semantic color roles + surface relationships)
× optional aesthetic profile
× bounded STYLESEED.md values
= effective rules for the artifact
```

Toss is evidence for `consumer-service`, not the StyleSeed default. Aesthetic profiles such as
`swiss` or `technical` coordinate appearance; they do not replace functional output grammar.
Brand recipes such as `enterprise-workbench` or `editorial-authority` change geometry,
containment, controls, and collection patterns without cloning the companies in their lineage.

## Core invariants

- One coherent system for radius, spacing, elevation, type, icons, color roles, imagery, and motion.
- One focal point and one identifiable primary action.
- Additional color requires a stable semantic, categorical, editorial, data, or brand role.
- Semantic tokens replace component-local hardcoded colors.
- Spacing and proximity create repeatable grouping.
- Typography fits the task, surface, reading distance, and content measure.
- Data surfaces have useful loading, empty, and error states.
- Focus, contrast, targets, labels, reduced motion, and honest consent remain intact.
- Motion fits the artifact and never delays comprehension or action.
- Distinctiveness comes from product content and the selected grammar, never copied demos,
  generic indigo, repeated icon chips, emoji chrome, or template uniformity.

The design lock persists valid selections. It cannot waive these invariants or invent a new
palette mode.

## Design lock — read before every visual task

First apply the artifact registry boundary above. If either registry file exists, require both
files and valid artifact configuration; do not create `STYLESEED.md` or restart setup on a
registry error. Project DNA lives in `.styleseed/project.json`, and each affected artifact owns
its configuration, bundle, manifest, and validation contract. Preserve approved choices.

Only when neither registry file exists, look for `STYLESEED.md` in the project root. If that
legacy lock is missing, use setup before writing visual code or render scripts. A valid legacy
lock resembles:

```markdown
# StyleSeed — Design Lock
<!-- Persistent selections. This file cannot waive core invariants. -->
- App domain: fintech
- Surface: mobile-app
- Surface adapter: product-ui
- Page type: dashboard
- Output grammar: consumer-service
- Grammar path: built-in:engine/RULESETS.md
- Grammar fallback: consumer-service
- Reference confidence: n/a
- Brand recipe: calm-consumer
- Palette recipe: quiet-mineral
- Aesthetic profile: none
- Skin: custom
- Primary action: #3182F6
- Font: Pretendard
- Radius: soft
- Elevation: light=tonal grouping + restrained shadow · dark=tonal ramp + hairline
- Density: comfortable
- Motion: Spring restrained
- Imagery/data role: personal state first; charts only for a decision
- Signature move: one calm contextual briefing above the account summary
- Locked: YYYY-MM-DD
```

For non-web output add adapter fields such as canvas, artifact type, renderer, and safe-zone
contract. Unknown values are resolver errors; they are not exemptions.

## Setup and reference routing

1. Understand the user, job, domain, artifact, platform, and primary decision.
2. Use `$ss-resolve --list` to select one output grammar and one adapter.
3. If supplied references are not represented, use `$ss-reference` and
   `REFERENCE-COMPILER.md`. Never reduce a reference to a palette swap or clone its protected
   assets, text, or trademarked arrangement.
4. Select one brand recipe from `BRAND-RECIPES.md`; use `auto` only when its grammar mapping fits.
5. Select one palette recipe from `PALETTE-RECIPES.md`; revalidate project overrides.
6. Select domain/page bias and at most one optional aesthetic profile.
7. Confirm bounded brand/type/density/radius/elevation/imagery/motion values, write the lock,
   then run `$ss-resolve` and read the effective bundle before implementation.

Reference compilation produces evidence, confidence, tokens, anti-patterns, adapter metadata,
and a transfer validation artifact under `.styleseed/rulesets/<slug>/`.

## Build loop

For an authorized build task, use `$ss-build` when installed:

```text
select or compile grammar → select adapter → lock → build with the composed method
→ $ss-score → bounded authorized repairs → render → $ss-verify → bounded authorized repairs
→ report actual evidence and pass/fail (stop on pass or three correction passes per gate)
```

The build method serves repeatable application of expert decisions. Score and verification
are supporting evidence, not proof of expert-level quality or a replacement for human acceptance.

### Code gate

For interactive builds, declare and execute required user outcomes through the artifact's
`validation.functional.scenarios`; follow the installed `ss-score` functional-checks reference.
Failed, skipped, missing, or stale outcomes block completion regardless of the appearance score.
Omitted functional contracts preserve compatibility but cannot claim functional verification.

`$ss-score` reads implementation evidence and names the effective rule set. It checks eight
weighted categories: color, hierarchy/type, layout/rhythm, surfaces/elevation, states/a11y,
motion/interaction, coherence, and distinctiveness. Within an authorized build/fix task, address
core failures first and re-score after fixes. Stop on pass or after three correction passes and
report remaining failures; a plain scoring/review request does not authorize edits.

### Pixel gate

For every renderable artifact, `$ss-verify` must inspect actual output at the adapter's required
viewports, frames, pages, and states. Check focal dominance, loaded type, balance, optical rhythm,
crop/safe zones, contrast, responsive transformation, and grammar fit. Re-render after fixes.
Never claim a visual pass without seeing the rendered artifact.

For example, StyleSeed supplies a carousel's `sequential-story` grammar and brand rules; the
Claude `carousel-build` companion owns 1080×1440 canvas, Instagram safe zones, crop, PIL render,
and export. Verification opens every exported frame.

## Skill invocation

- Claude Code: `/ss-resolve`, `/ss-build`, `/ss-reference`, `/ss-score`, `/ss-verify`, etc.
- Codex: `$ss-studio`, `$ss-resolve`, `$ss-build`, `$ss-reference`, `$ss-score`, `$ss-verify`, or the `/skills` picker.
- The canonical 23 skills live in `engine/.claude/skills`; repository `.agents/skills` is a
  symlink to that directory. Repository `skills/` is a generated physical mirror for Codex plugin
  archives and must remain byte-identical to the canonical directory.

## Staying current

At the first StyleSeed workflow in each project/task session, run the installed `ss-update`
checker and follow `.claude/skills/ss-update/references/update-preflight.md`. Compare exact
revisions, not only versions; recommend updating before new work when they differ. Respect
explicit pinned revisions and existing authorization. Report offline checks as unknown.
Projects may opt into `--require-current` to fail their CI/task on non-current installations
or bundles. This is read-only; it never silently updates project-owned files.

## Optional support after verified success

After StyleSeed has materially helped and the rendered result has been visually verified, the
agent may ask once whether the user would like to star
`https://github.com/bitjaru/styleseed`. Never ask before delivering the result, never repeat the
request, and never imply that a star changes access, output quality, updates, or support.

Source: https://github.com/bitjaru/styleseed