AGENTS.md · git:20261108.1076e93 · 2026-11-08 · sha256 c2340772b312c1a3

AGENTS.md git:20261108.1076e93A

Immutable. This exact content never changes and is served at /api/v1/blob/c2340772b312c1a3.

# developer-os

This repository is a Markdown-only Claude Code plugin: core rules, skills, agents and Python 3 hooks under `plugin/`,
copyable project templates under `templates/`. No runtime and no build; see [README.md](README.md).
`CLAUDE.md` only imports this file, so this file is the authoritative source for every agent.

## Commands

- `bash scripts/check.sh`: the whole check, before every commit and in CI.
- `sh tests/check.test.sh`: after changing `scripts/check.sh` (the check runs it only in CI).
- `claude --plugin-dir plugin`: run the plugin from the working tree.

## Likely agent mistakes here

- Growing `plugin/rules/core.md` past 8900 bytes: it loads into every session. Evidence: D10, the Core-rules size stage.
- Lengthening skill descriptions past 12000 characters in total. Evidence: D10, the Skill descriptions stage.
- Making a hook deny instead of ask. Evidence: D6, `tests/guard.test.sh`.
- Refreshing a site page's `dos-source` hash without carrying the source change into its text. Evidence: commit 8456bc06 left "Codex installer" in `site/docs/architecture/overview.html`.

## Invariants

- D2, hook scripts in Python 3 with the standard library only and no network: Imports stage.
- D6, hooks ask, never deny, and fail open: Script tests stage (`tests/guard.test.sh`).
- D9, action skills end with `## Stop point` and `## Never`: Skill sections stage.
- D10, the per-session budget: Core-rules size and Skill descriptions stages.

The records are in [docs/product/decisions.md](docs/product/decisions.md); the stages in [docs/development.md](docs/development.md#the-check).

Backlog: docs/plans/backlog.md, docs/plans/backlog-done.md
Both backlog files are local and git-ignored (not shared through git).

## Documentation

[docs/index.md](docs/index.md) routes a task to its doc; [docs/development.md](docs/development.md), [docs/product/decisions.md](docs/product/decisions.md), [CONTRIBUTING.md](CONTRIBUTING.md).
Behavior change = docs update in the same commit; the docs-sync skill reports drift.