Write scenarios an agent can run

The idea

Keep a SCENARIOS.md file alongside the code with high-level journeys written in plain English. An agent reads a scenario, uses the project’s CLI to perform it, and compares the observed state with the expected outcome.

This is a proposed repository convention, not a standardized file format. Its value comes from clear expectations and a reliable way to inspect the application.

When it helps

Use this for exploratory acceptance checks, workflows spanning several components, or behavior that is easier to explain as a story than as a unit test. It also gives developers a readable inventory of important journeys.

Put it into practice

Give each scenario an ID, an isolated starting state, concrete actions, and an expected result. Ask the agent to record evidence and report pass, fail, or blocked. A blocked check must never silently become a pass.

## S01 — Archive and restore a project

Given a fresh local fixture with one active project,
and a user who owns that project:

1. Archive the project through the CLI.
2. List active projects.
3. Inspect the archived project by ID.
4. Restore the project and list active projects again.

Expect:
- The archived project is absent from the active list.
- Inspecting it by ID still returns its data.
- After restoring, it appears exactly once in the active list.

Evidence:
Record commands, exit codes, and relevant returned state.

Cleanup:
Reset the isolated fixture, even if a check fails.

Where it breaks down

An agent can interpret vague language too generously. Prefer observable results over phrases like “works correctly.” Specify fixtures, identities, and cleanup so results do not depend on yesterday’s run.

Keep stable, critical checks in deterministic automated tests too. Agent-run scenarios provide exploration and acceptance evidence; they do not replace repeatable CI.

Connect the patterns

This closes the loop with the CLI pattern: intent lives in the scenario, actions happen through the interface, and state provides the evidence. Link to the scenario file from AGENTS.md so the next agent knows where to start.