AGENTS.md

1# AGENTS.md - Boring Is All You Need Codex Guide
2 
3This file gives Codex a compact project map for contributing to Boring Is All You Need.
4 
5## Project Intent
6 
7Boring Is All You Need is a local-first harness for AI coding agents. It packages concise instructions, progressive rules, validation scripts, lifecycle hook examples, and release evidence so agent-assisted development is easier to scope, verify, review, and recover.
8 
9## Working Rules
10 
11- Keep changes scoped to the requested workflow, tool, template, or documentation surface.
12- Read the nearest project guide, relevant docs, and directly touched scripts before editing.
13- Prefer deterministic scripts, tests, and hooks over longer instructions when behavior must be enforced.
14- Preserve the public release surface: no private paths, local credentials, unpublished plans, or maintainer-only notes.
15- Keep English as the default public surface; update the paired Chinese docs when user-facing behavior changes.
16- Use `rg` or `rg --files` for repository search.
17 
18## Validation
19 
20Run the smallest relevant gate before committing:
21 
22```powershell
23pwsh.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\validate-release-readiness.ps1
24```
25 
26Focused checks:
27 
28```powershell
29pwsh.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\validate-phase3.ps1
30pwsh.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\validate-runtime-slice.ps1
31pwsh.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\test-agent-hooks.ps1
32```
33 
34Use `-AllowDirty` with `validate-release-readiness.ps1` only while reviewing an intentional work-in-progress tree.
35 
36## Release Discipline
37 
38- Do not publish, retag, or rewrite remote history without explicit maintainer approval.
39- Treat `v1.0.0` and later releases as audited artifacts: clean history, reproducible validation, and clear release notes.
40- Use [docs/github-publication-runbook.md](docs/github-publication-runbook.md) for public release steps.
41