AGENTS.md ยท diff
git:20260929.4dab0ae to git:20261006.dacbcf4
18 added, 0 removed. Audit A to B.
# Repository guidance
This is Maintainer Skills Lab, an independent library of maintainer workflows.
Keep changes scoped to this repository. Source skills and agent profiles are
shared; client outputs are generated by `tools/kit.py`.
Edit `skills/` and `agents/`, then run `python3 tools/kit.py sync` to update
the checked-in provider folders and links. Include the source and its generated
outputs in the same change. Never edit provider copies independently.
## Before editing
- Read README.md and relevant implementation files.
- Check git status and existing PRs. Preserve unrelated or user-authored changes.
- Use a `codex/` branch for a coherent change and continue a matching open PR
rather than creating duplicates.
## Verification
Run the affected checks, and run the complete small suite before publishing an
implementation change:
```sh
python3 tools/kit.py check
python3 tools/kit.py sync --check
python3 tools/test_fast.py --runner unittest
# Or: pytest -q --tb=short -x
# Verbose CI-style: python3 -m unittest discover -s tests -v
python3 examples/bugfix/run.py
python3 tools/kit.py build
```
Source validation, fixture execution, and actual agent evaluation are different
claims. Record which happened. Never mark a client as tested solely because its
files parse. Native agent exports inherit model and execution policy.
## Hooks
- Keep hook activation opt-in and preserve existing hook configuration.
- Git checks must read the active index, including alternate indexes; never stage,
stash, or rewrite source files as a side effect of a validation hook.
- After staging, run `python3 -B tools/check_staged.py` before committing.
- Test hooks with actual Git operations in disposable repositories. Client protocol
fixtures do not establish live-client hook discovery or execution.
+ ## Command Sandbox & Safety
+
+ Before executing arbitrary shell commands, autonomous agents and maintainer scripts
+ can evaluate proposed commands against `tools/sandbox_check.py`:
+
+ ```sh
+ python3 tools/sandbox_check.py "git push --force origin main"
+ # Output: {"verdict": "BLOCKED", "category": "HIGH_RISK", ...}
+
+ # Fail with non-zero exit code if BLOCKED:
+ python3 tools/sandbox_check.py --strict "git status"
+ ```
+
+ Safety verdicts:
+ - `READ_ONLY` (Auto-Safe): inspection operations (`git status`, `git diff`, `cat`, `grep`, `ruff check`, `pytest`).
+ - `LOCAL_MUTATION` (Safe with warning): workspace edits (`git add`, `touch`, `mkdir`, `ruff format`).
+ - `BLOCKED` (High Risk): destructive operations requiring confirmation (`rm -rf /`, `git push --force`, `curl | sh`, `DROP TABLE`).
+
## Maintenance
- Prefer one useful, complete improvement over activity-only changes.
- Commit and push real verified work. Don't manufacture empty commits, alter
dates, add timestamp-only logs, or split changes solely to inflate activity.
- Keep documentation focused on available features, usage, and verified limitations.
- Don't send promotional messages or contact other people without a user request.
- Existing user authorization covers commits, pushes, and PRs for this project;
do not repeatedly ask for those permissions.
- Do not purchase services or run paid APIs as part of routine checks.