Oystro OSS User Guide

1. Before you start

Oystro is an Agentic Development Lifecycle (ADLC) protocol. It gives your AI agent guardrails to follow the lifecycle and generate the project artifacts.

The agent does the work. Oystro stops it at two human gates: you approve the spec before the build, and you approve the evidence before the release. The agent works alone between the two gates.

You need

• A computer with your project on it.
• An AI coding agent that can read and write files. Examples: Claude, Codex, OpenCode, Antigravity. (Oystro works best with the terminal clients of coding agents.)
• Git.

What Oystro is not

• Oystro is not an IDE or a coding agent. It is designed to work with any coding agent.

Oystro OSS is free to use and open source, licensed under AGPL-3.0.

Words used in this guide

• Agent: the AI program that writes code for you.
• Slice: one unit of work. A slice is one feature or one change.
• Phase: a group of slices. The phase is the unit of release.
• Spec: the plan for a slice. The plan is the file spec.yaml.
• Gate: a stop point. A person must approve to continue.
• Evidence: a test result or a record. Evidence shows that the work is correct.

Write a command as oystro:<command> — for example, oystro:init. There is no leading slash, so your agent does not treat it as one of its own slash-commands.

2. Install Oystro

Do these steps.

1. Open your agent in the project folder.
2. Paste this text into the agent:

read https://github.com/oystro/oystro-oss/blob/main/commands/init.md and follow the instructions to initialize oystro-oss in this folder

The agent installs the protocol. The agent creates two items:

• The file AGENTS.md. This file holds the workflow rules for the agent.
• The folder .oystro-oss/. This folder holds the protocol files.

Oystro OSS is free. The install needs no account and no key.

3. Start the project

Command: oystro:init

The agent reads your folder. Then the agent writes the base documents. The result depends on the folder.

Oystro has two start modes:

• Greenfield: a new, empty project. The agent interviews you to build the requirements.
• Brownfield: an existing codebase. The agent reads the code and reverse-engineers the requirements, the architecture, and the constitution from it.

In a brownfield project, the agent also:

• merges the Oystro workflow rules into your existing AGENTS.md. Your own rules stay, below a marker line;
• captures your existing agent rules (claude.md, .cursorrules, and others) into CONSTITUTION.md;
• links those files to AGENTS.md, so every agent reads one rule set.

A brownfield start needs extra review. The agent's reading of the existing code can be wrong. Read the base documents closely and correct them.

The base documents are:

• CONSTITUTION.md: the principles and the rules.
• BRD.md: the business requirements.
• ARCHITECTURE.md: the system design.
• technology.yaml: the tools and the technology.

Step: read the base documents. Correct any error. The agent does not overwrite these files later.

4. Define a slice

Command: oystro:define

A project has phases. A phase has slices.

• A slice is one unit of work: one feature or one change.
• A phase is a group of slices. The phase is the unit of release.

oystro:define starts a slice and adds it to the active phase. Then the workflow runs for that slice. When every slice of the phase is verified, oystro:release releases the whole phase.

The agent writes the plan for the slice. The plan is the file spec.yaml.

The spec contains:

• the requirements for the slice;
• the design;
• the tasks, in order;
• the acceptance criteria;
• the evidence contract. The evidence contract tells what proof the agent must show.

Step: read the spec. Correct any error. Do not approve a spec that is not clear.

5. Gate 1: approve the spec

Command: oystro:approve

This is Human Gate 1. The agent cannot write code before this gate.

1. Read spec.yaml.
2. Approve the spec, or send it back with a comment.

When you approve, the spec receives the mark Ref: APPROVED. The agent can then build.

After you approve

You approve once. Then the agent runs the rest of the sequence on its own: build, then verify, then the review (level L). It does not stop between the tasks. It stops only at Gate 2.

Some agents stop after each command and wait for you. If your agent stops, tell it to continue to the next stage. The protocol expects the agent to run the stages between the gates without a nudge.

Gate 1 applies at every level, including S. A level changes the design and task ceremony only. See section 11.

6. Build

Command: oystro:build

The agent implements the tasks. The agent does one task at a time. One task makes one commit.

You do not need to watch. The agent works alone between the gates.

Large projects (level L) can add a review before verify. Command: oystro:review-pre-verify. A second agent reviews the build against the spec.

7. Verify

Command: oystro:verify

The agent runs the tests and the acceptance checks. Then the agent writes two files:

• verification.md: the verdict. It says if each acceptance criterion passes or fails.
• proof.md: the raw evidence. For each check it records the command, the exit status, the time, and the raw output.

The verdict is bound to the commit. If evidence is missing, verification fails. The agent cannot hide a failed test: the raw output stays in proof.md as it was.

You read verification.md and proof.md at Gate 2.

8. Gate 2: approve the release

Command: oystro:release

This is Human Gate 2.

1. Read the evidence.
2. Read the deferred items. A deferred item is work that the team moved to later.
3. Approve the release.

Gate 2 releases the phase, not one slice. After your approval, the agent merges the phase, then archives it with its slices, specs, and proof, and updates the status.

9. Sample project

This sample shows one full journey. The sample is a small task list program.

Step 1: make the project

mkdir tasklist
cd tasklist
git init

Step 2: start your favorite agent

Start your favorite agent in the project folder, then paste the install text from section 2. Run oystro:init. Answer the questions; the agent writes the base documents.

Step 3: define the first slice

Run oystro:define. Ask for this slice:

Add a command that adds one task to the list.

The agent writes spec.yaml. The spec lists the tasks and the tests.

Step 4: approve the spec

Read the spec. Run oystro:approve.

Step 5: build

Run oystro:build. The agent makes one commit for each task.

Step 6: verify

Run oystro:verify. The agent runs the tests. Then it writes the report.

Step 7: release

Read the report. Run oystro:release.

Step 8: the next slice

Run oystro:define again. Ask for the next slice:

Add a command that marks one task complete.

Then repeat steps 4 to 7. This loop is the working method. One slice at a time.

10. Change a released feature

Command: oystro:change

Use this command for a bug fix or a change request. The agent does three steps:

1. It reads the baseline. The baseline is the current released code.
2. It makes the smallest change.
3. It verifies the change.

Gate 2 applies to a change. You approve the release.

11. Project levels

Oystro sets a workflow size for the project: S (Small), M (Medium), or L (Large). You choose the size during oystro:init; the level lives in CONSTITUTION.md and every spec follows it. The size sets how much process a change gets.

The level is a trade between speed and rigor. A small change does not need the process of a large one. You opt into the extra process; Oystro does not force it.

Gate 1 (approve the spec) applies at every level. Gate 2 (release) is the phase release. The only step a level skips is the L-level agent review.

Examples:

• S — change a config value, fix a typo, adjust a style.
• M — add a small feature, or change one module.
• L — change the data model, touch security, or change many modules.

When you are not sure, choose the larger level. Keep a change small by keeping its scope small.

Testing level

A project also has a testing level: Light, Standard, or Full. It lives in CONSTITUTION.md, next to the workflow size. It sets the depth of evidence that a change must show.

• Light — the lightest proof: the happy path, or the cheapest deterministic check.
• Standard — the full evidence contract. This is the default.
• Full — the deepest proof: the full contract, plus the extra checks that a high-risk change needs.

The workflow size (S/M/L) sets the design and the task ceremony. The testing level sets the proof. The two are independent. You choose both at oystro:init.

12. Branches

Oystro uses Git branches to isolate the work. The agent creates them. You do not manage them by hand.

The shape:

main
 └── phase/<phase-id>        the phase integration branch
      ├── feature/<FID>      slice 1
      └── feature/<FID>      slice 2

A slice merges into the phase branch when it verifies. The release merges the phase branch into the target branch (usually main) and archives the phase.

13. The domain model

During oystro:init, the agent records what your project is and the domain it serves, in CONSTITUTION.md. This is the domain model. Every spec must respect it.

The domain model records:

• the project type and the domain;
• the actors and their goals;
• the user journeys;
• the domain events and their state changes;
• the domain invariants: the rules that must always hold;
• the readiness path: the evidence chain that proves the product works along the real path, not only in unit tests.

The agent does not hardcode a domain. It assesses your project and asks you. Read this part of CONSTITUTION.md and correct it. The agent uses it to judge every later change.

14. Agent profiles

Oystro runs the work through predefined agent profiles. Each profile has a bounded role. A profile does one part of the workflow, and cannot do more.

No agent approves the work

A profile can propose, build, and verify. A profile cannot approve. Only a person approves, at Gate 1 and Gate 2. This keeps accountability with you.

The agent runtime runs the profiles. Oystro defines the roles and the bounds. Any agent that can read and write files can follow them.

15. Files and folders

16. Command reference

17. Troubleshooting

The agent does not know the command

Restart the agent. Then try again. If the command is still unknown, install Oystro again. See section 2.

The agent wrote code before my approval

Check spec.yaml. The file must contain Ref: APPROVED before the build. If the mark is absent, stop the agent and run oystro:approve.

Verification failed

Read the verification report. The report names the failed check. Correct the code. Then run oystro:verify again.

I want the extra tools

Oystro Standard adds enforced gates, evidence capture, and project memory. It launches in December 2026.