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