Oystro OSS User Guide

This guide shows one full project journey. You install Oystro, start a project, and ship one small feature. The guide uses short sentences. It uses Simplified Technical English.

Oystro provides the protocol. The outcome depends on your input at init and define and on the model's capability; some models follow the protocol more strictly than others. Oystro is agent- and model-agnostic.

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.
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.

Type a space before every /oystro: command — for example, /oystro:init. The space stops your agent from opening its own command menu.

2. Install Oystro

Do these steps.

Open your agent in the project folder.
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.

Folder state	What the agent does
Empty folder	The agent asks questions. Then it writes the base documents.
Existing code	The agent reads the code. Then it writes the base documents.
PRD and ADR ready	The agent derives the documents from your files.

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 slice is one unit of work. 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.

Read spec.yaml.
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.

Small projects (level S) skip this gate. 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 a verification report. The report is the evidence.

The report is bound to the commit. If evidence is missing, verification fails. The agent cannot hide a failed test.

8. Gate 2: approve the release

Command: /oystro:release

This is Human Gate 2.

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

After your approval, the agent merges the work. Then the agent updates the status. The slice is complete.

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:

It reads the baseline. The baseline is the current released code.
It makes the smallest change.
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 and /oystro:define. 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.

Level	What it is	Process	Gate 1	Review
S — Small	A quick change or a tweak.	Define, build, verify, release.	Skipped	No
M — Medium	The default. Normal feature work.	Full process with both human gates.	Human	No
L — Large	A large or high-risk change.	Full process, plus an agent review before verify.	Human	Yes

Gate 2 (release) applies to all levels. Gate 1 (approve the spec) is skipped at level S.

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.

12. 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.

Profile	Role
Collaborator	Works with you to explore the problem and define what to build. Runs `init` and `define`.
Developer	Builds the tasks, one commit each. Runs `build` and `change`.
Sr Tech Lead	Reviews the build against the plan, in a fresh context. Level L.
Gatekeeper	Runs the evidence and checks the acceptance criteria. Assembles the release.

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.

13. Files and folders

Item	Purpose
`AGENTS.md`	The workflow rules for your agent.
`.oystro-oss/CONSTITUTION.md`	Principles and rules. Never overwritten.
`.oystro-oss/BRD.md`	Business requirements. Never overwritten.
`.oystro-oss/ARCHITECTURE.md`	System design. Never overwritten.
`.oystro-oss/technology.yaml`	Tools and technology. Never overwritten.
`.oystro-oss/SLICE_LOG.md`	The build narrative. It records why each change was made.
`spec.yaml`	The plan for one slice: requirements, design, tasks, acceptance.
`.oystro-oss/commands/`	The command contracts.
`.oystro-oss/agents/`	The persona definitions.

14. Command reference

Command	Action	Gate
`/oystro:init`	Read the folder. Write the base documents.	—
`/oystro:define`	Write `spec.yaml` for one slice.	—
`/oystro:approve`	Approve the spec.	Human
`/oystro:build`	Implement the tasks. One commit for each task.	—
`/oystro:review-pre-verify`	Second-agent review of the build (level L only).	Agent
`/oystro:verify`	Run the evidence. Write the verification report.	—
`/oystro:release`	Approve the release. Merge and archive.	Human
`/oystro:change`	Fix a bug or make a change request.	Gate 2

15. 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

The Oystro engine adds enforced gates, evidence capture, and project memory. The engine is a paid product. It comes in December 2026.

← Back to home · Oystro OSS on GitHub