`docs/` pages are for humans `.agents/skills` pages are for agents #1631

New issue

Closed

opened 2026-07-31 22:56:11 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-07-31 22:56:11 +00:00

Owner

Humans need to know this: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/docs/compat-surface.md

Humans should not need to know about totally silent things, like reservations: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/docs/agent-reservation-cache.md. Whether an agent needs to know about reservations? unsure. But docs/ should be for humans. Honestly is it even worth a docs page if its totally silent to both humans and agents 90% of the time??? Probably not? That command sure, but the existence and mechanics of the cache?

dispatch broker is critical agents knowledge: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/docs/agent-dispatch-broker.md - surprised we've been getting away without it being a skill.

Humans need to know this: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/docs/compat-surface.md Humans should not need to know about totally silent things, like reservations: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/docs/agent-reservation-cache.md. Whether an agent needs to know about reservations? unsure. But docs/ should be for humans. Honestly is it even worth a docs page if its totally silent to both humans and agents 90% of the time??? Probably not? That *command* sure, but the existence and mechanics of the cache? dispatch broker is critical agents knowledge: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/src/branch/main/docs/agent-dispatch-broker.md - surprised we've been getting away without it being a skill.

coilyco-ops referenced this issue

2026-08-05 06:33:45 +00:00

Give Ward's high-level domain objects human names #1640

coilyco-ops commented

2026-08-05 09:38:56 +00:00

Member

Decision approved.

Placement rule:

docs/ contains supported behavior humans configure, observe, depend on, maintain, or recover.
.agents/skills/ contains procedures and decision routing an agent must actively apply.
AGENTS.md contains mandatory contributor doctrine.
CLI help and errors contain immediate command contracts.
Silent implementation mechanics belong in code, comments, and tests unless they change a human action or recovery decision.
Dispatcher behavior gets a human contract in docs and an agent operating procedure in the existing execution-model skill. Do not duplicate the same reference material.

A silent mechanism earns a human documentation section only when a human must configure it, observe it, rely on it as a product guarantee, or use it for recovery.

Implementation is folded into #1624. This issue is complete as a resolved design decision.

Decision approved. Placement rule: * `docs/` contains supported behavior humans configure, observe, depend on, maintain, or recover. * `.agents/skills/` contains procedures and decision routing an agent must actively apply. * `AGENTS.md` contains mandatory contributor doctrine. * CLI help and errors contain immediate command contracts. * Silent implementation mechanics belong in code, comments, and tests unless they change a human action or recovery decision. * Dispatcher behavior gets a human contract in docs and an agent operating procedure in the existing execution-model skill. Do not duplicate the same reference material. A silent mechanism earns a human documentation section only when a human must configure it, observe it, rely on it as a product guarantee, or use it for recovery. Implementation is folded into #1624. This issue is complete as a resolved design decision.

coilyco-ops referenced this issue

2026-08-05 09:39:08 +00:00

Collapse the documentation tree into durable product contracts #1624

coilyco-ops closed this issue

2026-08-05 09:39:16 +00:00

coilyco-ops referenced this issue

2026-08-05 10:09:42 +00:00

Collapse the documentation tree into durable product contracts #1624