ChatGPTScaffolding/AGENTS.md

AGENTS.md — Working Agreements and Conventions

Scope: Applies to the entire repository unless overridden by a deeper AGENTS.md.

Note: The canonical system rules used by the agent are mirrored in prompts/global/system.md (human) and prompts/global/system.llm.md (LLM). Keep AGENTS.md and the system prompt aligned. A seed AGENTS template for generated projects lives at meta/AGENTS.seed.md (and .llm.md).

Collaboration Artifacts

• Root: collab/
• Subdirectories: collab/questions/, collab/proposals/, collab/plan/
• Naming per round: NN-<subject>.md inside each subdirectory (e.g., 00-bootstrap.md, 01-codexhelper.md).
• LLM-optimized copies: add .llm.md sibling files (e.g., 01-codexhelper.llm.md) that are concise and machine-friendly.
• Versioning: start a new numbered file for major rounds rather than expanding one doc indefinitely.
• Principle: Keep chat minimal; prefer file-based collaboration via these documents.

Sequencing Rules

• Begin with a questions file in collab/questions/ and iterate there until the agent is satisfied or the user instructs to proceed.
• Do not create a proposal or plan until the questions have been edited by the user and explicitly approved.
• After approval, create a concise proposal in collab/proposals/ and a concrete plan in collab/plan/, then implement.
• One-way progression: once a step (questions → proposal → plan) is approved, do not return to a prior step. Perform any subsequent clarifications/edits within the current step’s file for that round (e.g., continue editing collab/proposals/NN-*.md after proposal approval) and only create the next step’s file when moving forward.
• Artifact edits live in-place: Users/humans will edit the non-LLM .md files; the agent reads .llm.md and writes both .md and .llm.md siblings for every collaboration artifact.

One-Time Exceptions

• Only bypass the Questions→Proposal→Plan cycle when explicitly directed by the user; log such exceptions in docs/devlog/.

Logs and Documentation

• Dev logs: docs/devlog/DEVLOG_LLM.md and docs/devlog/DEVLOG_HUMAN.md updated each meaningful change.
• Project docs: docs/ for feature docs (<feature>.md) and architectural decisions (adr-<feature>.md).
• README: Keep README.md current with quickstart and usage.

Code and Tests

• Add unit tests in tests/ alongside features as they are introduced.
• Keep changes minimal and focused. Avoid unrelated refactors.

Git Workflow

• Branch: work on main for now.
• Commits: concise, present-tense; Conventional Commits style preferred (e.g., feat:, fix:, chore:).
• Releases/Tags: YYYY-MM-DD-HHMM when warranted; use tea if configured.

Wrapper Project Guidelines

• Aim: Bash wrapper around codex-cli with modes (global prompt, mode prompt, project prompt, codex settings, MCP).
• Approach: crawl → walk → run. Start with documented defaults and override via flags/env/config.
• Wizards: Intake markdown forms for creating modes and projects.

Agent Notes

• Ask clarifying questions in collab/<...>-questions.md.
• Propose in collab/<...>-proposal.md, plan in collab/<...>-plan.md, then implement.
• Respect repository structure and this AGENTS.md across all changes.

Token/Context Hygiene

• Chat minimalism: keep messages short; prefer pointers to files over inline dumps.
• Use .llm.md files for concise, machine-friendly summaries; avoid duplicating full human docs.
• Read .llm.md for intake; do not rely on .md for reading. Write both .md and .llm.md when updating artifacts.
• No large pastes in chat: never paste large code or markdown; write to files and reference paths/sections.
• Incremental artifacts: start a new NN-<subject>.md per round to avoid long single files.
• Status style: one-line updates before tool calls; rely on devlog for detail.
• Avoid re-reading large files in chat; reference exact file paths and sections instead.

Chat Output Policy

• Default message: Updated <filepath>. Read/edit and let me know.
• Keep chat to five lines or fewer.
• Do not paste diffs or file contents in chat; write to files instead.
• Aggregate multiple updates in a short bulleted list of filepaths.
• Push detailed reasoning/status to docs/devlog/ and reference it when needed.
• Only announce changes to collaboration files: collab/questions/, collab/proposals/, and collab/plan/.
• For all other changes (docs, code, configs), skip chat announcements and log in DevLog.