Skip to content

About

An agent environment contract for Claude Code plus two maintenance commands. Bootstraps a multi-agent setup, then keeps it from drifting out of sync with reality.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

claude-code-agent-pack

Русская версия →

An environment contract plus two maintenance commands. One idea holds them together: an agent setup rots, and it rots silently. Files drift from reality, statuses go stale, rules files grow past the point anyone reads them — and nobody notices until a decision gets made on a line that stopped being true weeks ago.

AGENTS.md sets the environment up. /save and /reindex keep it honest.

This is not a prompt collection. Every rule here was added after something went wrong, and the incident is written next to the rule.


What's in here

File What it does
template/AGENTS.md The environment contract. Bootstrap protocol, agent generation with exclusive write scopes, routing rules, context handoff, a human-in-the-loop lessons loop.
commands/save.md Close a session. Reconcile the task registry against verified reality, update the status file, record the gotcha you were corrected on, keep the rules file from rotting, report only what was checked.
commands/reindex.md Rebuild file order once. Project map and folder indexes — without duplicating documentation the project already keeps.

"Your orchestrator — the one I took from you — works well, thanks for that. Used it on a different project: fitting a door into a doorway with AR."

— Timofey Kostarev, web designer · @thekostarev

Worth noting what that says: the environment was lifted into a domain it was never written for. That is the whole point of a contract rather than a set of project-specific prompts.


The rules that carry the weight

Verified reality outranks what was written down. When the registry disagrees with the machine's output, the registry is what gets fixed — never the other way round.

"X doesn't exist" gets re-verified before it's carried forward. Nobody disputes an absence, so those entries stay stale the longest. An entry saying "the run produced no file" was carried forward while a parallel session had created the file a day earlier — the next session would have redone the work and produced a duplicate.

A report may only contain facts checked in this session. A status file is a retelling, not verification: it was true when written, while the report asserts something about now. A report named a server backup based on a two-day-old entry; the file was long gone, and the owner issued a delete command into the void.

A gotcha entry is worthless without its symptom line. The retelling of the incident gets forgotten; the detector fires. Every entry ends with "how to tell you're in this mistake right now".

Edits are surgical, never a file rewrite. Two sessions on one machine overwrite each other, and git does not save you from that.

A registry nobody fills in is worse than no registry. /save will not create one "just in case" — it needs at least two symptoms and your consent, and it shows you the specific mismatches it found rather than arguing that registries are generally useful.

On a file conflict the agent stops and escalates. It never resolves the conflict on its own. Parallel execution requires three conditions at once: 3+ independent tasks, no shared state, no dependency between them.

Only summaries pass between agents, never full files. If agent B reads forty pages from agent A, it burns context on material it doesn't need.

The orchestrator proposes, the human decides. Lessons are drafted and offered, never written silently. /clear is offered with an explanation of what will be lost, and is never run automatically.


Install

The commands — copy into ~/.claude/commands/ to have them everywhere, or into .claude/commands/ inside one project:

mkdir -p ~/.claude/commands
cp commands/save.md commands/reindex.md ~/.claude/commands/

/save and /reindex are then available as slash commands.

The environment — copy the contract into the project you want to set up:

mkdir -p .claude
cp template/AGENTS.md .claude/AGENTS.md

On the first run the orchestrator sees there is no .claude/agents/ yet, asks five questions one at a time, proposes a structure, and creates nothing until you confirm it.


Design notes

Everything conditional is genuinely conditional. The commands check whether the project actually has a registry, a rules file or a reality-check script, and skip silently when it doesn't. A command that demands scaffolding gets abandoned on the second project.

Consolidation runs on symptoms, not on a schedule. A section gets compacted when it has actually grown — not when a month has passed — and only with consent, because it rewrites meaningful text. The method is written out in full, including the step that diffs technical markers before and after: the check once recovered eight fragments and a whole entry that had dropped out during a rewrite.

Nothing is deleted automatically. Both commands list candidates for review and stop there.

No catalogue of skills is included. The set of available skills changes faster than this file gets updated, and a stale list silently steers the choice. The selection principle is here instead; the catalogue is not.

The model block is the fastest-rotting part of any such file and is marked as such. The failure is silent: an agent runs on an outdated model and nobody notices.


License

MIT.

About

An agent environment contract for Claude Code plus two maintenance commands. Bootstraps a multi-agent setup, then keeps it from drifting out of sync with reality.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors