# AGENTS

This repository allows sub-agent delegation for parallel implementation work.

## Default Sub-Agent Configuration

When spawning sub-agents for this repo:

- model: `gpt-5.4`
- reasoning effort: `xhigh`

## Context Strategy

Sub-agents should use this context policy:

1. First attempt with `fork_context: true`
2. If the sub-agent fails due to context-window pressure, retry with `fork_context: false`
3. When retrying with `fork_context: false`, provide a compact task brief and explicitly list the local files the sub-agent must read first

## Practical Guidance

- Prefer fewer, higher-quality sub-agents over many shallow ones
- Give each sub-agent a clearly isolated write scope
- Keep shared integration files owned by the main thread whenever possible
- If a sub-agent needs a shared dependency or a shared export change, have it report that back rather than editing unrelated files

## Harness Workflow

Agents should treat the following files as the default system of record before making non-trivial
changes:

- `DESIGN.md`
- `README.md`
- `CONTRIBUTING.md`
- `roadmap.md`
- `packages/ui/src/lib/contracts.ts`
- `apps/docs/src/component-authoring.stories.tsx`
- `docs/harness-engineering.md`
- `docs/orchestration.md`

When work spans multiple surfaces or changes public behavior, start by creating or updating an
execution plan in `docs/exec-plans/`.

Prefer the narrowest useful harness suite while working:

- `pnpm harness:select`
- `pnpm harness:validate:changed`
- `pnpm harness:validate:static`
- `pnpm harness:validate:component`
- `pnpm harness:validate:docs`
- `pnpm harness:validate:docs-smoke`
- `pnpm harness:validate:consumers`
- `pnpm harness:validate:pr`
- `pnpm harness:validate:release`

Every suite writes a JSON report under `.artifacts/harness/`.
Worktree-backed orchestration runs use `pnpm harness:orch -- <orch command>` and store state under
`.artifacts/orch/`.

## Priority

If there is any conflict between older default delegation habits and this file:

- follow `DESIGN.md` for the active visual language and motion direction
- follow this file for sub-agent model selection
- follow this file for sub-agent reasoning effort
- follow this file for context fallback behavior