@awebai/oats 0.69.12 → 0.69.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
package/README.md
CHANGED
|
@@ -1,266 +1,304 @@
|
|
|
1
|
-
# OATS
|
|
1
|
+
# OATS
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**The Open Agent Team Specification.** Platform, provider and model agnostic agent teams. Define the agents your work needs in your own Git repositories, on GitHub, GitLab or another forge, and run them as a team on your machines with Claude Code, Codex or pi.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://github.com/oats-project/oats/releases) [](LICENSE)
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
[](https://github.com/awebai/oats/releases)
|
|
9
|
-
[](https://nodejs.org/)
|
|
10
|
-
[](LICENSE)
|
|
7
|
+
Free and open source.
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
> **Try it:** open Claude Code, Codex or pi in a project's folder and say *"Set up OATS for this project, following https://github.com/oats-project/oats"*. What you need, and what happens, is under [Start here](#start-here). An agent setting up OATS for someone goes there too.
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
- **The CLI and contracts set up the team; capabilities shape it.** Choose the agents, the tools you already use and how they coordinate. We ship opinionated defaults that we think work well, and you can change or replace any of them.
|
|
16
|
-
- **You keep control** of messaging, knowledge, coordination and anything else your team does, so your knowledge, workflows and team structure outlast any model or platform.
|
|
17
|
-
- **So you don't lose your head as the threads multiply,** there are two clients: **OATS Desktop**, a free, fully integrated ADE (an agentic IDE), and **`oats tui`** for the terminal (in preview).
|
|
18
|
-
- **Built on what you already use:** Git, GitHub or GitLab, and your agent harnesses. No OATS account, central server or OATS-hosted database; integrations you choose may run their own.
|
|
11
|
+
## What OATS is
|
|
19
12
|
|
|
20
|
-
|
|
13
|
+
**OATS is a framework for building agent teams that are provider and model agnostic.** It has two parts:
|
|
21
14
|
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
- where their knowledge lives and how it grows;
|
|
25
|
-
- which skills, tools and workflows they receive;
|
|
26
|
-
- how they communicate and coordinate.
|
|
15
|
+
- **Contracts** for defining agents: how you describe each kind of agent, and how each kind is assigned its own set of instructions, skills, tools and knowledge.
|
|
16
|
+
- **A command-line tool** that runs and manages the agents on your machines. It starts them, connects them and stops them, on your command, on a schedule or when something happens.
|
|
27
17
|
|
|
28
|
-
|
|
18
|
+
With the right tools, OATS gives you fully functional agent teams that coordinate however you want them to, across people and across machines, using the tools you already use. We provide defaults that we think work, but you can fully customise everything.
|
|
29
19
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
**If you are a coding agent and your person asked you to set up, install or try OATS, do this next:** download the `oats-getting-started` skill with the command below, then follow it step by step. It is the whole procedure; don't improvise one from this README.
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for this project". It then:
|
|
39
|
-
|
|
40
|
-
- **Asks first, in one round:** your project, its repositories and where the workspace should live, the knowledge tools you use, and how your agents message each other ([aweb](https://aweb.ai) by default).
|
|
41
|
-
- **Installs OATS, OATS Desktop and the messaging CLI.**
|
|
42
|
-
- **Creates your workspace's team,** with no sign-in: the workspace's team, on an aweb account created for it, that every agent you spawn joins. You attach yourself to the account later in the setup, with the setup expert, or sign in to your own aweb account instead if you want the team on it from the start.
|
|
43
|
-
- **Writes your workspace** in one commit, in your repository or a new private one: the workspace and its team, nothing else. Or it joins this machine to an existing workspace.
|
|
44
|
-
- **Spawns the setup expert and opens the Desktop on it.** The setup expert is an OATS agent that turns OATS's defaults into your own coordination, knowledge and tasks capabilities, with you. You type only passwords, logins and tokens.
|
|
45
|
-
|
|
46
|
-
You end with a working workspace, the Desktop open on it, and its setup expert running.
|
|
47
|
-
|
|
48
|
-
Download the skill, don't web-fetch it: a tool that summarises pages would lose its exact commands.
|
|
49
|
-
|
|
50
|
-
## Why OATS
|
|
51
|
-
|
|
52
|
-
OATS grew from a practical need: we wanted control over our agent setups—not just which model answered a prompt, but also:
|
|
53
|
-
|
|
54
|
-
- The knowledge our agents accumulated.
|
|
55
|
-
- The know-how and workflows they used.
|
|
56
|
-
- The ways they communicated and coordinated.
|
|
57
|
-
- The systems on which all of this depended.
|
|
20
|
+
Everything is defined in Git, shared and access controlled by your forge. OATS needs no account, server or hosted service of its own.
|
|
58
21
|
|
|
59
|
-
|
|
22
|
+
Each agent is a session of an **agent harness** you already use, such as Claude Code, Codex or pi, started in a folder of its own, with the full power of that harness. By choice, OATS runs them as **terminal agents**, agents that run in a terminal, on your machines: a laptop or a server.
|
|
60
23
|
|
|
61
|
-
|
|
24
|
+
With our default messaging, [aweb](https://aweb.ai), every agent gets a cryptographically verifiable identity and secure agent to agent messaging, across vendors and harnesses: every message is signed, and end-to-end encrypted when you turn encryption on. Messaging, and every other tool OATS uses, such as knowledge and tasks, are your choice: aweb is only the default for messaging, and with another tool the guarantees are that tool's own.
|
|
62
25
|
|
|
63
|
-
|
|
26
|
+
OATS also provides **OATS Desktop**, a free agent development environment (ADE) that makes working with your agents and coordinating them easier. It is optional.
|
|
64
27
|
|
|
65
|
-
|
|
28
|
+
## A new way to think about agents
|
|
66
29
|
|
|
67
|
-
|
|
30
|
+
Usually a repository has one `AGENTS.md`, the instructions every session reads, and a few **skills**, written procedures an agent loads when a task calls for one. Every session starts as the same generalist, and what it learns is lost when it ends, or scattered across the systems of different vendors.
|
|
68
31
|
|
|
69
|
-
OATS
|
|
32
|
+
OATS has you think of a project as worked on by several agents of different **kinds**, such as a code reviewer, a backend expert or a release manager. It is fully flexible: one generalist, or a whole team that coordinates its work. Each agent starts in a **home** of its own, a folder with its own `AGENTS.md`, the skills of its kind and only the instructions it needs. What it learns is kept for the next agent of its kind.
|
|
70
33
|
|
|
71
|
-
|
|
34
|
+
## The building blocks
|
|
72
35
|
|
|
73
|
-
|
|
36
|
+
Each block uses the ones before it.
|
|
74
37
|
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
38
|
+
- **Capability.** A bundle that gives agents one ability, such as messaging, knowledge, tasks or code review, shared by every kind of agent that uses it. It can ship skills, scripts, command-line tools and an **injection**: instructions OATS composes into the `AGENTS.md` of each agent that uses it.
|
|
39
|
+
- **Soul.** A kind of agent, such as a code reviewer or a backend expert. It defines the capabilities it uses, for the behaviours it shares with other souls, and its own `AGENTS.md` and skills, for what is unique to it. It is a folder in Git, changed by pull request.
|
|
40
|
+
- **Instance.** One agent at work: a soul started for one piece of work, as a terminal session of Claude Code, Codex or pi. Many instances of a soul can run at once. OATS composes each from its soul and its soul's capabilities, so it gets:
|
|
41
|
+
- **its `AGENTS.md`:** the soul's own, then each capability's injection, then a short OATS section on where it works;
|
|
42
|
+
- **its skills:** the soul's and every capability's;
|
|
43
|
+
- **its scripts and command-line tools,** from its capabilities.
|
|
44
|
+
- **Workspace.** The space that bounds your agents: their souls, capabilities, knowledge, schedules and triggers, and the **teams** they work in, groups of agents that can message each other. It can span several Git repositories. An organisation has one workspace; its teams are labels within it, and the workspace can hold as many as it needs.
|
|
79
45
|
|
|
80
|
-
|
|
46
|
+
### An instance's home
|
|
81
47
|
|
|
82
|
-
|
|
48
|
+
What an instance is composed from lands in a home of its own. The home of a code reviewer, working on its own branch:
|
|
83
49
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
50
|
+
```text
|
|
51
|
+
code-reviewer instance home
|
|
52
|
+
├── AGENTS.md composed from:
|
|
53
|
+
│ ├── the soul's own AGENTS.md role, responsibilities, boundaries
|
|
54
|
+
│ ├── code review injection how to read a change and report findings
|
|
55
|
+
│ ├── messaging injection how to reach other agents and people
|
|
56
|
+
│ ├── knowledge injection how to consult and record what it learns
|
|
57
|
+
│ └── OATS section where this instance works
|
|
58
|
+
├── CLAUDE.md → AGENTS.md the same file, for agents that read CLAUDE.md
|
|
59
|
+
├── TASK.md the work it was started for
|
|
60
|
+
├── instance.json what it was given, and from where
|
|
61
|
+
├── .agents/skills/ the soul's skills plus every capability's
|
|
62
|
+
├── .oats/modules/ each capability, copied whole with its scripts and tools
|
|
63
|
+
│ ├── oats.code-review/
|
|
64
|
+
│ ├── oats.aweb/ messaging
|
|
65
|
+
│ ├── oats.okf/ knowledge
|
|
66
|
+
│ └── acme-style-guide/
|
|
67
|
+
├── STATE.md, log.md, notes/ working notes its knowledge capability keeps
|
|
68
|
+
├── work/ its own branch of the repository it works on
|
|
69
|
+
└── .work-<purpose>/ more branches or repositories, when the work needs them
|
|
70
|
+
```
|
|
90
71
|
|
|
91
|
-
|
|
72
|
+
The agent then starts normally in its home and reads its `AGENTS.md` and skills as it always would. A change to a capability reaches the next instance of every soul that uses it (for a package, once its new version is pinned); a change to a soul's `AGENTS.md` reaches only that soul's. Running instances keep what they started with.
|
|
92
73
|
|
|
93
|
-
|
|
74
|
+
## Capabilities
|
|
94
75
|
|
|
95
|
-
|
|
76
|
+
- **Three are core: knowledge, messaging and tasks.** They turn separate agents into a team: what they know, how they reach each other and people, and what work they share. Other capabilities build on them, so OATS defines a contract for each. Any capability that meets it can fill it, such as Jira or Linear for tasks, and an agent has **at most one of each**.
|
|
77
|
+
- **Any other capability** adds other know-how and behaviours you want your agents to have, such as planning engineering work or reaching your own systems.
|
|
78
|
+
- **Coordination** is the one that shapes a team most: how agents divide work, hand it over, review it and bring in a person. It is a set of capabilities, not part of OATS, so each team can work its own way and change it by pull request. It starts from a template: a repository of coordination capabilities that a team copies into its own repository and adapts to how it works. The first is the engineering template, for work that lands as pull requests. OATS's own coordination is such a copy.
|
|
79
|
+
- **Use a ready-made one or write your own.** Ready-made capabilities, and sometimes souls, come in **packages**. You pin each package to a version, so every agent gets exactly the same thing.
|
|
80
|
+
- **Official packages** cover knowledge, messaging, and tasks including Jira and Linear.
|
|
96
81
|
|
|
97
|
-
|
|
98
|
-
- Another develops a capability integration.
|
|
99
|
-
- Another supports an ongoing upgrade.
|
|
82
|
+
## Why souls are valuable
|
|
100
83
|
|
|
101
|
-
|
|
84
|
+
A soul turns how a kind of agent should work into something you can keep, review and share. It gives each instance:
|
|
102
85
|
|
|
103
|
-
|
|
86
|
+
- **its capabilities,** the set that defines its way of working;
|
|
87
|
+
- **its instructions,** its `AGENTS.md`: the closest thing the agent has to a system prompt;
|
|
88
|
+
- **its skills,** for its own kind of task;
|
|
89
|
+
- **its knowledge:** decisions, their reasons and lessons, kept by your knowledge capability in a **knowledge base**. By default each area of it has one owning soul, and a soul also reads the areas its work touches ([Knowledge and learning](docs/knowledge-and-learning.md)).
|
|
104
90
|
|
|
105
|
-
|
|
91
|
+
So:
|
|
106
92
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
93
|
+
- **Agents are focused.** An agent given only what its role needs does better work than one given every procedure and trusted to ignore most of them.
|
|
94
|
+
- **Expertise compounds.** Lessons stay with the soul, so each new instance starts wiser than the last.
|
|
95
|
+
- **Souls are portable.** Change the model or the agent, and the soul and its knowledge stay.
|
|
96
|
+
- **Souls are reviewed.** Changing how an agent works is a pull request.
|
|
97
|
+
- **Souls are shared.** One soul serves everyone who uses it, and you can adopt ready-made ones.
|
|
98
|
+
- **Souls can speciate.** When a kind of work outgrows a soul, it can split into more specialised souls, each with its own capabilities and knowledge. Souls can also widen or merge. Every such change is proposed and reviewed.
|
|
112
99
|
|
|
113
|
-
|
|
100
|
+
**Why dividing work this way doesn't lose.** Teams of agents often do worse than one agent when they split a problem among them. A team of souls done well never splits a problem; it splits responsibility and context:
|
|
114
101
|
|
|
115
|
-
|
|
102
|
+
- each soul holds a whole area, with the knowledge that goes with it;
|
|
103
|
+
- work that crosses areas stays whole with one agent that leads it, while the others answer for their own areas;
|
|
104
|
+
- each area of knowledge has one owning soul;
|
|
105
|
+
- small work can stay with one agent, often the best shape for it.
|
|
116
106
|
|
|
117
|
-
|
|
107
|
+
## What OATS gives you
|
|
118
108
|
|
|
119
|
-
|
|
109
|
+
- **Work bigger than one session.** Divided by responsibility and context, a team can take on work no single session could hold.
|
|
110
|
+
- **One way of working across agents.** Define once how your agents work; everyone's agents follow it, on Claude Code, Codex or pi.
|
|
111
|
+
- **Automations.** Schedules and triggers start agents without anyone typing.
|
|
112
|
+
- **Yours to keep.** Souls, knowledge and workflows live in your repositories, independent of any model or provider.
|
|
120
113
|
|
|
121
|
-
|
|
114
|
+
## Work the way you choose
|
|
122
115
|
|
|
123
|
-
|
|
116
|
+
- **Start from a default.** Packages ship ready-made souls, and coordination starts from a template, such as the one below. During setup, an agent called the setup expert adapts the defaults to your project with you.
|
|
117
|
+
- **Adapt it.** Change instructions, swap capabilities, add or drop roles, each by pull request.
|
|
118
|
+
- **Or build your own:** one generalist, a set of specialists, a team with a person approving every merge, agents that only run on a schedule. Messaging, knowledge and tasks are capabilities too, so you can bring your own tools.
|
|
124
119
|
|
|
125
|
-
|
|
126
|
-
- A messaging capability can use a different communication service.
|
|
127
|
-
- A task capability can connect agents to the tracker or coordination model you prefer.
|
|
128
|
-
- Additional capabilities can extend a team without becoming mandatory parts of OATS.
|
|
120
|
+
## Example: the building of OATS
|
|
129
121
|
|
|
130
|
-
|
|
122
|
+
We are moving the building of OATS to this template. It has six kinds of agent, each holding one whole piece of work:
|
|
131
123
|
|
|
132
|
-
|
|
124
|
+
- **Dispatcher.** One per person, always running. You tell it what you want; it starts the work with the right expert, starting one if needed, and reports progress. It decides nothing about the work itself.
|
|
125
|
+
- **Expert.** Owns one area, such as the kernel or the Desktop, and that area's knowledge. It plans, writes the spec and acceptance tests, starts developers, checks their work and takes the pull request to the maintainer. A generalist expert owns the contracts between areas and leads work that crosses them.
|
|
126
|
+
- **Developer.** Builds one task from a spec on its own branch, works through the reviewer's findings, hands the branch back to the expert and retires.
|
|
127
|
+
- **Reviewer.** Reads the developer's change in a fresh context against the spec and tests, and reviews each fix until nothing is left. It never decides a merge.
|
|
128
|
+
- **Maintainer.** The merge gate for one part of the project. It merges where written rules allow and otherwise asks a person, and never plans the work it judges.
|
|
129
|
+
- **Routine.** A soul a schedule starts for each run of a recurring job, such as a morning digest.
|
|
133
130
|
|
|
134
|
-
|
|
131
|
+
```mermaid
|
|
132
|
+
flowchart LR
|
|
133
|
+
You(["You"]) --> D["Dispatcher"]
|
|
134
|
+
D --> E["Expert"]
|
|
135
|
+
E -->|spec| Dev["Developer"]
|
|
136
|
+
Dev <-->|findings and fixes until clean| R["Reviewer"]
|
|
137
|
+
Dev -->|hands back| E
|
|
138
|
+
E -->|pull request| M["Maintainer"]
|
|
139
|
+
M -->|merge| Main[("main")]
|
|
140
|
+
```
|
|
135
141
|
|
|
136
|
-
|
|
142
|
+
You approve each piece of work once, at the expert's plan, and hear again only if the plan changes materially. Every change is reviewed three times: the reviewer reads the lines, the expert checks it against the plan, and the maintainer judges whether it belongs.
|
|
143
|
+
|
|
144
|
+
## How it works
|
|
145
|
+
|
|
146
|
+
### The workspace
|
|
147
|
+
|
|
148
|
+
The workspace's `oats-workspace.yaml` lists the repositories that take part, the packages at their pinned versions, its teams and which souls may join each, and the capabilities every soul gets by default. Each repository it lists links back with an `oats-membership.yaml` that names the repository holding `oats-workspace.yaml`, and that repository does too. A repository takes part only when both sides name each other, so neither can add the other on its own; a listed repository that doesn't link back contributes nothing. Each machine keeps its own settings, its lock and its agents' homes in a deployment directory of its own.
|
|
149
|
+
|
|
150
|
+
```mermaid
|
|
151
|
+
flowchart LR
|
|
152
|
+
subgraph WS["Workspace: your Git repositories"]
|
|
153
|
+
direction TB
|
|
154
|
+
S["Souls"]
|
|
155
|
+
C["Capabilities"]
|
|
156
|
+
K["Knowledge base"]
|
|
157
|
+
T["Schedules and triggers"]
|
|
158
|
+
end
|
|
159
|
+
subgraph MC["Any machine: a laptop or a server"]
|
|
160
|
+
direction TB
|
|
161
|
+
I1["An expert on Claude Code"]
|
|
162
|
+
I2["A developer on Codex"]
|
|
163
|
+
I3["A reviewer on pi"]
|
|
164
|
+
end
|
|
165
|
+
P(["You"])
|
|
166
|
+
WS -->|start instances| MC
|
|
167
|
+
MC -->|lessons, by pull request| K
|
|
168
|
+
P <-->|requests and decisions| MC
|
|
169
|
+
```
|
|
137
170
|
|
|
138
|
-
|
|
139
|
-
|---|---|
|
|
140
|
-
| Reusable procedures and know-how | Skills and capabilities |
|
|
141
|
-
| Durable judgment and awareness of the larger picture | Accepted knowledge |
|
|
142
|
-
| A detailed understanding of the current problem | Instance context |
|
|
143
|
-
| Unfinished work and next steps | Instance state |
|
|
171
|
+
### Defining an agent
|
|
144
172
|
|
|
145
|
-
|
|
173
|
+
A soul is a folder in one of those repositories:
|
|
146
174
|
|
|
147
|
-
|
|
175
|
+
```text
|
|
176
|
+
souls/code-reviewer/
|
|
177
|
+
soul.yaml description, where it works, its capabilities
|
|
178
|
+
AGENTS.md its instructions
|
|
179
|
+
okf.json the knowledge areas it owns and reads, when it uses oats.okf
|
|
180
|
+
skills/ skills only this soul needs
|
|
181
|
+
```
|
|
148
182
|
|
|
149
|
-
|
|
183
|
+
```yaml
|
|
184
|
+
schemaVersion: 2
|
|
185
|
+
name: code-reviewer
|
|
186
|
+
description: Reviews one change against its spec and reports findings.
|
|
187
|
+
work: worktree # each instance gets its own branch
|
|
188
|
+
capabilities:
|
|
189
|
+
oats.code-review: { from: package } # from a pinned package
|
|
190
|
+
acme-style-guide: { from: here } # from this repository
|
|
191
|
+
```
|
|
150
192
|
|
|
151
|
-
|
|
193
|
+
A soul can name any capability, including the ones for knowledge, messaging and tasks. It also gets the workspace's default capabilities, unless it turns them off. It can name a preferred agent and model too, which each machine or each start can override.
|
|
152
194
|
|
|
153
|
-
|
|
154
|
-
2. Could it not have obtained this simply by reading the repository?
|
|
195
|
+
### Working with your agents
|
|
155
196
|
|
|
156
|
-
|
|
197
|
+
- **Start one** with a task in plain words from OATS Desktop, or let another agent, a schedule or a trigger start it.
|
|
198
|
+
- **OATS builds it** as above, gives it a working directory, and starts the agent normally. Nothing is wrapped or replaced.
|
|
199
|
+
- **Talk to it** in its terminal, as with any session.
|
|
200
|
+
- **Agents work together** by starting other agents, as their souls allow. With a messaging capability, they also message each other, as their teams and their controls allow.
|
|
201
|
+
- **An agent can ask you** for a decision, and waits for the answer.
|
|
202
|
+
- **It learns.** Lessons worth keeping go back into a real knowledge base by pull request. It can be organised by soul, each owning its own area, or as a more general knowledge base, as your knowledge capability supports.
|
|
203
|
+
- **It retires** when its work is done. The soul, and what it learned, remain.
|
|
157
204
|
|
|
158
|
-
|
|
205
|
+
OATS was founded on one claim: **an agent's expertise should be a versioned project artifact, not a side effect of a session.**
|
|
159
206
|
|
|
160
|
-
|
|
207
|
+
## Why we built it
|
|
161
208
|
|
|
162
|
-
|
|
209
|
+
Agents, coding agents in particular, can now do real work. The way most of us run them hasn't caught up:
|
|
163
210
|
|
|
164
|
-
|
|
211
|
+
- **Every session starts from zero.** Context is explained again and decisions are made again.
|
|
212
|
+
- **Everyone runs agents differently,** so an organisation's results depend on who is prompting.
|
|
213
|
+
- **Real work doesn't fit in one session.** Work that spans systems, hours or people outgrows a context window, and someone ends up coordinating sessions by hand.
|
|
214
|
+
- **Choosing a model is becoming choosing a platform.** Adopting a provider's memory, tools and workflows means starting again when you change model.
|
|
165
215
|
|
|
166
|
-
|
|
216
|
+
We believe:
|
|
167
217
|
|
|
168
|
-
-
|
|
169
|
-
-
|
|
170
|
-
-
|
|
171
|
-
- Useful learning can benefit future instances of that soul.
|
|
172
|
-
- Other souls read or link to relevant concepts rather than duplicating them.
|
|
218
|
+
- the way agents work should be yours: written down, reviewed, versioned and portable;
|
|
219
|
+
- machine intelligence should become a commodity, available from many providers, including models you run yourself;
|
|
220
|
+
- how agents are organised decides the quality of their work as much as the model does, and deserves the tools we give code.
|
|
173
221
|
|
|
174
|
-
For
|
|
222
|
+
## For your own projects
|
|
175
223
|
|
|
176
|
-
|
|
224
|
+
- **Any shape of team,** from one agent to a full team, changed as the project grows.
|
|
225
|
+
- **Work while you're away.** Schedules and triggers start or wake agents when nobody is at the keyboard.
|
|
226
|
+
- **You see who needs you.** The Desktop shows which agents are waiting on you.
|
|
227
|
+
- **Knowledge stays in your repositories,** ready for the next agent, whichever model it runs on.
|
|
177
228
|
|
|
178
|
-
|
|
179
|
-
2. **An independent harvester judges what is worth retaining.**
|
|
180
|
-
3. **Proposed knowledge is validated and delivered through the configured acceptance process.**
|
|
181
|
-
4. **Future instances can consult the accepted result.**
|
|
229
|
+
## For organisations
|
|
182
230
|
|
|
183
|
-
|
|
231
|
+
OATS is where the organisation defines, once, how its agents work.
|
|
184
232
|
|
|
185
|
-
|
|
233
|
+
- **One canonical way of working.** Everyone's agents start from the same souls, with packages at the same pinned versions. A code reviewer reviews the same way on every team.
|
|
234
|
+
- **Any model, your choice of agent.** People keep the agent they prefer, with its full power. OATS adds the organisation's souls without replacing it, and agents on different tools work alike and can message each other.
|
|
235
|
+
- **No new interface to learn.** No one has to use OATS Desktop: agents are ordinary sessions in their own terminals.
|
|
236
|
+
- **Changes are reviewed like code.** A change to how agents work is a pull request to one of the workspace's repositories.
|
|
237
|
+
- **Knowledge grows for everyone.** Once accepted, one person's agents' lessons are there for every later instance of that soul.
|
|
238
|
+
- **Agents of different people work together,** messaging each other across their areas while each asks its own person for decisions.
|
|
239
|
+
- **No OATS server.** OATS works from Git, your forge and your agents; integrations you choose may run their own services.
|
|
186
240
|
|
|
187
|
-
##
|
|
241
|
+
## Schedules and triggers
|
|
188
242
|
|
|
189
|
-
|
|
243
|
+
Agents don't have to wait for someone to type. Schedules and triggers are part of the team, like its souls.
|
|
190
244
|
|
|
191
|
-
|
|
245
|
+
- **A schedule** runs at set times in the time zone it names. It starts a new agent with a task, runs a command, or wakes a running agent with a message.
|
|
246
|
+
- **A trigger** starts a new agent when an event matches: a GitHub pull request opened, labelled or updated, or an event from a source a capability provides.
|
|
247
|
+
- **Shared or local.** Kept in the workspace, they are reviewed like everything else and run on the machine they name; or keep them local to one machine. On a server they keep running while your laptop sleeps.
|
|
192
248
|
|
|
193
|
-
|
|
194
|
-
- **Instances to develop their own specialisations.** Two UX-expert instances share a foundation, but one develops a deep understanding of checkout flows while another focuses on navigation.
|
|
195
|
-
- **Long-running instances to retain working understanding.** A customer-support instance carries its investigations, observations and unresolved questions across many tasks.
|
|
196
|
-
- **Selected learning to become shared knowledge.** Useful findings are reviewed and made available to other instances, while task-specific context stays with the instance that needs it.
|
|
249
|
+
For example, every knowledge harvest pull request can get its own reviewer agent minutes after it opens.
|
|
197
250
|
|
|
198
|
-
|
|
251
|
+
## OATS Desktop
|
|
199
252
|
|
|
200
|
-
|
|
253
|
+
A free agent development environment for macOS and Linux (x64) that puts a workspace in one window:
|
|
201
254
|
|
|
202
|
-
|
|
255
|
+
- every soul and running agent, and which agent started which;
|
|
256
|
+
- any agent's live terminal, files, notes and knowledge;
|
|
257
|
+
- starting, stopping, retiring and scheduling agents, and your triggers;
|
|
258
|
+
- which agents are waiting on you, and what each is asking;
|
|
259
|
+
- agents on several machines, including servers.
|
|
203
260
|
|
|
204
|
-
|
|
261
|
+
It is optional: agents run, message each other and follow their schedules whether it is open or not.
|
|
205
262
|
|
|
206
|
-
|
|
263
|
+
## Start here
|
|
207
264
|
|
|
208
|
-
|
|
265
|
+
**If you are a person,** your coding agent does the setup for you.
|
|
209
266
|
|
|
210
|
-
|
|
267
|
+
1. **You need** macOS or Linux, a coding agent (Claude Code, Codex or pi) and a GitHub account. Without a GitHub account, you make a free one during setup. Windows is not supported.
|
|
268
|
+
2. **Open your agent in the folder of a project** you want agents to help with, and say:
|
|
211
269
|
|
|
212
|
-
|
|
213
|
-
- Per-soul and topic-based knowledge.
|
|
214
|
-
- Speciation, widening, merging and ownership changes.
|
|
215
|
-
- Harvesting, maintenance and acceptance.
|
|
216
|
-
- Context handoffs and cloning.
|
|
217
|
-
- Knowledge-capability contracts and their implementation boundaries.
|
|
270
|
+
> Set up OATS for this project, following https://github.com/oats-project/oats
|
|
218
271
|
|
|
219
|
-
|
|
272
|
+
3. **Answer its questions.** It asks everything in one round and lists the changes it will make to your computer; say yes to them. After that you only approve the GitHub login and type a password or token if one is asked for.
|
|
220
273
|
|
|
221
|
-
|
|
274
|
+
Your agent then installs OATS, OATS Desktop and what they need. It creates a private GitHub repository for your agents' shared setup (the workspace), creates the group your agents message each other in (on [aweb](https://aweb.ai), with no sign-up), and starts the **setup expert**, an agent that adapts the defaults with you. OATS Desktop opens on it. Allow 5 to 10 minutes.
|
|
222
275
|
|
|
223
|
-
|
|
224
|
-
2. Select the capabilities your team needs.
|
|
225
|
-
3. Define specialists with clear responsibilities.
|
|
226
|
-
4. Create instances for their assignments.
|
|
227
|
-
5. Verify that work, communication, learning and handoff behave as intended.
|
|
276
|
+
**To join a workspace a teammate already runs,** say instead *"Join our OATS workspace at \<its GitHub repository\>, following https://github.com/oats-project/oats"*. Your teammate's agent makes you an invite, which your teammate passes to you privately; your agent tells you when to paste it.
|
|
228
277
|
|
|
229
|
-
|
|
278
|
+
**If you are an agent** asked to set up, install or try OATS, download the `oats-getting-started` skill and follow it step by step. It is the whole procedure; don't improvise one from this README.
|
|
230
279
|
|
|
231
280
|
```bash
|
|
232
|
-
|
|
233
|
-
oats onboard ~/acme --workspace git:github.com/acme/agents # this machine's deployment
|
|
234
|
-
oats spawn <soul> --task "First concrete task"
|
|
281
|
+
curl -fsSL https://raw.githubusercontent.com/oats-project/oats/main/skills/oats-getting-started/SKILL.md
|
|
235
282
|
```
|
|
236
283
|
|
|
237
|
-
|
|
284
|
+
Download it rather than web-fetching it: a summarising fetch would lose its exact commands.
|
|
238
285
|
|
|
239
|
-
|
|
286
|
+
## Learn more
|
|
240
287
|
|
|
241
288
|
- [Souls and instances](docs/souls-and-instances.md)
|
|
242
|
-
- [
|
|
243
|
-
- [Capabilities](docs/capabilities.md) and [
|
|
244
|
-
- [Knowledge
|
|
245
|
-
- [
|
|
246
|
-
- [Packages](docs/packages.md)
|
|
247
|
-
- [Sessions](docs/execution-targets.md)
|
|
248
|
-
- [Upgrading OATS on a host](docs/upgrading.md)
|
|
289
|
+
- [Workspaces](docs/workspaces.md)
|
|
290
|
+
- [Capabilities](docs/capabilities.md), [packages](docs/packages.md) and the [official catalog](docs/official-catalog.md)
|
|
291
|
+
- [Knowledge and learning](docs/knowledge-and-learning.md), and in depth, [knowledge, instances and evolving expertise](docs/knowledge-theory.md)
|
|
292
|
+
- [Schedules and triggers](docs/schedules.md)
|
|
249
293
|
- [OATS Desktop](docs/desktop.md)
|
|
250
|
-
- [
|
|
251
|
-
|
|
252
|
-
This README explains the framework and its direction. Advanced mechanisms such as automatic speciation and context cloning require their own implementation and verification; the model is not a claim that every feature or capability combination already works.
|
|
294
|
+
- [Release notes](docs/release-notes/)
|
|
253
295
|
|
|
254
|
-
## Contributing
|
|
296
|
+
## Contributing
|
|
255
297
|
|
|
256
|
-
Source, issues and pull requests live at [
|
|
257
|
-
|
|
258
|
-
Versioned releases publish the kernel, Pi bridge and Desktop installers. Check the [release notes](docs/release-notes/) before changing an existing deployment; installing software does not automatically migrate knowledge or reconfigure live agents.
|
|
298
|
+
Source, issues and pull requests live at [oats-project/oats](https://github.com/oats-project/oats). The [implementation guide](docs/implementation.md) covers the repository and the [release lane](docs/release-lane.md) how releases are verified and published. Read the [release notes](docs/release-notes/) before changing an existing deployment.
|
|
259
299
|
|
|
260
300
|
## Origins and licence
|
|
261
301
|
|
|
262
|
-
OATS began as **OAS
|
|
263
|
-
|
|
264
|
-
OATS grew from the a2am team architecture and the LFX engineering vision for agent-native engineering. It builds on open formats and conventions, including AGENTS.md, Agent Skills and Open Knowledge Format.
|
|
302
|
+
OATS began as **OAS, Open Agent Specialization**, designed and written by Josep (Pepe) Garcia-Reyero Sais. The architecture, kernel, package engine, Desktop and official packages are his work; OATS continues it under its current name. It grew from the a2am team architecture and builds on open formats, including AGENTS.md, Agent Skills and Open Knowledge Format.
|
|
265
303
|
|
|
266
|
-
OATS is free and [MIT-licensed](LICENSE). Models and services
|
|
304
|
+
OATS is free and [MIT-licensed](LICENSE). Models and services a deployment chooses may have their own licences and costs.
|