88 lines
4.1 KiB
Markdown
88 lines
4.1 KiB
Markdown
# AGENTS.md
|
|
|
|
## Scope
|
|
|
|
This file applies to the entire repository.
|
|
|
|
## Read First
|
|
|
|
Before starting substantial work, read the source-of-truth docs that match the task:
|
|
|
|
- implementation and repository-structure work: [docs/architecture.md](/home/kurihada/project/ai-workflow-skill/docs/architecture.md), [docs/skill-workspace-monorepo.md](/home/kurihada/project/ai-workflow-skill/docs/skill-workspace-monorepo.md)
|
|
- inbox Markdown test-plan work: [docs/tests/inbox/ROADMAP.md](/home/kurihada/project/ai-workflow-skill/docs/tests/inbox/ROADMAP.md)
|
|
|
|
## Documentation Update Rule
|
|
|
|
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 add, remove, or materially revise inbox Markdown test cases or test-plan documents, update [docs/tests/inbox/ROADMAP.md](/home/kurihada/project/ai-workflow-skill/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
|
|
|
|
## 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 the relevant source-of-truth docs 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:
|
|
|
|
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
|
|
|
|
### 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
|