Best Practices Agent Package

This package adds a 13-rule production coding ruleset, Codex/Claude Code skills, and a todo-complete hook to a repository.

Files

BEST_PRACTICES.md                         Universal production coding ruleset
AGENTS.md                                 Codex project instructions
CLAUDE.md                                 Claude Code project memory
LICENSE                                   Package license for redistribution
.agents/skills/best-practices/SKILL.md    Codex repo skill
.claude/skills/best-practices/SKILL.md    Claude Code repo skill
.claude/settings.json                     Claude Code hook config
.codex/hooks.json                         Codex hook config
hooks/todo_complete_gate.py               Shared todo-complete gate hook
scripts/install_best_practices.sh         Installer for an existing repo
tests/test_todo_complete_gate.py          Hook test suite (stdlib unittest)

Running the tests

python3 -m unittest discover -s tests -v

Standard library only — no pytest, no install step. The hook decides whether an agent may stop, so the suite is built around the two ways that can go wrong: a false "complete" that lets unfinished work skip the rule-13 pass, and a false "incomplete" that wedges the agent in a loop. Tests are not copied into consumer repositories; they cover the package itself.

What the hook does

The hook reads the current hook input and transcript, looks for the latest visible todo list, and only acts when every todo is complete. When that happens, it triggers a one-time production completion gate using BEST_PRACTICES.md and rule 13:

You are delivering production software. Do not deliver work you know to be deficient — incomplete, unverified, internally inconsistent, or in violation of the rules above. Before delivering, review the implementation against every rule and answer honestly: are you satisfied it follows this ruleset, or would you make revisions? If revisions are needed, make them before you deliver. (This ruleset is itself subject to this rule.)

For Claude Code, .claude/settings.json registers the hook on TaskCompleted (the task-list completion point in current Claude Code), on PostToolUse for TodoWrite (older todo-based sessions), and on Stop as the catch-all. On TaskCompleted the hook exits 2 to block the final task's completion until the gate passes. For Codex, .codex/hooks.json registers the hook on Stop, which is the portable completion point available in Codex hooks.

Install into a repository

From this package directory, run:

./scripts/install_best_practices.sh /path/to/your/repo

Or copy the files manually into the repository root.

After copying:

chmod +x hooks/todo_complete_gate.py

If your repo already has AGENTS.md, CLAUDE.md, .claude/settings.json, or .codex/hooks.json, merge the relevant sections instead of overwriting them. The installer does not overwrite different existing files; it stages the package version beside the existing file with a .best-practices-new.<timestamp> suffix for manual merge.

Optional automatic verification

By default, the hook prompts the agent to perform the final production review. To also run a deterministic command when todos are complete, set:

export BEST_PRACTICES_VERIFY_COMMAND="npm test && npm run lint"
export BEST_PRACTICES_VERIFY_TIMEOUT=180

If the command fails, the hook blocks completion and returns the failure output to the agent.

Notes

• The hook uses a temporary one-time state marker per session so the self-review gate does not loop forever after blocking once.
• If optional verification is configured and fails, the hook does not write the one-time marker; it continues blocking until the verification command passes or is disabled.
• If no todo list is found, the hook does nothing.
• If a todo is pending, in progress, blocked, or failed, the hook does nothing.
• The final quality gate still depends on the agent honestly applying BEST_PRACTICES.md; use repository tests, linting, type checks, CI, and code review as the enforcement layer for deterministic guarantees.