A conceptual minimum, not the website tree
This is the minimal conceptual example, not a claim about the actual website layout.
project/
├── AGENTS.md
├── agent_instructions/
│ ├── [project-defined].md
│ └── [other-project-defined].md
├── specifications/
│ └── [project-defined specification documents]
└── ...
The root entry point discovers standing Markdown instructions. File names, counts, source directories, test tools, and specification granularity are project choices. The specification lifecycle uses the three directories below. A single agent-maintained master file remains an exploratory option, not a requirement.
Use the specification lifecycle: specifications/requests/ holds human-authored requests awaiting implementation; specifications/archive/ preserves implemented human-authored requests as historical records; specifications/current/ contains agent-maintained descriptions of currently required product behavior. Move implemented requests to the archive without rewriting their historical content, and update current-state specifications. Direct prompts and conversations can authorize development without a formal specification file; maintain the current-state record regardless of request format.
Managing Specifications
SHAPE separates human-authored change requests from agent-maintained current-state specifications. Formal requests can wait until implementation is authorized. Completed requests are archived, while current-state specifications continuously reflect the product’s required functionality.
specifications/requests/— Human-authored requests awaiting implementation.specifications/archive/— Implemented human-authored requests retained for traceability.specifications/current/— Agent-maintained, logically organized specifications of current required functionality.
Conversational instructions do not need to be written into requests/ before
implementation: they can direct the agent immediately. The illustrated route through
requests/ is optional for conversations. See Specifications
for maintenance guidance.
The minimal discovery instruction
# AGENTS.md
Read and observe all Markdown (`.md`) files in `agent_instructions/` before starting work and throughout implementation.
The entry point directs agents to all Markdown files instead of enumerating them. Each instruction file starts by declaring its own purpose. Names such as STACK.md, DESIGN.md, ARCHITECTURE.md, LIBRARIES.md and OBJECTIVES.md are illustrative, not mandatory. The real website's root is larger; see the actual walkthrough.
What belongs where and who decides
| Category | Contents and exclusions | Decisions and agent work | Reason and scope |
|---|---|---|---|
Root AGENTS.md | Discovery entry; no universal detailed catalog | Owner controls changes; agents read it | Make standing context discoverable |
agent_instructions/ | Self-describing enduring rules/context; not feature behavior | Domain owners govern standards; agents read them and change only within granted authority | Separate concerns without prescribing filenames |
| Product knowledge | Intent, flows, permissions, exceptions and outcomes; not merely code observations | Humans settle consequential intent; agents maintain it during implementation | Continuity and independent checks, with flexible grouping |
| Implementation/tests | Product and ordinary automated checks; not authority to invent policy | PE directs approved implementation; separate context independently verifies intent | Project-selected architecture and tools |
| Enterprise assets | Shared platforms, libraries, UI/design, identity and integration; not needless local copies | Authorized enterprise owners govern changes and access | Reuse and technical restrictions may live outside the repository |
Authority is not created by prose
An agent cannot gain rights by writing that it has them. Protected framework or enterprise directives require their authorized owner's decision; project context may evolve only within its granted scope. Product-intent upkeep is different from changing the engineering rules that constrain it. Where precedence or ownership is unknown, confirm with the repository owner instead of inventing a universal hierarchy. Markdown guides; repository permissions, reviews and execution controls enforce. See instruction governance and execution boundaries.