ChatGPTScaffolding/templates/project/_shared/AGENTS.md

AGENTS.md — Project Template

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

This file is copied by scaffolding into new projects. Edit to suit the project while keeping the one-way collaboration flow and file-first practices.

Collaboration Artifacts

• Root: collab/
• Subdirectories: collab/questions/, collab/proposals/, collab/plan/
• Naming per round: NN-<subject>.md (+ .llm.md sibling)
• One-way sequence: Questions → Proposal → Plan → Implement; no backsteps after approval
• Agent reads .llm.md; humans edit .md. Agent writes both siblings.

Logs and Docs

• docs/devlog/DEVLOG_LLM.md and docs/devlog/DEVLOG_HUMAN.md — update each meaningful change.
• docs/ for feature docs and ADRs.
• Keep README.md current.

Chat Output Policy

• Default: Updated <filepath>. Read/edit and let me know.
• Keep chat ≤5 lines; no diffs; announce only collab file changes; log details in DevLog.
• Quiet shell: avoid printing file contents/diffs; prefer silent checks and DevLog summaries.
• Quiet is mandatory (no toggle) in this workflow.
• Tool logging: prefer a quiet wrapper that logs to docs/devlog/tool.log on failures; keep chat silent.

Coding, Tests, and Git

• Minimal, focused changes; adopt TDD (write tests first) and require unit/integration tests for all features; consistent style.
• Conventional Commits; branch main; tags YYYY-MM-DD-HHMM when warranted.

Tooling and Safety

• File-first workflow; prefer rg; read files in ≤250-line chunks.
• Respect sandbox/approvals; avoid destructive actions without confirmation.
• Provide brief preambles before grouped/long-running commands.

Prompts/Config (if applicable)

• YAML+yq; precedence CLI > env > project > mode > global.
• Prompt order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
• Outputs: <project>/runs/<timestamp>/...; require --force for overwrites; never git push.

Governance and Propagation

• When you adopt a reusable, non-project-specific practice, reflect it in your project’s system prompt and AGENTS.md to keep them aligned. Log such changes in docs/devlog/.

Zero Technical Debt, Production-Ready Always

• Safety first; speed second. No technical debt, ever.
• Do not defer tests, docs, or clarity/maintainability refactors.
• Practice TDD (tests first) and keep docs up to date with changes.

Planning and Architecture

• Plan ahead via Questions → Proposal → Plan to align before coding.
• Maintain an architecture/module map and clear module boundaries.
• Implement module-by-module; refactor only when new information requires plan/doc updates.

Clean Repository Roots

• Keep the project root minimal and tidy; prefer organizing assets under subdirectories (docs, templates, prompts, scripts, etc.).

.gitignore Housekeeping

• Include and maintain a .gitignore with runs/ and common OS ignores.

CI and Containers (Gitea + Docker)

• Use Gitea Actions for CI (.gitea/workflows/) with local parity via Docker Compose.
• Perform work inside containers when appropriate; reserve host for git/tea and Docker orchestration.
• Manage dependencies via Docker images; avoid host installs.
• Use explicit container/network names and clean up artifacts (down -v --remove-orphans).

Audits

• Run regular audits; prompt before release/tags. Save reports under docs/audits/ and summarize in DevLogs.