Define your product beside the code.

Keystone puts product intent in structured Markdown that people and coding agents can follow. Define the whole product or only the features that need a durable contract. Separate what exists from what remains to be built, then keep implementation aligned as the product changes.

Tests answer Does the code behave as expected?

Keystone answers Is this the product we intended to build?

Read the full specification View on GitHub

feature-spec/TODO.Leash.Walkers.Scheduling.md plain Markdown

# Leash.Walkers.Scheduling

## Requirements
- A walker MUST be able to define recurring available hours.
- An owner MUST NOT be offered a walk outside
  a walker's available hours.
- Changing availability MUST NOT alter a confirmed walk.

Getting started

Give agent-prompt.md to a coding agent. It drafts the product context, adds KEYSTONE.md, updates existing agent guidance, and proposes active specifications plus TODO documents for approval.

Setup prompt

Give this file to your coding agent

Open setup prompt

The self-contained file includes the complete setup contract, the content for KEYSTONE.md, and the instruction to update agent guidance files.

What gets added Project structure

your-project/
├── KEYSTONE.md
├── AGENTS.md  (existing or approved)
└── feature-spec/
    ├── Leash.md
    ├── Leash.Settings.md
    ├── Leash.Owners.md
    ├── Leash.Walkers.md
    ├── Leash.Walkers.Availability.md
    ├── Leash.Walkers.TimeOff.md
    ├── Leash.Walks.md
    └── TODO.Leash.Walkers.Scheduling.md

`KEYSTONE.md` explains the project and guides agents.

This root-level file explains the product, identifies relevant surfaces, and maps them to feature namespaces. Product behavior belongs in active specifications and TODO documents under feature-spec/.

README.md remains the human-facing overview, while AGENTS.md contains repository-wide working guidance.

KEYSTONE.md Describes the project and maps its namespaces.

Top-level spec Defines requirements inherited by its namespace.

# Keystone agent guidance

This project uses Keystone to define intended product behavior
beside the code. Unprefixed files are active specifications.
Files prefixed with `TODO.` define unimplemented behavior.

## Feature context

This example project runs Leash, a dog-walking app. Dog owners
use the app to manage dogs and request walks. Dog walkers use a
separate workspace to manage availability and assigned walks.

- `Leash.Settings.*` describes shared app settings and safety controls.
- `Leash.Owners.*` describes the dog-owner experience.
- `Leash.Walkers.*` describes the dog-walker experience.

## Before changing implemented behavior

Before changing a documented feature, an agent MUST:

1. ignore unrelated TODO documents;
2. identify the most specific affected active specification;
3. read its active parents and related specifications;
4. identify inherited requirements and exceptions;
5. make implementation and tests conform; and
6. report conflicts instead of weakening a requirement.

For future work, read matching TODO documents and their active
context. After implementation, reconcile the TODO document with
the active specification and remove the `TODO.` prefix.

## Navigate `feature-spec/` efficiently

Do not load every file in `feature-spec/`. Start with filenames,
derive the parent chain from the target feature name, and open
only the active or TODO context relevant to the task.

Define what exists and what comes next.

Keystone can define a whole product or selected features. Use an unprefixed file for implemented behavior and a TODO. prefix for behavior that is not implemented. Describe what each feature must do, not how its code is built.

TODO documents are not backlog items. They define intended product behavior without assigning, prioritizing, scheduling, or authorizing work. After implementation, reconcile the document with any matching active specification and remove the prefix.

Put shared requirements at the namespace root. A single-product project can use a root such as Leash.md for product-wide guarantees inherited by Leash.Owners.md and Leash.Walkers.md. A monorepo can instead use separate roots such as Desktop.md, Server.md, and Shared.md.

Need to describe something more specific? Add another part to the filename, separated by a dot. For example, Leash.Walkers.Availability.md includes the requirements from Leash.Walkers.md because its name starts with that name. The new file only needs the added requirements for showing walker availability.

Run the engineering demo to validate the full collection, resolve an active feature, and inspect intended scheduling behavior separately from current time-off controls.

# Leash.Walkers.Scheduling

Defines intended scheduling behavior that has not been implemented.

## Requirements

- A walker MUST be able to define recurring available hours.
- An owner MUST NOT be offered a walk outside available hours.
- Changing availability MUST NOT alter a confirmed walk.

## Related specifications

- `Leash.Walkers`