ChatGPTScaffolding/meta/AGENTS.seed.md

AGENTS.md — Seed Template (For New Projects)

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

Note: This is a template copied into generated projects. Customize as needed for your project. Keep this AGENTS.md aligned with your system prompt and collaboration norms.

Collaboration Artifacts

• Root: collab/
• Subdirectories: collab/questions/, collab/proposals/, collab/plan/
• Naming per round: NN-<subject>.md (e.g., 00-bootstrap.md, 01-feature.md).
• LLM-optimized copies: add .llm.md siblings (machine-friendly).
• Versioning: start a new numbered file for major rounds; do not grow one file indefinitely.
• Principle: Keep chat minimal; prefer file-based collaboration via these docs.

Sequencing Rules (One-Way)

• Start with questions; after approval, proceed to proposal; after approval, proceed to plan; then implement.
• Once a step is approved, never return to a prior step. Perform edits within the current step’s file for that round and only create the next step’s file when moving forward.
• The agent reads .llm.md files; humans edit .md. The agent writes both .md and .llm.md siblings.
• Strict gates (phrases must appear in the human .md): Questions → "Approved for Proposal"; Proposal → "Approved for Plan"; Plan → "Approved to Implement". Do not create or advance steps without prior approval.

Logs and Documentation

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

Code and Tests

• Keep changes minimal and focused; avoid unrelated refactors.
• Adopt Test-Driven Development (TDD): write tests first and require unit/integration tests for all features.
• Maintain tests/ folder and a test runner script; keep tests fast and focused.
• Maintain consistent style with the existing codebase.

Git Workflow

• Branch: main (unless project policy differs).
• Commits: concise, present-tense; Conventional Commits style (feat:, fix:, chore:).
• Releases/Tags: YYYY-MM-DD-HHMM when warranted.

Chat Output Policy

• Default message: Updated <filepath>. Read/edit and let me know.
• Keep chat ≤5 lines; no diffs or large pastes.
• Only announce changes to collaboration files in collab/; log details in DevLog.
• Quiet shell: avoid streaming file contents/diffs; prefer silent checks and log details to DevLog.
• Quiet is mandatory (no toggle) for this tool’s workflows.
• Tool logging: use a quiet wrapper to log to docs/devlog/tool.log on failures; keep chat silent.

Tooling and Safety

• Use filesystem-first workflow; prefer rg for search; read files in ≤250-line chunks.
• Respect sandbox/approval constraints; avoid destructive actions without confirmation.
• Provide a short preamble before grouped/long-running tool calls.

Prompts/Configuration (if applicable)

• If using a wrapper like CodexHelper: YAML config preferred; precedence CLI > env > project > mode > global.
• Prompt composition order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
• Outputs: write run artifacts to <project>/runs/<timestamp>/....
• Safety: do not overwrite without --force; never git push on behalf of users.

Token/Context Hygiene

• Keep chat minimal; rely on files and dev logs.
• Avoid re-reading large files in chat; reference exact file paths.

Governance and Propagation

• When introducing non-project-specific collaboration or workflow rules, mirror them in your project’s system prompt and this AGENTS.md template so they persist across projects.
• Keep AGENTS.md aligned with your system prompt; log such changes in docs/devlog/.

Zero Technical Debt, Production-Ready Always

• Safety is top priority; speed is second. Never compromise quality.
• No technical debt allowed. Every commit must be production-ready.
• No deferring tests, documentation, or necessary refactors.
• Adopt TDD (tests first); keep docs current with changes.

---

Customize this AGENTS.md to fit your project specifics while preserving the one-way collaboration flow and file-first practices.

Planning and Architecture

• Plan ahead: use Questions → Proposal → Plan to align before coding.
• Maintain a project architecture/module map and document boundaries.
• Implement module-by-module per plan; avoid refactors, except when new info requires plan/doc updates.

Clean Repository Roots

• Keep the project root minimal and tidy. Prefer directories over many files at root.
• Place docs, templates, prompts, and scripts under dedicated subdirectories.

.gitignore Housekeeping

• Include a .gitignore with runs/ and common OS ignores; keep it up to date.

CI and Containers (Gitea + Docker)

• Use Gitea Actions for CI (.gitea/workflows/).
• Ensure local parity with Docker Compose; provide scripts to run the same CI tasks locally.
• Perform work inside containers where appropriate; use host for git/tea and Docker orchestration only.
• Manage dependencies via container images; avoid host-level installs.
• Use explicit container/network names; clean up containers, networks, and volumes.

Audits

• Perform regular audits; prompt for an audit before any release/tag. Save reports under docs/audits/ and log summaries in DevLogs.