Setup prompt
Give this file to your coding agent
The self-contained file includes the complete setup contract, the content for KEYSTONE.md, and the instruction to update agent guidance files.
Keep essential feature requirements beside the code.
Keystone records the essential behavior a project intends to preserve. It does not need to describe everything. Tests alone cannot protect a defined feature: an agent can remove the behavior and its tests while leaving the remaining suite green. Keystone keeps selected requirements outside the implementation so people and coding agents can review what must remain before changing code.
Tests answer
Does the code behave as expected?
Keystone answers
Does the project still preserve its defined features?
# Lending.Loans
## Requirements
- Every active loan MUST identify the borrowed item
and its due date.
- An unavailable item MUST NOT be checked out.
- Renewing one loan MUST NOT change another.Getting started
Give agent-prompt.md to a coding agent. It drafts the feature context, adds KEYSTONE.md, updates existing agent guidance, asks before creating AGENTS.md, and proposes a focused set of essential feature specifications for approval.
What gets added
Project structure
your-project/
├── KEYSTONE.md
├── AGENTS.md (existing or approved)
└── feature-spec/
├── Lending.md
├── Lending.Loans.md
└── Catalog.mdKEYSTONE.md explains the project and guides agents.
This root-level file can explain what is being built, distinguish relevant surfaces, and map them to feature namespaces. It stays compatible with README.md as the human-facing overview and AGENTS.md as repository-wide working guidance.
# Keystone agent guidance
This project uses Keystone to keep essential feature requirements
separate from their implementation. Treat the Markdown documents
in `feature-spec/` as behavior the project intends to preserve.
## Feature context
This example project runs a community tool library with a
self-service kiosk and a staff desk. Members use the kiosk to
borrow available tools. Staff use a separate workspace to manage
the catalog and resolve lending issues.
- `Lending.*` describes rules shared by borrowing workflows.
- `Kiosk.*` describes the member-facing kiosk experience.
- `Staff.*` describes staff-only tools and workflows.
## Before changing a Keystone feature
Before changing a documented feature, an agent MUST:
1. identify the most specific affected specification;
2. read its namespace parents from least to most specific;
3. read the target and its related specifications;
4. identify inherited requirements and exceptions;
5. make implementation and tests conform; and
6. report conflicts instead of weakening a requirement.
## Navigate `feature-spec/` efficiently
Do not load every file in `feature-spec/`. Start with filenames,
derive the parent chain from the dot-separated name, and open
only that chain and relevant related specifications.Describe the features that must stay.
Keystone does not require you to document every feature. For each feature of your application, create a Markdown file named after it. Describe what it must do, not how the code is built.
Need to describe something more specific? Add another part to the filename, separated by a dot. For example, Lending.Loans.Returns.md includes the requirements from Lending.md and Lending.Loans.md because its name starts with those names. The new file only needs the added requirements for returning an item.
# Lending.Loans
Defines requirements for borrowing and managing tool loans.
## Requirements
- Every active loan MUST identify the item, member, and due date.
- An unavailable item MUST NOT be checked out to another member.
- Users MUST be told why a checkout cannot be completed.
- Renewing one loan MUST NOT change another loan.
- Loan status MUST NOT rely on color alone.
- Returning an item MUST make it available for future loans.
## Related specifications
- `Catalog.Availability`