AGENTS.md

Scope

This file applies to the entire repository.

Read First

Before starting substantial work, read the roadmap that matches the task:

implementation work: docs/implementation-roadmap.md
inbox Markdown test-plan work: docs/tests/inbox/ROADMAP.md
execution-trace workflow: docs/roadmaps/README.md

Roadmap Update Rule

Updating the relevant roadmap is part of the definition of done.

Do not finish a task and leave its roadmap stale.

Required behavior:

if you complete or materially change implementation progress, update docs/implementation-roadmap.md in the same change
if you add, remove, or materially revise inbox Markdown test cases or test-plan documents, update docs/tests/inbox/ROADMAP.md in the same change
when a test-plan document is created, update document progress
when a test case is written, update authored-case tracking and pending backlog
when a planned item is no longer needed, mark it as removed or deferred instead of silently dropping it

For substantial multi-step work, also keep an execution roadmap under docs/roadmaps/active/ while the work is in progress, then move it to docs/roadmaps/archive/ when the work is complete.

Required behavior for execution roadmaps:

before starting substantial multi-step work, create or adopt one roadmap file under docs/roadmaps/active/
write the intended task as checklist items and keep them updated as work progresses
if work is unfinished, blocked, or paused, leave the roadmap in active/ with current status and next step
when all checklist items are complete, add a completion summary and move the file to archive/ in the same change
use stable slug filenames and prefer one roadmap file per workstream rather than one file per tiny action

Inbox Test-Plan Specific Rule

For docs/tests/inbox/:

organize by folder plus README.md
do not use numeric test IDs
use stable case slugs and keep the roadmap synchronized with the actual files on disk

Project Skills

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 docs/implementation-roadmap.md in the same change

Frontend UI Reuse

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

Sub-Agent Delegation

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:

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

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

Priority

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

follow this file for sub-agent model selection
follow this file for sub-agent reasoning effort
follow this file for context fallback behavior

5.0 KiB Raw Blame History