# 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](/home/kurihada/project/ai-workflow-skill/docs/implementation-roadmap.md)
- inbox Markdown test-plan work: [docs/tests/inbox/ROADMAP.md](/home/kurihada/project/ai-workflow-skill/docs/tests/inbox/ROADMAP.md)
- execution-trace workflow: [docs/roadmaps/README.md](/home/kurihada/project/ai-workflow-skill/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](/home/kurihada/project/ai-workflow-skill/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](/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

For substantial multi-step work, also keep an execution roadmap under [docs/roadmaps/active/](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/active/) while the work is in progress, then move it to [docs/roadmaps/archive/](/home/kurihada/project/ai-workflow-skill/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/](/home/kurihada/project/ai-workflow-skill/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](/home/kurihada/project/ai-workflow-skill/docs/implementation-roadmap.md) in the same change

## 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