71 lines
2.7 KiB
Markdown
71 lines
2.7 KiB
Markdown
|
# <PROJECT NAME>
|
||
|
|
|
||
|
|
<One or two sentences: what this is and who it is for. Not a feature list.>
|
||
|
|
|
||
|
|
**Read `docs/DOC_TRUST_MAP.md` before trusting anything else in `docs/`.** It
|
||
|
|
says which document owns which answer. This file is deliberately short and
|
||
|
|
points at it rather than repeating it — a second copy of the map is the failure
|
||
|
|
that map exists to prevent.
|
||
|
|
|
||
|
|
## What this file is for
|
||
|
|
|
||
|
|
Only what an agent needs **before** it can read anything else, and that is not
|
||
|
|
already owned by a document. If you are about to add current state, a task list,
|
||
|
|
or a summary of `docs/`, it goes in the tracker or in `docs/` respectively.
|
||
|
|
|
||
|
|
## Exit codes are an API
|
||
|
|
|
||
|
|
<Delete if this project has no scheduled or scripted work.>
|
||
|
|
|
||
|
|
| Code | Means |
|
||
|
|
| --- | --- |
|
||
|
|
| `0` | did its work |
|
||
|
|
| `1` | refused for a normal, designed reason |
|
||
|
|
| `2` | **did not run** — a precondition failed. Never a pass |
|
||
|
|
| `3` | ran and the work failed |
|
||
|
|
| `99` | a lock was held; another copy is running |
|
||
|
|
|
||
|
|
Three states, never two: `ok` / `skipped` / `failed`. An exit code alone cannot
|
||
|
|
tell "nothing to do" from "I did nothing".
|
||
|
|
|
||
|
|
## Before you finish
|
||
|
|
|
||
|
|
`docs/WORK_CYCLE.md` owns this and outranks anything here. In short:
|
||
|
|
|
||
|
|
- Run this project's own guards, not just its tests: <name them, e.g.
|
||
|
|
`python3 tests/run_all.py`, `bash scripts/doc-claims.sh`>
|
||
|
|
- **Never `git add -A`.** Stage by explicit path — <`bash scripts/commit-mine.sh`
|
||
|
|
if adopted>. A shared checkout means someone else's work is one careless
|
||
|
|
`add` away from your commit.
|
||
|
|
- Update the documents this change triggered, **in the same commit as the
|
||
|
|
code**. Check each document's `Review trigger:` line.
|
||
|
|
- Close issues with the evidence that proves them: a path, a symbol, a test
|
||
|
|
name, or the command that shows it. "Done" is not a close.
|
||
|
|
|
||
|
|
## Before you plan
|
||
|
|
|
||
|
|
`docs/WORK_CYCLE.md` lists six sections **every plan must name**: unified code,
|
||
|
|
error handling, logging, blind spots, rolled-in landmine fixes, and
|
||
|
|
hardcode-as-little-as-possible. Read them there.
|
||
|
|
|
||
|
|
## Two standing instructions
|
||
|
|
|
||
|
|
**Flag anything that looks wrong, even if it is not what you were asked about.**
|
||
|
|
Most real defects are found while looking at something else. Say so, then fix it
|
||
|
|
or ask — a known bug that ships is a decision, and it is never yours to make
|
||
|
|
silently.
|
||
|
|
|
||
|
|
**Never print a credential.** Not from a file, not from a command's output, not
|
||
|
|
from a config subtree "with the secrets filtered out" — that filter has failed
|
||
|
|
before, because it matched key *names* and the secret sat inside an object whose
|
||
|
|
name was innocent. Name the variable or the path; never the value. To compare
|
||
|
|
two secrets, compare hashes.
|
||
|
|
|
||
|
|
## Conventions
|
||
|
|
|
||
|
|
<Delete what does not apply.>
|
||
|
|
|
||
|
|
- <Language/runtime and version>
|
||
|
|
- <Naming and layout rules an agent would otherwise guess at>
|
||
|
|
- <Anything that has bitten someone twice>
|