AGENTS.md

Scope

This file applies to the entire repository.

Before starting substantial work, read the source-of-truth docs that match the task:

Updating the relevant source-of-truth documentation is part of the definition of done.

Do not finish a task and leave its documentation stale.

Required behavior:

if you complete or materially change implementation behavior, architecture, runtime ownership, or product structure, update the relevant source-of-truth docs in the same change
if you materially change automated test coverage or test structure, keep the relevant source files and repository docs consistent in the same change

For automated tests in this repository:

do not create or maintain standalone Markdown test-plan documents under docs/tests/
keep test intent close to the executable test by adding a short comment above each top-level Test... function
keep test comments concise and focused on the behavior or contract the test is protecting

For skills/:

treat this directory as project-local Codex skill packages, not general documentation
use skills to package reusable agent workflows, constraints, and bundled assets so other agents can use them without rediscovering repository context
keep each skill self-contained around SKILL.md; add agents/openai.yaml and bundled assets only when they directly support real invocation
if a skill depends on an executable or other runtime asset, prefer bundling the required artifact with the skill instead of relying on ad hoc rebuild instructions as the primary workflow
when updating an existing skill, keep SKILL.md, agents/openai.yaml, and bundled assets consistent with each other
if you add or materially change a project skill, update the relevant source-of-truth docs in the same change

For frontend work in this repository:

default to reusing Cadence UI source-owned components before building custom UI pieces
business pages and feature flows may compose existing components freely, but do not introduce new foundational UI primitives when the need can be met by existing Cadence UI components or by installing additional Cadence UI components
if a task appears to require a genuinely new foundational UI primitive, explicitly tell the user before creating it instead of adding it silently

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

When spawning sub-agents for this repo:

Sub-agents should use this context policy:

first attempt with fork_context: true
if the sub-agent fails due to context-window pressure, retry with fork_context: false
when retrying with fork_context: false, provide a compact task brief and explicitly list the local files the sub-agent must read first

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

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