comfyui_o1key/docs/decisions/0001-ai-native-repository-guidance.md

0001: AI-native repository guidance and documentation

• Status: Accepted
• Date: 2026-08-29
• Owners: Maintainers

Context

The plugin accumulated implementation notes, local tool state, root-level tests, and stale scripts. Important knowledge was scattered between code and temporary reports, making it difficult for a new maintainer or coding agent to identify runtime boundaries, compatibility constraints, and the correct validation commands.

Codex supports layered AGENTS.md files from repository root to working directory. ComfyUI also auto-loads frontend files, so generic repository assumptions can be unsafe for web/ and node-schema work.

Decision

• Use a concise root AGENTS.md for repository-wide executable rules.
• Use scoped AGENTS.md files only in nodes/, web/, and tests/, where local constraints materially differ.
• Use docs/ as the structured maintainer knowledge base.
• Keep user documentation in root README.md and durable design choices in numbered ADRs.
• Keep one-off cleanup reports under docs/maintenance/.
• Keep tests in tests/ and run them in isolated processes through tests/run_all.py.

Consequences

• Agents receive the right constraints close to the files they edit without overloading the root instruction file.
• Architecture and operational knowledge becomes reviewable and versioned.
• Changes that affect configuration, compatibility, or runtime boundaries must update documentation in the same work unit.
• Maintainers must keep links and commands synchronized as the portable layout evolves.

Alternatives considered

• One large root instruction file: rejected because it mixes executable rules with background knowledge and approaches instruction-size limits as the project grows.
• Documentation only in README: rejected because user guidance and maintainer internals have different audiences and change rates.
• Tool-specific hidden configuration directories: rejected because they are not portable across agents and should not be runtime project state.

Validation

• Verify root and scoped instruction files are discoverable from their directories.
• Verify every path linked from docs/README.md exists.
• Run the full isolated test suite and the plugin import smoke test after structural changes.